From 8cb65bf1d70dd23e226a361ca9f75dbdc531849a Mon Sep 17 00:00:00 2001 From: Ingo Weinhold Date: Tue, 19 Nov 2013 02:04:08 +0100 Subject: [PATCH] Add find_path*() API docs, improve FindDirectory.h docs --- docs/user/storage/FindDirectory.dox | 680 +++++++++++++++++++++++++--- 1 file changed, 628 insertions(+), 52 deletions(-) diff --git a/docs/user/storage/FindDirectory.dox b/docs/user/storage/FindDirectory.dox index 1dd98a11f0..afa310ad40 100644 --- a/docs/user/storage/FindDirectory.dox +++ b/docs/user/storage/FindDirectory.dox @@ -1,14 +1,15 @@ /* - * Copyright 2011-2013 Haiku Inc. All rights reserved. + * Copyright 2011-2013, Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Documentation by: * Adrien Destugues, pulkomandy@pulkomandy.ath.cx * John Scipione, jscipione@gmail.com + * Ingo Weinhold, ingo_weinhold@gmx.de * * Corresponds to: - * headers/os/storage/FindDirectory.h hrev46316 - * src/kits/storage/FindDirectory.cpp hrev46316 + * headers/os/storage/FindDirectory.h hrev46390 + * src/kits/storage/FindDirectory.cpp hrev46390 */ @@ -16,17 +17,45 @@ \file FindDirectory.h \ingroup storage \ingroup libbe - \brief Provides the find_directory function. + \brief Provides the find_directory(), find_path(), find_paths(), etc. + functions. Haiku provides a set of directories for applications to use. These can be - accessed using the find_directory function. It is very important to use the - function at runtime and not hardcode the path, as it may change in future - versions of Haiku, and already changed in past ones. Using this function - makes your application more future-proof, and makes sure everyone puts data - in the same place, which makes the system cleaner and easier to manage. + accessed using the functions find_directory(), find_path(), find_path_etc(), + find_paths(), find_paths_etc(), find_path_for_path(), + find_path_for_path_etc(). It is very important to use the functions at + runtime and not hardcode the path, as it may change in future versions of + Haiku, and already changed in past ones. Using these functions makes your + application more future-proof, and makes sure everyone puts data in the same + place, which makes the system cleaner and easier to manage. - Note this function can be accessed from C code, to make it easy to use also - in ported applications. + Note that while the find_directory() function is still needed for some, it + is deprecated for many other use cases, like: + - When collecting files from all installation locations, be it data files + (like fonts) or add-ons your application/library supports, use + find_paths(), find_paths_etc(), or BPathFinder::FindPaths() instead. + Formerly you had to use find_directory() and iterate through all possible + constants manually. Not only is this less convenient, it also doesn't + account for the possibility of installation locations being added or + removed in a later Haiku release. + - If your code needs to access another file that also belongs to your + software (i.e. if packaged it is included in the same package), use + find_path() or BPathFinder::FindPath() instead. + Formerly this case could not really be handled properly. Either you had + to hard-code the installation location by using the respective directory + constant or you had to manually construct a path relative to your code's + image file. + + Cases for which find_directory() is still useful: + - Getting per-volume paths like for the trash directory. + - Getting specific paths like for the user's home directory or the user's + settings directory. + + Note that these functions can be accessed from C code (they are implemented + in libroot), to make it easy to use also in ported applications. However, + there are also a C++ version of find_directory() and the BPathFinder class + (both implemented in libbe), which may be more convenient to use in C++ + code. */ @@ -77,15 +106,15 @@ The system servers directory. \var directory_which B_SYSTEM_APPS_DIRECTORY - The system applications directory. Contains applications executable from - Tracker. + The system applications directory. Contains applications with graphical + user interface. \var directory_which B_SYSTEM_BIN_DIRECTORY The system bin directory. Contains command-line applications runnable from Terminal. \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY - The system documentation directory. Contains manpages. + The system documentation directory. Contains e.g. man pages. \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY The system preferences directory. @@ -101,41 +130,76 @@ \var directory_which B_SYSTEM_DATA_DIRECTORY The system data directory. + + \var directory_which B_SYSTEM_DEVELOP_DIRECTORY + The system directory containing development related files. + + \var directory_which B_SYSTEM_PACKAGES_DIRECTORY + The system directory where activated packages live. + + \var directory_which B_SYSTEM_HEADERS_DIRECTORY + The system directory for development header files. + + \var directory_which B_SYSTEM_ETC_DIRECTORY + The system directory used for Unix-like installation location wide settings + (Unix "etc" directory). + + \var directory_which B_SYSTEM_SETTINGS_DIRECTORY + The system directory used for installation location wide settings. + + \var directory_which B_SYSTEM_LOG_DIRECTORY + The system directory where log files are put. + + \var directory_which B_SYSTEM_SPOOL_DIRECTORY + The system directory for spool data (e.g. pending printer jobs). + + \var directory_which B_SYSTEM_TEMP_DIRECTORY + The global directory for temporary files. + + \var directory_which B_SYSTEM_VAR_DIRECTORY + The system directory for variable data (Unix "var" directory). + + \var directory_which B_SYSTEM_CACHE_DIRECTORY + The system directory used for cache files. + + \var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY + The system non-packaged installation location directory. + + \var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY + The system non-packaged add-ons directory + + \var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY + The system non-packaged translator directory. + + \var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY + The system non-packaged media nodes directory. + + \var directory_which B_SYSTEM_NONPACKAGED_BIN_DIRECTORY + The system non-packaged bin directory. Contains command-line applications + runnable from Terminal. + + \var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY + The system non-packaged data directory. + + \var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY + The system non-packaged fonts directory + + \var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY + The system non-packaged sounds directory. + + \var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY + The system non-packaged documentation directory. Contains e.g. man pages. + + \var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY + The system non-packaged lib directory. + + \var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY + The system non-packaged directory for development header files. + + \var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY + The system non-packaged directory containing development related files. */ -// \var directory_which B_COMMON_DIRECTORY -// The common directory. - -// \var directory_which B_COMMON_SYSTEM_DIRECTORY -// \var directory_which B_COMMON_ADDONS_DIRECTORY -// \var directory_which B_COMMON_BOOT_DIRECTORY -// \var directory_which B_COMMON_FONTS_DIRECTORY -// \var directory_which B_COMMON_LIB_DIRECTORY -// \var directory_which B_COMMON_SERVERS_DIRECTORY -// \var directory_which B_COMMON_BIN_DIRECTORY -// \var directory_which B_COMMON_ETC_DIRECTORY -// \var directory_which B_COMMON_DOCUMENTATION_DIRECTORY -// \var directory_which B_COMMON_SETTINGS_DIRECTORY -// \var directory_which B_COMMON_DEVELOP_DIRECTORY -// The common development directory. Contains toolchains, include files, -// and other tools related to application development. - -// \var directory_which B_COMMON_LOG_DIRECTORY -// The common log directory. Log files are stored here. - -// \var directory_which B_COMMON_SPOOL_DIRECTORY -// \var directory_which B_COMMON_TEMP_DIRECTORY -// \var directory_which B_COMMON_VAR_DIRECTORY -// \var directory_which B_COMMON_TRANSLATORS_DIRECTORY -// \var directory_which B_COMMON_MEDIA_NODES_DIRECTORY -// \var directory_which B_COMMON_SOUNDS_DIRECTORY -// \var directory_which B_COMMON_DATA_DIRECTORY -// The common data directory. You may store application data here, such as -// resources (graphics, music) for your application. - -// \var directory_which B_COMMON_CACHE_DIRECTORY -// The common cache directory. You may store temporary data here, such as -// thumbnails for a picture viewer application, or a web browser data cache. /*! \var directory_which B_USER_DIRECTORY @@ -143,10 +207,20 @@ instead use B_USER_SETTINGS_DIRECTORY. \var directory_which B_USER_CONFIG_DIRECTORY + The user's packaged installation location directory. + \var directory_which B_USER_ADDONS_DIRECTORY + The user add-ons directory + \var directory_which B_USER_BOOT_DIRECTORY + The user directory containing booting related files. + \var directory_which B_USER_FONTS_DIRECTORY + The user fonts directory + \var directory_which B_USER_LIB_DIRECTORY + The user lib directory. + \var directory_which B_USER_SETTINGS_DIRECTORY The user settings directory. You may store your application settings here. Create a subdirectory for your application if you have multiple files to @@ -158,15 +232,237 @@ it shows up in the user deskbar's leaf menu. \var directory_which B_USER_PRINTERS_DIRECTORY - \var directory_which B_USER_TRANSLATORS_DIRECTORY - \var directory_which B_USER_MEDIA_NODES_DIRECTORY - \var directory_which B_USER_SOUNDS_DIRECTORY - \var directory_which B_USER_DATA_DIRECTORY - \var directory_which B_USER_CACHE_DIRECTORY + The user directory for printer settings. + \var directory_which B_USER_TRANSLATORS_DIRECTORY + The user translator directory. + + \var directory_which B_USER_MEDIA_NODES_DIRECTORY + The user media nodes directory. + + \var directory_which B_USER_SOUNDS_DIRECTORY + The user sounds directory. + + \var directory_which B_USER_DATA_DIRECTORY + The user data directory. + + \var directory_which B_USER_CACHE_DIRECTORY + The system directory used for cache files. + + \var directory_which B_USER_PACKAGES_DIRECTORY + The user directory where activated packages live. + + \var directory_which B_USER_HEADERS_DIRECTORY + The user directory for development header files. + + \var directory_which B_USER_DEVELOP_DIRECTORY + The user directory containing development related files. + + \var directory_which B_USER_DOCUMENTATION_DIRECTORY + The user documentation directory. Contains e.g. man pages. + + \var directory_which B_USER_SERVERS_DIRECTORY + The user servers directory. + + \var directory_which B_USER_APPS_DIRECTORY + The user applications directory. Contains applications with graphical + user interface. + + \var directory_which B_USER_BIN_DIRECTORY + The user bin directory. Contains command-line applications runnable from + Terminal. + + \var directory_which B_USER_PREFERENCES_DIRECTORY + The user preference applications directory. + + \var directory_which B_USER_ETC_DIRECTORY + The user directory used for Unix-like installation location wide settings + (Unix "etc" directory). + + \var directory_which B_USER_LOG_DIRECTORY + The user directory where log files are put. + + \var directory_which B_USER_SPOOL_DIRECTORY + The user directory for spool data (e.g. pending printer jobs). + + \var directory_which B_USER_VAR_DIRECTORY + The user directory for variable data (Unix "var" directory). + + \var directory_which B_USER_NONPACKAGED_DIRECTORY + The user non-packaged installation location directory. + + \var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY + The user non-packaged add-ons directory + + \var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY + The user non-packaged translator directory. + + \var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY + The user non-packaged media nodes directory. + + \var directory_which B_USER_NONPACKAGED_BIN_DIRECTORY + The user non-packaged bin directory. Contains command-line applications + runnable from Terminal. + + \var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY + The user non-packaged data directory. + + \var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY + The user non-packaged fonts directory + + \var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY + The user non-packaged sounds directory. + + \var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY + The user non-packaged documentation directory. Contains e.g. man pages. + + \var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY + The user non-packaged lib directory. + + \var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY + The user non-packaged directory for development header files. + + \var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY + The user non-packaged directory containing development related files. +*/ + + +/*! \var directory_which B_APPS_DIRECTORY + The global applications directory. Contains applications with graphical + user interface. + \var directory_which B_PREFERENCES_DIRECTORY + The global preference applications directory. + \var directory_which B_UTILITIES_DIRECTORY + The global utility applications directory. + + \var directory_which B_PACKAGE_LINKS_DIRECTORY + The global package links directory. This is where symlink directories for + all activated packages are exposed. +*/ + + +/* find_path[s]() flags */ + + +/*! + \var B_FIND_PATH_CREATE_DIRECTORY + Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), + and BPathFinder API. Specifies that, if the resulting path doesn't exist, + it shall be created as a directory, including all missing ancestors. Failure + to create the path will cause the respective function to fail. + + \var B_FIND_PATH_CREATE_PARENT_DIRECTORY + Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), + and BPathFinder API. Specifies that, if the resulting path's parent doesn't + exist, the parent shall be created as a directory, including all missing + ancestors. Failure to create the directory will cause the respective + function to fail. + + \var B_FIND_PATH_EXISTING_ONLY + Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), + and BPathFinder API. Specifies that, if the resulting path doesn't exist, + the respective function shall skip it. In case multiple paths shall be + retrieved and none of the paths exists, the function shall fail with + \c B_ENTRY_NOT_FOUND. +*/ + + +/*! + \enum path_base_directory + \brief Path constants to use with find_path(), find_paths(), et al. + + There are two kinds of constants. Those that are based off an installation + location and those that based off an image or given path. The latter are not + valid argument for all functions. + + \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY + The installation location base directory. + + \var B_FIND_PATH_ADD_ONS_DIRECTORY + The add-ons directory. + + \var B_FIND_PATH_APPS_DIRECTORY + The application directory. + + \var B_FIND_PATH_BIN_DIRECTORY + The command line application directory (Unix "bin" directory). + + \var B_FIND_PATH_BOOT_DIRECTORY + The directory containing booting related files. + + \var B_FIND_PATH_CACHE_DIRECTORY + The directory used for cache files. + + \var B_FIND_PATH_DATA_DIRECTORY + The base directory used for read-only data. + + \var B_FIND_PATH_DEVELOP_DIRECTORY + The directory containing development related files. + + \var B_FIND_PATH_DEVELOP_LIB_DIRECTORY + The the development library directory. This is the directory where the + linker finds libraries. + + \var B_FIND_PATH_DOCUMENTATION_DIRECTORY + The base directory used for documentation. + + \var B_FIND_PATH_ETC_DIRECTORY + The directory used for Unix-like installation location wide settings (Unix + "etc" directory). + + \var B_FIND_PATH_FONTS_DIRECTORY + The fonts directory. + + \var B_FIND_PATH_HEADERS_DIRECTORY + The development header files directory. + + \var B_FIND_PATH_LIB_DIRECTORY + The runtime library directory. This is where the runtime loader finds + libraries. + + \var B_FIND_PATH_LOG_DIRECTORY + The directory where log files are put. + + \var B_FIND_PATH_MEDIA_NODES_DIRECTORY + The media node add-ons directory. + + \var B_FIND_PATH_PACKAGES_DIRECTORY + The directory where activated packages live. + + \var B_FIND_PATH_PREFERENCES_DIRECTORY + The preference application directory. + + \var B_FIND_PATH_SERVERS_DIRECTORY + The server and daemon program directory. + + \var B_FIND_PATH_SETTINGS_DIRECTORY + The directory used for installation location wide settings. Note that for + the user's home config installation location, this is not the same as the + user's settings directory. Software installed in that installation location + puts their global settings files here. + + \var B_FIND_PATH_SOUNDS_DIRECTORY + The directory for sound files. + + \var B_FIND_PATH_SPOOL_DIRECTORY + The directory for spool data (e.g. pending printer jobs). + + \var B_FIND_PATH_TRANSLATORS_DIRECTORY + The translator add-ons directory. + + \var B_FIND_PATH_VAR_DIRECTORY + The directory for variable data (Unix "var" directory). + + \var B_FIND_PATH_IMAGE_PATH + The path of the image file that was identified by a pointer argument passed + to the respective function. + + \var B_FIND_PATH_PACKAGE_PATH + The path of the package the file referred to by the specified path belongs + to. */ @@ -188,3 +484,283 @@ Set \a path to \a which on \a volume. */ + + +/*! + \fn status_t find_path(const void* codePointer, + path_base_directory baseDirectory, const char* subPath, + char* pathBuffer, size_t bufferSize) + \brief Retrieves a path in the file system layout based on a loaded image + file. + + The function determines the path of the image (i.e. executable, library, or + add-on) file associated with \a codePointer, a pointer to a location in the + code or static data of an image loaded in the caller's team. Based on that, + path \a baseDirectory is evaluated. In most cases that means first + determining the path of the installation location from the path, then + appending the relative path corresponding to the given \a baseDirectory + constant, and finally appending \a subPath, if given. + + If \a baseDirectory specifies a path that is architecture dependent, the + caller's architecture (as returned by get_architecture()) is used for + constructing the path. + + If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are + specified, \a subPath is ignored. In the former case the path of the image + file is returned. In the latter case the path of the package containing the + image file, if any. + + \param codePointer A pointer to code or static data belonging to the image + based on which the path shall be computed. The special value + \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and + \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + \param baseDirectory Constant indicating which path to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param pathBuffer Pointer to a pre-allocated buffer the retrieved path + shall be stored in. + \param bufferSize Size of the \a pathBuffer buffer. + \return A status code. + \retval B_OK Everything went fine. + \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file doesn't belong to a package. +*/ + + +/*! + \fn status_t find_path_etc(const void* codePointer, const char* dependency, + const char* architecture, path_base_directory baseDirectory, + const char* subPath, uint32 flags, char* pathBuffer, size_t bufferSize) + \brief Retrieves a path in the file system layout based on a loaded image + file. + + The function determines the path of the image (i.e. executable, library, or + add-on) file associated with \a codePointer, a pointer to a location in the + code or static data of an image loaded in the caller's team. Based on that, + path \a baseDirectory is evaluated. In most cases that means first + determining the path of the installation location from the path, then + appending the relative path corresponding to the given \a baseDirectory + constant, and finally appending \a subPath, if given. + + If \a dependency is specified, instead of determining the installation + location path from the image path, the installation location path of the + dependency \a dependency of the package containing the image file is used. + + If \a baseDirectory specifies a path that is architecture dependent, + \a architecture is used for constructing the path. If \a architecture is + \c NULL, the caller's architecture (as returned by get_architecture()) is + used. + + If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are + specified, \a dependency and \a subPath are ignored. In the former case the + path of the image file is returned. In the latter case the path of the + package containing the image file, if any. + + \param codePointer A pointer to code or static data belonging to the image + based on which the path shall be computed. The special value + \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and + \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + \param dependency The name of the package's "requires" entry to be used for + resolving the installation location. Can be \c NULL. + \param architecture The name of the architecture to be used for resolving + architecture dependent paths. Can be \c NULL, in which case the caller's + architecture is used. + \param baseDirectory Constant indicating which path to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param flags Bitwise OR of any of the following flags: + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, + create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent + doesn't exist, create the parent directory (including all missing + ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. + \param pathBuffer Pointer to a pre-allocated buffer the retrieved path + shall be stored in. + \param bufferSize Size of the \a pathBuffer buffer. + \return A status code. + \retval B_OK Everything went fine. + \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file doesn't belong to a package, or \c dependency was + specified, but isn't a "requires" entry of the package, or + \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path + doesn't exist. +*/ + + +/*! + \fn status_t find_path_for_path(const char* path, + path_base_directory baseDirectory, const char* subPath, + char* pathBuffer, size_t bufferSize) + \brief Retrieves a path in the file system layout based on a given path. + + Based on the given path \a path the function evaluates \a baseDirectory. In + most cases that means first determining the path of the installation + location from the given path, then appending the relative path corresponding + to the given \a baseDirectory constant, and finally appending \a subPath, if + given. + + If \a baseDirectory specifies a path that is architecture dependent, the + architecture associated with the given path (as returned by + guess_architecture_for_path()) is used for constructing the path. + + If \c B_FIND_PATH_PACKAGE_PATH is specified, \a subPath is ignored. In + this case the path of the package containing the file referred to by \a path + is returned. \c B_FIND_PATH_IMAGE_PATH is not a valid argument for this + function. + + \param path A path based on which the path shall be computed. + \param baseDirectory Constant indicating which path to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param pathBuffer Pointer to a pre-allocated buffer the retrieved path + shall be stored in. + \param bufferSize Size of the \a pathBuffer buffer. + \return A status code. + \retval B_OK Everything went fine. + \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and \a path does refer to a file that belongs to a package. +*/ + + +/*! + \fn status_t find_path_for_path_etc(const char* path, + const char* dependency, const char* architecture, + path_base_directory baseDirectory, const char* subPath, uint32 flags, + char* pathBuffer, size_t bufferSize) + \brief Retrieves a path in the file system layout based on a given path. + + Based on the given path \a path the function evaluates \a baseDirectory. In + most cases that means first determining the path of the installation + location from the given path, then appending the relative path corresponding + to the given \a baseDirectory constant, and finally appending \a subPath, if + given. + + If \a dependency is specified, instead of determining the installation + location path from the given path, the installation location path of the + dependency \a dependency of the package containing the file referred to by + \a path is used. + + If \a baseDirectory specifies a path that is architecture dependent, + \a architecture is used for constructing the path. If \a architecture is + \c NULL, the architecture associated with the given path (as returned by + guess_architecture_for_path()) is used. + + If \c B_FIND_PATH_PACKAGE_PATH is specified, \a dependency and + \a subPath are ignored. In this case the path of the package containing the + file referred to by \a path is returned. \c B_FIND_PATH_IMAGE_PATH is not + a valid argument for this function. + + \param path A path based on which the path shall be computed. + \param dependency The name of the package's "requires" entry to be used for + resolving the installation location. Can be \c NULL. + \param architecture The name of the architecture to be used for resolving + architecture dependent paths. Can be \c NULL, in which case the + architecture associated with \a path is used. + \param baseDirectory Constant indicating which path to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param flags Bitwise OR of any of the following flags: + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, + create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent + doesn't exist, create the parent directory (including all missing + ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. + \param pathBuffer Pointer to a pre-allocated buffer the retrieved path + shall be stored in. + \param bufferSize Size of the \a pathBuffer buffer. + \return A status code. + \retval B_OK Everything went fine. + \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and \a path does refer to a file that belongs to a package, or + \c dependency was specified, but isn't a "requires" entry of the + package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting + path doesn't exist. +*/ + + +/*! + \fn status_t find_paths(path_base_directory baseDirectory, + const char* subPath, char*** _paths, size_t* _pathCount) + \brief Retrieves a list of paths in the file system layout. + + For each installation location -- in the order most specific to most + generic, non-packaged before packaged -- the function evaluates + \a baseDirectory to a path and appends \a subPath, if given. + + If \a baseDirectory specifies a path that is architecture dependent, + the caller's architecture (as returned by get_architecture()) is used for + constructing each path. + + \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not + valid arguments for this function. + + The array of paths retrieved is allocated on the heap and returned via + \a _paths. The caller is responsible for calling free() for the returned + pointer. + + \param baseDirectory Constant indicating which paths to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param _paths Pointer to a pre-allocated variable where the pointer to the + allocated path array shall be stored on success. + \param _pathCount Pointer to a pre-allocated variable where the number of + paths in the path array shall be stored on success. + \return A status code. + \retval B_OK Everything went fine. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + paths doesn't exist. +*/ + + +/*! + \fn status_t find_paths_etc(const char* architecture, + path_base_directory baseDirectory, const char* subPath, uint32 flags, + char*** _paths, size_t* _pathCount) + \brief Retrieves a list of paths in the file system layout. + + For each installation location -- in the order most specific to most + generic, non-packaged before packaged -- the function evaluates + \a baseDirectory to a path and appends \a subPath, if given. + + If \a baseDirectory specifies a path that is architecture dependent, + \a architecture is used for constructing each path. If \a architecture is + \c NULL, the caller's architecture (as returned by get_architecture()) is + used. + + \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not + valid arguments for this function. + + The array of paths retrieved is allocated on the heap and returned via + \a _paths. The caller is responsible for calling free() for the returned + pointer. + + \param architecture The name of the architecture to be used for resolving + architecture dependent paths. Can be \c NULL, in which case the caller's + architecture is used. + \param baseDirectory Constant indicating which paths to retrieve. + \param subPath Relative subpath that shall be appended. Can be \c NULL. + \param flags Bitwise OR of any of the following flags: + - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, + create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent + doesn't exist, create the parent directory (including all missing + ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip + it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. + \param _paths Pointer to a pre-allocated variable where the pointer to the + allocated path array shall be stored on success. + \param _pathCount Pointer to a pre-allocated variable where the number of + paths in the path array shall be stored on success. + \return A status code. + \retval B_OK Everything went fine. + \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the + paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and + none of the resulting paths do exist. +*/