1.\" Copyright (c) 2011 Kai Wang 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: dwarf_get_str.3 2071 2011-10-27 03:20:00Z jkoshy $ 26.\" 27.Dd April 3, 2011 28.Os 29.Dt DWARF_GET_STR 3 30.Sh NAME 31.Nm dwarf_get_str 32.Nd retrieve a string from the DWARF string section 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_str 39.Fa "Dwarf_Debug dbg" 40.Fa "Dwarf_Off offset" 41.Fa "char **string" 42.Fa "Dwarf_Signed *len" 43.Fa "Dwarf_Error *err" 44.Fc 45.Sh DESCRIPTION 46Function 47.Fn dwarf_get_str 48retrieves a NUL-terminated string from the DWARF string section 49.Dq ".debug_str" . 50.Pp 51Argument 52.Ar dbg 53should reference a DWARF debug context allocated using 54.Xr dwarf_init 3 . 55.Pp 56Argument 57.Ar offset 58should be an offset, relative to the 59.Dq ".debug_str" 60section, specifying the start of the desired string. 61.Pp 62Argument 63.Ar string 64should point to a location which will hold a returned 65pointer to a NUL-terminated string. 66.Pp 67Argument 68.Ar len 69should point to a location which will hold the length 70of the returned string. 71The returned length does not include the space needed for 72the NUL-terminator. 73.Pp 74If argument 75.Ar err 76is not NULL, it will be used to store error information in case of an 77error. 78.Sh RETURN VALUES 79Function 80.Fn dwarf_get_str 81returns 82.Dv DW_DLV_OK 83when it succeeds. 84It returns 85.Dv DW_DLV_NO_ENTRY 86if there is no 87.Dq ".debug_str" 88section associated with the specified debugging context, 89or if the provided offset 90.Ar offset 91is at the very end of 92.Dq ".debug_str" 93section. 94In case of an error, it returns 95.Dv DW_DLV_ERROR 96and sets the argument 97.Ar err . 98.Sh ERRORS 99Function 100.Fn dwarf_get_str 101can fail with: 102.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 103.It Bq Er DW_DLE_ARGUMENT 104One of the arguments 105.Ar dbg , 106.Ar string 107or 108.Ar len 109was NULL. 110.It Bq Er DW_DLE_ARGUMENT 111Argument 112.Ar offset 113was out of range. 114.It Bq Er DW_DLE_NO_ENTRY 115The debugging context 116.Ar dbg 117did not contain a 118.Dq ".debug_str" 119string section. 120.It Bq Er DW_DLE_NO_ENTRY 121Argument 122.Ar offset 123was at the very end of the 124.Dq ".debug_str" 125section. 126.El 127.Sh EXAMPLE 128To retrieve all the strings in the DWARF string section, use: 129.Bd -literal -offset indent 130Dwarf_Debug dbg; 131Dwarf_Off offset; 132Dwarf_Signed len; 133Dwarf_Error de; 134char *str; 135int ret 136 137offset = 0; 138while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) == 139 DW_DLV_OK) { 140 /* .. Use the retrieved string. .. */ 141 offset += len + 1; /* Account for the terminating NUL. */ 142} 143 144if (ret == DW_DLV_ERROR) 145 warnx("dwarf_get_str: %s", dwarf_errmsg(de)); 146.Ed 147.Sh SEE ALSO 148.Xr dwarf 3 , 149.Xr dwarf_init 3 150