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