5d8aec9c02
descriptor. Requested and tested by: des (previous version) Reviewed by: des, kan (previous version) MFC after: 2 weeks
409 lines
11 KiB
Groff
409 lines
11 KiB
Groff
.\" 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 21, 2011
|
|
.Dt DLOPEN 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dlopen ,
|
|
.Nm fdlopen ,
|
|
.Nm dlsym ,
|
|
.Nm dlfunc ,
|
|
.Nm dlerror ,
|
|
.Nm dlclose
|
|
.Nd programmatic interface to the dynamic linker
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In dlfcn.h
|
|
.Ft void *
|
|
.Fn dlopen "const char *path" "int mode"
|
|
.Ft void *
|
|
.Fn fdlopen "int fd" "int mode"
|
|
.Ft void *
|
|
.Fn dlsym "void * restrict handle" "const char * restrict symbol"
|
|
.Ft dlfunc_t
|
|
.Fn dlfunc "void * restrict handle" "const char * restrict symbol"
|
|
.Ft 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
|
|
The
|
|
.Fn dlopen
|
|
function
|
|
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.
|
|
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.
|
|
The
|
|
.Fa mode
|
|
argument
|
|
controls the way in which external function references from the
|
|
loaded object are bound to their referents.
|
|
It must contain one of the following values, possibly ORed with
|
|
additional flags which will be described subsequently:
|
|
.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 .
|
|
.Pp
|
|
One of the following flags may be ORed into the
|
|
.Fa mode
|
|
argument:
|
|
.Bl -tag -width RTLD_NODELETE
|
|
.It Dv RTLD_GLOBAL
|
|
Symbols from this shared object and its directed acyclic graph (DAG)
|
|
of needed objects will be available for resolving undefined references
|
|
from all other shared objects.
|
|
.It Dv RTLD_LOCAL
|
|
Symbols in this shared object and its DAG of needed objects will be
|
|
available for resolving undefined references only from other objects
|
|
in the same DAG.
|
|
This is the default, but it may be specified
|
|
explicitly with this flag.
|
|
.It Dv RTLD_TRACE
|
|
When set, causes dynamic linker to exit after loading all objects
|
|
needed by this shared object and printing a summary which includes
|
|
the absolute pathnames of all objects, to standard output.
|
|
With this flag
|
|
.Fn dlopen
|
|
will return to the caller only in the case of error.
|
|
.It Dv RTLD_NODELETE
|
|
Prevents unload of the loaded object on
|
|
.Fn dlclose .
|
|
The same behaviour may be requested by
|
|
.Fl "z 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
|
|
.Dv NULL
|
|
is returned.
|
|
Other mode flags may be specified, which will be applied for promotion
|
|
for the found object.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Fn dlopen
|
|
fails, it returns a null pointer, and sets an error condition which may
|
|
be interrogated with
|
|
.Fn dlerror .
|
|
.Pp
|
|
The
|
|
.Fn fdlopen
|
|
function is similar to
|
|
.Fn dlopen ,
|
|
but it takes the file descriptor argument
|
|
.Fa fd ,
|
|
which is used for the file operations needed to load an object
|
|
into the address space.
|
|
The file descriptor
|
|
.Fa fd
|
|
is not closed by the function regardless a result of execution,
|
|
but a duplicate of the file descriptor is.
|
|
This may be important if a
|
|
.Xr lockf 3
|
|
lock is held on the passed descriptor.
|
|
The
|
|
.Fa fd
|
|
argument -1 is interpreted as a reference to the main
|
|
executable of the process, similar to
|
|
.Va NULL
|
|
value for the
|
|
.Fa name
|
|
argument to
|
|
.Fn dlopen .
|
|
The
|
|
.Fn fdlopen
|
|
function can be used by the code that needs to perform
|
|
additional checks on the loaded objects, to prevent races with
|
|
symlinking or renames.
|
|
.Pp
|
|
The
|
|
.Fn dlsym
|
|
function
|
|
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 .
|
|
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.
|
|
.Pp
|
|
If
|
|
.Fn dlsym
|
|
is called with the special
|
|
.Fa handle
|
|
.Dv NULL ,
|
|
it is interpreted as a reference to the executable or shared object
|
|
from which the call
|
|
is being made.
|
|
Thus a shared object can reference its own symbols.
|
|
.Pp
|
|
If
|
|
.Fn dlsym
|
|
is called with the special
|
|
.Fa handle
|
|
.Dv RTLD_DEFAULT ,
|
|
the search for the symbol follows the algorithm used for resolving
|
|
undefined symbols when objects are loaded.
|
|
The objects searched are
|
|
as follows, in the given order:
|
|
.Bl -enum
|
|
.It
|
|
The referencing object itself (or the object from which the call to
|
|
.Fn dlsym
|
|
is made), if that object was linked using the
|
|
.Fl Wsymbolic
|
|
option to
|
|
.Xr ld 1 .
|
|
.It
|
|
All objects loaded at program start-up.
|
|
.It
|
|
All objects loaded via
|
|
.Fn dlopen
|
|
with the
|
|
.Dv RTLD_GLOBAL
|
|
flag set in the
|
|
.Fa mode
|
|
argument.
|
|
.It
|
|
All objects loaded via
|
|
.Fn dlopen
|
|
which are in needed-object DAGs that also contain the referencing object.
|
|
.El
|
|
.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\&") .
|
|
(Actually, the
|
|
.Fn dlfunc
|
|
interface, below, should be used, since
|
|
.Fn getpid
|
|
is a function and not a data object.)
|
|
.Pp
|
|
If
|
|
.Fn dlsym
|
|
is called with the special
|
|
.Fa handle
|
|
.Dv RTLD_SELF ,
|
|
then the search for the symbol is limited to the shared object
|
|
issuing the call to
|
|
.Fn dlsym
|
|
and those shared objects which were loaded after it.
|
|
.Pp
|
|
The
|
|
.Fn dlsym
|
|
function
|
|
returns a null pointer if the symbol cannot be found, and sets an error
|
|
condition which may be queried with
|
|
.Fn dlerror .
|
|
.Pp
|
|
The
|
|
.Fn dlfunc
|
|
function
|
|
implements all of the behavior of
|
|
.Fn dlsym ,
|
|
but has a return type which can be cast to a function pointer without
|
|
triggering compiler diagnostics.
|
|
(The
|
|
.Fn dlsym
|
|
function
|
|
returns a data pointer; in the C standard, conversions between
|
|
data and function pointer types are undefined.
|
|
Some compilers and
|
|
.Xr lint 1
|
|
utilities warn about such casts.)
|
|
The precise return type of
|
|
.Fn dlfunc
|
|
is unspecified; applications must cast it to an appropriate function pointer
|
|
type.
|
|
.Pp
|
|
The
|
|
.Fn dlerror
|
|
function
|
|
returns a null-terminated character string describing the last error that
|
|
occurred during a call to
|
|
.Fn dlopen ,
|
|
.Fn dladdr ,
|
|
.Fn dlinfo ,
|
|
.Fn dlsym ,
|
|
.Fn dlfunc ,
|
|
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
|
|
The
|
|
.Fn dlclose
|
|
function
|
|
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.
|
|
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 NOTES
|
|
ELF executables need to be linked
|
|
using the
|
|
.Fl export-dynamic
|
|
option to
|
|
.Xr ld 1
|
|
for symbols defined in the executable to become visible to
|
|
.Fn dlsym .
|
|
.Pp
|
|
In previous implementations, it was necessary to prepend an underscore
|
|
to all external symbols in order to gain symbol
|
|
compatibility with object code compiled from the C language.
|
|
This is
|
|
still the case when using the (obsolete)
|
|
.Fl aout
|
|
option to the C language compiler.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn dlopen ,
|
|
.Fn fdlopen ,
|
|
.Fn dlsym ,
|
|
and
|
|
.Fn dlfunc
|
|
functions
|
|
return a null pointer in the event of errors.
|
|
The
|
|
.Fn dlclose
|
|
function
|
|
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 dladdr 3 ,
|
|
.Xr dlinfo 3 ,
|
|
.Xr link 5
|