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