DLSYM(3)                   POSIX Programmer's Manual                  DLSYM(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       dlsym -- get the address of a symbol from a symbol table handle

SSYYNNOOPPSSIISS
       #include <dlfcn.h>

       void *dlsym(void *restrict _h_a_n_d_l_e, const char *restrict _n_a_m_e);

DDEESSCCRRIIPPTTIIOONN
       The _d_l_s_y_m() function shall obtain the address of a symbol (a function
       identifier or a data object identifier) defined in the symbol table
       identified by the _h_a_n_d_l_e argument. The _h_a_n_d_l_e argument is a symbol
       table handle returned from a call to _d_l_o_p_e_n() (and which has not since
       been released by a call to _d_l_c_l_o_s_e()), and _n_a_m_e is the symbol's name as
       a character string. The return value from _d_l_s_y_m(), 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.

       The _d_l_s_y_m() function shall search for the named symbol in the symbol
       table referenced by _h_a_n_d_l_e.  If the symbol table was created with lazy
       loading (see RTLD_LAZY in _d_l_o_p_e_n()), load ordering shall be used in
       _d_l_s_y_m() operations to relocate executable object files needed to
       resolve the symbol. The symbol resolution algorithm used shall be
       dependency order as described in _d_l_o_p_e_n().

       The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined
       in _<_d_l_f_c_n_._h_>) are reserved for future use as special values that
       applications may be allowed to use for _h_a_n_d_l_e.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, if _n_a_m_e names a function identifier,
       _d_l_s_y_m() shall return the address of the function converted from type
       pointer to function to type pointer to vvooiidd; otherwise, _d_l_s_y_m() shall
       return the address of the data object associated with the data object
       identifier named by _n_a_m_e converted from a pointer to the type of the
       data object to a pointer to vvooiidd.  If _h_a_n_d_l_e does not refer to a valid
       symbol table handle or if the symbol named by _n_a_m_e cannot be found in
       the symbol table associated with _h_a_n_d_l_e, _d_l_s_y_m() shall return a null
       pointer.

       More detailed diagnostic information shall be available through
       _d_l_e_r_r_o_r().

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The following example shows how _d_l_o_p_e_n() and _d_l_s_y_m() can be used to
       access either a function or a data object. For simplicity, error
       checking has been omitted.

           vvooiidd **hhaannddllee;;
           iinntt ((**ffppttrr))((iinntt)),, **iippttrr,, rreessuulltt;;
           //** ooppeenn tthhee nneeeeddeedd ssyymmbbooll ttaabbllee **//
           hhaannddllee == ddllooppeenn((""//uussrr//hhoommee//mmee//lliibbffoooo..ssoo"",, RRTTLLDD__LLOOCCAALL || RRTTLLDD__LLAAZZYY));;
           //** ffiinndd tthhee aaddddrreessss ooff tthhee ffuunnccttiioonn mmyy__ffuunnccttiioonn **//
           ffppttrr == ((iinntt ((**))((iinntt))))ddllssyymm((hhaannddllee,, ""mmyy__ffuunnccttiioonn""));;
           //** ffiinndd tthhee aaddddrreessss ooff tthhee ddaattaa oobbjjeecctt mmyy__oobbjjeecctt **//
           iippttrr == ((iinntt **))ddllssyymm((hhaannddllee,, ""mmyy__OOBBJJ""));;
           //** iinnvvookkee mmyy__ffuunnccttiioonn,, ppaassssiinngg tthhee vvaalluuee ooff mmyy__OOBBJJ aass tthhee ppaarraammeetteerr **//
           rreessuulltt == ((**ffppttrr))((**iippttrr));;

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The following special purpose values for _h_a_n_d_l_e are reserved for future
       use and have the indicated meanings:

       RTLD_DEFAULT
                   The identifier lookup happens in the normal global scope;
                   that is, a search for an identifier using _h_a_n_d_l_e would find
                   the same definition as a direct use of this identifier in
                   the program code.

       RTLD_NEXT   Specifies the next executable object file after this one
                   that defines _n_a_m_e.  This one refers to the executable
                   object file containing the invocation of _d_l_s_y_m().  The next
                   executable object file is the one found upon the
                   application of a load order symbol resolution algorithm
                   (see _d_l_o_p_e_n()).  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 _d_l_o_p_e_n()
                   operation including the RTLD_GLOBAL flag), or is in an
                   executable object file that was included in the same
                   _d_l_o_p_e_n() operation that loaded this one.

       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
       _m_a_l_l_o_c() that embedded some statistics gathering about memory
       allocations, such an implementation could use the real _m_a_l_l_o_c()
       definition to perform the memory allocation -- and itself only embed
       the necessary logic to implement the statistics gathering function.

       Note that conversion from a vvooiidd ** pointer to a function pointer as in:

           ffppttrr == ((iinntt ((**))((iinntt))))ddllssyymm((hhaannddllee,, ""mmyy__ffuunnccttiioonn""));;

       is not defined by the ISO C standard. This standard requires this
       conversion to work correctly on conforming implementations.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _d_l_c_l_o_s_e(), _d_l_e_r_r_o_r(), _d_l_o_p_e_n()

       The Base Definitions volume of POSIX.1-2008, <<ddllffccnn..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .



IEEE/The Open Group                  2013                             DLSYM(3)
