DLERROR(3P)                POSIX Programmer's Manual               DLERROR(3P)



PROLOG
       This  manual page is part of the POSIX Programmer's Man-
       ual.  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.

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(), dler-
       ror() 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 link-
       ing 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 dler-
       ror().   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 asyn-
       chronous execution events,  such  as  signals  or  other
       asynchronous computation sharing the address space, con-
       forming 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 vol-
       ume 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  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  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.open-
       group.org/unix/online.html .



IEEE/The Open Group                  2003                          DLERROR(3P)
