[apple/dyld.git] / doc / man / man3 / dlsym.3

.Dd August 28, 2008
.Dt DLSYM 3
.Sh NAME
.Nm dlsym
.Nd get address of a symbol
.Sh SYNOPSIS
.In dlfcn.h
.Ft void*
.Fn dlsym "void* handle" "const char* symbol"
.Sh DESCRIPTION
.Fn dlsym
returns the address of the code or data location 
specified by the null-terminated character string
.Fa symbol .
Which libraries and bundles are searched depends on the  
.Fa handle 
parameter. 
.Pp
If
.Fn dlsym
is called with a
.Fa handle ,
returned by
.Fn dlopen
then only that image and any libraries it depends on are searched for
.Fa symbol .
.Pp
If
.Fn dlsym
is called with the special
.Fa handle
.Dv RTLD_DEFAULT ,
then all mach-o images in the process (except those loaded with dlopen(xxx, RTLD_LOCAL))
are searched in the order they were loaded.
This can be a costly search and should be avoided.  
.Pp
If
.Fn dlsym
is called with the special
.Fa handle
.Dv RTLD_NEXT ,
then dyld searches for the symbol in the dylibs the calling image 
linked against when built. It is usually used when
you intentionally have multiply defined symbol across images
and want to find the "next" definition.  It searches other images 
for the definition that the caller would be using if it did not
have a definition.  The exact search algorithm depends on whether
the caller's image was linked -flat_namespace or -twolevel_namespace.
For flat linked images, the search starts in the load ordered list
of all images, in the image right after the caller's image.  
For two-level images, the search simulates how the static linker
would have searched for the symbol when linking the caller's
image.  
.Pp
If
.Fn dlsym
is called with the special
.Fa handle
.Dv RTLD_SELF ,
then the search for the symbol starts with the image that called
.Fn dlsym .
If it is not found, the search continues as if RTLD_NEXT was used.
.Pp
If
.Fn dlsym
is called with the special
.Fa handle
.Dv RTLD_MAIN_ONLY ,
then it only searches for 
.Fa symbol
in the main executable.
.Pp
.Sh RETURN VALUES
The
.Fn dlsym
function
returns a null pointer if the symbol cannot be found, and sets an error
condition which may be queried with
.Fn dlerror .
.Pp
.Sh NOTES
The symbol name passed to
.Fn dlsym
is the name used in C source code.  For example to find the address
of function foo(), you would pass "foo" as the symbol name.  This
is unlike the older dyld APIs which required a leading underscore.
If you looking up a C++ symbol, you need to use the mangled C++ symbol
name.  
.Sh SEE ALSO
.Xr dlopen 3
.Xr dlerror 3
.Xr dyld 3
.Xr ld 1
.Xr cc 1
Commit	Line	Data
39a8cd10	1	.Dd August 28, 2008
0959b6d4 A	2	.Dt DLSYM 3
	3	.Sh NAME
	4	.Nm dlsym
	5	.Nd get address of a symbol
	6	.Sh SYNOPSIS
	7	.In dlfcn.h
	8	.Ft void*
	9	.Fn dlsym "void* handle" "const char* symbol"
	10	.Sh DESCRIPTION
	11	.Fn dlsym
	12	returns the address of the code or data location
	13	specified by the null-terminated character string
	14	.Fa symbol .
	15	Which libraries and bundles are searched depends on the
	16	.Fa handle
	17	parameter.
	18	.Pp
	19	If
	20	.Fn dlsym
	21	is called with a
	22	.Fa handle ,
	23	returned by
	24	.Fn dlopen
	25	then only that image and any libraries it depends on are searched for
	26	.Fa symbol .
	27	.Pp
	28	If
	29	.Fn dlsym
	30	is called with the special
	31	.Fa handle
	32	.Dv RTLD_DEFAULT ,
bac542e6 A	33	then all mach-o images in the process (except those loaded with dlopen(xxx, RTLD_LOCAL))
bac542e6 A	34	are searched in the order they were loaded.
0959b6d4 A	35	This can be a costly search and should be avoided.
	36	.Pp
	37	If
	38	.Fn dlsym
	39	is called with the special
	40	.Fa handle
	41	.Dv RTLD_NEXT ,
39a8cd10 A	42	then dyld searches for the symbol in the dylibs the calling image
	43	linked against when built. It is usually used when
	44	you intentionally have multiply defined symbol across images
	45	and want to find the "next" definition. It searches other images
	46	for the definition that the caller would be using if it did not
	47	have a definition. The exact search algorithm depends on whether
	48	the caller's image was linked -flat_namespace or -twolevel_namespace.
	49	For flat linked images, the search starts in the load ordered list
	50	of all images, in the image right after the caller's image.
	51	For two-level images, the search simulates how the static linker
	52	would have searched for the symbol when linking the caller's
	53	image.
2028a915 A	54	.Pp
	55	If
	56	.Fn dlsym
	57	is called with the special
	58	.Fa handle
	59	.Dv RTLD_SELF ,
	60	then the search for the symbol starts with the image that called
	61	.Fn dlsym .
	62	If it is not found, the search continues as if RTLD_NEXT was used.
0959b6d4	63	.Pp
39a8cd10 A	64	If
	65	.Fn dlsym
	66	is called with the special
	67	.Fa handle
	68	.Dv RTLD_MAIN_ONLY ,
	69	then it only searches for
	70	.Fa symbol
	71	in the main executable.
	72	.Pp
0959b6d4 A	73	.Sh RETURN VALUES
	74	The
	75	.Fn dlsym
	76	function
	77	returns a null pointer if the symbol cannot be found, and sets an error
	78	condition which may be queried with
	79	.Fn dlerror .
	80	.Pp
	81	.Sh NOTES
39a8cd10	82	The symbol name passed to
0959b6d4	83	.Fn dlsym
39a8cd10 A	84	is the name used in C source code. For example to find the address
	85	of function foo(), you would pass "foo" as the symbol name. This
	86	is unlike the older dyld APIs which required a leading underscore.
	87	If you looking up a C++ symbol, you need to use the mangled C++ symbol
	88	name.
0959b6d4 A	89	.Sh SEE ALSO
0959b6d4 A	90	.Xr dlopen 3
0959b6d4 A	91	.Xr dlerror 3
0959b6d4 A	92	.Xr dyld 3
0959b6d4 A	93	.Xr ld 1
0959b6d4 A	94	.Xr cc 1