diff --git a/src/app-utils/file-utils.c b/src/app-utils/file-utils.c index c5a5f7a55d..4ed79ea1c3 100644 --- a/src/app-utils/file-utils.c +++ b/src/app-utils/file-utils.c @@ -65,42 +65,42 @@ gncFindFile (const char * filename) } /********************************************************************\ - * htmlRead * + * gncReadFile * * * - * Args: file - the name of the html file to read * + * Args: filename - the name of the html file to read * * data - pointer to set to the buffer of data read in * * Return: size of data read * * Global: helpPath - the path to the help files * \********************************************************************/ int -gncReadFile (const char * file, char ** data) +gncReadFile (const char * filename, char ** data) { char *buf = NULL; - char *filename; + char *fullname; int size = 0; int fd; /* construct absolute path -- twiddle the relative path we received */ - if (!file || file[0] == '\0') return 0; + if (!filename || filename[0] == '\0') return 0; /* take absolute paths without searching */ - if (!g_path_is_absolute (file)) - filename = gncFindFile (file); + if (!g_path_is_absolute (filename)) + fullname = gncFindFile (filename); else - filename = g_strdup (file); + fullname = g_strdup (filename); - if (!filename) return 0; + if (!fullname) return 0; /* Open file: */ - fd = g_open( filename, O_RDONLY, 0 ); + fd = g_open( fullname, O_RDONLY, 0 ); - g_free(filename); - filename = NULL; + g_free(fullname); + fullname = NULL; if ( fd == -1 ) { int norr = errno; - PERR ("file %s: (%d) %s \n", file, norr, strerror(norr)); + PERR ("file %s: (%d) %s \n", filename, norr, strerror(norr)); return 0; } @@ -128,7 +128,7 @@ gncReadFile (const char * file, char ** data) return size; } -/** +/*********************************************************************** * gnc_getline -- read a line from the input file, up to and including * the newline. * diff --git a/src/app-utils/file-utils.h b/src/app-utils/file-utils.h index b5a9b9057c..16aaa3a835 100644 --- a/src/app-utils/file-utils.h +++ b/src/app-utils/file-utils.h @@ -25,36 +25,69 @@ * Huntington Beach, CA 92648-4632 * \********************************************************************/ +/** @addtogroup Utils Utility functions + @{ */ +/** @addtogroup UtilFile File + * @{ */ +/** @file file-utils.h + * @brief Utility functions for file access + * @author Copyright (C) 1997 Robin D. Clark + * @author Copyright (C) 1998 Linas Vepstas + * @author Copyright (C) 1998 Rob Browning + * @author Copyright (C) 2004 Derek Atkins + * + * These functions help you to locate files that can reside + * in multiple locations. + */ #ifndef GNC_FILE_UTILS_H #define GNC_FILE_UTILS_H #include /* for FILE* */ +/** Locates a file in the search path of the program and + * returns its absolute pathname. + * + * If the file is not found + * this function will return NULL. + * + * Uses the global xxxPath as the path to search + * + * @param filename The filename to search + * + * @return The absolute path to the file or NULL if the file + * wasn't found. + */ char * gncFindFile (const char * filename); -/********************************************************************\ - * gncReadFile * - * * - * Args: file - the name of the html file to read * - * data - pointer to data pointer * - * Return: file size * - * Global: xxxPath - the path to search * -\********************************************************************/ -int gncReadFile (const char * file, char ** data); +/** Reads the contents of a file into a buffer for further processing. + * + * If the filename is not an absolute filename, it will be searched + * for in the search path available to the program. This can be used + * to find for example help files,... + * + * Uses the global xxxPath as the path to search + * + * @param filename the name of the html file to read + * + * @param data Pointer to a buffer to store the file's content. + * + * @return The file size +*/ +int gncReadFile (const char * filename, char ** data); -/** - * gnc_getline -- read a line from the input file, up to and including - * the newline. +/** Read a line from the input file, up to and including the newline. * - * Args: line - pointer to hold the buffer for the whole line (allocated by - * this function) - * file - the file from which to read - * Return: the number of bytes read + * The caller MUST g_free() the line returned from this call in all + * cases where it is non-NULL! * - * The caller MUST g_free() the line returned from this call in all - * cases where it is non-NULL! + * @param line pointer to hold the buffer for the whole line (allocated by + * this function) + * + * @param file the file from which to read + * + * @return The number of bytes read */ gint64 gnc_getline (gchar **line, FILE *file); @@ -64,12 +97,13 @@ gint64 gnc_getline (gchar **line, FILE *file); #define STATE_FILE_BOOK_GUID "BookGuid" #define STATE_FILE_BOOK_GUID_OLD "Book Guid" -/** Find the state file that corresponds to this URL and guid. The - * URL is used to compute the base name of the file (which will be in +/** Find the state file that corresponds to this URL and guid. + * + * The URL is used to compute the base name of the file (which will be in * ~/.gnucash/books) and the guid is used to differentiate when the * user has multiple data files with the same name. * - * @param url The usrl of the data file being used. + * @param url The url of the data file being used. * * @param guid The guid of the book associated with this data file. * @@ -81,3 +115,6 @@ gint64 gnc_getline (gchar **line, FILE *file); GKeyFile *gnc_find_state_file (const gchar *url, const gchar *guid, gchar **filename); #endif /* GNC_FILE_UTILS_H */ +/** @} */ +/** @} */ +