xref: /dragonfly/lib/libc/gen/dlsym.3 (revision 650094e1) 
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
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 dlsym "void *handle" "const char *name"
48.Ft dlfunc_t
49.Fn dlfunc "void *handle" "const char *name"
50.Sh DESCRIPTION
51The
52.Fn dlsym
53function
54returns the address binding of the symbol described in the null-terminated
55character string
56.Fa symbol ,
57as it occurs in the shared object identified by
58.Fa handle .
59The symbols exported by objects added to the address space by
60.Fn dlopen
61can be accessed only through calls to
62.Fn dlsym .
63Such symbols do not supersede any definition of those symbols already present
64in the address space when the object is loaded, nor are they available to
65satisfy normal dynamic linking references.
66.Pp
67If
68.Fn dlsym
69is called with the special
70.Fa handle
71.Dv NULL ,
72it is interpreted as a reference to the executable or shared object
73from which the call
74is being made.
75Thus a shared object can reference its own symbols.
76.Pp
77If
78.Fn dlsym
79is called with the special
80.Fa handle
81.Dv RTLD_DEFAULT ,
82the search for the symbol follows the algorithm used for resolving
83undefined symbols when objects are loaded.
84The objects searched are
85as follows, in the given order:
86.Bl -enum
87.It
88The referencing object itself (or the object from which the call to
89.Fn dlsym
90is made), if that object was linked using the
91.Fl Wsymbolic
92option to
93.Xr ld 1 .
94.It
95All objects loaded at program start-up.
96.It
97All objects loaded via
98.Fn dlopen
99with the
100.Dv RTLD_GLOBAL
101flag set in the
102.Fa mode
103argument.
104.It
105All objects loaded via
106.Fn dlopen
107which are in needed-object DAGs that also contain the referencing object.
108.El
109.Pp
110If
111.Fn dlsym
112is called with the special
113.Fa handle
114.Dv RTLD_NEXT ,
115then the search for the symbol is limited to the shared objects
116which were loaded after the one issuing the call to
117.Fn dlsym .
118Thus, if the function is called from the main program, all
119the shared libraries are searched.
120If it is called from a shared library, all subsequent shared
121libraries are searched.
122.Dv RTLD_NEXT
123is useful for implementing wrappers around library functions.
124For example, a wrapper function
125.Fn getpid
126could access the
127.Dq real
128.Fn getpid
129with
130.Li dlsym(RTLD_NEXT, \&"getpid\&") .
131(Actually, the
132.Fn dlfunc
133interface, below, should be used, since
134.Fn getpid
135is a function and not a data object.)
136.Pp
137If
138.Fn dlsym
139is called with the special
140.Fa handle
141.Dv RTLD_SELF ,
142then the search for the symbol is limited to the shared object
143issuing the call to
144.Fn dlsym
145and those shared objects which were loaded after it.
146.Pp
147The
148.Fn dlfunc
149function
150implements all of the behavior of
151.Fn dlsym ,
152but has a return type which can be cast to a function pointer without
153triggering compiler diagnostics.
154(The
155.Fn dlsym
156function
157returns a data pointer; in the C standard, conversions between
158data and function pointer types are undefined.
159Some compilers and
160.Xr lint 1
161utilities warn about such casts.)
162The precise return type of
163.Fn dlfunc
164is unspecified; applications must cast it to an appropriate function pointer
165type.
166.Sh NOTES
167ELF executables need to be linked
168using the
169.Fl export-dynamic
170option to
171.Xr ld 1
172for symbols defined in the executable to become visible to
173.Fn dlsym .
174.Sh RETURN VALUE
175The
176.Fn dlsym
177and
178.Fn dlfunc
179functions
180return the address of the symbol unless the symbol can not be found.
181In this case, they return a null pointer and set an error condition
182which may be queried with
183.Fn dlerror .
184.Sh EXAMPLE
185The following program will obtain a pointer to the cosine function using
186dlsym, and then it will use it to print out the value of cosine (2.0).
187.Bd -literal
188#include <dlfcn.h>
189#include <stdlib.h>
190#include <stdio.h>
191
192int
193main (int argc, char *argv[])
194{
195    void       *handle;
196    double     (*func_cosine)(double x);
197
198    /* open the system shared math library */
199    handle = dlopen("libm.so", RTLD_LAZY);
200    if (!handle) {
201       fprintf (stderr, "%s\en", dlerror ());
202       exit (EXIT_FAILURE);
203    }
204
205    /* get pointer to cosine function */
206    func_cosine = dlsym (handle, "cos");
207    if (func_cosine == NULL) {
208       fprintf (stderr, "%s function not found\en", "cos");
209       dlclose (handle);
210       exit (EXIT_FAILURE);
211    }
212
213    /* Calculate and display the cosine of 2.0 */
214    printf ("cosine of 2.0 = %f\en", func_cosine(2.0));
215    dlclose (handle);
216
217    exit(EXIT_SUCCESS);
218}
219.Ed
220.Sh SEE ALSO
221.Xr rtld 1 ,
222.Xr dlfcn 3 ,
223.Xr dlopen 3 ,
224.Xr dlvsym 3
225