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