diff options
Diffstat (limited to 'man3/dlopen.3')
| -rw-r--r-- | man3/dlopen.3 | 627 |
1 files changed, 0 insertions, 627 deletions
diff --git a/man3/dlopen.3 b/man3/dlopen.3 deleted file mode 100644 index a21e6e1b4..000000000 --- a/man3/dlopen.3 +++ /dev/null @@ -1,627 +0,0 @@ -'\" t -.\" Copyright 1995 Yggdrasil Computing, Incorporated. -.\" written by Adam J. Richter (adam@yggdrasil.com), -.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). -.\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28. -.\" Applied patch by Terran Melconian, aeb, 2001-12-14. -.\" Modified by Hacksaw <hacksaw@hacksaw.org> 2003-03-13. -.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete -.\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16. -.\" Modified by Walter Harms: dladdr, dlvsym -.\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat -.\" -.TH dlopen 3 (date) "Linux man-pages (unreleased)" -.SH NAME -dlclose, dlopen, dlmopen \- -open and close a shared object -.SH LIBRARY -Dynamic linking library -.RI ( libdl ", " \-ldl ) -.SH SYNOPSIS -.nf -.B #include <dlfcn.h> -.PP -.BI "void *dlopen(const char *" filename ", int " flags ); -.BI "int dlclose(void *" handle ); -.PP -.B #define _GNU_SOURCE -.br -.B #include <dlfcn.h> -.PP -.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags ); -.fi -.SH DESCRIPTION -.SS dlopen() -The function -.BR dlopen () -loads the dynamic shared object (shared library) -file named by the null-terminated -string -.I filename -and returns an opaque "handle" for the loaded object. -This handle is employed with other functions in the dlopen API, such as -.BR dlsym (3), -.BR dladdr (3), -.BR dlinfo (3), -and -.BR dlclose (). -.PP -If -.I filename -.\" FIXME On Solaris, when handle is NULL, we seem to get back -.\" a handle for (something like) the root of the namespace. -.\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then -.\" the filename==NULL case returns a different handle than -.\" in the initial namespace. But, on glibc, the same handle is -.\" returned. This is probably a bug in glibc. -.\" -is NULL, then the returned handle is for the main program. -If -.I filename -contains a slash ("/"), then it is interpreted as a (relative -or absolute) pathname. -Otherwise, the dynamic linker searches for the object as follows -(see -.BR ld.so (8) -for further details): -.IP \[bu] 3 -(ELF only) If the calling object -(i.e., the shared library or executable from which -.BR dlopen () -is called) -contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, -then the directories listed in the DT_RPATH tag are searched. -.IP \[bu] -If, at the time that the program was started, the environment variable -.B LD_LIBRARY_PATH -was defined to contain a colon-separated list of directories, -then these are searched. -(As a security measure, this variable is ignored for set-user-ID and -set-group-ID programs.) -.IP \[bu] -(ELF only) If the calling object -contains a DT_RUNPATH tag, then the directories listed in that tag -are searched. -.IP \[bu] -The cache file -.I /etc/ld.so.cache -(maintained by -.BR ldconfig (8)) -is checked to see whether it contains an entry for -.IR filename . -.IP \[bu] -The directories -.I /lib -and -.I /usr/lib -are searched (in that order). -.PP -If the object specified by -.I filename -has dependencies on other shared objects, -then these are also automatically loaded by the dynamic linker -using the same rules. -(This process may occur recursively, -if those objects in turn have dependencies, and so on.) -.PP -One of the following two values must be included in -.IR flags : -.TP -.B RTLD_LAZY -Perform lazy binding. -Resolve symbols only as the code that references them is executed. -If the symbol is never referenced, then it is never resolved. -(Lazy binding is performed only for function references; -references to variables are always immediately bound when -the shared object is loaded.) -Since glibc 2.1.1, -.\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072 -this flag is overridden by the effect of the -.B LD_BIND_NOW -environment variable. -.TP -.B RTLD_NOW -If this value is specified, or the environment variable -.B LD_BIND_NOW -is set to a nonempty string, -all undefined symbols in the shared object are resolved before -.BR dlopen () -returns. -If this cannot be done, an error is returned. -.PP -Zero or more of the following values may also be ORed in -.IR flags : -.TP -.B RTLD_GLOBAL -The symbols defined by this shared object will be -made available for symbol resolution of subsequently loaded shared objects. -.TP -.B RTLD_LOCAL -This is the converse of -.BR RTLD_GLOBAL , -and the default if neither flag is specified. -Symbols defined in this shared object are not made available to resolve -references in subsequently loaded shared objects. -.TP -.BR RTLD_NODELETE " (since glibc 2.2)" -Do not unload the shared object during -.BR dlclose (). -Consequently, the object's static and global variables are not reinitialized -if the object is reloaded with -.BR dlopen () -at a later time. -.TP -.BR RTLD_NOLOAD " (since glibc 2.2)" -Don't load the shared object. -This can be used to test if the object is already resident -.RB ( dlopen () -returns NULL if it is not, or the object's handle if it is resident). -This flag can also be used to promote the flags on a shared object -that is already loaded. -For example, a shared object that was previously loaded with -.B RTLD_LOCAL -can be reopened with -.BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . -.\" -.TP -.BR RTLD_DEEPBIND " (since glibc 2.3.4)" -.\" Inimitably described by UD in -.\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. -Place the lookup scope of the symbols in this -shared object ahead of the global scope. -This means that a self-contained object will use -its own symbols in preference to global symbols with the same name -contained in objects that have already been loaded. -.PP -If -.I filename -is NULL, then the returned handle is for the main program. -When given to -.BR dlsym (3), -this handle causes a search for a symbol in the main program, -followed by all shared objects loaded at program startup, -and then all shared objects loaded by -.BR dlopen () -with the flag -.BR RTLD_GLOBAL . -.PP -Symbol references in the shared object are resolved using (in order): -symbols in the link map of objects loaded for the main program and its -dependencies; -symbols in shared objects (and their dependencies) -that were previously opened with -.BR dlopen () -using the -.B RTLD_GLOBAL -flag; -and definitions in the shared object itself -(and any dependencies that were loaded for that object). -.PP -Any global symbols in the executable that were placed into -its dynamic symbol table by -.BR ld (1) -can also be used to resolve references in a dynamically loaded shared object. -Symbols may be placed in the dynamic symbol table -either because the executable was linked with the flag "\-rdynamic" -(or, synonymously, "\-\-export\-dynamic"), which causes all of -the executable's global symbols to be placed in the dynamic symbol table, -or because -.BR ld (1) -noted a dependency on a symbol in another object during static linking. -.PP -If the same shared object is opened again with -.BR dlopen (), -the same object handle is returned. -The dynamic linker maintains reference -counts for object handles, so a dynamically loaded shared object is not -deallocated until -.BR dlclose () -has been called on it as many times as -.BR dlopen () -has succeeded on it. -Constructors (see below) are called only when the object is actually loaded -into memory (i.e., when the reference count increases to 1). -.PP -A subsequent -.BR dlopen () -call that loads the same shared object with -.B RTLD_NOW -may force symbol resolution for a shared object earlier loaded with -.BR RTLD_LAZY . -Similarly, an object that was previously opened with -.B RTLD_LOCAL -can be promoted to -.B RTLD_GLOBAL -in a subsequent -.BR dlopen (). -.PP -If -.BR dlopen () -fails for any reason, it returns NULL. -.\" -.SS dlmopen() -This function performs the same task as -.BR dlopen ()\[em]the -.I filename -and -.I flags -arguments, as well as the return value, are the same, -except for the differences noted below. -.PP -The -.BR dlmopen () -function differs from -.BR dlopen () -primarily in that it accepts an additional argument, -.IR lmid , -that specifies the link-map list (also referred to as a -.IR namespace ) -in which the shared object should be loaded. -(By comparison, -.BR dlopen () -adds the dynamically loaded shared object to the same namespace as -the shared object from which the -.BR dlopen () -call is made.) -The -.I Lmid_t -type is an opaque handle that refers to a namespace. -.PP -The -.I lmid -argument is either the ID of an existing namespace -.\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? -(which can be obtained using the -.BR dlinfo (3) -.B RTLD_DI_LMID -request) or one of the following special values: -.TP -.B LM_ID_BASE -Load the shared object in the initial namespace -(i.e., the application's namespace). -.TP -.B LM_ID_NEWLM -Create a new namespace and load the shared object in that namespace. -The object must have been correctly linked -to reference all of the other shared objects that it requires, -since the new namespace is initially empty. -.PP -If -.I filename -is NULL, then the only permitted value for -.I lmid -is -.BR LM_ID_BASE . -.SS dlclose() -The function -.BR dlclose () -decrements the reference count on the -dynamically loaded shared object referred to by -.IR handle . -.PP -If the object's reference count drops to zero -and no symbols in this object are required by other objects, -then the object is unloaded -after first calling any destructors defined for the object. -(Symbols in this object might be required in another object -because this object was opened with the -.B RTLD_GLOBAL -flag and one of its symbols satisfied a relocation in another object.) -.PP -All shared objects that were automatically loaded when -.BR dlopen () -was invoked on the object referred to by -.I handle -are recursively closed in the same manner. -.PP -A successful return from -.BR dlclose () -does not guarantee that the symbols associated with -.I handle -are removed from the caller's address space. -In addition to references resulting from explicit -.BR dlopen () -calls, a shared object may have been implicitly loaded -(and reference counted) because of dependencies in other shared objects. -Only when all references have been released can the shared object -be removed from the address space. -.SH RETURN VALUE -On success, -.BR dlopen () -and -.BR dlmopen () -return a non-NULL handle for the loaded object. -On error -(file could not be found, was not readable, had the wrong format, -or caused errors during loading), -these functions return NULL. -.PP -On success, -.BR dlclose () -returns 0; on error, it returns a nonzero value. -.PP -Errors from these functions can be diagnosed using -.BR dlerror (3). -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.ad l -.nh -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.BR dlopen (), -.BR dlmopen (), -.BR dlclose () -T} Thread safety MT-Safe -.TE -.hy -.ad -.sp 1 -.SH STANDARDS -.TP -.BR dlopen () -.TQ -.BR dlclose () -POSIX.1-2008. -.TP -.BR dlmopen () -.TQ -.B RTLD_NOLOAD -.TQ -.B RTLD_NODELETE -GNU. -.TP -.B RTLD_DEEPBIND -Solaris. -.SH HISTORY -.TP -.BR dlopen () -.TQ -.BR dlclose () -glibc 2.0. -POSIX.1-2001. -.TP -.BR dlmopen () -glibc 2.3.4. -.SH NOTES -.SS dlmopen() and namespaces -A link-map list defines an isolated namespace for the -resolution of symbols by the dynamic linker. -Within a namespace, -dependent shared objects are implicitly loaded according to the usual rules, -and symbol references are likewise resolved according to the usual rules, -but such resolution is confined to the definitions provided by the -objects that have been (explicitly and implicitly) loaded into the namespace. -.PP -The -.BR dlmopen () -function permits object-load isolation\[em]the ability -to load a shared object in a new namespace without -exposing the rest of the application to the symbols -made available by the new object. -Note that the use of the -.B RTLD_LOCAL -flag is not sufficient for this purpose, -since it prevents a shared object's symbols from being available to -.I any -other shared object. -In some cases, -we may want to make the symbols provided by a dynamically -loaded shared object available to (a subset of) other shared objects -without exposing those symbols to the entire application. -This can be achieved by using a separate namespace and the -.B RTLD_GLOBAL -flag. -.PP -The -.BR dlmopen () -function also can be used to provide better isolation than the -.B RTLD_LOCAL -flag. -In particular, shared objects loaded with -.B RTLD_LOCAL -may be promoted to -.B RTLD_GLOBAL -if they are dependencies of another shared object loaded with -.BR RTLD_GLOBAL . -Thus, -.B RTLD_LOCAL -is insufficient to isolate a loaded shared object except in the (uncommon) -case where one has explicit control over all shared object dependencies. -.PP -Possible uses of -.BR dlmopen () -are plugins where the author of the plugin-loading framework -can't trust the plugin authors and does not wish -any undefined symbols from the plugin framework to be resolved to plugin -symbols. -Another use is to load the same object more than once. -Without the use of -.BR dlmopen (), -this would require the creation of distinct copies of the shared object file. -Using -.BR dlmopen (), -this can be achieved by loading the same shared object file into -different namespaces. -.PP -The glibc implementation supports a maximum of -.\" DL_NNS -16 namespaces. -.\" -.SS Initialization and finalization functions -Shared objects may export functions using the -.B __attribute__((constructor)) -and -.B __attribute__((destructor)) -function attributes. -Constructor functions are executed before -.BR dlopen () -returns, and destructor functions are executed before -.BR dlclose () -returns. -A shared object may export multiple constructors and destructors, -and priorities can be associated with each function -to determine the order in which they are executed. -See the -.B gcc -info pages (under "Function attributes") -.\" info gcc "C Extensions" "Function attributes" -for further information. -.PP -An older method of (partially) achieving the same result is via the use of -two special symbols recognized by the linker: -.B _init -and -.BR _fini . -If a dynamically loaded shared object exports a routine named -.BR _init (), -then that code is executed after loading a shared object, before -.BR dlopen () -returns. -If the shared object exports a routine named -.BR _fini (), -then that routine is called just before the object is unloaded. -In this case, one must avoid linking against the system startup files, -which contain default versions of these files; -this can be done by using the -.BR gcc (1) -.I \-nostartfiles -command-line option. -.PP -Use of -.B _init -and -.B _fini -is now deprecated in favor of the aforementioned -constructors and destructors, -which among other advantages, -permit multiple initialization and finalization functions to be defined. -.\" -.\" Using these routines, or the gcc -.\" .B \-nostartfiles -.\" or -.\" .B \-nostdlib -.\" options, is not recommended. -.\" Their use may result in undesired behavior, -.\" since the constructor/destructor routines will not be executed -.\" (unless special measures are taken). -.\" .\" void _init(void) __attribute__((constructor)); -.\" .\" void _fini(void) __attribute__((destructor)); -.\" -.PP -Since glibc 2.2.3, -.BR atexit (3) -can be used to register an exit handler that is automatically -called when a shared object is unloaded. -.SS History -These functions are part of the dlopen API, derived from SunOS. -.SH BUGS -As at glibc 2.24, specifying the -.B RTLD_GLOBAL -flag when calling -.BR dlmopen () -.\" dlerror(): "invalid mode" -generates an error. -Furthermore, specifying -.B RTLD_GLOBAL -when calling -.BR dlopen () -results in a program crash -.RB ( SIGSEGV ) -.\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684 -if the call is made from any object loaded in a -namespace other than the initial namespace. -.SH EXAMPLES -The program below loads the (glibc) math library, -looks up the address of the -.BR cos (3) -function, and prints the cosine of 2.0. -The following is an example of building and running the program: -.PP -.in +4n -.EX -$ \fBcc dlopen_demo.c \-ldl\fP -$ \fB./a.out\fP -\-0.416147 -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (dlopen.c) -.EX -#include <dlfcn.h> -#include <stdio.h> -#include <stdlib.h> -\& -#include <gnu/lib\-names.h> /* Defines LIBM_SO (which will be a - string such as "libm.so.6") */ -int -main(void) -{ - void *handle; - double (*cosine)(double); - char *error; -\& - handle = dlopen(LIBM_SO, RTLD_LAZY); - if (!handle) { - fprintf(stderr, "%s\en", dlerror()); - exit(EXIT_FAILURE); - } -\& - dlerror(); /* Clear any existing error */ -\& - cosine = (double (*)(double)) dlsym(handle, "cos"); -\& - /* According to the ISO C standard, casting between function - pointers and \[aq]void *\[aq], as done above, produces undefined results. - POSIX.1\-2001 and POSIX.1\-2008 accepted this state of affairs and - proposed the following workaround: -\& - *(void **) (&cosine) = dlsym(handle, "cos"); -\& - This (clumsy) cast conforms with the ISO C standard and will - avoid any compiler warnings. -\& - The 2013 Technical Corrigendum 1 to POSIX.1\-2008 improved matters - by requiring that conforming implementations support casting - \[aq]void *\[aq] to a function pointer. Nevertheless, some compilers - (e.g., gcc with the \[aq]\-pedantic\[aq] option) may complain about the - cast used in this program. */ -.\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 -.\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 -.\" http://austingroupbugs.net/view.php?id=74 -\& - error = dlerror(); - if (error != NULL) { - fprintf(stderr, "%s\en", error); - exit(EXIT_FAILURE); - } -\& - printf("%f\en", (*cosine)(2.0)); - dlclose(handle); - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR ld (1), -.BR ldd (1), -.BR pldd (1), -.BR dl_iterate_phdr (3), -.BR dladdr (3), -.BR dlerror (3), -.BR dlinfo (3), -.BR dlsym (3), -.BR rtld\-audit (7), -.BR ld.so (8), -.BR ldconfig (8) -.PP -gcc info pages, ld info pages |