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