SGIDLADD(3C)SGIDLADD(3C)NAMEsgidladd - open a shared object and add its variables to the name space.
SYNOPSIS
cc [flag ...] file ... -lc [library ...]
#include <dlfcn.h>
void *sgidladd(const char *pathname, int mode);
DESCRIPTIONsgidladd is a facility for dynamically loading shared objects. Unlike
dlopen(3)(without RTLD_GLOBAL), the shared object loaded (and all it's
dependent shared objects), are added to the list of shared objects just
as if they had been specified at the time the program had been linked, or
as if the _RLD_LIST (see rld(1)) envariable had been used. That is to
say, all the names in the shared object become available to satisfy
references in shared objects during lazy text resolution (the DSOs are
globally visible: see also dlopen "NAMESPACE ISSUES").
mode may be any one of RTLD_LAZY, RTLD_NOW, or RTLD_NOW_REPORT_ERROR.
The mode RTLD_NOW does exactly the same thing as RTLD_LAZY. When the
mode is specified as RTLD_LAZY or RTLD_NOW, resolution of all symbols is
performed, so that references which were previously unbound or bound to
weak symbols can be rebound to strong symbols. However, unresolvable
references (a reference to a symbol which does not exist in any shared
object or in the mainline) to functions are left dangling for further
"lazy" resolution, pending another call to sgidladd perhaps.
When the mode is specified as RTLD_NOW_REPORT_ERROR resolution of all
symbols is performed, and any unresolvable reference results in an error
return from sgidladd. In this case, it is very dangerous to continue
execution, since resolution was not completed. The main use for this
function is to ensure that at the point of the sgidladd, all symbols have
now been resolved. This is useful for verifying completeness of
interfaces.
As with dlopen, a handle to the added object is returned, and this handle
may be used to obtain addresses of specific symbols within the added
object. This is somewhat less useful than with dlopen(without
RTLD_GLOBAL), since in the case of sgidladd rld can resolve these symbols
directly (as can dlopen with RTLD_GLOBAL).
sgidladd is available in a library which is loaded if the option -lc is
used with cc , f77 , or ld.
SEARCHING FOR SHARED OBJECTS
If other shared objects were link edited with pathname when pathname was
built, those objects are automatically loaded by dlopen. The directory
search path used to find both pathname and the other needed objects is
the same as that used by rld(1). In particular, pathname is searched for
Page 1
SGIDLADD(3C)SGIDLADD(3C)
in
1) the directory specified by pathname if it is not a simple file name
(i.e. it contains a / character). In this case, the exact file is the
only placed searched; steps two through four below are ignored.
2) any path specified via the -rpath argument to ld(1) when the
executable was statically linked.
3) any directory specified by the environment variable LD_LIBRARY_PATH.
This environment variable should contain a colon-separated list of
directories, in the same format as the PATH variable [see sh(1)]. 64-bit
programs examine the variable LD_LIBRARY64_PATH and if it is not set
examine LD_LIBRARY_PATH. New 32-bit ABI programs examine the variable
LD_LIBRARYN32_PATH and if it is not set examine LD_LIBRARY_PATH to
determine if an ABI-specific path has been specified.
All three of these variables are ignored if the process is running setuid
or setgid [see exec(2)].
4) the default search paths are used. These are /usr/lib:/lib for 32-bit
programs, /usr/lib64:/lib64 for 64-bit programs, and /usr/lib32:/lib32
for new 32-bit ABI programs.
The variable _RLD_ROOT has its usual effect, as documented in the manpage
for rld(1) (which means that for a setuid or setgid program _RLD_ROOT is
ignored).
Objects whose names resolve to the same absolute or relative path name
may be opened any number of times using sgidladd, however, the object
referenced is only loaded once into the address space of the current
process. The same object referenced by two different path names,
however, may be loaded multiple times. For example, given the object
/usr/home/me/mylibs/mylib.so, and assuming the current working directory
is /usr/home/me/workdir,
...
void *handle1;
void *handle2;
handle1 = sgidladd("../mylibs/mylib.so", RTLD_LAZY);
handle2 = sgidladd("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
...
results in mylib.so being loaded twice for the current process. On the
other hand, given the same object and current working directory, if
LD_LIBRARY_PATH=/usr/home/me/mylibs, then
Page 2
SGIDLADD(3C)SGIDLADD(3C)
...
void *handle1;
void *handle2;
handle1 = sgidladd("mylib.so", RTLD_LAZY);
handle2 = sgidladd("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
...
results in mylib.so being loaded only once.
SEE ALSOdlopen(3)dlerror(3), dlclose(3), dlsym(3), sgidlopen_version(3), rld(1),
dso(5).
DIAGNOSTICS
If pathname cannot be found, cannot be opened for reading, is not a
shared object, or if an error occurs during the process of loading
pathname or relocating its symbolic references, sgidladd returns NULL.
More detailed diagnostic information is available through dlerror.
NOTES
Use of dlclose on a dladded DSO can cause surprising side effects because
dlclose forces many symbol's GOT entries to be reset for re-lazy-
evaluation. A result of this is that previously-saved (by the
application or some library) function pointers may hold values that could
be obsolete or no longer correct.
Symbol lookups proceed in order on a linear list, and a DSO is not opened
twice with the same version number (unless different dlopen paths make
the DSO name appear different to rld). When multiple sgidladds are done
and an earlier DSO is dlclosed this can change what symbol a call is
resolved to. See the discussion of this in the dlopen description under
"NAMESPACE ISSUES".
Page 3
