Standard C Library Functions                           dladdr(3C)



NAME
     dladdr, dladdr1 - translate address to symbolic information

SYNOPSIS
     #include 

     int dladdr(void *address, Dlinfot *dlip);


     int dladdr1(void *address, Dlinfot *dlip, void **info, int flags);


DESCRIPTION
     The dladdr() and dladdr1() functions determine if the speci-
     fied  address  is  located  within one of the mapped objects
     that make up the  current  applications  address  space.  An
     address  is deemed to fall within a mapped object when it is
     between the base address,  and  the  end  address  of  that
     object.  See  NOTES.  If a mapped object fits this criteria,
     the symbol table made available to  the  runtime  linker  is
     searched  to  locate  the  nearest  symbol  to the specified
     address.  The nearest symbol is one that has  a  value  less
     than or equal to the required address.


     The Dlinfot structure must be preallocated  by  the  user.
     The  structure  members  are filled in by dladdr(), based on
     the specified address. The Dlinfot structure includes  the
     following members:

           const char    *dlifname;
           void          *dlifbase;
           const char    *dlisname;
           void          *dlisaddr;



     The Dlinfot members provide the following information.

     dlifname    Contains a pointer to the filename of the  con-
                  taining object.


     dlifbase    Contains the base  address  of  the  containing
                  object.


     dlisname    Contains a pointer to the symbol name  that  is
                  nearest  to  the specified address. This symbol
                  either represents the exact  address  that  was
                  specified,  or  is  the  nearest  symbol with a
                  lower address.



SunOS 5.11           Last change: 4 Feb 2009                    1






Standard C Library Functions                           dladdr(3C)



     dlisaddr    Contains  the  actual  address  of  the  symbol
                  pointed to by dlisname.



     The dladdr1() function provides for addition information  to
     be returned as specified by the flags argument:

     RTLDLSYMENT     Obtain the ELF symbol table entry for the
                        matched  symbol. The info argument points
                        to  a  symbol  pointer  as   defined   in
                            (Elf32Sym    **info    or
                        Elf64Sym **info). Most of  the  informa-
                        tion  found  in an ELF symbol can only be
                        properly  interpreted  by   the   runtime
                        linker.  However,  there  are  two fields
                        that contain information  useful  to  the
                        caller  of  dladdr1():  The stsize field
                        contains the size of the referenced item.
                        The  stinfo  field  provides symbol type
                        and binding attributes.  See  the  Linker
                        and Libraries Guild for more information.


     RTLDLINKMAP    Obtain the Linkmap for the matched file.
                        The  info  argument  points to a Linkmap
                        pointer  as   defined   in   
                        (Linkmap **info).


RETURN VALUES
     If the specified address  cannot  be  matched  to  a  mapped
     object,  a  0  is  returned. Otherwise, a non-zero return is
     made and the associated Dlinfot elements are filled.

USAGE
     The dladdr() and dladdr1() functions are one of a family  of
     functions  that  give  the user direct access to the dynamic
     linking  facilities.  These  facilities  are  available   to
     dynamically-linked  processes only. See Linker and Libraries
     Guide.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:










SunOS 5.11           Last change: 4 Feb 2009                    2






Standard C Library Functions                           dladdr(3C)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     ld(1),  dlclose(3C),  dldump(3C),  dlerror(3C),  dlopen(3C),
     dlsym(3C), attributes(5)


     Linker and Libraries Guide

NOTES
     The Dlinfot pointer elements point to addresses within the
     mapped objects. These pointers can become invalid if objects
     are removed prior to these elements use. See dlclose(3C).


     If no symbol is found to  describe  the  specified  address,
     both the dlisname and dlisaddr members are set to 0.


     If the address specified exists within a  mapped  object  in
     the  range  between  the base address and the address of the
     first global symbol in the object, the reserved local symbol
     START  is returned. This symbol acts as a label represent-
     ing the start of the mapped object. As a label, this  symbol
     has no size. The dlisaddr member is set to the base address
     of the associated object. The dlisname member is set to the
     symbol  name  START.  If  the  flag  argument  is  set  to
     RTLDLSYMENT, symbol information for START is returned.


     If an object is acting as a filter,  care  should  be  taken
     when interpreting the address of any symbol obtained using a
     handle to this  object.  For  example,  using  dlsym(3C)  to
     obtain the symbol end for this object, results in returning
     the address of the symbol end within the  filtee,  not  the
     filter.  For  more information on filters see the Linker and
     Libraries Guide.













SunOS 5.11           Last change: 4 Feb 2009                    3