dyld-43.tar.gz
[apple/dyld.git] / doc / man / man3 / dladdr.3
1 .Dd September 24, 2004
2 .Os
3 .Dt DLADDR 3
4 .Sh NAME
5 .Nm dladdr
6 .Nd find the image containing a given address
7 .Sh SYNOPSIS
8 .In dlfcn.h
9 .Ft int
10 .Fn dladdr "const void* addr" "Dl_info* info"
11 .Sh DESCRIPTION
12 The
13 .Fn dladdr
14 function
15 queries dyld (the dynamic linker) for information about the image
16 containing the address
17 .Fa addr .
18 The information is returned in the structure specified by
19 .Fa info .
20 The structure contains at least the following members:
21 .Bl -tag -width "XXXconst char *dli_fname"
22 .It Li "const char* dli_fname"
23 The pathname of the shared object containing the address.
24 .It Li "void* dli_fbase"
25 The base address (mach_header) at which the image is mapped into the
26 address space of the calling process.
27 .It Li "const char* dli_sname"
28 The name of the nearest run-time symbol with a value less than or
29 equal to
30 .Fa addr .
31 .It Li "void* dli_saddr"
32 The value of the symbol returned in
33 .Li dli_sname .
34 .El
35 .Pp
36 The
37 .Fn dladdr
38 function
39 is available only in dynamically linked programs.
40 .Sh ERRORS
41 If an image containing
42 .Fa addr
43 cannot be found,
44 .Fn dladdr
45 returns 0.
46 On success, a non-zero value is returned.
47 .Pp
48 If the image containing 
49 .Fa addr
50 is found, but no nearest symbol was found,
51 the dli_sname and dli_saddr fields are set to NULL.
52 .Sh SEE ALSO
53 .Xr dyld 3 ,
54 .Xr dlopen 3
55 .Sh HISTORY
56 The
57 .Fn dladdr
58 function first appeared in the Solaris operating system.
59 .Sh AUTHORS
60 Mac OS X 10.3 incorporated the dlcompat package written by Jorge Acereda <jacereda@users.sourceforge.net>
61 and Peter O'Gorman <ogorman@users.sourceforge.net>.
62 .Pp
63 In Mac OS X 10.4, dlopen was rewritten to be a native part of dyld.
64 .Pp
65 This man page was borrowed from FreeBSD and modified.
66 .Sh BUGS
67 This implementation is almost bug-compatible with the Solaris
68 implementation.  The following bugs are present:
69 .Bl -bullet
70 .It
71 Returning 0 as an indication of failure goes against long-standing
72 Unix tradition.
73 .El