1.\" $NetBSD: dwarf_get_str.3,v 1.4 2020/11/26 22:51:35 jkoshy 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 3644 2018-10-15 19:55:01Z jkoshy 28.\" 29.Dd April 3, 2011 30.Dt DWARF_GET_STR 3 31.Os 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 EXAMPLES 101To retrieve all the strings in the DWARF string section, use: 102.Bd -literal -offset indent 103Dwarf_Debug dbg; 104Dwarf_Off offset; 105Dwarf_Signed len; 106Dwarf_Error de; 107char *str; 108int ret 109 110offset = 0; 111while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) == 112 DW_DLV_OK) { 113 /* .. Use the retrieved string. .. */ 114 offset += len + 1; /* Account for the terminating NUL. */ 115} 116 117if (ret == DW_DLV_ERROR) 118 warnx("dwarf_get_str: %s", dwarf_errmsg(de)); 119.Ed 120.Sh ERRORS 121Function 122.Fn dwarf_get_str 123can fail with: 124.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 125.It Bq Er DW_DLE_ARGUMENT 126One of the arguments 127.Ar dbg , 128.Ar string 129or 130.Ar len 131was NULL. 132.It Bq Er DW_DLE_ARGUMENT 133Argument 134.Ar offset 135was out of range. 136.It Bq Er DW_DLE_NO_ENTRY 137The debugging context 138.Ar dbg 139did not contain a 140.Dq ".debug_str" 141string section. 142.It Bq Er DW_DLE_NO_ENTRY 143Argument 144.Ar offset 145was at the very end of the 146.Dq ".debug_str" 147section. 148.El 149.Sh SEE ALSO 150.Xr dwarf 3 , 151.Xr dwarf_init 3 152