.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "DLERROR" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" dlerror 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
dlerror \- get diagnostic information
.SH SYNOPSIS
.LP
\fB#include <dlfcn.h>
.br
.sp
char *dlerror(void); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIdlerror\fP() function shall return a null-terminated character
string (with no trailing <newline>) that describes
the last error that occurred during dynamic linking processing. If
no dynamic linking errors have occurred since the last
invocation of \fIdlerror\fP(), \fIdlerror\fP() shall return NULL.
Thus, invoking \fIdlerror\fP() a second time, immediately
following a prior invocation, shall result in NULL being returned.
.LP
The \fIdlerror\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe.
.SH RETURN VALUE
.LP
If successful, \fIdlerror\fP() shall return a null-terminated character
string; otherwise, NULL shall be returned.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
The following example prints out the last dynamic linking error:
.sp
.RS
.nf

\fB\&...
#include <dlfcn.h>
.sp

char *errstr;
.sp

errstr = dlerror();
if (errstr != NULL)
printf ("A dynamic linking error occurred: (%s)\\n", errstr);
\&...
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
The messages returned by \fIdlerror\fP() may reside in a static buffer
that is overwritten on each call to \fIdlerror\fP().
Application code should not write to this buffer. Programs wishing
to preserve an error message should make their own copies of
that message. Depending on the application environment with respect
to asynchronous execution events, such as signals or other
asynchronous computation sharing the address space, conforming applications
should use a critical section to retrieve the error
pointer and buffer.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIdlclose\fP(), \fIdlopen\fP(), \fIdlsym\fP(), the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, \fI<dlfcn.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .