259 lines
6.7 KiB
Groff
259 lines
6.7 KiB
Groff
.\" Copyright (c) 2011 Kai Wang
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: dwarf_get_ranges.3 2122 2011-11-09 15:35:14Z jkoshy $
|
|
.\"
|
|
.Dd November 9, 2011
|
|
.Os
|
|
.Dt DWARF_GET_RANGES 3
|
|
.Sh NAME
|
|
.Nm dwarf_get_ranges
|
|
.Nd retrieve non-contiguous address ranges
|
|
.Sh LIBRARY
|
|
.Lb libdwarf
|
|
.Sh SYNOPSIS
|
|
.In libdwarf.h
|
|
.Ft int
|
|
.Fo dwarf_get_ranges
|
|
.Fa "Dwarf_Debug dbg"
|
|
.Fa "Dwarf_Off offset"
|
|
.Fa "Dwarf_Ranges **ranges"
|
|
.Fa "Dwarf_Signed *cnt"
|
|
.Fa "Dwarf_Unsigned *byte_cnt"
|
|
.Fa "Dwarf_Error *err"
|
|
.Fc
|
|
.Ft int
|
|
.Fo dwarf_get_ranges_a
|
|
.Fa "Dwarf_Debug dbg"
|
|
.Fa "Dwarf_Off offset"
|
|
.Fa "Dwarf_Die die"
|
|
.Fa "Dwarf_Ranges **ranges"
|
|
.Fa "Dwarf_Signed *cnt"
|
|
.Fa "Dwarf_Unsigned *byte_cnt"
|
|
.Fa "Dwarf_Error *err"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
Function
|
|
.Fn dwarf_get_ranges
|
|
retrieves information about the non-contiguous address ranges associated
|
|
with a DWARF debugging information entry.
|
|
Information about address ranges is returned as an array of
|
|
descriptors of type
|
|
.Vt Dwarf_Ranges ,
|
|
with each
|
|
.Vt Dwarf_Ranges
|
|
descriptor describing one address range entry.
|
|
.Pp
|
|
Argument
|
|
.Ar dbg
|
|
should reference a DWARF debug context allocated using
|
|
.Xr dwarf_init 3 .
|
|
.Pp
|
|
Argument
|
|
.Ar offset
|
|
is an offset, relative to the
|
|
.Dq ".debug_ranges"
|
|
section, to the start of the desired list of address ranges.
|
|
The offset of an address ranges list is indicated by the
|
|
.Dv DW_AT_ranges
|
|
attribute of a debugging information entry.
|
|
.Pp
|
|
Argument
|
|
.Ar die
|
|
(function
|
|
.Fn dwarf_get_ranges_a
|
|
only) is ignored in this implementation; see the section
|
|
.Sx "Compatibility Notes"
|
|
below.
|
|
.Pp
|
|
Argument
|
|
.Ar ranges
|
|
should point to a location that will be set to a pointer to an array
|
|
of
|
|
.Vt Dwarf_Ranges
|
|
descriptors.
|
|
.Pp
|
|
Argument
|
|
.Ar cnt
|
|
should point to a location that will be set to the number of entries
|
|
returned.
|
|
If argument
|
|
.Ar byte_cnt
|
|
is not NULL, it will be set to the number of bytes occupied by the
|
|
returned entries in the
|
|
.Dq ".debug_ranges"
|
|
section.
|
|
.Pp
|
|
If argument
|
|
.Ar err
|
|
is not NULL, it will be used to store error information in case
|
|
of an error.
|
|
.Pp
|
|
.Vt Dwarf_Ranges
|
|
descriptors are defined in the header file
|
|
.In libdwarf.h ,
|
|
and consists of the following fields:
|
|
.Bl -tag -width ".Va dwr_addr1"
|
|
.It Va dwr_addr1
|
|
The first address offset, whose meaning depends on the type of the
|
|
entry.
|
|
.It Va dwr_addr2
|
|
The second address offset, whose meaning depends on the type of the
|
|
entry.
|
|
.It Va dwr_type
|
|
The type of this address range entry:
|
|
.Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact
|
|
.It Dv DW_RANGES_ENTRY
|
|
A range list entry.
|
|
For this type of entry, the fields
|
|
.Va dwr_addr1
|
|
and
|
|
.Va dwr_addr2
|
|
hold the beginning and ending offsets of the address range, respectively.
|
|
.It Dv DW_RANGES_ADDRESS_SELECTION
|
|
A base address selection entry.
|
|
For this type of entry, the field
|
|
.Va dwr_addr1
|
|
is the value of the largest representable address offset, and
|
|
.Va dwr_addr2
|
|
is a base address for the begining and ending address offsets of
|
|
subsequent address range entries in the list.
|
|
.It Dv DW_RANGES_END
|
|
An end of list mark.
|
|
Both
|
|
.Va dwr_addr1
|
|
and
|
|
.Va dwr_addr2
|
|
are set to 0.
|
|
.El
|
|
.El
|
|
.Ss Memory Management
|
|
The memory area used for the array of
|
|
.Vt Dwarf_Ranges
|
|
descriptors returned in argument
|
|
.Ar ranges
|
|
is owned by the
|
|
.Lb libdwarf .
|
|
The application should not attempt to directly free this pointer.
|
|
Portable code should instead use
|
|
.Fn dwarf_ranges_dealloc
|
|
to indicate that the memory may be freed.
|
|
.Sh COMPATIBILITY
|
|
Function
|
|
.Fn dwarf_get_ranges_a
|
|
is identical to
|
|
.Fn dwarf_get_ranges ,
|
|
except that it requires one additional argument
|
|
.Ar die
|
|
denoting the debugging information entry associated with
|
|
the address range list.
|
|
In this implementation of the
|
|
.Lb libdwarf ,
|
|
the argument
|
|
.Ar die
|
|
is ignored, and function
|
|
.Fn dwarf_get_ranges_a
|
|
is only provided for compatibility with other implementations of the
|
|
DWARF(3) API.
|
|
.Sh RETURN VALUES
|
|
These functions
|
|
return
|
|
.Dv DW_DLV_OK
|
|
when they succeed.
|
|
They return
|
|
.Dv DW_DLV_NO_ENTRY
|
|
if there is no address range list at the specified offset
|
|
.Ar offset .
|
|
In case of an error, they return
|
|
.Dv DW_DLV_ERROR
|
|
and set the argument
|
|
.Ar err .
|
|
.Sh ERRORS
|
|
These function can fail with:
|
|
.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
|
|
.It Bq Er DW_DLE_ARGUMENT
|
|
One of the arguments
|
|
.Ar dbg ,
|
|
.Ar ranges
|
|
or
|
|
.Ar cnt
|
|
was NULL.
|
|
.It Bq Er DW_DLE_NO_ENTRY
|
|
There is no address range list at the specified offset
|
|
.Ar offset .
|
|
.El
|
|
.Sh EXAMPLE
|
|
To retrieve the address range list associated with a debugging
|
|
information entry, use:
|
|
.Bd -literal -offset indent
|
|
Dwarf_Debug dbg;
|
|
Dwarf_Die die;
|
|
Dwarf_Error de;
|
|
Dwarf_Addr base;
|
|
Dwarf_Attribute *attr_list;
|
|
Dwarf_Ranges *ranges;
|
|
Dwarf_Signed cnt;
|
|
Dwarf_Unsigned off, attr_count, bytecnt;
|
|
int i, j;
|
|
|
|
if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) !=
|
|
DW_DLV_OK)
|
|
errx(EXIT_FAILURE, "dwarf_attrlist failed: %s",
|
|
dwarf_errmsg(de));
|
|
|
|
for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) {
|
|
if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) {
|
|
warnx("dwarf_whatattr failed: %s",
|
|
dwarf_errmsg(de));
|
|
continue;
|
|
}
|
|
if (attr != DW_AT_ranges)
|
|
continue;
|
|
if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) {
|
|
warnx("dwarf_formudata failed: %s",
|
|
dwarf_errmsg(de));
|
|
continue;
|
|
}
|
|
if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt,
|
|
&bytecnt, &de) != DW_DLV_OK)
|
|
continue;
|
|
for (j = 0; j < cnt; j++) {
|
|
if (ranges[j].dwr_type == DW_RANGES_END)
|
|
break;
|
|
else if (ranges[j].dwr_type ==
|
|
DW_RANGES_ADDRESS_SELECTION)
|
|
base = ranges[j].dwr_addr2;
|
|
else {
|
|
/*
|
|
* DW_RANGES_ENTRY entry.
|
|
* .. Use dwr_addr1 and dwr_addr2 ..
|
|
*/
|
|
}
|
|
}
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr dwarf 3 ,
|
|
.Xr dwarf_ranges_dealloc 3
|