usr/src/man/man3c/dladdr.3c

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DLADDR 3C "Feb 4, 2009"
   8 .SH NAME
   9 dladdr, dladdr1 \- translate address to symbolic information
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <dlfcn.h>
  14
  15 \fBint\fR \fBdladdr\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBdladdr1\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR, \fBvoid **\fR\fIinfo\fR, \fBint\fR \fIflags\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBdladdr()\fR and \fBdladdr1()\fR functions determine if the specified
  27 \fIaddress\fR is located within one of the mapped objects that make up the
  28 current applications address space. An address is deemed to fall within a
  29 mapped object when it is between the base address, and the \fI_end\fR address
  30 of that object. See NOTES. If a mapped object fits this criteria, the symbol
  31 table made available to the runtime linker is searched to locate the nearest
  32 symbol to the specified address.  The nearest symbol is one that has a value
  33 less than or equal to the required address.
  34 .sp
  35 .LP
  36 The \fBDl_info_t\fR structure must be preallocated by the user. The structure
  37 members are filled in by \fBdladdr()\fR, based on the specified \fIaddress\fR.
  38 The \fBDl_info_t\fR structure includes the following members:
  39 .sp
  40 .in +2
  41 .nf
  42     const char    *dli_fname;
  43     void          *dli_fbase;
  44     const char    *dli_sname;
  45     void          *dli_saddr;
  46 .fi
  47 .in -2
  48
  49 .sp
  50 .LP
  51 The \fBDl_info_t\fR members provide the following information.
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fBdli_fname\fR\fR
  56 .ad
  57 .RS 13n
  58 Contains a pointer to the filename of the containing object.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBdli_fbase\fR\fR
  65 .ad
  66 .RS 13n
  67 Contains the base address of the containing object.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBdli_sname\fR\fR
  74 .ad
  75 .RS 13n
  76 Contains a pointer to the symbol name that is nearest to the specified address.
  77 This symbol either represents the exact address that was specified, or is the
  78 nearest symbol with a lower address.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBdli_saddr\fR\fR
  85 .ad
  86 .RS 13n
  87 Contains the actual address of the symbol pointed to by \fBdli_sname\fR.
  88 .RE
  89
  90 .sp
  91 .LP
  92 The \fBdladdr1()\fR function provides for addition information to be returned
  93 as specified by the \fIflags\fR argument:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBRTLD_DL_SYMENT\fR\fR
  98 .ad
  99 .RS 19n
 100 Obtain the \fBELF\fR symbol table entry for the matched symbol. The \fIinfo\fR
 101 argument points to a symbol pointer as defined in <\fBsys/elf.h\fR>
 102 (\fBElf32_Sym **\fR\fIinfo\fR or \fBElf64_Sym **\fR\fIinfo\fR). Most of the
 103 information found in an ELF symbol can only be properly interpreted by the
 104 runtime linker. However, there are two fields that contain information useful
 105 to the caller of \fBdladdr1()\fR: The \fBst_size\fR field contains the size of
 106 the referenced item. The \fBst_info\fR field provides symbol type and binding
 107 attributes. See the \fILinker and Libraries Guild\fR for more information.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBRTLD_DL_LINKMAP\fR\fR
 114 .ad
 115 .RS 19n
 116 Obtain the \fBLink_map\fR for the matched file. The \fIinfo\fR argument points
 117 to a \fBLink_map\fR pointer as defined in <\fBsys/link.h\fR> (\fBLink_map
 118 **\fR\fIinfo\fR).
 119 .RE
 120
 121 .SH RETURN VALUES
 122 .sp
 123 .LP
 124 If the specified \fIaddress\fR cannot be matched to a mapped object, a \fB0\fR
 125 is returned. Otherwise, a non-zero return is made and the associated
 126 \fBDl_info_t\fR elements are filled.
 127 .SH USAGE
 128 .sp
 129 .LP
 130 The \fBdladdr()\fR and \fBdladdr1()\fR functions are one of a family of
 131 functions that give the user direct access to the dynamic linking facilities.
 132 These facilities are available to dynamically-linked processes only. See
 133 \fILinker and Libraries Guide\fR.
 134 .SH ATTRIBUTES
 135 .sp
 136 .LP
 137 See \fBattributes\fR(5) for descriptions of the following attributes:
 138 .sp
 139
 140 .sp
 141 .TS
 142 box;
 143 c | c
 144 l | l .
 145 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 146 _
 147 MT-Level        MT-Safe
 148 .TE
 149
 150 .SH SEE ALSO
 151 .sp
 152 .LP
 153 \fBld\fR(1), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C),
 154 \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBattributes\fR(5)
 155 .sp
 156 .LP
 157 \fILinker and Libraries Guide\fR
 158 .SH NOTES
 159 .sp
 160 .LP
 161 The \fBDl_info_t\fR pointer elements point to addresses within the mapped
 162 objects. These pointers can become invalid if objects are removed prior to
 163 these elements use. See \fBdlclose\fR(3C).
 164 .sp
 165 .LP
 166 If no symbol is found to describe the specified address, both the
 167 \fBdli_sname\fR and \fBdli_saddr\fR members are set to \fB0\fR.
 168 .sp
 169 .LP
 170 If the address specified exists within a mapped object in the range between the
 171 base address and the address of the first global symbol in the object, the
 172 reserved local symbol \fB_START_\fR is returned. This symbol acts as a label
 173 representing the start of the mapped object. As a label, this symbol has no
 174 size. The \fBdli_saddr\fR member is set to the base address of the associated
 175 object. The \fBdli_sname\fR member is set to the symbol name \fB_START_\fR. If
 176 the flag argument is set to \fBRTLD_DL_SYMENT\fR, symbol information for
 177 \fB_START_\fR is returned.
 178 .sp
 179 .LP
 180 If an object is acting as a filter, care should be taken when interpreting the
 181 address of any symbol obtained using a handle to this object. For example,
 182 using \fBdlsym\fR(3C) to obtain the symbol \fI_end\fR for this object, results
 183 in returning the address of the symbol \fI_end\fR within the filtee, not the
 184 filter. For more information on filters see the \fILinker and Libraries
 185 Guide\fR.