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 43This function is not in a library. 44It 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 52The 53.Fn dlopen 54function 55provides access to the shared object in 56.Fa name , 57returning a descriptor that can be used for later 58references to the object in calls to other dl functions. 59If 60.Fa name 61was not in the address space prior to the call to 62.Fn dlopen , 63it is placed in the address space. 64When an object is first loaded into the address space in this way, its 65function 66.Fn _init , 67if any, is called by the dynamic linker. 68If 69.Fa name 70has already been placed in the address space in a previous call to 71.Fn dlopen , 72it is not added a second time, although a reference count of 73.Fn dlopen 74operations on 75.Fa name 76is maintained. 77A null pointer supplied for 78.Fa name 79is interpreted as a reference to the main 80executable of the process. 81The 82.Fa mode 83argument 84controls the way in which external function references from the 85loaded object are bound to their referents. 86It must contain one of the following values, possibly ORed with 87additional flags which will be described subsequently: 88.Bl -tag -width ".Dv RTLD_NODELETE" 89.It Dv RTLD_LAZY 90Each external function reference is resolved when the function is first 91called. 92.It Dv RTLD_NOW 93All external function references are bound immediately by 94.Fn dlopen . 95.El 96.Pp 97.Dv RTLD_LAZY 98is normally preferred, for reasons of efficiency. 99However, 100.Dv RTLD_NOW 101is useful to ensure that any undefined symbols are discovered during the 102call to 103.Fn dlopen . 104.Pp 105One of the following flags may be ORed into the 106.Fa mode 107argument: 108.Bl -tag -width ".Dv RTLD_NODELETE" 109.It Dv RTLD_GLOBAL 110Symbols from this shared object and its directed acyclic graph (DAG) 111of needed objects will be available for resolving undefined references 112from all other shared objects. 113.It Dv RTLD_LOCAL 114Symbols in this shared object and its DAG of needed objects will be 115available for resolving undefined references only from other objects 116in the same DAG. 117This is the default, but it may be specified 118explicitly with this flag. 119.It Dv RTLD_TRACE 120When set, causes dynamic linker to exit after loading all objects 121needed by this shared object and printing a summary which includes 122the absolute pathnames of all objects, to standard output. 123With this flag 124.Fn dlopen 125will return to the caller only in the case of error. 126.It Dv RTLD_NODELETE 127Prevents unload of the loaded object on 128.Fn dlclose . 129The same behaviour may be requested by 130.Fl "z nodelete" 131option of the static linker 132.Xr ld 1 . 133.It Dv RTLD_NOLOAD 134Only return valid handle for the object if it is already loaded in 135the process address space, otherwise 136.Dv NULL 137is returned. 138Other mode flags may be specified, which will be applied for promotion 139for the found object. 140.El 141.Pp 142If 143.Fn dlopen 144fails, it returns a null pointer, and sets an error condition which may 145be interrogated with 146.Fn dlerror . 147.Pp 148The 149.Fn fdlopen 150function is similar to 151.Fn dlopen , 152but it takes the file descriptor argument 153.Fa fd , 154which is used for the file operations needed to load an object 155into the address space. 156The file descriptor 157.Fa fd 158is not closed by the function regardless a result of execution, 159but a duplicate of the file descriptor is. 160This may be important if a 161.Xr lockf 3 162lock is held on the passed descriptor. 163The 164.Fa fd 165argument -1 is interpreted as a reference to the main 166executable of the process, similar to 167.Va NULL 168value for the 169.Fa name 170argument to 171.Fn dlopen . 172The 173.Fn fdlopen 174function can be used by the code that needs to perform 175additional checks on the loaded objects, to prevent races with 176symlinking or renames. 177.Sh RETURN VALUES 178The functions return a null pointer in the event of an error. 179Whenever an error has been detected, a message detailing it can be 180retrieved via a call to 181.Fn dlerror . 182.Sh EXAMPLES 183The following program will open any shared gcc library found 184and display the directory in which it was found using the 185dfinfo function. 186.Bd -literal 187#include <dlfcn.h> 188#include <stdlib.h> 189#include <stdio.h> 190 191int 192main (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 226