| 1 | .\" |
| 2 | .\" Copyright (c) 1998 John D. Polstra |
| 3 | .\" All rights reserved. |
| 4 | .\" |
| 5 | .\" Redistribution and use in source and binary forms, with or without |
| 6 | .\" modification, are permitted provided that the following conditions |
| 7 | .\" are met: |
| 8 | .\" 1. Redistributions of source code must retain the above copyright |
| 9 | .\" notice, this list of conditions and the following disclaimer. |
| 10 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 11 | .\" notice, this list of conditions and the following disclaimer in the |
| 12 | .\" documentation and/or other materials provided with the distribution. |
| 13 | .\" |
| 14 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 15 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 16 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 17 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 18 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 19 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 20 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 21 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 22 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 23 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 24 | .\" SUCH DAMAGE. |
| 25 | .\" |
| 26 | .\" $FreeBSD: src/lib/libc/gen/dladdr.3,v 1.3.2.4 2003/03/15 15:11:05 trhodes Exp $ |
| 27 | .\" |
| 28 | .Dd February 5, 1998 |
| 29 | .Os |
| 30 | .Dt DLADDR 3 |
| 31 | .Sh NAME |
| 32 | .Nm dladdr |
| 33 | .Nd find the shared object containing a given address |
| 34 | .Sh LIBRARY |
| 35 | .Lb libc |
| 36 | .Sh SYNOPSIS |
| 37 | .In dlfcn.h |
| 38 | .Ft int |
| 39 | .Fn dladdr "const void *addr" "Dl_info *info" |
| 40 | .Sh DESCRIPTION |
| 41 | The |
| 42 | .Fn dladdr |
| 43 | function queries the dynamic linker for information about the shared object |
| 44 | containing the address |
| 45 | .Fa addr . |
| 46 | The information is returned in the structure specified by |
| 47 | .Fa info . |
| 48 | The structure contains at least the following members: |
| 49 | .Bl -tag -width "XXXconst char *dli_fname" |
| 50 | .It Li "const char *dli_fname" |
| 51 | The pathname of the shared object containing the address. |
| 52 | .It Li "void *dli_fbase" |
| 53 | The base address at which the shared object is mapped into the |
| 54 | address space of the calling process. |
| 55 | .It Li "const char *dli_sname" |
| 56 | The name of the nearest run-time symbol with a value less than or |
| 57 | equal to |
| 58 | .Fa addr . |
| 59 | When possible, the symbol name is returned as it would appear in C |
| 60 | source code. |
| 61 | .Pp |
| 62 | If no symbol with a suitable value is found, both this field and |
| 63 | .Va dli_saddr |
| 64 | are set to |
| 65 | .Dv NULL . |
| 66 | .It Li "void *dli_saddr" |
| 67 | The value of the symbol returned in |
| 68 | .Li dli_sname . |
| 69 | .El |
| 70 | .Pp |
| 71 | The |
| 72 | .Fn dladdr |
| 73 | function is available only in dynamically linked programs. |
| 74 | .Sh ERRORS |
| 75 | If a mapped shared object containing |
| 76 | .Fa addr |
| 77 | cannot be found, |
| 78 | .Fn dladdr |
| 79 | returns 0. |
| 80 | In that case, a message detailing the failure can be retrieved by |
| 81 | calling |
| 82 | .Fn dlerror . |
| 83 | .Pp |
| 84 | On success, a non-zero value is returned. |
| 85 | .Sh SEE ALSO |
| 86 | .Xr rtld 1 , |
| 87 | .Xr dlopen 3 |
| 88 | .Sh HISTORY |
| 89 | The |
| 90 | .Fn dladdr |
| 91 | function first appeared in the Solaris operating system. |
| 92 | .Sh BUGS |
| 93 | This implementation is bug-compatible with the Solaris |
| 94 | implementation. In particular, the following bugs are present: |
| 95 | .Bl -bullet |
| 96 | .It |
| 97 | If |
| 98 | .Fa addr |
| 99 | lies in the main executable rather than in a shared library, the |
| 100 | pathname returned in |
| 101 | .Va dli_fname |
| 102 | may not be correct. The pathname is taken directly from |
| 103 | .Va argv[0] |
| 104 | of the calling process. When executing a program specified by its |
| 105 | full pathname, most shells set |
| 106 | .Va argv[0] |
| 107 | to the pathname. But this is not required of shells or guaranteed |
| 108 | by the operating system. |
| 109 | .It |
| 110 | If |
| 111 | .Fa addr |
| 112 | is of the form |
| 113 | .Va &func , |
| 114 | where |
| 115 | .Va func |
| 116 | is a global function, its value may be an unpleasant surprise. In |
| 117 | dynamically linked programs, the address of a global function is |
| 118 | considered to point to its program linkage table entry, rather than to |
| 119 | the entry point of the function itself. This causes most global |
| 120 | functions to appear to be defined within the main executable, rather |
| 121 | than in the shared libraries where the actual code resides. |
| 122 | .It |
| 123 | Returning 0 as an indication of failure goes against long-standing |
| 124 | Unix tradition. |
| 125 | .El |