From c0800cf0d482f78782c1c877535c8f4b717999e4 Mon Sep 17 00:00:00 2001 From: twinaphex Date: Thu, 8 Jan 2015 23:08:53 +0100 Subject: [PATCH] (SDK) Document file_path.c --- libretro-sdk/file/file_path.c | 285 +++++++++++++++++++++++++- libretro-sdk/include/file/file_path.h | 248 +++++++++++++++++++--- 2 files changed, 491 insertions(+), 42 deletions(-) diff --git a/libretro-sdk/file/file_path.c b/libretro-sdk/file/file_path.c index 146ce4e10a..d60d4f683e 100644 --- a/libretro-sdk/file/file_path.c +++ b/libretro-sdk/file/file_path.c @@ -66,6 +66,15 @@ #include #endif +/** + * path_get_extension: + * @path : path + * + * Gets extension of file. Only '.'s + * after the last slash are considered. + * + * Returns: extension part from the path. + */ const char *path_get_extension(const char *path) { const char *ext = strrchr(path_basename(path), '.'); @@ -74,6 +83,16 @@ const char *path_get_extension(const char *path) return ext + 1; } +/** + * path_remove_extension: + * @path : path + * + * Removes the extension from the path and returns the result. + * Removes all text after and including the last '.'. + * Only '.'s after the last slash are considered. + * + * Returns: path with the extension part removed. + */ char *path_remove_extension(char *path) { char *last = (char*)strrchr(path_basename(path), '.'); @@ -82,6 +101,14 @@ char *path_remove_extension(char *path) return last; } +/** + * path_char_is_slash: + * @c : character + * + * Checks if character (@c) is a slash. + * + * Returns: true (1) if character is a slash, otherwise false (0). + */ static bool path_char_is_slash(char c) { #ifdef _WIN32 @@ -91,6 +118,13 @@ static bool path_char_is_slash(char c) #endif } +/** + * path_default_slash: + * + * Gets the default slash separator. + * + * Returns: default slash separator. + */ static const char *path_default_slash(void) { #ifdef _WIN32 @@ -100,15 +134,33 @@ static const char *path_default_slash(void) #endif } +/** + * path_contains_compressed_file: + * @path : path + * + * Checks if path contains a compressed file. + * + * Currently we only check for hash symbol (#) inside the pathname. + * If path is ever expanded to a general URI, we should check for that here. + * + * Example: Somewhere in the path there might be a compressed file + * E.g.: /path/to/file.7z#mygame.img + * + * Returns: true (1) if path contains compressed file, otherwise false (0). + **/ bool path_contains_compressed_file(const char *path) { - /* - * Currently we only check for hash symbol inside the pathname. - * If path is ever expanded to a general URI, we should check for that here. - */ return (strchr(path,'#') != NULL); } +/** + * path_is_compressed_file: + * @path : path + * + * Checks if path is a compressed file. + * + * Returns: true (1) if path is a compressed file, otherwise false (0). + **/ bool path_is_compressed_file(const char* path) { #ifdef HAVE_COMPRESSION @@ -126,6 +178,14 @@ bool path_is_compressed_file(const char* path) return false; } +/** + * path_is_directory: + * @path : path + * + * Checks if path is a directory. + * + * Returns: true (1) if path is a directory, otherwise false (0). + */ bool path_is_directory(const char *path) { #ifdef _WIN32 @@ -140,6 +200,14 @@ bool path_is_directory(const char *path) #endif } +/** + * path_file_exists: + * @path : path + * + * Checks if a file already exists at the specified path (@path). + * + * Returns: true (1) if file already exists, otherwise false (0). + */ bool path_file_exists(const char *path) { FILE *dummy = fopen(path, "rb"); @@ -151,6 +219,27 @@ bool path_file_exists(const char *path) return true; } +/** + * fill_pathname: + * @out_path : output path + * @in_path : input path + * @replace : what to replace + * @size : buffer size of output path + * + * FIXME: Verify + * + * Replaces filename extension with 'replace' and outputs result to out_path. + * The extension here is considered to be the string from the last '.' + * to the end. + * + * Only '.'s after the last slash are considered as extensions. + * If no '.' is present, in_path and replace will simply be concatenated. + * 'size' is buffer size of 'out_path'. + * E.g.: in_path = "/foo/bar/baz/boo.c", replace = ".asm" => + * out_path = "/foo/bar/baz/boo.asm" + * E.g.: in_path = "/foo/bar/baz/boo.c", replace = "" => + * out_path = "/foo/bar/baz/boo" + */ void fill_pathname(char *out_path, const char *in_path, const char *replace, size_t size) { @@ -166,6 +255,20 @@ void fill_pathname(char *out_path, const char *in_path, rarch_assert(strlcat(out_path, replace, size) < size); } +/** + * fill_pathname_noext: + * @out_path : output path + * @in_path : input path + * @replace : what to replace + * @size : buffer size of output path + * + * Appends a filename extension 'replace' to 'in_path', and outputs + * result in 'out_path'. + * + * Assumes in_path has no extension. If an extension is still + * present in 'in_path', it will be ignored. + * + */ void fill_pathname_noext(char *out_path, const char *in_path, const char *replace, size_t size) { @@ -186,14 +289,20 @@ static char *find_last_slash(const char *str) return (char*)slash; } -/* Assumes path is a directory. Appends a slash - * if not already there. */ +/** + * fill_pathname_slash: + * @path : path + * @size : size of path + * + * Assumes path is a directory. Appends a slash + * if not already there. + **/ void fill_pathname_slash(char *path, size_t size) { size_t path_len = strlen(path); const char *last_slash = find_last_slash(path); - // Try to preserve slash type. + /* Try to preserve slash type. */ if (last_slash && (last_slash != (path + path_len - 1))) { char join_str[2] = {*last_slash}; @@ -203,6 +312,23 @@ void fill_pathname_slash(char *path, size_t size) rarch_assert(strlcat(path, path_default_slash(), size) < size); } +/** + * fill_pathname_dir: + * @in_dir : input directory path + * @in_basename : input basename to be appended to @in_dir + * @replace : replacement to be appended to @in_basename + * @size : size of buffer + * + * Appends basename of 'in_basename', to 'in_dir', along with 'replace'. + * Basename of in_basename is the string after the last '/' or '\\', + * i.e the filename without directories. + * + * If in_basename has no '/' or '\\', the whole 'in_basename' will be used. + * 'size' is buffer size of 'in_dir'. + * + * E.g..: in_dir = "/tmp/some_dir", in_basename = "/some_content/foo.c", + * replace = ".asm" => in_dir = "/tmp/some_dir/foo.c.asm" + **/ void fill_pathname_dir(char *in_dir, const char *in_basename, const char *replace, size_t size) { @@ -213,6 +339,14 @@ void fill_pathname_dir(char *in_dir, const char *in_basename, rarch_assert(strlcat(in_dir, replace, size) < size); } +/** + * fill_pathname_base: + * @out : output path + * @in_path : input path + * @size : size of output path + * + * Copies basename of @in_path into @out_path. + **/ void fill_pathname_base(char *out, const char *in_path, size_t size) { const char *ptr = find_last_slash(in_path); @@ -241,6 +375,16 @@ void fill_pathname_base(char *out, const char *in_path, size_t size) rarch_assert(strlcpy(out, ptr, size) < size); } +/** + * fill_pathname_basedir: + * @out_dir : output directory + * @in_path : input path + * @size : size of output directory + * + * Copies base directory of @in_path into @out_path. + * If in_path is a path without any slashes (relative current directory), + * @out_path will get path "./". + **/ void fill_pathname_basedir(char *out_dir, const char *in_path, size_t size) { @@ -248,6 +392,15 @@ void fill_pathname_basedir(char *out_dir, path_basedir(out_dir); } +/** + * fill_pathname_parent_dir: + * @out_dir : output directory + * @in_dir : input directory + * @size : size of output directory + * + * Copies parent directory of @in_dir into @out_dir. + * Assumes @in_dir is a directory. Keeps trailing '/'. + **/ void fill_pathname_parent_dir(char *out_dir, const char *in_dir, size_t size) { @@ -255,6 +408,18 @@ void fill_pathname_parent_dir(char *out_dir, path_parent_dir(out_dir); } +/** + * fill_dated_filename: + * @out_filename : output filename + * @ext : extension of output filename + * @size : buffer size of output filename + * + * Creates a 'dated' filename prefixed by 'RetroArch', and + * concatenates extension (@ext) to it. + * + * E.g.: + * out_filename = "RetroArch-{month}{day}-{Hours}{Minutes}.{@ext}" + **/ void fill_dated_filename(char *out_filename, const char *ext, size_t size) { @@ -266,6 +431,13 @@ void fill_dated_filename(char *out_filename, strlcat(out_filename, ext, size); } +/** + * path_basedir: + * @path : path + * + * Extracts base directory by mutating path. + * Keeps trailing '/'. + **/ void path_basedir(char *path) { char *last = NULL; @@ -287,6 +459,13 @@ void path_basedir(char *path) snprintf(path, 3, ".%s", path_default_slash()); } +/** + * path_parent_dir: + * @path : path + * + * Extracts parent directory by mutating path. + * Assumes that path is a directory. Keeps trailing '/'. + **/ void path_parent_dir(char *path) { size_t len = strlen(path); @@ -295,12 +474,20 @@ void path_parent_dir(char *path) path_basedir(path); } +/** + * path_basename: + * @path : path + * + * Get basename from @path. + * + * Returns: basename from path. + **/ const char *path_basename(const char *path) { const char *last = find_last_slash(path); - /* We cut either at the last hash or the last slash; whichever comes last */ #ifdef HAVE_COMPRESSION + /* We cut either at the last hash or the last slash; whichever comes last */ const char *last_hash = strchr(path,'#'); if (last_hash > last) return last_hash + 1; @@ -311,6 +498,14 @@ const char *path_basename(const char *path) return path; } +/** + * path_is_absolute: + * @path : path + * + * Checks if @path is an absolute path or a relative path. + * + * Returns: true (1) if path is absolute, false (1) if path is relative. + **/ bool path_is_absolute(const char *path) { #ifdef _WIN32 @@ -322,6 +517,14 @@ bool path_is_absolute(const char *path) #endif } +/** + * path_resolve_realpath: + * @buf : buffer for path + * @size : size of buffer + * + * Turns relative paths into absolute path. + * If relative, rebases on current working dir. + **/ void path_resolve_realpath(char *buf, size_t size) { #ifndef RARCH_CONSOLE @@ -348,6 +551,14 @@ void path_resolve_realpath(char *buf, size_t size) #endif } +/** + * path_mkdir_norecurse: + * @dir : directory + * + * Create directory on filesystem. + * + * Returns: true (1) if directory could be created, otherwise false (0). + **/ static bool path_mkdir_norecurse(const char *dir) { int ret; @@ -366,6 +577,14 @@ static bool path_mkdir_norecurse(const char *dir) return ret == 0; } +/** + * path_mkdir: + * @dir : directory + * + * Create directory on filesystem. + * + * Returns: true (1) if directory could be created, otherwise false (0). + **/ bool path_mkdir(const char *dir) { const char *target = NULL; @@ -406,6 +625,18 @@ end: return ret; } +/** + * fill_pathname_resolve_relative: + * @out_path : output path + * @in_refpath : input reference path + * @in_path : input path + * @size : size of @out_path + * + * Joins basedir of @in_refpath together with @in_path. + * If @in_path is an absolute path, out_path = in_path. + * E.g.: in_refpath = "/foo/bar/baz.a", in_path = "foobar.cg", + * out_path = "/foo/bar/foobar.cg". + **/ void fill_pathname_resolve_relative(char *out_path, const char *in_refpath, const char *in_path, size_t size) { @@ -419,6 +650,17 @@ void fill_pathname_resolve_relative(char *out_path, } } +/** + * fill_pathname_join: + * @out_path : output path + * @dir : directory + * @path : path + * @size : size of output path + * + * Joins a directory (@dir) and path (@path) together. + * Makes sure not to get two consecutive slashes + * between directory and path. + **/ void fill_pathname_join(char *out_path, const char *dir, const char *path, size_t size) { @@ -430,6 +672,17 @@ void fill_pathname_join(char *out_path, rarch_assert(strlcat(out_path, path, size) < size); } +/** + * fill_pathname_join_delim: + * @out_path : output path + * @dir : directory + * @path : path + * @delim : delimiter + * @size : size of output path + * + * Joins a directory (@dir) and path (@path) together + * using the given delimiter (@delim). + **/ void fill_pathname_join_delim(char *out_path, const char *dir, const char *path, const char delim, size_t size) { @@ -483,6 +736,21 @@ void fill_pathname_expand_special(char *out_path, rarch_assert(strlcpy(out_path, in_path, size) < size); } +/** + * fill_short_pathname_representation: + * @out_rep : output representation + * @in_path : input path + * @size : size of output representation + * + * Generates a short representation of path. It should only + * be used for displaying the result; the output representation is not + * binding in any meaningful way (for a normal path, this is the same as basename) + * In case of more complex URLs, this should cut everything except for + * the main image file. + * + * E.g.: "/path/to/game.img" -> game.img + * "/path/to/myarchive.7z#folder/to/game.img" -> game.img + */ void fill_short_pathname_representation(char* out_rep, const char *in_path, size_t size) { @@ -507,7 +775,6 @@ void fill_short_pathname_representation(char* out_rep, strlcpy(out_rep,path_short, size); } - void fill_pathname_abbreviate_special(char *out_path, const char *in_path, size_t size) { diff --git a/libretro-sdk/include/file/file_path.h b/libretro-sdk/include/file/file_path.h index c8e9bfd8e3..5793f55b80 100644 --- a/libretro-sdk/include/file/file_path.h +++ b/libretro-sdk/include/file/file_path.h @@ -47,47 +47,141 @@ enum }; -/* path_is_compressed_file also means: The compressed file is supported */ +/** + * path_is_compressed_file: + * @path : path + * + * Checks if path is a compressed file. + * + * Returns: true (1) if path is a compressed file, otherwise false (0). + **/ bool path_is_compressed_file(const char *path); -/* Somewhere in the path there might be a compressed file +/** + * path_contains_compressed_file: + * @path : path + * + * Checks if path contains a compressed file. + * + * Currently we only check for hash symbol (#) inside the pathname. + * If path is ever expanded to a general URI, we should check for that here. + * + * Example: Somewhere in the path there might be a compressed file * E.g.: /path/to/file.7z#mygame.img - */ + * + * Returns: true (1) if path contains compressed file, otherwise false (0). + **/ bool path_contains_compressed_file(const char *path); +/** + * path_is_directory: + * @path : path + * + * Checks if path is a directory. + * + * Returns: true (1) if path is a directory, otherwise false (0). + */ bool path_is_directory(const char *path); +/** + * path_file_exists: + * @path : path + * + * Checks if a file already exists at the specified path (@path). + * + * Returns: true (1) if file already exists, otherwise false (0). + */ bool path_file_exists(const char *path); -/* Gets extension of file. Only '.'s after the last slash are considered. */ +/** + * path_get_extension: + * @path : path + * + * Gets extension of file. Only '.'s + * after the last slash are considered. + * + * Returns: extension part from the path. + */ const char *path_get_extension(const char *path); +/** + * path_mkdir: + * @dir : directory + * + * Create directory on filesystem. + * + * Returns: true (1) if directory could be created, otherwise false (0). + **/ bool path_mkdir(const char *dir); -/* Removes all text after and including the last '.'. - * Only '.'s after the last slash are considered. */ +/** + * path_remove_extension: + * @path : path + * + * Removes the extension from the path and returns the result. + * Removes all text after and including the last '.'. + * Only '.'s after the last slash are considered. + * + * Returns: path with the extension part removed. + */ char *path_remove_extension(char *path); -/* Returns basename from path. */ +/** + * path_basename: + * @path : path + * + * Get basename from @path. + * + * Returns: basename from path. + **/ const char *path_basename(const char *path); -/* Extracts base directory by mutating path. - * Keeps trailing '/'. */ +/** + * path_basedir: + * @path : path + * + * Extracts base directory by mutating path. + * Keeps trailing '/'. + **/ void path_basedir(char *path); -/* Extracts parent directory by mutating path. - * Assumes that path is a directory. Keeps trailing '/'. */ +/** + * path_parent_dir: + * @path : path + * + * Extracts parent directory by mutating path. + * Assumes that path is a directory. Keeps trailing '/'. + **/ void path_parent_dir(char *path); -/* Turns relative paths into absolute path. - * If relative, rebases on current working dir. */ +/** + * path_resolve_realpath: + * @buf : buffer for path + * @size : size of buffer + * + * Turns relative paths into absolute path. + * If relative, rebases on current working dir. + **/ void path_resolve_realpath(char *buf, size_t size); +/** + * path_is_absolute: + * @path : path + * + * Checks if @path is an absolute path or a relative path. + * + * Returns: true (1) if path is absolute, false (1) if path is relative. + **/ bool path_is_absolute(const char *path); -/* Path-name operations. - * If any of these operation are detected to overflow, the application will - * be terminated. +/** + * fill_pathname: + * @out_path : output path + * @in_path : input path + * @replace : what to replace + * @size : buffer size of output path + * + * FIXME: Verify * * Replaces filename extension with 'replace' and outputs result to out_path. * The extension here is considered to be the string from the last '.' @@ -104,20 +198,46 @@ bool path_is_absolute(const char *path); void fill_pathname(char *out_path, const char *in_path, const char *replace, size_t size); +/** + * fill_dated_filename: + * @out_filename : output filename + * @ext : extension of output filename + * @size : buffer size of output filename + * + * Creates a 'dated' filename prefixed by 'RetroArch', and + * concatenates extension (@ext) to it. + * + * E.g.: + * out_filename = "RetroArch-{month}{day}-{Hours}{Minutes}.{@ext}" + **/ void fill_dated_filename(char *out_filename, const char *ext, size_t size); -/* Appends a filename extension 'replace' to 'in_path', and outputs +/** + * fill_pathname_noext: + * @out_path : output path + * @in_path : input path + * @replace : what to replace + * @size : buffer size of output path + * + * Appends a filename extension 'replace' to 'in_path', and outputs * result in 'out_path'. * * Assumes in_path has no extension. If an extension is still * present in 'in_path', it will be ignored. * - * 'size' is buffer size of 'out_path'. */ + */ void fill_pathname_noext(char *out_path, const char *in_path, const char *replace, size_t size); -/* Appends basename of 'in_basename', to 'in_dir', along with 'replace'. +/** + * fill_pathname_dir: + * @in_dir : input directory path + * @in_basename : input basename to be appended to @in_dir + * @replace : replacement to be appended to @in_basename + * @size : size of buffer + * + * Appends basename of 'in_basename', to 'in_dir', along with 'replace'. * Basename of in_basename is the string after the last '/' or '\\', * i.e the filename without directories. * @@ -126,45 +246,99 @@ void fill_pathname_noext(char *out_path, const char *in_path, * * E.g..: in_dir = "/tmp/some_dir", in_basename = "/some_content/foo.c", * replace = ".asm" => in_dir = "/tmp/some_dir/foo.c.asm" - * - * */ + **/ void fill_pathname_dir(char *in_dir, const char *in_basename, const char *replace, size_t size); -/* Copies basename of in_path into out_path. */ +/** + * fill_pathname_base: + * @out : output path + * @in_path : input path + * @size : size of output path + * + * Copies basename of @in_path into @out_path. + **/ void fill_pathname_base(char *out_path, const char *in_path, size_t size); -/* Copies base directory of in_path into out_path. +/** + * fill_pathname_basedir: + * @out_dir : output directory + * @in_path : input path + * @size : size of output directory + * + * Copies base directory of @in_path into @out_path. * If in_path is a path without any slashes (relative current directory), - * out_path will get path "./". */ + * @out_path will get path "./". + **/ void fill_pathname_basedir(char *out_path, const char *in_path, size_t size); -/* Copies parent directory of in_dir into out_dir. - * Assumes in_dir is a directory. Keeps trailing '/'. */ +/** + * fill_pathname_parent_dir: + * @out_dir : output directory + * @in_dir : input directory + * @size : size of output directory + * + * Copies parent directory of @in_dir into @out_dir. + * Assumes @in_dir is a directory. Keeps trailing '/'. + **/ void fill_pathname_parent_dir(char *out_dir, const char *in_dir, size_t size); -/* Joins basedir of in_refpath together with in_path. - * If in_path is an absolute path, out_path = in_path. +/** + * fill_pathname_resolve_relative: + * @out_path : output path + * @in_refpath : input reference path + * @in_path : input path + * @size : size of @out_path + * + * Joins basedir of @in_refpath together with @in_path. + * If @in_path is an absolute path, out_path = in_path. * E.g.: in_refpath = "/foo/bar/baz.a", in_path = "foobar.cg", - * out_path = "/foo/bar/foobar.cg". */ + * out_path = "/foo/bar/foobar.cg". + **/ void fill_pathname_resolve_relative(char *out_path, const char *in_refpath, const char *in_path, size_t size); -/* Joins a directory and path together. Makes sure not to get - * two consecutive slashes between dir and path. */ +/** + * fill_pathname_join: + * @out_path : output path + * @dir : directory + * @path : path + * @size : size of output path + * + * Joins a directory (@dir) and path (@path) together. + * Makes sure not to get two consecutive slashes + * between directory and path. + **/ void fill_pathname_join(char *out_path, const char *dir, const char *path, size_t size); -/* Joins a directory and path together using the given char. */ +/** + * fill_pathname_join_delim: + * @out_path : output path + * @dir : directory + * @path : path + * @delim : delimiter + * @size : size of output path + * + * Joins a directory (@dir) and path (@path) together + * using the given delimiter (@delim). + **/ void fill_pathname_join_delim(char *out_path, const char *dir, const char *path, const char delim, size_t size); -/* Generates a short representation of path. It should only +/** + * fill_short_pathname_representation: + * @out_rep : output representation + * @in_path : input path + * @size : size of output representation + * + * Generates a short representation of path. It should only * be used for displaying the result; the output representation is not * binding in any meaningful way (for a normal path, this is the same as basename) * In case of more complex URLs, this should cut everything except for * the main image file. + * * E.g.: "/path/to/game.img" -> game.img * "/path/to/myarchive.7z#folder/to/game.img" -> game.img */ @@ -177,6 +351,14 @@ void fill_pathname_expand_special(char *out_path, void fill_pathname_abbreviate_special(char *out_path, const char *in_path, size_t size); +/** + * fill_pathname_slash: + * @path : path + * @size : size of path + * + * Assumes path is a directory. Appends a slash + * if not already there. + **/ void fill_pathname_slash(char *path, size_t size); #ifndef RARCH_CONSOLE