libdw: Extend documentation to explain relative file paths and comp_dir.

Signed-off-by: Mark Wielaard <mark@klomp.org>

diff --git a/libdw/ChangeLog b/libdw/ChangeLog
index f552644d3db3c0bb7f7e220d86beb3ec912bcd48..025b24ad6609da01b19faf2f524688168f3fa5ad 100644 (file)
--- a/libdw/ChangeLog
+++ b/libdw/ChangeLog
@@ -1,3 +1,9 @@
+2018-03-29  Mark Wielaard  <mark@klomp.org>
+
+       * libdw.h (dwarf_decl_file): Extend documentation.
+       (dwarf_linesrc): Likewise.
+       (dwarf_filesrc): Likewise.
+
 2018-03-06  Mark Wielaard  <mark@klomp.org>
 
        * dwarf.h: Add DW_OP_implicit_pointer, DW_OP_addrx, DW_OP_constx,

diff --git a/libdw/libdw.h b/libdw/libdw.h
index ac43ad97ad02bc7eebab7cf6e8b498835a3dcbca..0ca887824235bb4ba0f3fb560a7d9e4e2797e54b 100644 (file)
--- a/libdw/libdw.h
+++ b/libdw/libdw.h
@@ -679,11 +679,15 @@ extern int dwarf_linediscriminator (Dwarf_Line *line, unsigned int *discp)
      __nonnull_attribute__ (2);
 
 
-/* Find line information for address.  */
+/* Find line information for address.  The returned string is NULL when
+   an error occured, or the file path.  The file path is either absolute
+   or relative to the compilation directory.  See dwarf_decl_file.  */
 extern const char *dwarf_linesrc (Dwarf_Line *line,
                                  Dwarf_Word *mtime, Dwarf_Word *length);
 
-/* Return file information.  */
+/* Return file information.  The returned string is NULL when
+   an error occured, or the file path.  The file path is either absolute
+   or relative to the compilation directory.  See dwarf_decl_file.  */
 extern const char *dwarf_filesrc (Dwarf_Files *file, size_t idx,
                                  Dwarf_Word *mtime, Dwarf_Word *length);
 
@@ -855,7 +859,14 @@ extern ptrdiff_t dwarf_getfuncs (Dwarf_Die *cudie,
                                 void *arg, ptrdiff_t offset);
 
 
-/* Return file name containing definition of the given declaration.  */
+/* Return file name containing definition of the given declaration.
+   Of the DECL has an (indirect, see dwarf_attr_integrate) decl_file
+   attribute.  The returned file path is either absolute, or relative
+   to the compilation directory.  Given the decl DIE, the compilation
+   directory can be retrieved through:
+   dwarf_formstring (dwarf_attr (dwarf_diecu (decl, &cudie, NULL, NULL),
+                                 DW_AT_comp_dir, &attr));
+   Returns NULL if no decl_file could be found or an error occured.  */
 extern const char *dwarf_decl_file (Dwarf_Die *decl);
 
 /* Get line number of beginning of given declaration.  */