diff options
Diffstat (limited to 'static/netbsd/man3/dlfcn.3')
| -rw-r--r-- | static/netbsd/man3/dlfcn.3 | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/static/netbsd/man3/dlfcn.3 b/static/netbsd/man3/dlfcn.3 new file mode 100644 index 00000000..65910c07 --- /dev/null +++ b/static/netbsd/man3/dlfcn.3 @@ -0,0 +1,377 @@ +.\" $NetBSD: dlfcn.3,v 1.42 2024/03/09 18:43:39 gutteridge Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 7, 2024 +.Dt DLFCN 3 +.Os +.Sh NAME +.Nm _dlauxinfo , +.Nm dlopen , +.Nm dlclose , +.Nm dlsym , +.Nm dlvsym , +.Nm dladdr , +.Nm dlctl , +.Nm dlerror +.Nd dynamic link interface +.Sh LIBRARY +(These functions are not in a library. +They are included in every +dynamically linked program automatically.) +.Sh SYNOPSIS +.In dlfcn.h +.Ft "void *" +.Fn _dlauxinfo "void" +.Ft "void *" +.Fn dlopen "const char *path" "int mode" +.Ft "int" +.Fn dlclose "void *handle" +.Ft "void *" +.Fn dlsym "void * restrict handle" "const char * restrict symbol" +.Ft "void *" +.Fn dlvsym "void * restrict handle" "const char * restrict symbol" "const char *version" +.Ft "int" +.Fn dladdr "void * restrict addr" "Dl_info * restrict dli" +.Ft "int" +.Fn dlctl "void *handle" "int cmd" "void *data" +.Ft "char *" +.Fn dlerror "void" +.Sh DESCRIPTION +These functions provide an interface to the run-time linker +.Xr ld.so 1 . +They allow new shared objects to be loaded into the process' address space +under program control. +.Pp +The +.Fn _dlauxinfo +function returns a pointer to the +.Xr elf 5 +array of +.Vt AuxInfo +structures for the current executable. +.Pp +The +.Fn dlopen +function takes the name of a shared object as the first argument. +The +.Fa path +argument can be specified as either an absolute pathname to a shared object +or just the name of the shared object itself. +When an absolute pathname is specified, +only the path provided will be searched. +When just a shared object name is specified, the same search rules apply that +are used for +.Dq intrinsic +shared object searches +.Po +see +.Xr ld.elf_so 1 +.Pc . +.Pp +Shared libraries take the following form: +.Sm off +.Ic lib\^ Ao Ar name Ac Ic .so Oo Ic \&. Ar xx\^ Oo Ic \&. Ar yy\^ Oc Oc . +.Sm on +.Pp +The shared object is mapped into the address space, relocated, and +its external references are resolved in the same way as is done +with the implicitly loaded shared libraries at program startup. +.Pp +If the first argument is +.Dv NULL , +.Fn dlopen +returns a +.Fa handle +on the global symbol object. +This object +provides access to all symbols from an ordered set of objects consisting +of the original program image and any dependencies loaded during startup. +.Pp +The +.Fa mode +parameter specifies symbol resolution time and symbol visibility. +One of the following values may be used to specify symbol resolution time: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_NOW +Symbols are resolved immediately. +.It Dv RTLD_LAZY +Symbols are resolved when they are first referred to. +This is the default value if resolution time is unspecified. +.El +.Pp +One of the following values may be used to specify symbol visibility: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_GLOBAL +The object's symbols and the symbols of its dependencies will be visible to +other objects. +.It Dv RTLD_LOCAL +The object's symbols and the symbols of its dependencies will not be visible to +other objects. +This is the default value if visibility is unspecified. +.El +.Pp +To specify both resolution time and visibility, bitwise inclusive +.Tn OR +one of each of the above values together. +If an object was opened with +.Dv RTLD_LOCAL +and later opened with +.Dv RTLD_GLOBAL , +then it is promoted to +.Dv RTLD_GLOBAL . +.Pp +Additionally, one of the following flags may be +.Tn OR Ap ed +into the +.Fa mode +argument: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_NODELETE +Prevents unload of the loaded object on +.Fn dlclose . +The same behaviour may be requested by +.Fl z Cm nodelete +option of the static linker +.Xr ld 1 . +.It Dv RTLD_NOLOAD +Only return valid handle for the object if it is already loaded in +the process address space, otherwise do not load the object and return +.Dv NULL . +.El +.Pp +.Fn dlopen +returns a +.Fa handle +to be used in calls to +.Fn dlclose , +.Fn dlsym , +.Fn dlvsym , +and +.Fn dlctl . +If the named shared object has already +been loaded by a previous call to +.Fn dlopen +.Pq and not yet unloaded by Fn dlclose , +a +.Fa handle +referring to the resident copy is returned. +.Pp +.Fn dlclose +unlinks and removes the object referred to by +.Fa handle +from the process address space. +If multiple calls to +.Fn dlopen +have been done on this object, or the object was one loaded at startup time, +or the object is a dependency of another object +then the object is removed when its reference count drops to zero. +.Fn dlclose +returns 0 on success and non-zero on failure. +.Pp +.Fn dlsym +looks for a definition of +.Fa symbol +in the shared object designated by +.Fa handle , +and all shared objects that are listed as dependencies. +The symbol's address is returned. +If the symbol cannot be resolved, +.Dv NULL +is returned. +.Pp +.Fn dlsym +may also be called with special +.Fa handle +values. +.Fn dlsym +respects symbol visibility as specified by the +.Fn dlopen +.Fa mode +parameter. +However, the symbols of an object's dependencies are always visible to it. +All shared objects loaded at program startup are globally visible. +Only the symbols in the main executable that are referenced by a +shared object at link time will be visible unless it has been linked +with the +.Fl Fl export-dynamic +option where all of its symbols will be visible. +The following special +.Fa handle +values may be used with +.Fn dlsym : +.Bl -tag -width ".Dv RTLD_DEFAULT" -offset indent +.It Dv NULL +Interpreted as a reference to the executable or shared object +from which the call is being made. +Thus an object can reference its own symbols and the symbols of its +dependencies without calling +.Fn dlopen . +.It Dv RTLD_DEFAULT +All the visible shared objects and the executable will be searched in the order +they were loaded. +.It Dv RTLD_NEXT +The search for +.Fa symbol +is limited to the visible shared objects which were loaded after the one +issuing the call to +.Fn dlsym . +Thus, if +.Fn dlsym +is called from the main program, all the visible shared libraries are searched. +If it is called from a shared library, all subsequently visible shared +libraries are searched. +.It Dv RTLD_SELF +The search for +.Fa symbol +is limited to the shared object issuing the call to +.Fn dlsym +and those shared objects which were loaded after it that are visible. +.El +.Pp +.Fn dlvsym +does the same as +.Fn dlsym +but takes a +.Fa version +string as an additional argument. +Both the +.Fa symbol +and the +.Fa version +must match in order for the symbol to be resolved. +.Pp +.Fn dladdr +examines all currently mapped shared objects for a symbol whose address \(em +as mapped in the process address space \(em is closest to but not exceeding +the value passed in the first argument +.Fa addr . +The symbols of a shared object are only eligible if +.Fa addr +is between the base address of the shared object and the value of the +symbol +.Va _end +in the same shared object. +If no object for which this condition holds true can be found, +.Fn dladdr +will return 0. +Otherwise, a non-zero value is returned and the +.Fa dli +argument will be used to provide information on the selected symbol +and the shared object it is contained in. +The +.Fa dli +argument points at a caller-provided +.Vt Dl_info +structure defined as follows: +.Bd -literal -offset indent +typedef struct { + const char *dli_fname; /* File defining the symbol */ + void *dli_fbase; /* Base address */ + const char *dli_sname; /* Symbol name */ + const void *dli_saddr; /* Symbol address */ +} Dl_info; +.Ed +.Pp +The structure members are further described as follows: +.Bl -tag -width Fa +.It Fa dli_fname +The pathname of the shared object containing the address +.Fa addr . +.It Fa dli_fbase +The base address at which this shared object is loaded in the process +address space. +This may be zero if the symbol was found in the internally generated +.Dq copy +section +.Po +see +.Xr link 5 +.Pc +which is not associated with a file. +.It Fa dli_sname +points at the nul-terminated name of the selected symbol +.It Fa dli_saddr +is the actual address +.Pq as it appears in the process address space +of the symbol. +.El +.Pp +.Em Note : +both strings pointed at by +.Fa dli_fname +and +.Fa dli_sname +reside in memory private to the run-time linker module and should not +be modified by the caller. +.Pp +In dynamically linked programs, the address of a global function will +point to its program linkage table entry, rather than to the entry +point of the function itself. +This causes most global functions to appear to be defined within the +main executable, rather than in the shared libraries where the actual +code resides. +.Pp +.Fn dlctl +provides an interface similar to +.Xr ioctl 2 +to control several aspects of the run-time linker's operation. +This interface is +.Ud +.Pp +.Fn dlerror +returns a character string representing the most recent error that has +occurred while processing one of the other functions described here. +If no dynamic linking errors have occurred since the last invocation of +.Fn dlerror , +.Fn dlerror +returns +.Dv NULL . +Thus, invoking +.Fn dlerror +a second time, immediately following a prior invocation, will result in +.Dv NULL +being returned. +.Sh ERRORS +.Bl -diag +.It Cannot dlopen non-loadable /usr/lib/libpthread.so.1 +A program tries to +.Fn dlopen +a module that needs +.Lb libpthread +but the program isn't linked against it itself. +.El +.Sh SEE ALSO +.Xr ld 1 , +.Xr rtld 1 , +.Xr dlinfo 3 , +.Xr link 5 +.Sh HISTORY +Some of the +.Nm dl* +functions first appeared in SunOS\~4. |