dlsym.3p (6072B)
- '\" et
- .TH DLSYM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- dlsym
- \(em get the address of a symbol from a symbol table handle
- .SH SYNOPSIS
- .LP
- .nf
- #include <dlfcn.h>
- .P
- void *dlsym(void *restrict \fIhandle\fP, const char *restrict \fIname\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIdlsym\fR()
- function shall obtain the address of a symbol (a function identifier or
- a data object identifier) defined in the symbol table identified by the
- .IR handle
- argument. The
- .IR handle
- argument is a symbol table handle returned from a call to
- \fIdlopen\fR()
- (and which has not since been released by a call to
- \fIdlclose\fR()),
- and
- .IR name
- is the symbol's name as a character string. The return value from
- \fIdlsym\fR(),
- cast to a pointer to the type of the named symbol, can be used to call
- (in the case of a function) or access the contents of (in the case of
- a data object) the named symbol.
- .P
- The
- \fIdlsym\fR()
- function shall search for the named symbol in the symbol table
- referenced by
- .IR handle .
- If the symbol table was created with lazy loading
- (see RTLD_LAZY in
- \fIdlopen\fR()),
- load ordering shall be used in
- \fIdlsym\fR()
- operations to relocate executable object files needed to resolve the
- symbol. The symbol resolution algorithm used shall be dependency order
- as described in
- \fIdlopen\fR().
- .P
- The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined in
- .IR <dlfcn.h> )
- are reserved for future use as special values that applications may be
- allowed to use for
- .IR handle .
- .SH "RETURN VALUE"
- Upon successful completion, if
- .IR name
- names a function identifier,
- \fIdlsym\fR()
- shall return the address of the function converted from type pointer to
- function to type pointer to
- .BR void ;
- otherwise,
- \fIdlsym\fR()
- shall return the address of the data object associated with the data
- object identifier named by
- .IR name
- converted from a pointer to the type of the data object to a pointer to
- .BR void .
- If
- .IR handle
- does not refer to a valid symbol table handle or if the symbol named by
- .IR name
- cannot be found in the symbol table associated with
- .IR handle ,
- \fIdlsym\fR()
- shall return a null pointer.
- .P
- More detailed diagnostic information shall be available through
- \fIdlerror\fR().
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH "EXAMPLES"
- The following example shows how
- \fIdlopen\fR()
- and
- \fIdlsym\fR()
- can be used to access either a function or a data object. For simplicity,
- error checking has been omitted.
- .sp
- .RS 4
- .nf
- void *handle;
- int (*fptr)(int), *iptr, result;
- /* open the needed symbol table */
- handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY);
- /* find the address of the function my_function */
- fptr = (int (*)(int))dlsym(handle, "my_function");
- /* find the address of the data object my_object */
- iptr = (int *)dlsym(handle, "my_OBJ");
- /* invoke my_function, passing the value of my_OBJ as the parameter */
- result = (*fptr)(*iptr);
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The following special purpose values for
- .IR handle
- are reserved for future use and have the indicated meanings:
- .IP RTLD_DEFAULT 12
- The identifier lookup happens in the normal global scope; that is,
- a search for an identifier using
- .IR handle
- would find the same definition as a direct use of this identifier in
- the program code.
- .IP RTLD_NEXT 12
- Specifies the next executable object file after this one that defines
- .IR name .
- This one refers to the executable object file containing the invocation of
- \fIdlsym\fR().
- The next executable object file is the one found upon the application
- of a load order symbol resolution algorithm (see
- \fIdlopen\fR()).
- The next symbol is either one of global scope (because it was introduced
- as part of the original process image or because it was added with a
- \fIdlopen\fR()
- operation including the RTLD_GLOBAL flag), or is in an executable object
- file that was included in the same
- \fIdlopen\fR()
- operation that loaded this one.
- .P
- The RTLD_NEXT flag is useful to navigate an intentionally created
- hierarchy of multiply-defined symbols created through interposition. For
- example, if a program wished to create an implementation of
- \fImalloc\fR()
- that embedded some statistics gathering about memory allocations, such
- an implementation could use the real
- \fImalloc\fR()
- definition to perform the memory allocation \(em and itself only embed
- the necessary logic to implement the statistics gathering function.
- .P
- Note that conversion from a
- .BR "void *"
- pointer to a function pointer as in:
- .sp
- .RS 4
- .nf
- fptr = (int (*)(int))dlsym(handle, "my_function");
- .fi
- .P
- .RE
- .P
- is not defined by the ISO\ C standard. This standard requires this conversion to
- work correctly on conforming implementations.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIdlclose\fR\^(\|)",
- .IR "\fIdlerror\fR\^(\|)",
- .IR "\fIdlopen\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<dlfcn.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .