2012-03-01 Pedro Alves <palves@redhat.com>

[deliverable/binutils-gdb.git] / gdb / source.h

diff --git a/gdb/source.h b/gdb/source.h
index 3ee8e532bb52ea2be0c6c810eae7a28e17083c2e..bf9a688903081f504da61c7fb4bca8b420d59d9e 100644 (file)
--- a/gdb/source.h
+++ b/gdb/source.h
@@ -21,6 +21,29 @@
 
 struct symtab;
 
+/* This function is capable of finding the absolute path to a
+   source file, and opening it, provided you give it a FILENAME.  Both the
+   DIRNAME and FULLNAME are only added suggestions on where to find the file.
+
+   FILENAME should be the filename to open.
+   DIRNAME is the compilation directory of a particular source file.
+          Only some debug formats provide this info.
+   FULLNAME can be the last known absolute path to the file in question.
+     Space for the path must have been malloc'd.  If a path substitution
+     is applied we free the old value and set a new one.
+
+   On Success
+     A valid file descriptor is returned (the return value is positive).
+     FULLNAME is set to the absolute path to the file just opened.
+     The caller is responsible for freeing FULLNAME.
+
+   On Failure
+     An invalid file descriptor is returned (the return value is negative).
+     FULLNAME is set to NULL.  */
+extern int find_and_open_source (const char *filename,
+                                const char *dirname,
+                                char **fullname);
+
 /* Open a source file given a symtab S.  Returns a file descriptor or
    negative number for error.  */
 extern int open_source_file (struct symtab *s);