8999 SMBIOS: cleanup 32-bit specific code

[unleashed.git] / usr / src / man / man3c / dladdr.3c

'\" 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 "Feb 4, 2009"
.SH NAME
dladdr, dladdr1 \- translate address to symbolic information
.SH SYNOPSIS
.LP
.nf
#include <dlfcn.h>

\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
.na
\fB\fBdli_fname\fR\fR
.ad
.RS 13n
Contains a pointer to the filename of the containing object.
.RE

.sp
.ne 2
.na
\fB\fBdli_fbase\fR\fR
.ad
.RS 13n
Contains the base address of the containing object.
.RE

.sp
.ne 2
.na
\fB\fBdli_sname\fR\fR
.ad
.RS 13n
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
.na
\fB\fBdli_saddr\fR\fR
.ad
.RS 13n
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
.na
\fB\fBRTLD_DL_SYMENT\fR\fR
.ad
.RS 19n
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
.na
\fB\fBRTLD_DL_LINKMAP\fR\fR
.ad
.RS 19n
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
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
MT-Level        MT-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.