NAME

       dlerror - get diagnostic information

SYNOPSIS

       #include <dlfcn.h>

       char *dlerror(void);

DESCRIPTION

       The  dlerror() 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  dlerror(), dlerror() shall return NULL.  Thus, invoking
       dlerror() a second time, immediately following a prior invocation, shall result in NULL being returned.

       The dlerror() function need not be reentrant. A function that is not required  to  be  reentrant  is  not
       required to be thread-safe.

RETURN VALUE

       If  successful,  dlerror()  shall  return  a  null-terminated  character string; otherwise, NULL shall be
       returned.

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

       The following example prints out the last dynamic linking error:

              ...
              #include <dlfcn.h>

              char *errstr;

              errstr = dlerror();
              if (errstr != NULL)
              printf ("A dynamic linking error occurred: (%s)\n", errstr);
              ...

APPLICATION USAGE

       The messages returned by dlerror() may reside in a static buffer that is  overwritten  on  each  call  to
       dlerror().   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.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       dlclose() , dlopen() , dlsym() , the Base Definitions volume of IEEE Std 1003.1-2001, <dlfcn.h>

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 .

IEEE/The Open Group                                   2003                                            DLERROR(P)