contrib/elftoolchain/libdwarf/dwarf_srcfiles.3

   1 .\" Copyright (c) 2010 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $Id: dwarf_srcfiles.3 3640 2018-10-14 14:09:13Z jkoshy $
  25 .\"
  26 .Dd April 28, 2010
  27 .Dt DWARF_SRCFILES 3
  28 .Os
  29 .Sh NAME
  30 .Nm dwarf_srcfiles
  31 .Nd retrieve source file information
  32 .Sh LIBRARY
  33 .Lb libdwarf
  34 .Sh SYNOPSIS
  35 .In libdwarf.h
  36 .Ft int
  37 .Fo dwarf_srcfiles
  38 .Fa "Dwarf_Die die"
  39 .Fa "char ***filenames"
  40 .Fa "Dwarf_Signed *filenamecount"
  41 .Fa "Dwarf_Error *err"
  42 .Fc
  43 .Sh DESCRIPTION
  44 Function
  45 .Fn dwarf_srcfiles
  46 returns the source file names associated with a compilation unit.
  47 Source file names are returned as an array of NUL-terminated strings.
  48 .Pp
  49 Argument
  50 .Ar die
  51 should reference a DWARF debugging information entry descriptor with
  52 source file information, see
  53 .Xr dwarf 3 .
  54 Argument
  55 .Ar filenames
  56 should point to a location that will hold a pointer to the returned array
  57 of file names.
  58 Argument
  59 .Ar filenamecount
  60 should point to a location that will hold the number of file names returned.
  61 If argument
  62 .Ar err
  63 is not NULL, it will be used to store error information in case of an
  64 error.
  65 .Ss Memory Management
  66 The memory areas used for the file names and for array of pointers
  67 being returned are managed by the DWARF(3) library.
  68 The application should not attempt to directly free these memory areas.
  69 Portable code should indicate that the memory areas are to be freed
  70 by using
  71 .Xr dwarf_dealloc 3 .
  72 .Sh RETURN VALUES
  73 Function
  74 .Fn dwarf_srcfiles
  75 returns
  76 .Dv DW_DLV_OK
  77 when it succeeds.
  78 In case of an error, it returns
  79 .Dv DW_DLV_ERROR
  80 and sets the argument
  81 .Ar err .
  82 .Sh ERRORS
  83 Function
  84 .Fn dwarf_srcfiles
  85 can fail with:
  86 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
  87 .It Bq Er DW_DLE_ARGUMENT
  88 One of the arguments
  89 .Ar die ,
  90 .Ar filenames
  91 or
  92 .Ar filenamecount
  93 was NULL.
  94 .It Bq Er DW_DLE_NO_ENTRY
  95 The compilation unit referenced by argument
  96 .Ar die
  97 does not have associated source file information.
  98 .It Bq Er DW_DLE_MEMORY
  99 An out of memory condition was encountered during the execution of
 100 this function.
 101 .El
 102 .Sh SEE ALSO
 103 .Xr dwarf 3 ,
 104 .Xr dwarf_dealloc 3 ,
 105 .Xr dwarf_srclines 3