Provides the find_directory(), find_path(), find_paths() functions as well as the directory_which
constants.
More...
Enumerations |
Functions | |
status_t | find_directory (directory_which which, dev_t volume, bool createIt, char *pathString, int32 length) |
C interface to find_directory. More... | |
status_t | find_directory (directory_which which, BPath *path, bool createIt=false, BVolume *volume=NULL) |
C++ interface to find_directory. More... | |
status_t | find_path (const void *codePointer, path_base_directory baseDirectory, const char *subPath, char *pathBuffer, size_t bufferSize) |
Retrieves a path in the file system layout based on a loaded image file. More... | |
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) |
Retrieves a path in the file system layout based on a loaded image file. More... | |
status_t | find_path_for_path (const char *path, path_base_directory baseDirectory, const char *subPath, char *pathBuffer, size_t bufferSize) |
Retrieves a path in the file system layout based on a given path. More... | |
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) |
Retrieves a path in the file system layout based on a given path. More... | |
status_t | find_paths (path_base_directory baseDirectory, const char *subPath, char ***_paths, size_t *_pathCount) |
Retrieves a list of paths in the file system layout. More... | |
status_t | find_paths_etc (const char *architecture, path_base_directory baseDirectory, const char *subPath, uint32 flags, char ***_paths, size_t *_pathCount) |
Retrieves a list of paths in the file system layout. More... | |
Provides the find_directory(), find_path(), find_paths() functions as well as the directory_which
constants.
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:
Cases for which find_directory() is still useful:
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.
anonymous enum |
Enumerator | |
---|---|
B_FIND_PATH_CREATE_DIRECTORY |
Specifies that if the resulting path doesn't exist, it shall be created a directory, including all missing ancestors. Failure to create the path will cause the respective function to fail. Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), and BPathFinder API.
|
B_FIND_PATH_CREATE_PARENT_DIRECTORY |
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. Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), and BPathFinder API.
|
B_FIND_PATH_EXISTING_ONLY |
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 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), and BPathFinder API.
|
enum directory_which |
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 location in each of them. For example the location of the trash directory depends on the filesystem. System directories are system-wide, they live on only one volume. System is meant for internal system management and system-wide applications. User directories have a different value depending on the UID of the application calling the function. They are usually located in the user's home directory.
Use system directories for system-wide files such as drivers and use user directories are for application settings, since each user may want different settings.
B_COMMON_*
constants have been intentionally removed in Haiku R1, use the B_SYSTEM_*
constants instead.enum path_base_directory |
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.
status_t find_directory | ( | directory_which | which, |
dev_t | volume, | ||
bool | createIt, | ||
char * | pathString, | ||
int32 | length | ||
) |
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. \since BeOS R3
status_t find_directory | ( | directory_which | which, |
BPath * | path, | ||
bool | createIt = false , |
||
BVolume * | volume = NULL |
||
) |
C++ interface to find_directory.
Set path to which on volume.
status_t find_path | ( | const void * | codePointer, |
path_base_directory | baseDirectory, | ||
const char * | subPath, | ||
char * | pathBuffer, | ||
size_t | bufferSize | ||
) |
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 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 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 baseDirectory constant, and finally appending subPath, if given.
If baseDirectory specifies a path that is architecture dependent, the caller's architecture (as returned by get_architecture()) is used for constructing the path.
If B_FIND_PATH_IMAGE_PATH
or B_FIND_PATH_PACKAGE_PATH
are specified, 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.
codePointer | A pointer to code or static data belonging to the image based on which the path shall be computed. The special value B_APP_IMAGE_SYMBOL can be used to refer to the program image, and B_CURRENT_IMAGE_SYMBOL for the caller's image. |
baseDirectory | Constant indicating which path to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
pathBuffer | Pointer to a pre-allocated buffer the retrieved path shall be stored in. |
bufferSize | Size of the pathBuffer buffer. |
B_OK | Everything went fine. |
B_BUFFER_OVERFLOW | The provided pathBuffer wasn't large enough. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the path doesn't exist. E.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file doesn't belong to a package. |
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 | ||
) |
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 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 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 baseDirectory constant, and finally appending subPath, if given.
If dependency is specified, instead of determining the installation location path from the image path, the installation location path of the dependency dependency of the package containing the image file is used.
If baseDirectory specifies a path that is architecture dependent, architecture is used for constructing the path. If architecture is NULL
, the caller's architecture (as returned by get_architecture()) is used.
If B_FIND_PATH_IMAGE_PATH
or B_FIND_PATH_PACKAGE_PATH
are specified, dependency and 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.
codePointer | A pointer to code or static data belonging to the image based on which the path shall be computed. The special value B_APP_IMAGE_SYMBOL can be used to refer to the program image, and B_CURRENT_IMAGE_SYMBOL for the caller's image. |
dependency | The name of the package's "requires" entry to be used for resolving the installation location. Can be NULL . |
architecture | The name of the architecture to be used for resolving architecture dependent paths. Can be NULL , in which case the caller's architecture is used. |
baseDirectory | Constant indicating which path to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
flags | Bitwise OR of any of the following flags:
|
pathBuffer | Pointer to a pre-allocated buffer the retrieved path shall be stored in. |
bufferSize | Size of the pathBuffer buffer. |
B_OK | Everything went fine. |
B_BUFFER_OVERFLOW | The provided pathBuffer wasn't large enough. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the path doesn't exist. E.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file doesn't belong to a package, or dependency was specified, but isn't a "requires" entry of the package, or B_FIND_PATH_EXISTING_ONLY was specified and the resulting path doesn't exist. |
status_t find_path_for_path | ( | const char * | path, |
path_base_directory | baseDirectory, | ||
const char * | subPath, | ||
char * | pathBuffer, | ||
size_t | bufferSize | ||
) |
Retrieves a path in the file system layout based on a given path.
Based on the given path path the function evaluates 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 baseDirectory constant, and finally appending subPath, if given.
If 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 B_FIND_PATH_PACKAGE_PATH
is specified, subPath is ignored. In this case the path of the package containing the file referred to by path is returned. B_FIND_PATH_IMAGE_PATH
is not a valid argument for this function.
path | A path based on which the path shall be computed. |
baseDirectory | Constant indicating which path to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
pathBuffer | Pointer to a pre-allocated buffer the retrieved path shall be stored in. |
bufferSize | Size of the pathBuffer buffer. |
B_OK | Everything went fine. |
B_BUFFER_OVERFLOW | The provided pathBuffer wasn't large enough. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the path doesn't exist. E.g. B_FIND_PATH_PACKAGE_PATH was specified and path does refer to a file that belongs to a package. |
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 | ||
) |
Retrieves a path in the file system layout based on a given path.
Based on the given path path the function evaluates 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 baseDirectory constant, and finally appending subPath, if given.
If dependency is specified, instead of determining the installation location path from the given path, the installation location path of the dependency dependency of the package containing the file referred to by path is used.
If baseDirectory specifies a path that is architecture dependent, architecture is used for constructing the path. If architecture is NULL
, the architecture associated with the given path (as returned by guess_architecture_for_path()) is used.
If B_FIND_PATH_PACKAGE_PATH
is specified, dependency and subPath are ignored. In this case the path of the package containing the file referred to by path is returned. B_FIND_PATH_IMAGE_PATH
is not a valid argument for this function.
path | A path based on which the path shall be computed. |
dependency | The name of the package's "requires" entry to be used for resolving the installation location. Can be NULL . |
architecture | The name of the architecture to be used for resolving architecture dependent paths. Can be NULL , in which case the architecture associated with path is used. |
baseDirectory | Constant indicating which path to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
flags | Bitwise OR of any of the following flags:
|
pathBuffer | Pointer to a pre-allocated buffer the retrieved path shall be stored in. |
bufferSize | Size of the pathBuffer buffer. |
B_OK | Everything went fine. |
B_BUFFER_OVERFLOW | The provided pathBuffer wasn't large enough. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the path doesn't exist. E.g. B_FIND_PATH_PACKAGE_PATH was specified and path does refer to a file that belongs to a package, or dependency was specified, but isn't a "requires" entry of the package, or B_FIND_PATH_EXISTING_ONLY was specified and the resulting path doesn't exist. |
status_t find_paths | ( | path_base_directory | baseDirectory, |
const char * | subPath, | ||
char *** | _paths, | ||
size_t * | _pathCount | ||
) |
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 baseDirectory to a path and appends subPath, if given.
If baseDirectory specifies a path that is architecture dependent, the caller's architecture (as returned by get_architecture()) is used for constructing each path.
B_FIND_PATH_PACKAGE_PATH
and 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 _paths. The caller is responsible for calling free() for the returned pointer.
baseDirectory | Constant indicating which paths to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
_paths | Pointer to a pre-allocated variable where the pointer to the allocated path array shall be stored on success. |
_pathCount | Pointer to a pre-allocated variable where the number of paths in the path array shall be stored on success. |
B_OK | Everything went fine. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the paths doesn't exist. |
status_t find_paths_etc | ( | const char * | architecture, |
path_base_directory | baseDirectory, | ||
const char * | subPath, | ||
uint32 | flags, | ||
char *** | _paths, | ||
size_t * | _pathCount | ||
) |
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 baseDirectory to a path and appends subPath, if given.
If baseDirectory specifies a path that is architecture dependent, architecture is used for constructing each path. If architecture is NULL
, the caller's architecture (as returned by get_architecture()) is used.
B_FIND_PATH_PACKAGE_PATH
and 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 _paths. The caller is responsible for calling free() for the returned pointer.
architecture | The name of the architecture to be used for resolving architecture dependent paths. Can be NULL , in which case the caller's architecture is used. |
baseDirectory | Constant indicating which paths to retrieve. |
subPath | Relative subpath that shall be appended. Can be NULL . |
flags | Bitwise OR of any of the following flags:
|
_paths | Pointer to a pre-allocated variable where the pointer to the allocated path array shall be stored on success. |
_pathCount | Pointer to a pre-allocated variable where the number of paths in the path array shall be stored on success. |
B_OK | Everything went fine. |
B_ENTRY_NOT_FOUND | A file system entry required for retrieving the paths doesn't exist. E.g. B_FIND_PATH_EXISTING_ONLY was specified and none of the resulting paths do exist. |