767 lines
30 KiB
Plaintext
767 lines
30 KiB
Plaintext
/*
|
|
* 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 hrev46390
|
|
* src/kits/storage/FindDirectory.cpp hrev46390
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file FindDirectory.h
|
|
\ingroup storage
|
|
\ingroup libbe
|
|
\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 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 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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\enum directory_which
|
|
\brief Directory constants to use with find_directory.
|
|
|
|
There are four kind of directories. Volume-local directories exist on each
|
|
volume. They may be at a different place in each of them, for example the
|
|
trash location depends on the filesystem. System and common directories are
|
|
system-wide. They live on only one volume. The difference is system is
|
|
only meant for internal system management and shouldn't be used by
|
|
applications. The common directories have a similar hierarchy, and they are
|
|
ignored when the user disable user add-ons in the boot menu. User
|
|
directories have a different value depending on the UID of the application
|
|
calling the function. They are usually located in the user home directory.
|
|
|
|
Use common directories for system-wide files such as drivers. Use user
|
|
directories for application settings, since each user may want different
|
|
settings.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var directory_which B_DESKTOP_DIRECTORY
|
|
The desktop for a given volume.
|
|
|
|
\var directory_which B_TRASH_DIRECTORY
|
|
The trash for a given volume.
|
|
|
|
\var directory_which B_SYSTEM_DIRECTORY
|
|
The system directory.
|
|
|
|
\var directory_which B_SYSTEM_ADDONS_DIRECTORY
|
|
The system add-ons directory
|
|
|
|
\var directory_which B_SYSTEM_BOOT_DIRECTORY
|
|
The system boot directory. Contains the minimal set of files required for
|
|
booting Haiku.
|
|
|
|
\var directory_which B_SYSTEM_FONTS_DIRECTORY
|
|
The system fonts directory
|
|
|
|
\var directory_which B_SYSTEM_LIB_DIRECTORY
|
|
The system lib directory.
|
|
|
|
\var directory_which B_SYSTEM_SERVERS_DIRECTORY
|
|
The system servers directory.
|
|
|
|
\var directory_which B_SYSTEM_APPS_DIRECTORY
|
|
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 e.g. man pages.
|
|
|
|
\var directory_which B_SYSTEM_PREFERENCES_DIRECTORY
|
|
The system preferences directory.
|
|
|
|
\var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY
|
|
The system translator directory.
|
|
|
|
\var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY
|
|
The system media nodes directory.
|
|
|
|
\var directory_which B_SYSTEM_SOUNDS_DIRECTORY
|
|
The system sounds directory.
|
|
|
|
\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_USER_DIRECTORY
|
|
The user home directory. Do NOT store application settings here as on unix,
|
|
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
|
|
store, else, put a single file. The file or directory should have the same
|
|
name as your application, so the user knows what it's used for.
|
|
|
|
\var directory_which B_USER_DESKBAR_DIRECTORY
|
|
The user deskbar directory. You may add a link to your application here, so
|
|
it shows up in the user deskbar's leaf menu.
|
|
|
|
\var directory_which B_USER_PRINTERS_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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t find_directory(directory_which which, dev_t volume,
|
|
bool createIt, char* pathString, int32 length)
|
|
\brief C interface to find_directory
|
|
|
|
Fills up to \a length characters of \a pathString with the path to \a which
|
|
on \a volume. Creates the directory if it doesn't exists if \a createIt is
|
|
set.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t find_directory(directory_which which, BPath* path, bool createIt,
|
|
BVolume* volume)
|
|
\brief C++ interface to find_directory
|
|
|
|
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.
|
|
*/
|