share/man/man3c/dlsym.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DLSYM 3C "Sep 26, 2005"
   7 .SH NAME
   8 dlsym \- get the address of a symbol in a shared object or executable
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <dlfcn.h>
  13
  14 \fBvoid *\fR\fBdlsym\fR(\fBvoid *restrict\fR \fIhandle\fR, \fBconst char *restrict\fR \fIname\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBdlsym()\fR function allows a process to obtain the address of a symbol
  21 that is defined within a shared object or executable. The \fIhandle\fR argument
  22 is either the value returned from a call to \fBdlopen()\fR or one of a family
  23 of special handles. The \fIname\fR argument is the symbol's name as a character
  24 string.
  25 .sp
  26 .LP
  27 If \fIhandle\fR is returned from \fBdlopen()\fR, the associated shared object
  28 must not have been closed using \fBdlclose()\fR. A \fIhandle\fR can be obtained
  29 from \fBdlopen()\fR using the \fBRTLD_FIRST\fR mode. With this mode, the
  30 \fBdlsym()\fR function searches for the named symbol in the initial object
  31 referenced by \fIhandle\fR. Without this mode, the \fBdlsym()\fR function
  32 searches for the named symbol in the group of shared objects loaded
  33 automatically as a result of loading the object referenced by \fIhandle\fR. See
  34 \fBdlopen\fR(3C) and NOTES.
  35 .sp
  36 .LP
  37 The following special handles are supported.
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fBRTLD_DEFAULT\fR\fR
  42 .ad
  43 .RS 16n
  44 Instructs \fBdlsym()\fR to search for the named symbol starting with the first
  45 object loaded, typically the dynamic executable. The search continues through
  46 the list of initial dependencies that are loaded with the process, followed by
  47 any objects obtained with \fBdlopen\fR(3C). This search follows the default
  48 model that is used to relocate all objects within the process.
  49 .sp
  50 This model also provides for transitioning into a lazy loading environment. If
  51 a symbol can not be found in the presently loaded objects, any pending lazy
  52 loaded objects are processed in an attempt to locate the symbol. This loading
  53 compensates for objects that have not fully defined their dependencies.
  54 However, this compensation can undermine the advantages of lazy loading.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBRTLD_PROBE\fR\fR
  61 .ad
  62 .RS 16n
  63 Instructs \fBdlsym()\fR to search for the named symbol in the same manner as
  64 occurs with a \fIhandle\fR of \fBRTLD_DEFAULT\fR. However, this model only
  65 searches for symbols in the presently loaded objects, together with any lazy
  66 loadable objects specifically identified by the caller to provide the named
  67 symbol. This handle does not trigger an exhaustive load of any lazy loadable
  68 symbols in an attempt to find the named symbol. This handle can provide a more
  69 optimal search than would occur using \fBRTLD_DEFAULT\fR.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBRTLD_NEXT\fR\fR
  76 .ad
  77 .RS 16n
  78 Instructs \fBdlsym()\fR to search for the named symbol in the objects that were
  79 loaded following the object from which the \fBdlsym()\fR call is being made.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBRTLD_SELF\fR\fR
  86 .ad
  87 .RS 16n
  88 Instructs \fBdlsym()\fR to search for the named symbol in the objects that were
  89 loaded starting with the object from which the \fBdlsym()\fR call is being
  90 made.
  91 .RE
  92
  93 .sp
  94 .LP
  95 When used with a special handle, \fBdlsym()\fR is selective in searching
  96 objects that have been loaded using \fBdlopen()\fR. These objects are searched
  97 for symbols if one of the following conditions are true.
  98 .RS +4
  99 .TP
 100 .ie t \(bu
 101 .el o
 102 The object is part of the same local \fBdlopen()\fR dependency hierarchy as the
 103 calling object. See the \fILinker and Libraries Guide\fR for a description of
 104 \fBdlopen()\fR dependency hierarchies.
 105 .RE
 106 .RS +4
 107 .TP
 108 .ie t \(bu
 109 .el o
 110 The object has global search access. See \fBdlopen\fR(3C) for a discussion of
 111 the \fBRTLD_GLOBAL\fR mode.
 112 .RE
 113 .SH RETURN VALUES
 114 .sp
 115 .LP
 116 The \fBdlsym()\fR function returns \fINULL\fR if \fIhandle\fR does not refer to
 117 a valid object opened by \fBdlopen()\fR or is not one of the special handles.
 118 The function also returns \fINULL\fR if the named symbol cannot be found within
 119 any of the objects associated with \fIhandle\fR. Additional diagnostic
 120 information is available through \fBdlerror\fR(3C).
 121 .SH EXAMPLES
 122 .LP
 123 \fBExample 1 \fRUse \fBdlopen()\fR and \fBdlsym()\fR to access a function or
 124 data objects.
 125 .sp
 126 .LP
 127 The following code fragment demonstrates how to use \fBdlopen()\fR and
 128 \fBdlsym()\fR to access either function or data objects. For simplicity, error
 129 checking has been omitted.
 130
 131 .sp
 132 .in +2
 133 .nf
 134 void      *handle;
 135 int       *iptr, (*fptr)(int);
 136
 137 /* open the needed object */
 138 handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);
 139
 140 /* find the address of function and data objects */
 141 fptr = (int (*)(int))dlsym(handle, "my_function");
 142 iptr = (int *)dlsym(handle, "my_object");
 143
 144 /* invoke function, passing value of integer as a parameter */
 145 (*fptr)(*iptr);
 146 .fi
 147 .in -2
 148
 149 .LP
 150 \fBExample 2 \fRUse \fBdlsym()\fR to verify that a particular function is
 151 defined.
 152 .sp
 153 .LP
 154 The following code fragment shows how to use \fBdlsym()\fR to verify that a
 155 function is defined. If the function exists, the function is called.
 156
 157 .sp
 158 .in +2
 159 .nf
 160 int (*fptr)();
 161
 162 if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
 163     "my_function")) != NULL) {
 164         (*fptr)();
 165 }
 166 .fi
 167 .in -2
 168
 169 .SH USAGE
 170 .sp
 171 .LP
 172 The \fBdlsym()\fR function is one of a family of functions that give the user
 173 direct access to the dynamic linking facilities. These facilities are available
 174 to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR.
 175 .SH ATTRIBUTES
 176 .sp
 177 .LP
 178 See \fBattributes\fR(5) for descriptions of the following attributes:
 179 .sp
 180
 181 .sp
 182 .TS
 183 box;
 184 c | c
 185 l | l .
 186 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 187 _
 188 Interface Stability     Standard
 189 _
 190 MT-Level        MT-Safe
 191 .TE
 192
 193 .SH SEE ALSO
 194 .sp
 195 .LP
 196 \fBld\fR(1), \fBld.so.1\fR(1), \fBdladdr\fR(3C), \fBdlclose\fR(3C),
 197 \fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlinfo\fR(3C), \fBdlopen\fR(3C),
 198 \fBattributes\fR(5), \fBstandards\fR(5)
 199 .sp
 200 .LP
 201 \fILinker and Libraries Guide\fR
 202 .SH NOTES
 203 .sp
 204 .LP
 205 If an object is acting as a filter, care should be taken when interpreting the
 206 address of any symbol obtained using a handle to this object. For example,
 207 using dlsym(3C) to obtain the symbol \fI_end\fR for this object, results in
 208 returning the address of the symbol \fI_end\fR within the filtee, not the
 209 filter. For more information on filters see the \fILinker and Libraries
 210 Guide\fR.