diff options
Diffstat (limited to 'lib/csu/i386/dlopen.3')
-rw-r--r-- | lib/csu/i386/dlopen.3 | 236 |
1 files changed, 0 insertions, 236 deletions
diff --git a/lib/csu/i386/dlopen.3 b/lib/csu/i386/dlopen.3 deleted file mode 100644 index b9a987c..0000000 --- a/lib/csu/i386/dlopen.3 +++ /dev/null @@ -1,236 +0,0 @@ -.\" This source code is a product of Sun Microsystems, Inc. and is provided -.\" for unrestricted use provided that this legend is included on all tape -.\" media and as a part of the software program in whole or part. Users -.\" may copy or modify this source code without charge, but are not authorized -.\" to license or distribute it to anyone else except as part of a product or -.\" program developed by the user. -.\" -.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC. -.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY -.\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT -.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS -.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN -.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT, -.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING -.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY. -.\" -.\" This source code is provided with no support and without any obligation on -.\" the part of Sun Microsystems, Inc. to assist in its use, correction, -.\" modification or enhancement. -.\" -.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE -.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS -.\" SOURCE CODE OR ANY PART THEREOF. -.\" -.\" Sun Microsystems, Inc. -.\" 2550 Garcia Avenue -.\" Mountain View, California 94043 -.\" -.\" Copyright (c) 1991 Sun Microsystems, Inc. -.\" -.\" @(#) dlopen.3 1.6 90/01/31 SMI -.Dd September 24, 1989 -.Os FreeBSD -.Dt DLOPEN 3 -.Sh NAME -.Nm dlopen, dlsym, dlerror, dlclose -.Nd programmatic interface to the dynamic linker -.Sh SYNOPSIS -.Fd #include <dlfcn.h> -.Ft void * -.Fn dlopen "const char *path" "int mode" -.Ft void * -.Fn dlsym "void *handle" "const char *symbol" -.Ft const char * -.Fn dlerror "void" -.Ft int -.Fn dlclose "void *handle" -.Sh DESCRIPTION -These functions provide a simple programmatic interface to the services of the -dynamic linker. -Operations are provided to add new shared objects to a -program's address space, to obtain the address bindings of symbols -defined by such -objects, and to remove such objects when their use is no longer required. -.Pp -.Fn dlopen -provides access to the shared object in -.Fa path , -returning a descriptor that can be used for later -references to the object in calls to -.Fn dlsym -and -.Fn dlclose . -If -.Fa path -was not in the address space prior to the call to -.Fn dlopen , -it is placed in the address space. -When an object is first loaded into the address space in this way, its -function -.Fn _init , -if any, is called by the dynamic linker. -(Note that -.Ql _init -is the name as expressed in the C language. -From assembly language, the name would appear as -.Ql __init -instead.) -If -.Fa path -has already been placed in the address space in a previous call to -.Fn dlopen , -it is not added a second time, although a reference count of -.Fn dlopen -operations on -.Fa path -is maintained. -A null pointer supplied for -.Fa path -is interpreted as a reference to the main -executable of the process. -.Fa mode -controls the way in which external function references from the -loaded object are bound to their referents. -It must contains one of the following values: -.Bl -tag -width RTLD_LAZYX -.It Dv RTLD_LAZY -Each external function reference is resolved when the function is first -called. -.It Dv RTLD_NOW -All external function references are bound immediately by -.Fn dlopen . -.El -.Pp -.Dv RTLD_LAZY -is normally preferred, for reasons of efficiency. -However, -.Dv RTLD_NOW -is useful to ensure that any undefined symbols are discovered during the -call to -.Fn dlopen . -If -.Fn dlopen -fails, it returns a null pointer, and sets an error condition which may -be interrogated with -.Fn dlerror . -.Pp -.Fn dlsym -returns the address binding of the symbol described in the null-terminated -character string -.Fa symbol , -as it occurs in the shared object identified by -.Fa handle . -Note that -.Fa symbol -is the assembly language representation of the symbol name. -The assembly language representation of a C language symbol contains an -extra underscore at the beginning. -For example, the symbol -.Ql foo -in C would appear as -.Ql _foo -in assembly language, and in the -.Fa symbol -argument to -.Fn dlsym . -The symbols exported by objects added to the address space by -.Fn dlopen -can be accessed only through calls to -.Fn 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. -A null pointer supplied as the value of -.Fa handle -is interpreted as a reference to the executable from which the call to -.Fn dlsym -is being made. Thus a shared object can reference its own symbols. -.Fn dlsym -returns a null pointer if the symbol cannot be found, and sets an error -condition which may be queried with -.Fn dlerror . -.Pp -If -.Fn dlsym -is called with the special -.Fa handle -.Dv RTLD_NEXT , -then the search for the symbol is limited to the shared objects -which were loaded after the one issuing the call to -.Fn dlsym . -Thus, if the function is called from the main program, all -the shared libraries are searched. -If it is called from a shared library, all subsequent shared -libraries are searched. -.Dv RTLD_NEXT -is useful for implementing wrappers around library functions. -For example, a wrapper function -.Fn getpid -could access the -.Dq real -.Fn getpid -with -.Li dlsym(RTLD_NEXT, \&"_getpid\&") . -.Pp -.Fn dlerror -returns a null-terminated character string describing the last error that -occurred during a call to -.Fn dlopen , -.Fn dlsym , -or -.Fn dlclose . -If no such error has occurred, -.Fn dlerror -returns a null pointer. -At each call to -.Fn dlerror , -the error indication is reset. Thus in the case of two calls -to -.Fn dlerror , -where the second call follows the first immediately, the second call -will always return a null pointer. -.Pp -.Fn dlclose -deletes a reference to the shared object referenced by -.Fa handle . -If the reference count drops to 0, the object is removed from the -address space, and -.Fa handle -is rendered invalid. -Just before removing a shared object in this way, the dynamic linker -calls the object's -.Fn _fini -function, if such a function is defined by the object. -As with -.Ql _init , -.Ql _fini -is the C language name of the function. -If -.Fn dlclose -is successful, it returns a value of 0. -Otherwise it returns -1, and sets an error condition that can be -interrogated with -.Fn dlerror . -.Pp -The object-intrinsic functions -.Fn _init -and -.Fn _fini -are called with no arguments, and are not expected to return values. -.Sh ERRORS -.Fn dlopen -and -.Fn dlsym -return the null pointer in the event of errors. -.Fn dlclose -returns 0 on success, or -1 if an error occurred. -Whenever an error has been detected, a message detailing it can be -retrieved via a call to -.Fn dlerror . -.Sh SEE ALSO -.Xr ld 1 , -.Xr rtld 1 , -.Xr link 5 - |