lib/libc/gen/dlopen.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 .\" @(#) dlopen.3 1.6 90/01/31 SMI
  33 .\" $FreeBSD: head/lib/libc/gen/dlopen.3 211397 2010-08-16 15:18:30Z joel $
  34 .\"
  35 .Dd April 6, 2012
  36 .Dt DLOPEN 3
  37 .Os
  38 .Sh NAME
  39 .Nm dlopen ,
  40 .Nm fdlopen
  41 .Nd returns handle to dynamically loaded shared object
  42 .Sh LIBRARY
  43 This function is not in a library.
  44 It is included in every dynamically linked program automatically.
  45 .Sh SYNOPSIS
  46 .In dlfcn.h
  47 .Ft void *
  48 .Fn dlopen "const char *name" "int mode"
  49 .Ft void *
  50 .Fn fdlopen "int fd" "int mode"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn dlopen
  54 function
  55 provides access to the shared object in
  56 .Fa name ,
  57 returning a descriptor that can be used for later
  58 references to the object in calls to other dl functions.
  59 If
  60 .Fa name
  61 was not in the address space prior to the call to
  62 .Fn dlopen ,
  63 it is placed in the address space.
  64 When an object is first loaded into the address space in this way, its
  65 function
  66 .Fn _init ,
  67 if any, is called by the dynamic linker.
  68 If
  69 .Fa name
  70 has already been placed in the address space in a previous call to
  71 .Fn dlopen ,
  72 it is not added a second time, although a reference count of
  73 .Fn dlopen
  74 operations on
  75 .Fa name
  76 is maintained.
  77 A null pointer supplied for
  78 .Fa name
  79 is interpreted as a reference to the main
  80 executable of the process.
  81 The
  82 .Fa mode
  83 argument
  84 controls the way in which external function references from the
  85 loaded object are bound to their referents.
  86 It must contain one of the following values, possibly ORed with
  87 additional flags which will be described subsequently:
  88 .Bl -tag -width RTLD_LAZYX
  89 .It Dv RTLD_LAZY
  90 Each external function reference is resolved when the function is first
  91 called.
  92 .It Dv RTLD_NOW
  93 All external function references are bound immediately by
  94 .Fn dlopen .
  95 .El
  96 .Pp
  97 .Dv RTLD_LAZY
  98 is normally preferred, for reasons of efficiency.
  99 However,
 100 .Dv RTLD_NOW
 101 is useful to ensure that any undefined symbols are discovered during the
 102 call to
 103 .Fn dlopen .
 104 .Pp
 105 One of the following flags may be ORed into the
 106 .Fa mode
 107 argument:
 108 .Bl -tag -width RTLD_NODELETE
 109 .It Dv RTLD_GLOBAL
 110 Symbols from this shared object and its directed acyclic graph (DAG)
 111 of needed objects will be available for resolving undefined references
 112 from all other shared objects.
 113 .It Dv RTLD_LOCAL
 114 Symbols in this shared object and its DAG of needed objects will be
 115 available for resolving undefined references only from other objects
 116 in the same DAG.
 117 This is the default, but it may be specified
 118 explicitly with this flag.
 119 .It Dv RTLD_TRACE
 120 When set, causes dynamic linker to exit after loading all objects
 121 needed by this shared object and printing a summary which includes
 122 the absolute pathnames of all objects, to standard output.
 123 With this flag
 124 .Fn dlopen
 125 will return to the caller only in the case of error.
 126 .It Dv RTLD_NODELETE
 127 Prevents unload of the loaded object on
 128 .Fn dlclose .
 129 The same behaviour may be requested by
 130 .Fl "z nodelete"
 131 option of the static linker
 132 .Xr ld 1 .
 133 .It Dv RTLD_NOLOAD
 134 Only return valid handle for the object if it is already loaded in
 135 the process address space, otherwise
 136 .Dv NULL
 137 is returned.
 138 Other mode flags may be specified, which will be applied for promotion
 139 for the found object.
 140 .El
 141 .Pp
 142 If
 143 .Fn dlopen
 144 fails, it returns a null pointer, and sets an error condition which may
 145 be interrogated with
 146 .Fn dlerror .
 147 .Pp
 148 The
 149 .Fn fdlopen
 150 function is similar to
 151 .Fn dlopen ,
 152 but it takes the file descriptor argument
 153 .Fa fd ,
 154 which is used for the file operations needed to load an object
 155 into the address space.
 156 The file descriptor
 157 .Fa fd
 158 is not closed by the function regardless a result of execution,
 159 but a duplicate of the file descriptor is.
 160 This may be important if a
 161 .Xr lockf 3
 162 lock is held on the passed descriptor.
 163 The
 164 .Fa fd
 165 argument -1 is interpreted as a reference to the main
 166 executable of the process, similar to
 167 .Va NULL
 168 value for the
 169 .Fa name
 170 argument to
 171 .Fn dlopen .
 172 The
 173 .Fn fdlopen
 174 function can be used by the code that needs to perform
 175 additional checks on the loaded objects, to prevent races with
 176 symlinking or renames.
 177 .Sh RETURN VALUE
 178 The functions return a null pointer in the event of an error.
 179 Whenever an error has been detected, a message detailing it can be
 180 retrieved via a call to
 181 .Fn dlerror .
 182 .Sh EXAMPLE
 183 The following program will open any shared gcc library found
 184 and display the directory in which it was found using the
 185 dfinfo function.
 186 .Bd -literal
 187 #include <dlfcn.h>
 188 #include <stdlib.h>
 189 #include <stdio.h>
 190
 191 int
 192 main (int argc, char *argv[])
 193 {
 194     void *handle;
 195     int   result;
 196     char origin[256];
 197
 198     /* open shared gcc library  */
 199     handle = dlopen("libgcc_s.so", RTLD_LAZY);
 200     if (!handle) {
 201        fprintf (stderr, "%s\en", dlerror ());
 202        exit (EXIT_FAILURE);
 203     }
 204
 205     /* get information about the library origin */
 206     result = dlinfo (handle, RTLD_DI_ORIGIN, (void *)&origin);
 207     if (result < 0) {
 208        fprintf (stderr, "%s\en", dlerror ());
 209        dlclose (handle);
 210        exit (EXIT_FAILURE);
 211     }
 212
 213     /* Display the origin */
 214     printf ("libgcc_s origin is %s\en", &origin[0]);
 215     dlclose (handle);
 216
 217     exit(EXIT_SUCCESS);
 218 }
 219 .Ed
 220 .Sh SEE ALSO
 221 .Xr rtld 1 ,
 222 .Xr dlclose 3 ,
 223 .Xr dlerror 3 ,
 224 .Xr dlfcn 3 ,
 225 .Xr dlinfo 3