'\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved .\" Copyright 1989 AT&T .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH dladdr 3C "4 Feb 2009" "SunOS 5.11" "Standard C Library Functions" .SH NAME dladdr, dladdr1 \- translate address to symbolic information .SH SYNOPSIS .LP .nf #include \fBint\fR \fBdladdr\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR); .fi .LP .nf \fBint\fR \fBdladdr1\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR, \fBvoid **\fR\fIinfo\fR, \fBint\fR \fIflags\fR); .fi .SH DESCRIPTION .sp .LP The \fBdladdr()\fR and \fBdladdr1()\fR functions determine if the specified \fIaddress\fR is located within one of the mapped objects that make up the current applications address space. An address is deemed to fall within a mapped object when it is between the base address, and the \fI_end\fR address of that object. See NOTES. If a mapped object fits this criteria, the symbol table made available to the runtime linker is searched to locate the nearest symbol to the specified address. The nearest symbol is one that has a value less than or equal to the required address. .sp .LP The \fBDl_info_t\fR structure must be preallocated by the user. The structure members are filled in by \fBdladdr()\fR, based on the specified \fIaddress\fR. The \fBDl_info_t\fR structure includes the following members: .sp .in +2 .nf const char *dli_fname; void *dli_fbase; const char *dli_sname; void *dli_saddr; .fi .in -2 .sp .LP The \fBDl_info_t\fR members provide the following information. .sp .ne 2 .mk .na \fB\fBdli_fname\fR\fR .ad .RS 13n .rt Contains a pointer to the filename of the containing object. .RE .sp .ne 2 .mk .na \fB\fBdli_fbase\fR\fR .ad .RS 13n .rt Contains the base address of the containing object. .RE .sp .ne 2 .mk .na \fB\fBdli_sname\fR\fR .ad .RS 13n .rt Contains a pointer to the symbol name that is nearest to the specified address. This symbol either represents the exact address that was specified, or is the nearest symbol with a lower address. .RE .sp .ne 2 .mk .na \fB\fBdli_saddr\fR\fR .ad .RS 13n .rt Contains the actual address of the symbol pointed to by \fBdli_sname\fR. .RE .sp .LP The \fBdladdr1()\fR function provides for addition information to be returned as specified by the \fIflags\fR argument: .sp .ne 2 .mk .na \fB\fBRTLD_DL_SYMENT\fR\fR .ad .RS 19n .rt Obtain the \fBELF\fR symbol table entry for the matched symbol. The \fIinfo\fR argument points to a symbol pointer as defined in <\fBsys/elf.h\fR> (\fBElf32_Sym **\fR\fIinfo\fR or \fBElf64_Sym **\fR\fIinfo\fR). Most of the information found in an ELF symbol can only be properly interpreted by the runtime linker. However, there are two fields that contain information useful to the caller of \fBdladdr1()\fR: The \fBst_size\fR field contains the size of the referenced item. The \fBst_info\fR field provides symbol type and binding attributes. See the \fILinker and Libraries Guild\fR for more information. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DL_LINKMAP\fR\fR .ad .RS 19n .rt Obtain the \fBLink_map\fR for the matched file. The \fIinfo\fR argument points to a \fBLink_map\fR pointer as defined in <\fBsys/link.h\fR> (\fBLink_map **\fR\fIinfo\fR). .RE .SH RETURN VALUES .sp .LP If the specified \fIaddress\fR cannot be matched to a mapped object, a \fB0\fR is returned. Otherwise, a non-zero return is made and the associated \fBDl_info_t\fR elements are filled. .SH USAGE .sp .LP The \fBdladdr()\fR and \fBdladdr1()\fR functions are one of a family of functions that give the user direct access to the dynamic linking facilities. These facilities are available to dynamically-linked processes only. See \fILinker and Libraries Guide\fR. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBld\fR(1), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBattributes\fR(5) .sp .LP \fILinker and Libraries Guide\fR .SH NOTES .sp .LP The \fBDl_info_t\fR pointer elements point to addresses within the mapped objects. These pointers can become invalid if objects are removed prior to these elements use. See \fBdlclose\fR(3C). .sp .LP If no symbol is found to describe the specified address, both the \fBdli_sname\fR and \fBdli_saddr\fR members are set to \fB0\fR. .sp .LP If the address specified exists within a mapped object in the range between the base address and the address of the first global symbol in the object, the reserved local symbol \fB_START_\fR is returned. This symbol acts as a label representing the start of the mapped object. As a label, this symbol has no size. The \fBdli_saddr\fR member is set to the base address of the associated object. The \fBdli_sname\fR member is set to the symbol name \fB_START_\fR. If the flag argument is set to \fBRTLD_DL_SYMENT\fR, symbol information for \fB_START_\fR is returned. .sp .LP If an object is acting as a filter, care should be taken when interpreting the address of any symbol obtained using a handle to this object. For example, using \fBdlsym\fR(3C) to obtain the symbol \fI_end\fR for this object, results in returning the address of the symbol \fI_end\fR within the filtee, not the filter. For more information on filters see the \fILinker and Libraries Guide\fR.