lib/libc/gen/dlsym.3

   1 .\" This source code is a product of Sun Microsystems, Inc. and is provided
   2 .\" for unrestricted use provided that this legend is included on all tape
   3 .\" media and as a part of the software program in whole or part.  Users
   4 .\" may copy or modify this source code without charge, but are not authorized
   5 .\" to license or distribute it to anyone else except as part of a product or
   6 .\" program developed by the user.
   7 .\"
   8 .\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
   9 .\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
  10 .\" OF SUCH SOURCE CODE FOR ANY PURPOSE.  IT IS PROVIDED "AS IS" WITHOUT
  11 .\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND.  SUN MICROSYSTEMS, INC. DISCLAIMS
  12 .\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
  13 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN
  14 .\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
  15 .\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  16 .\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
  17 .\"
  18 .\" This source code is provided with no support and without any obligation on
  19 .\" the part of Sun Microsystems, Inc. to assist in its use, correction,
  20 .\" modification or enhancement.
  21 .\"
  22 .\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  23 .\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
  24 .\" SOURCE CODE OR ANY PART THEREOF.
  25 .\"
  26 .\" Sun Microsystems, Inc.
  27 .\" 2550 Garcia Avenue
  28 .\" Mountain View, California 94043
  29 .\"
  30 .\" Copyright (c) 1991 Sun Microsystems, Inc.
  31 .\"
  32 .\" $FreeBSD: release/8.1.0/lib/libc/gen/dlopen.3 205979 2010-03-31 13:51:31Z gahr $
  33 .\"
  34 .Dd April 28, 2011
  35 .Dt DLSYM 3
  36 .Os
  37 .Sh NAME
  38 .Nm dlsym ,
  39 .Nm dlfunc
  40 .Nd shared object symbol lookup function
  41 .Sh LIBRARY
  42 This function is not in a library.
  43 It is included in every dynamically linked program automatically.
  44 .Sh SYNOPSIS
  45 .In dlfcn.h
  46 .Ft void *
  47 .Fn dlsym "void *handle" "const char *name"
  48 .Ft dlfunc_t
  49 .Fn dlfunc "void *handle" "const char *name"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn dlsym
  53 function
  54 returns the address binding of the symbol described in the null-terminated
  55 character string
  56 .Fa symbol ,
  57 as it occurs in the shared object identified by
  58 .Fa handle .
  59 The symbols exported by objects added to the address space by
  60 .Fn dlopen
  61 can be accessed only through calls to
  62 .Fn dlsym .
  63 Such symbols do not supersede any definition of those symbols already present
  64 in the address space when the object is loaded, nor are they available to
  65 satisfy normal dynamic linking references.
  66 .Pp
  67 If
  68 .Fn dlsym
  69 is called with the special
  70 .Fa handle
  71 .Dv NULL ,
  72 it is interpreted as a reference to the executable or shared object
  73 from which the call
  74 is being made.
  75 Thus a shared object can reference its own symbols.
  76 .Pp
  77 If
  78 .Fn dlsym
  79 is called with the special
  80 .Fa handle
  81 .Dv RTLD_DEFAULT ,
  82 the search for the symbol follows the algorithm used for resolving
  83 undefined symbols when objects are loaded.
  84 The objects searched are
  85 as follows, in the given order:
  86 .Bl -enum
  87 .It
  88 The referencing object itself (or the object from which the call to
  89 .Fn dlsym
  90 is made), if that object was linked using the
  91 .Fl Wsymbolic
  92 option to
  93 .Xr ld 1 .
  94 .It
  95 All objects loaded at program start-up.
  96 .It
  97 All objects loaded via
  98 .Fn dlopen
  99 with the
 100 .Dv RTLD_GLOBAL
 101 flag set in the
 102 .Fa mode
 103 argument.
 104 .It
 105 All objects loaded via
 106 .Fn dlopen
 107 which are in needed-object DAGs that also contain the referencing object.
 108 .El
 109 .Pp
 110 If
 111 .Fn dlsym
 112 is called with the special
 113 .Fa handle
 114 .Dv RTLD_NEXT ,
 115 then the search for the symbol is limited to the shared objects
 116 which were loaded after the one issuing the call to
 117 .Fn dlsym .
 118 Thus, if the function is called from the main program, all
 119 the shared libraries are searched.
 120 If it is called from a shared library, all subsequent shared
 121 libraries are searched.
 122 .Dv RTLD_NEXT
 123 is useful for implementing wrappers around library functions.
 124 For example, a wrapper function
 125 .Fn getpid
 126 could access the
 127 .Dq real
 128 .Fn getpid
 129 with
 130 .Li dlsym(RTLD_NEXT, \&"getpid\&") .
 131 (Actually, the
 132 .Fn dlfunc
 133 interface, below, should be used, since
 134 .Fn getpid
 135 is a function and not a data object.)
 136 .Pp
 137 If
 138 .Fn dlsym
 139 is called with the special
 140 .Fa handle
 141 .Dv RTLD_SELF ,
 142 then the search for the symbol is limited to the shared object
 143 issuing the call to
 144 .Fn dlsym
 145 and those shared objects which were loaded after it.
 146 .Pp
 147 The
 148 .Fn dlfunc
 149 function
 150 implements all of the behavior of
 151 .Fn dlsym ,
 152 but has a return type which can be cast to a function pointer without
 153 triggering compiler diagnostics.
 154 (The
 155 .Fn dlsym
 156 function
 157 returns a data pointer; in the C standard, conversions between
 158 data and function pointer types are undefined.
 159 Some compilers and code checkers warn about such casts.)
 160 The precise return type of
 161 .Fn dlfunc
 162 is unspecified; applications must cast it to an appropriate function pointer
 163 type.
 164 .Sh NOTES
 165 ELF executables need to be linked
 166 using the
 167 .Fl export-dynamic
 168 option to
 169 .Xr ld 1
 170 for symbols defined in the executable to become visible to
 171 .Fn dlsym .
 172 .Sh RETURN VALUE
 173 The
 174 .Fn dlsym
 175 and
 176 .Fn dlfunc
 177 functions
 178 return the address of the symbol unless the symbol can not be found.
 179 In this case, they return a null pointer and set an error condition
 180 which may be queried with
 181 .Fn dlerror .
 182 .Sh EXAMPLE
 183 The following program will obtain a pointer to the cosine function using
 184 dlsym, and then it will use it to print out the value of cosine (2.0).
 185 .Bd -literal
 186 #include <dlfcn.h>
 187 #include <stdlib.h>
 188 #include <stdio.h>
 189
 190 int
 191 main (int argc, char *argv[])
 192 {
 193     void       *handle;
 194     double     (*func_cosine)(double x);
 195
 196     /* open the system shared math library */
 197     handle = dlopen("libm.so", RTLD_LAZY);
 198     if (!handle) {
 199        fprintf (stderr, "%s\en", dlerror ());
 200        exit (EXIT_FAILURE);
 201     }
 202
 203     /* get pointer to cosine function */
 204     func_cosine = dlsym (handle, "cos");
 205     if (func_cosine == NULL) {
 206        fprintf (stderr, "%s function not found\en", "cos");
 207        dlclose (handle);
 208        exit (EXIT_FAILURE);
 209     }
 210
 211     /* Calculate and display the cosine of 2.0 */
 212     printf ("cosine of 2.0 = %f\en", func_cosine(2.0));
 213     dlclose (handle);
 214
 215     exit(EXIT_SUCCESS);
 216 }
 217 .Ed
 218 .Sh SEE ALSO
 219 .Xr rtld 1 ,
 220 .Xr dlfcn 3 ,
 221 .Xr dlopen 3 ,
 222 .Xr dlvsym 3