1*5ac3bc71Schristos.\" $NetBSD: dwarf_srcfiles.3,v 1.6 2024/03/03 17:37:32 christos Exp $ 2e81373b4Schristos.\" 39dd9d0cfSchristos.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. 49dd9d0cfSchristos.\" 59dd9d0cfSchristos.\" Redistribution and use in source and binary forms, with or without 69dd9d0cfSchristos.\" modification, are permitted provided that the following conditions 79dd9d0cfSchristos.\" are met: 89dd9d0cfSchristos.\" 1. Redistributions of source code must retain the above copyright 99dd9d0cfSchristos.\" notice, this list of conditions and the following disclaimer. 109dd9d0cfSchristos.\" 2. Redistributions in binary form must reproduce the above copyright 119dd9d0cfSchristos.\" notice, this list of conditions and the following disclaimer in the 129dd9d0cfSchristos.\" documentation and/or other materials provided with the distribution. 139dd9d0cfSchristos.\" 149dd9d0cfSchristos.\" This software is provided by Joseph Koshy ``as is'' and 159dd9d0cfSchristos.\" any express or implied warranties, including, but not limited to, the 169dd9d0cfSchristos.\" implied warranties of merchantability and fitness for a particular purpose 179dd9d0cfSchristos.\" are disclaimed. in no event shall Joseph Koshy be liable 189dd9d0cfSchristos.\" for any direct, indirect, incidental, special, exemplary, or consequential 199dd9d0cfSchristos.\" damages (including, but not limited to, procurement of substitute goods 209dd9d0cfSchristos.\" or services; loss of use, data, or profits; or business interruption) 219dd9d0cfSchristos.\" however caused and on any theory of liability, whether in contract, strict 229dd9d0cfSchristos.\" liability, or tort (including negligence or otherwise) arising in any way 239dd9d0cfSchristos.\" out of the use of this software, even if advised of the possibility of 249dd9d0cfSchristos.\" such damage. 259dd9d0cfSchristos.\" 26cdbf1fe1Sjkoshy.\" Id: dwarf_srcfiles.3 3963 2022-03-12 16:07:32Z jkoshy 279dd9d0cfSchristos.\" 289dd9d0cfSchristos.Dd April 28, 2010 299dd9d0cfSchristos.Dt DWARF_SRCFILES 3 30604b0842Sjkoshy.Os 319dd9d0cfSchristos.Sh NAME 329dd9d0cfSchristos.Nm dwarf_srcfiles 339dd9d0cfSchristos.Nd retrieve source file information 349dd9d0cfSchristos.Sh LIBRARY 359dd9d0cfSchristos.Lb libdwarf 369dd9d0cfSchristos.Sh SYNOPSIS 379dd9d0cfSchristos.In libdwarf.h 389dd9d0cfSchristos.Ft int 399dd9d0cfSchristos.Fo dwarf_srcfiles 409dd9d0cfSchristos.Fa "Dwarf_Die die" 419dd9d0cfSchristos.Fa "char ***filenames" 429dd9d0cfSchristos.Fa "Dwarf_Signed *filenamecount" 439dd9d0cfSchristos.Fa "Dwarf_Error *err" 449dd9d0cfSchristos.Fc 459dd9d0cfSchristos.Sh DESCRIPTION 469dd9d0cfSchristosFunction 479dd9d0cfSchristos.Fn dwarf_srcfiles 489dd9d0cfSchristosreturns the source file names associated with a compilation unit. 499dd9d0cfSchristosSource file names are returned as an array of NUL-terminated strings. 509dd9d0cfSchristos.Pp 519dd9d0cfSchristosArgument 52cdbf1fe1Sjkoshy.Fa die 539dd9d0cfSchristosshould reference a DWARF debugging information entry descriptor with 549dd9d0cfSchristossource file information, see 559dd9d0cfSchristos.Xr dwarf 3 . 569dd9d0cfSchristosArgument 57cdbf1fe1Sjkoshy.Fa filenames 589dd9d0cfSchristosshould point to a location that will hold a pointer to the returned array 599dd9d0cfSchristosof file names. 609dd9d0cfSchristosArgument 61cdbf1fe1Sjkoshy.Fa filenamecount 629dd9d0cfSchristosshould point to a location that will hold the number of file names returned. 639dd9d0cfSchristosIf argument 64cdbf1fe1Sjkoshy.Fa err 65cdbf1fe1Sjkoshyis not 66cdbf1fe1Sjkoshy.Dv NULL , 67cdbf1fe1Sjkoshyit will be used to store error information in case of an error. 689dd9d0cfSchristos.Ss Memory Management 699dd9d0cfSchristosThe memory areas used for the file names and for array of pointers 709dd9d0cfSchristosbeing returned are managed by the DWARF(3) library. 719dd9d0cfSchristosThe application should not attempt to directly free these memory areas. 729dd9d0cfSchristosPortable code should indicate that the memory areas are to be freed 739dd9d0cfSchristosby using 749dd9d0cfSchristos.Xr dwarf_dealloc 3 . 759dd9d0cfSchristos.Sh RETURN VALUES 769dd9d0cfSchristosFunction 779dd9d0cfSchristos.Fn dwarf_srcfiles 789dd9d0cfSchristosreturns 799dd9d0cfSchristos.Dv DW_DLV_OK 809dd9d0cfSchristoswhen it succeeds. 819dd9d0cfSchristosIn case of an error, it returns 829dd9d0cfSchristos.Dv DW_DLV_ERROR 839dd9d0cfSchristosand sets the argument 84cdbf1fe1Sjkoshy.Fa err . 859dd9d0cfSchristos.Sh ERRORS 869dd9d0cfSchristosFunction 879dd9d0cfSchristos.Fn dwarf_srcfiles 889dd9d0cfSchristoscan fail with: 899dd9d0cfSchristos.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 909dd9d0cfSchristos.It Bq Er DW_DLE_ARGUMENT 919dd9d0cfSchristosOne of the arguments 92cdbf1fe1Sjkoshy.Fa die , 93cdbf1fe1Sjkoshy.Fa filenames 949dd9d0cfSchristosor 95cdbf1fe1Sjkoshy.Fa filenamecount 96cdbf1fe1Sjkoshywas 97cdbf1fe1Sjkoshy.Dv NULL . 989dd9d0cfSchristos.It Bq Er DW_DLE_NO_ENTRY 999dd9d0cfSchristosThe compilation unit referenced by argument 100cdbf1fe1Sjkoshy.Fa die 1019dd9d0cfSchristosdoes not have associated source file information. 1029dd9d0cfSchristos.It Bq Er DW_DLE_MEMORY 1039dd9d0cfSchristosAn out of memory condition was encountered during the execution of 1049dd9d0cfSchristosthis function. 1059dd9d0cfSchristos.El 1069dd9d0cfSchristos.Sh SEE ALSO 1079dd9d0cfSchristos.Xr dwarf 3 , 1089dd9d0cfSchristos.Xr dwarf_dealloc 3 , 1099dd9d0cfSchristos.Xr dwarf_srclines 3 110