diff options
Diffstat (limited to 'common/path_utils/path_utils.h')
| -rw-r--r-- | common/path_utils/path_utils.h | 429 |
1 files changed, 0 insertions, 429 deletions
diff --git a/common/path_utils/path_utils.h b/common/path_utils/path_utils.h deleted file mode 100644 index 2fd567c4e..000000000 --- a/common/path_utils/path_utils.h +++ /dev/null @@ -1,429 +0,0 @@ -/* - Authors: - John Dennis <jdennis.redhat.com> - - Copyright (C) 2009 Red Hat - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with this program. If not, see <http://www.gnu.org/licenses/>. -*/ - -#ifndef PATH_UTILS_H -#define PATH_UTILS_H - -/*****************************************************************************/ -/******************************** Documentation ******************************/ -/*****************************************************************************/ - -/** @mainpage Pathname manipulation utilities - * - * This library contains a set of utilities designed to extract info from - * and manipulate path names. - * - */ - -/*****************************************************************************/ -/******************************* Include Files *******************************/ -/*****************************************************************************/ - -#include <stdbool.h> -#include <libintl.h> -#include <sys/param.h> -#include <sys/stat.h> - -/*****************************************************************************/ -/*********************************** Defines *********************************/ -/*****************************************************************************/ - -/** - * @defgroup constants Constants - * @{ - */ - -#ifndef _ -#define _(String) gettext(String) -#endif - -/** - * @brief SUCCESS (=0) is returned by all functions in the path_utils - * library on success. - */ -#ifndef SUCCESS -#define SUCCESS 0 -#endif - -/** - * @} - */ - -/** - * @defgroup errors Error codes and macros - * @{ - */ - -#define PATH_UTILS_ERROR_BASE -3000 -#define PATH_UTILS_ERROR_LIMIT (PATH_UTILS_ERROR_BASE+20) - -/** - * @brief You can use this macro to check if an error code is one of - * the internal path_utils codes. - */ -#define IS_PATH_UTILS_ERROR(error) (((error) >= PATH_UTILS_ERROR_BASE) && ((error) < PATH_UTILS_ERROR_LIMIT)) - -/** @brief A path cannot be normalized due to too many parent links - * - * Returned when a relative path contains too many parent (\c "..") links. - * Please see the documentation of \c normalize_path() for full explanation. - */ -#define PATH_UTILS_ERROR_NOT_FULLY_NORMALIZED (PATH_UTILS_ERROR_BASE + 1) - -/** - * @} - */ - -/*****************************************************************************/ -/******************************* Type Definitions ****************************/ -/*****************************************************************************/ - -/*****************************************************************************/ -/************************* External Global Variables ***********************/ -/*****************************************************************************/ - -/*****************************************************************************/ -/**************************** Exported Functions ***************************/ -/*****************************************************************************/ - -/** - * @defgroup functions Functions - * @{ - */ - -/** @brief Given an error code return the string description. - * - * @param[in] error The error code - * - * @return Error string. If error code is not recognized \c NULL is returned. - */ -const char *path_utils_error_string(int error); - -/** @brief Get the basename component of a path - * - * Given a path, copy the basename component (in the usual case, the part - * following the final "/") into the buffer \c base_name - * whose length is \c base_name_size. If the path does not contain a slash, - * \c get_basename() returns a copy of path. - * - * @param[out] base_name The basename component - * @param[in] base_name_size The size of the base_name buffer - * @param[in] path The full path to parse - * - * @return \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS if the buffer space is too small - * \li \c EINVAL The path was a NULL pointer - */ -int get_basename(char *base_name, size_t base_name_size, const char *path); - -/** @brief Copy the directory components of a path - * - * Given a path, copy the directory components (in the usual case, the path - * up to, but not including the final "/") into the buffer \c dir_path whose - * length is \c dir_path_size. If the path does not contain a slash, - * \c get_dirname() returns the current working directory. - * - * @param[out] dir_path The directory component - * @param[in] dir_path_size The size of the dir_path buffer - * @param[in] path The full path to parse - * - * @return \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS If the buffer space is too small - * \li \c EACCES Permission to read or search a component of the filename was denied. - * \li \c ENAMETOOLONG The size of the null-terminated pathname exceeds PATH_MAX bytes. - * \li \c ENOENT The current working directory has been unlinked. - * \li \c EINVAL The path was a NULL pointer - */ -int get_dirname(char *dir_path, size_t dir_path_size, const char *path); - -/** @brief Get the basaname and directory components of a path - * - * Given a path, copy the directory components into the buffer \c dir_path whose - * length is \c dir_path_size and copy the basename component into the buffer - * \c base_name whose length is \c base_name_size. - * - * @param[out] base_name The basename component - * @param[in] base_name_size The size of the base_name buffer - * @param[out] dir_path The directory component - * @param[in] dir_path_size The size of the dir_path buffer - * @param[in] path The full path to parse - * - * @return \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS If the buffer space is too small - * \li \c EACCES Permission to read or search a component of the filename was denied. - * \li \c ENAMETOOLONG The size of the null-terminated pathname exceeds PATH_MAX bytes. - * \li \c ENOENT The current working directory has been unlinked. - * \li \c EINVAL The path was a NULL pointer - */ -int get_directory_and_base_name(char *dir_path, size_t dir_path_size, - char *base_name, size_t base_name_size, - const char *path); - -/** @brief Tell if path is absolute or relative - * - * @param[in] path The path to check - * - * @return \c true if the path is absolute, \c false otherwise. - */ -bool is_absolute_path(const char *path); - -/** @brief Concatenate two components of a path - * - * Given two paths, \c head & \c tail, copy their concatenation into the - * buffer \c path whose length is \c path_size. - * - * @param[out] path The full path - * @param[in] path_size The size of the path buffer - * @param[in] head The first component of the path - * @param[in] tail The second component of the path - * - * @return \c SUCCESS if successful, non-zero error code otherwise. - * \li \c ENOBUFS If the buffer space is too small - */ -int path_concat(char *path, size_t path_size, const char *head, const char *tail); - -/** @brief Convert a path into absolute - * - * Given a path make it absolute storing the absolute path in into the buffer - * \c absolute_path whose length is \c absolute_path_size. - * - * Returns \c SUCCESS if successful, non-zero error code otherwise. Possible errors: - * \li \c ENOBUFS If the buffer space is too small - * \li \c ENOMEM If user memory cannot be mapped - * \li \c ENOENT If directory does not exist (i.e. it has been deleted) - * \li \c EFAULT If memory access violation occurs while copying - * \li \c EINVAL The path was a NULL pointer - */ -int make_path_absolute(char *absolute_path, size_t absolute_path_size, const char *path); - -/** @brief Split a file system path into individual components. - * - * Split a file system path into individual components. Return a pointer to an - * array of char pointers, each array entry is a pointer to a copy of the - * component. As a special case if the path begins with / then the first - * component is "/" so the caller can identify the pah as absolute with the - * first component being the root. The last entry in the array is \c NULL serving - * as a termination sentinel. An optional integer count parameter can be - * provided, which if non-NULL will have the number of components written into - * it. Thus the caller can iterate on the array until it sees a \c NULL pointer or - * iterate count times indexing the array. - * - * The caller is responsible for calling \c free() on the returned array. This - * frees both the array of component pointers and the copies of each component - * in one operation because the copy of each component is stored in the same - * allocation block. - * - * The original path parameter is not modified. - * - * In the event of an error \c NULL is returned and count (if specified) will be -1. - * - * Examples: - * - * \code - * char **components, **component; - * int i; - * - * components = split_path(path, NULL); - * for (component = components; *component; component++) - * printf("\"%s\" ", *component); - * free(components); - * \endcode - * - * -OR- - * - * \code - * components = split_path(path, &count); - * for (i = 0; i < count; i++) - * printf("\"%s\" ", components[i]); - * free(components); - * \endcode - * - * @param[in] path The original path - * @param[out] count The number of components the path was split into - * - * @return An array of char pointers, each array entry is a pointer to a - * copy of the component or NULL on error. - */ -char **split_path(const char *path, int *count); - -/** @brief Normalizes a path - * - * Normalizes a path copying the resulting normalized path into the buffer - * \c normalized_path whose length is \c normalized_size. - * - * A path is normalized when: - * \li only 1 slash separates all path components - * \li there are no \c . path components (except if \c . is the only component) - * \li there are no \c .. path components - * - * The input path may either be an absolute path or a path fragment. - * - * As a special case if the input path is \c NULL, the empty string \c "", - * or \c "." the returned normalized path will be \c ".". - * - * \c ".." path components point to the parent directory which effectively - * means poping the parent off the path. But what happens when there are - * more \c ".." path components than ancestors in the path? The answer depends - * on whether the path is an absolute path or a path fragment. If the path is - * absolute then the extra \c ".." components which would move above the root - * (/) are simply ignored. This effectively limits the path to the root. - * However if the path is not absolute, rather it is a path fragment, and - * there are more \c ".." components than ancestors which can be "popped off" - * then as many \c ".." components will be popped off the fragement as - * possible without changing the meaning of the path fragment. In this case - * some extra \c ".." components will be left in the path and the function - * will return the error \c ERROR_COULD_NOT_NORMALIZE_PATH_FULLY. However the - * function will still normalize as much of the path fragment as is possible. - * The behavior of \c ".." components when the input path is a fragment is - * adopted because after normalizing a path fragment then the normalized path - * fragment if made absolute should reference the same file system name as if - * the unnormalized fragment were made absolute. Note this also means - * \c ERROR_COULD_NOT_NORMALIZE_PATH_FULLY will never be returned if the input - * path is absolute. - * - * @returns \c SUCCESS if successful, non-zero error code otherwise. Possible - * errors: - * \li \c ENOBUFS If the buffer space is too small - * \li \c ERROR_COULD_NOT_NORMALIZE_PATH_FULLY If not all \c ".." path components could be removed - */ -int normalize_path(char *normalized_path, size_t normalized_path_size, const char *path); - -/** @brief Find the common prefix between two paths - * - * Finds the common prefix between two paths, returns the common prefix and - * optionally the count of how many path components were common between the - * two paths (if \c common_count is non-NULL). Please note that for absolute - * paths, the \c "/" root prefix is treated as a common components, so the - * paths \c "/usr/lib" and \c "/usr/share" would have two common components - - * \c "/" and \c "/usr". - * - * Contrary to some other implementations, \c common_path_prefix() works on - * path components, not characters, which guarantees at least some level of - * sanity of the returned prefixes (for example, the common prefix of - * \c "/usr/share" and \c "/usr/src" would be \c "/usr") - * - * @returns \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS if the buffer space is too small - */ -int common_path_prefix(char *common_path, - size_t common_path_size, - int *common_count, - const char *path1, const char *path2); - - -/** @brief Make the input path absolute if it's not already, then normalize it. - * - * @returns \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS if the buffer space is too small - */ -int make_normalized_absolute_path(char *result_path, size_t result_path_size, const char *path); - -/** - * Find the first path component which is an existing directory by walking from - * the tail of the path to it's head, return the path of the existing directory. - * - * If the pathname is relative and does not contain a directory, the current - * directory is returned as parent. - * - * @returns \c SUCCESS if successful, non-zero error code otherwise. - * Possible errors: - * \li \c ENOBUFS if the buffer space is too small - * \li \c EACCES Search permission is denied for one of the directories. - * \li \c ELOOP Too many symbolic links encountered while traversing the path. - * \li \c ENAMETOOLONG File name too long. - * \li \c ENOMEM Out of memory (i.e., kernel memory). - */ -int find_existing_directory_ancestor(char *ancestor, size_t ancestor_size, const char *path); - -/** @brief callback for the \c directory_list() function - * - * Please see the description of \c directory_list() to see more - * details about this callback - * - * @param[in] directory Directory name of the visited path - * @param[in] base_name Base name of the visited path - * @param[in] path Full name of the visited path - * @param[in] info Info about the visited directory - * @param[in] user_data Callback data passed by caller - * - * @returns if \c false, do not recursively descend into the directory, - * descend if \c true - */ -typedef bool (*directory_list_callback_t)(const char *directory, const char *base_name, - const char *path, struct stat *info, - void *user_data); -/** @brief Walk a directory. - * - * Walk a directory. If \c recursive is \c true child directories will be - * descended into. The supplied callback is invoked for each entry in the - * directory. - * - * The callback is provided with the directory name, basename, the full - * pathname (i.e. directory name + basename) a stat structure for the path - * item and a pointer to any user supplied data specified in the \c user_data - * parameter. If the callback returns \c false for a directory the recursive - * descent into that directory does not occur thus effectively "pruning" - * the tree. - * - * @param[in] path The path to examine - * @param[in] recursive Whether to recursively examine entries in the directory - * @param[in] callback The callback to invoke for each entry - * @param[in] user_data The data to pass into the callback - * - * @returns SUCCESS if successfull, an error code if not. - */ -int directory_list(const char *path, bool recursive, - directory_list_callback_t callback, void *user_data); - -/** @brief Tell if one path is ancestor of another - * - * Test to see if the path passed in the \c ancestor parameter is an ancestor - * of the path passed in the path parameter returning true if it is, \c false - * otherwise. - * - * The test is "static" as such it is performed on the string components in - * each path. Live symbolic links in the file system are not taken into - * consideration. The test operates by splitting each path into it's individual - * components and then comparing each component pairwise for string - * equality. Both paths mush share a common root component for the test to be - * meaningful (e.g. don't attempt to compare an absolute path with a relative - * path). - * - * Example: - * \code - * is_ancestor_path("/a/b/c" "/a/b/c/d") => true - * is_ancestor_path("/a/b/c/d" "/a/b/c/d") => false // equal, not ancestor - * is_ancestor_path("/a/x/c" "/a/b/c/d") => false - * \endcode - * - * @returns \c true if \c ancestor is an ancestor of \c path - */ -bool is_ancestor_path(const char *ancestor, const char *path); - -/** - * @} - */ - -#endif /* PATH_UTILS_H */ |