xref: /dragonfly/lib/libc/gen/dlsym.3 (revision e5a92d33) 
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 February 22, 2018
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 * restrict handle" "const char * restrict name"
48.Ft dlfunc_t
49.Fn dlfunc "void * restrict handle" "const char * restrict 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 code checkers warn about such casts.)
160The precise return type of
161.Fn dlfunc
162is unspecified; applications must cast it to an appropriate function pointer
163type.
164.Sh NOTES
165ELF executables need to be linked
166using the
167.Fl export-dynamic
168option to
169.Xr ld 1
170for symbols defined in the executable to become visible to
171.Fn dlsym .
172.Sh RETURN VALUES
173The
174.Fn dlsym
175and
176.Fn dlfunc
177functions
178return the address of the symbol unless the symbol can not be found.
179In this case, they return a null pointer and set an error condition
180which may be queried with
181.Fn dlerror .
182.Sh EXAMPLES
183The following program will obtain a pointer to the cosine function using
184dlsym, and then it will use it to print out the value of cosine (2.0).
185.Bd -literal
186#include <dlfcn.h>
187#include <stdlib.h>
188#include <stdio.h>
189
190int
191main (int argc, char *argv[])
192{
193    void       *handle;
194    double     (*func_cosine)(double x);
195
196    /* open the system shared math library */
197    handle = dlopen("libm.so", RTLD_LAZY);
198    if (!handle) {
199       fprintf (stderr, "%s\en", dlerror ());
200       exit (EXIT_FAILURE);
201    }
202
203    /* get pointer to cosine function */
204    func_cosine = dlsym (handle, "cos");
205    if (func_cosine == NULL) {
206       fprintf (stderr, "%s function not found\en", "cos");
207       dlclose (handle);
208       exit (EXIT_FAILURE);
209    }
210
211    /* Calculate and display the cosine of 2.0 */
212    printf ("cosine of 2.0 = %f\en", func_cosine(2.0));
213    dlclose (handle);
214
215    exit(EXIT_SUCCESS);
216}
217.Ed
218.Sh SEE ALSO
219.Xr rtld 1 ,
220.Xr dlfcn 3 ,
221.Xr dlopen 3 ,
222.Xr dlvsym 3
223