unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

DLOPEN(3X)                                                          DLOPEN(3X)



NAME
       dlopen,  dlsym, dlerror, dlclose - simple programmatic interface to the
       dynamic linker

SYNOPSIS
       #include <&lt;dlfcn.h>&gt;

       void *dlopen(path, mode)
       char *path; int mode;

       void *dlsym(handle, symbol)
       void *handle; char *symbol;

       char *dlerror()

       int dlclose(handle);
       void *handle;

DESCRIPTION
       These functions provide a simple programmatic interface to the services
       of  the  dynamic  link-editor.   Operations  are  provided to add a new
       shared object to an program's address space, obtain the  address  bind-
       ings  of  symbols  defined  by such objects, and to remove such objects
       when their use is no longer required.

       dlopen() provides access to the shared  object  in  path,  returning  a
       descriptor that can be used for later references to the object in calls
       to dlsym() and dlclose().  If path was not in the address  space  prior
       to  the  call to dlopen(), then it will be placed in the address space,
       and if it defines a function with the name _init that function will  be
       called  by  dlopen().  If, however, path has already been placed in the
       address space in a previous call to dlopen(), then it will not be added
       a  second time, although a count of dlopen() operations on path will be
       maintained.  mode is an integer containing flags describing options  to
       be  applied  to  the  opening and loading process -- it is reserved for
       future expansion and must always have the value 1.  A null pointer sup-
       plied  for  path is interpreted as a reference to the "main" executable
       of the process.  If dlopen() fails, it will return a null pointer.

       dlsym() returns the address binding of  the  symbol  described  in  the
       null-terminated  character  string  symbol  as  it occurs in the shared
       object identified by handle.  The symbols exported by objects added  to
       the  address  space  by  dlopen() can be accessed only through calls to
       dlsym(), such symbols do not supersede any definition of those  symbols
       already present in the address space when the object is loaded, nor are
       they available to satisfy "normal" dynamic linking references.  dlsym()
       returns  a null pointer if the symbol can not be found.  A null pointer
       supplied as the value of handle is interpreted as a  reference  to  the
       executable  from  which  the  call  to  dlsym() is being made -- thus a
       shared object can reference its own symbols.

       dlerror returns a null-terminated character string describing the  last
       error  that  occurred  during a dlopen(), dlsym(), or dlclose().  If no
       such error has occurred, then dlerror() will return a null pointer.  At
       each call to dlerror(), the "last error" indication will be reset, thus
       in the case of two calls to dlerror(), and where the second  call  fol-
       lows  the  first immediately, the second call will always return a null
       pointer.

       dlclose() deletes a reference to the shared object referenced  by  han-
       dle.   If the reference count drops to 0, then if the object referenced
       by handle defines a function _fini, that function will be  called,  the
       object  removed  from  the  address  space,  and  handle destroyed.  If
       dlclose() is successful, it will return a value of 0.  A  failing  call
       to dlclose() will return a non-zero value.

       The object-intrinsic functions _init and _fini are called with no argu-
       ments and treated as though their types were void.

       These functions are obtained by specifying -ldl as an option to ld(1).

SEE ALSO
       ld(1), link(5)




                               24 September 1989                    DLOPEN(3X)