Re: Relative path X full path

[Mark Wielaard <mark at klomp dot org>]

On Mon, 2018-03-26 at 21:11 +0200, Torsten Polle wrote:
> > Am 26.03.2018 um 18:45 schrieb Sasha Da Rocha Pinheiro <darochapinh
> > e@wisc.edu>:
> > 
> > I have noticed that when we compile out-of-source, the paths
> > returned from libdw are gonna be relative. Otherwise, they show up
> > as full path.
> > Have you noticed it?
> > 
> this is the issue that was discussed in [1] and [2].
>
> [1] https://sourceware.org/ml/elfutils-devel/2017-q1/msg00117.html
> [2] https://sourceware.org/ml/elfutils-devel/2017-q2/msg00148.html

It does indeed come up more often, and it is a little confusing.
So I am proposing the following documentation update to hopefully
explain better how to get the absolute path for a file (decl).

Hopefully this helps.

Cheers,

Mark

From e87cfeb2290bff320c7f0a45f93ba571ffe3c58d Mon Sep 17 00:00:00 2001
From: Mark Wielaard <mark@klomp.org>
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 <mark@klomp.org>
---
 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  <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 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