From e87cfeb2290bff320c7f0a45f93ba571ffe3c58d Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Thu, 29 Mar 2018 14:09:12 +0200 Subject: [PATCH] libdw: Extend documentation to explain relative file paths and comp_dir. Signed-off-by: Mark Wielaard --- libdw/ChangeLog | 6 ++++++ libdw/libdw.h | 17 ++++++++++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/libdw/ChangeLog b/libdw/ChangeLog index f552644..025b24a 100644 --- a/libdw/ChangeLog +++ b/libdw/ChangeLog @@ -1,3 +1,9 @@ +2018-03-29 Mark Wielaard + + * libdw.h (dwarf_decl_file): Extend documentation. + (dwarf_linesrc): Likewise. + (dwarf_filesrc): Likewise. + 2018-03-06 Mark Wielaard * dwarf.h: Add DW_OP_implicit_pointer, DW_OP_addrx, DW_OP_constx, diff --git a/libdw/libdw.h b/libdw/libdw.h index ac43ad9..0ca8878 100644 --- 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. */ -- 1.8.3.1