-/* 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. */
-