2 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
6 * Adrien Destugues, pulkomandy@pulkomandy.ath.cx
7 * John Scipione, jscipione@gmail.com
8 * Ingo Weinhold, ingo_weinhold@gmx.de
11 * headers/os/storage/FindDirectory.h hrev47402
12 * src/kits/storage/FindDirectory.cpp hrev47402
20 \brief Provides the find_directory(), find_path(), find_paths() functions
21 as well as the \c directory_which constants.
23 Haiku provides a set of directories for applications to use. These can be
24 accessed using the functions find_directory(), find_path(), find_path_etc(),
25 find_paths(), find_paths_etc(), find_path_for_path(),
26 find_path_for_path_etc(). It is very important to use the functions at
27 runtime and not hardcode the path, as it may change in future versions of
28 Haiku, and already changed in past ones. Using these functions makes your
29 application more future-proof, and makes sure everyone puts data in the same
30 place, which makes the system cleaner and easier to manage.
32 Note that while the find_directory() function is still needed for some, it
33 is deprecated for many other use cases, like:
34 - When collecting files from all installation locations, be it data files
35 (like fonts) or add-ons your application/library supports, use
36 find_paths(), find_paths_etc(), or BPathFinder::FindPaths() instead.
37 Formerly you had to use find_directory() and iterate through all possible
38 constants manually. Not only is this less convenient, it also doesn't
39 account for the possibility of installation locations being added or
40 removed in a later Haiku release.
41 - If your code needs to access another file that also belongs to your
42 software (i.e. if packaged it is included in the same package), use
43 find_path() or BPathFinder::FindPath() instead.
44 Formerly this case could not really be handled properly. Either you had
45 to hard-code the installation location by using the respective directory
46 constant or you had to manually construct a path relative to your code's
49 Cases for which find_directory() is still useful:
50 - Getting per-volume paths like for the trash directory.
51 - Getting specific paths like for the user's home directory or the user's
54 Note that these functions can be accessed from C code (they are implemented
55 in libroot), to make it easy to use also in ported applications. However,
56 there are also a C++ version of find_directory() and the BPathFinder class
57 (both implemented in libbe), which may be more convenient to use in C++
64 \brief Directory constants to use with find_directory().
66 There are four kind of directories. Volume-local directories exist on each
67 volume, they may be at a different location in each of them. For example
68 the location of the trash directory depends on the filesystem. System
69 directories are system-wide, they live on only one volume. System is meant
70 for internal system management and system-wide applications. User
71 directories have a different value depending on the UID of the application
72 calling the function. They are usually located in the user's home
75 Use system directories for system-wide files such as drivers and use user
76 directories are for application settings, since each user may want
79 \remark The \c B_COMMON_* constants have been intentionally removed in
80 Haiku R1, use the \c B_SYSTEM_* constants instead.
87 \var directory_which B_DESKTOP_DIRECTORY
88 \brief The desktop directory for a given volume.
95 \var directory_which B_TRASH_DIRECTORY
96 \brief The trash directory for a given volume.
103 \var directory_which B_SYSTEM_DIRECTORY
104 \brief The system directory.
111 \var directory_which B_SYSTEM_ADDONS_DIRECTORY
112 \brief The system add-ons directory
119 \var directory_which B_SYSTEM_BOOT_DIRECTORY
120 \brief The system boot directory.
122 Contains the minimal set of files required for booting Haiku.
129 \var directory_which B_SYSTEM_FONTS_DIRECTORY
130 \brief The system fonts directory.
137 \var directory_which B_SYSTEM_LIB_DIRECTORY
138 \brief The system lib directory.
145 \var directory_which B_SYSTEM_SERVERS_DIRECTORY
146 \brief The system servers directory.
153 \var directory_which B_SYSTEM_APPS_DIRECTORY
154 \brief The system applications directory.
156 Contains applications with graphical user interface.
163 \var directory_which B_SYSTEM_BIN_DIRECTORY
164 \brief The system bin directory.
166 Contains command-line applications runnable from Terminal.
173 \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY
174 \brief The system documentation directory, contains e.g. man pages.
181 \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY
182 \brief The system preferences directory.
189 \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY
190 \brief The system translator directory.
197 \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY
198 \brief The system media nodes directory.
205 \var directory_which B_SYSTEM_SOUNDS_DIRECTORY
206 \brief The system sounds directory.
213 \var directory_which B_SYSTEM_DATA_DIRECTORY
214 \brief The system data directory.
221 \var directory_which B_SYSTEM_DEVELOP_DIRECTORY
222 \brief The system directory containing development related files.
229 \var directory_which B_SYSTEM_PACKAGES_DIRECTORY
230 \brief The system directory where activated packages live.
237 \var directory_which B_SYSTEM_HEADERS_DIRECTORY
238 \brief The system directory for development header files.
245 \var directory_which B_SYSTEM_ETC_DIRECTORY
246 \brief The system directory used for Unix-like installation location-wide
247 settings (Unix "etc" directory).
254 \var directory_which B_SYSTEM_SETTINGS_DIRECTORY
255 \brief The system directory used for installation location-wide settings.
262 \var directory_which B_SYSTEM_LOG_DIRECTORY
263 \brief The system directory where log files are put.
270 \var directory_which B_SYSTEM_SPOOL_DIRECTORY
271 \brief The system directory for spool data (e.g. pending printer jobs).
278 \var directory_which B_SYSTEM_TEMP_DIRECTORY
279 \brief The global directory for temporary files (Unix "tmp" directory).
286 \var directory_which B_SYSTEM_VAR_DIRECTORY
287 \brief The system directory for variable data (Unix "var" directory).
294 \var directory_which B_SYSTEM_CACHE_DIRECTORY
295 \brief The system directory used for cache files.
302 \var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY
303 \brief The system non-packaged installation location directory.
310 \var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY
311 \brief The system non-packaged add-ons directory
318 \var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY
319 \brief The system non-packaged translator directory.
326 \var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY
327 \brief The system non-packaged media nodes directory.
334 \var directory_which B_SYSTEM_NONPACKAGED_BIN_DIRECTORY
335 The system non-packaged bin directory. Contains command-line applications
336 \brief runnable from Terminal.
343 \var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY
344 \brief The system non-packaged data directory.
351 \var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY
352 \brief The system non-packaged fonts directory
359 \var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY
360 \brief The system non-packaged sounds directory.
367 \var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY
368 \brief The system non-packaged documentation directory. Contains e.g. man pages.
375 \var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY
376 \brief The system non-packaged lib directory.
383 \var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY
384 \brief The system non-packaged directory for development header files.
391 \var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY
392 \brief The system non-packaged directory containing development related
400 \var directory_which B_USER_DIRECTORY
401 \brief The user home directory.
403 Do NOT store application settings here as on unix, instead use
404 \c B_USER_SETTINGS_DIRECTORY.
411 \var directory_which B_USER_CONFIG_DIRECTORY
412 \brief The user packaged installation location directory.
419 \var directory_which B_USER_ADDONS_DIRECTORY
420 \brief The user add-ons directory
427 \var directory_which B_USER_BOOT_DIRECTORY
428 \brief The user directory containing booting related files.
435 \var directory_which B_USER_FONTS_DIRECTORY
436 \brief The user fonts directory.
443 \var directory_which B_USER_LIB_DIRECTORY
444 \brief The user lib directory.
451 \var directory_which B_USER_SETTINGS_DIRECTORY
452 \brief The user settings directory.
454 You may store your application settings here. Create a subdirectory for
455 your application if you have multiple files to store, else, put a single
456 file. The file or directory should have the same name as your
457 application, so the user knows what it's used for.
464 \var directory_which B_USER_DESKBAR_DIRECTORY
465 \brief The user Deskbar directory.
467 You may add a link to your application here, so it shows up in the user's
475 \var directory_which B_USER_PRINTERS_DIRECTORY
476 \brief The user directory for printer settings.
483 \var directory_which B_USER_TRANSLATORS_DIRECTORY
484 \brief The user translator directory.
491 \var directory_which B_USER_MEDIA_NODES_DIRECTORY
492 \brief The user media nodes directory.
499 \var directory_which B_USER_SOUNDS_DIRECTORY
500 \brief The user sounds directory.
507 \var directory_which B_USER_DATA_DIRECTORY
508 \brief The user data directory.
515 \var directory_which B_USER_CACHE_DIRECTORY
516 \brief The user directory used for cache files.
523 \var directory_which B_USER_PACKAGES_DIRECTORY
524 \brief The user directory where activated packages live.
531 \var directory_which B_USER_HEADERS_DIRECTORY
532 \brief The user directory for development header files.
539 \var directory_which B_USER_DEVELOP_DIRECTORY
540 \brief The user directory containing development related files.
547 \var directory_which B_USER_DOCUMENTATION_DIRECTORY
548 \brief The user documentation directory, contains e.g. man pages.
555 \var directory_which B_USER_SERVERS_DIRECTORY
556 \brief The user servers directory.
563 \var directory_which B_USER_APPS_DIRECTORY
564 \brief The user applications directory.
566 Contains applications with graphical user interface.
573 \var directory_which B_USER_BIN_DIRECTORY
574 \brief The user bin directory.
576 Contains command-line applications runnable from Terminal.
583 \var directory_which B_USER_PREFERENCES_DIRECTORY
584 \brief The user preference applications directory.
591 \var directory_which B_USER_ETC_DIRECTORY
592 \brief The user directory used for Unix-like installation location-wide
593 settings (Unix "etc" directory).
600 \var directory_which B_USER_LOG_DIRECTORY
601 \brief The user directory where log files are put.
608 \var directory_which B_USER_SPOOL_DIRECTORY
609 \brief The user directory for spool data, e.g. pending printer jobs.
616 \var directory_which B_USER_VAR_DIRECTORY
617 \brief The user directory for variable data (Unix "var" directory).
624 \var directory_which B_USER_NONPACKAGED_DIRECTORY
625 \brief The user non-packaged installation location directory.
632 \var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY
633 \brief The user non-packaged add-ons directory
640 \var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY
641 \brief The user non-packaged translator directory.
648 \var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY
649 \brief The user non-packaged media nodes directory.
656 \var directory_which B_USER_NONPACKAGED_BIN_DIRECTORY
657 \brief The user non-packaged bin directory.
659 Contains command-line applications runnable from Terminal.
666 \var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY
667 \brief The user non-packaged data directory.
674 \var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY
675 \brief The user non-packaged fonts directory
682 \var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY
683 \brief The user non-packaged sounds directory.
690 \var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY
691 \brief The user non-packaged documentation directory, contains e.g. man
699 \var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY
700 \brief The user non-packaged lib directory.
707 \var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY
708 \brief The user non-packaged directory for development header files.
715 \var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY
716 \brief The user non-packaged directory containing development related
724 \var directory_which B_APPS_DIRECTORY
725 \brief The global applications directory.
727 Contains applications with graphical user interface.
734 \var directory_which B_PREFERENCES_DIRECTORY
735 \brief The global preference applications directory.
742 \var directory_which B_UTILITIES_DIRECTORY
743 \brief The global utility applications directory.
750 \var directory_which B_PACKAGE_LINKS_DIRECTORY
751 \brief The global package links directory.
753 This is where symlink directories for all activated packages are exposed.
760 \var directory_which B_BEOS_DIRECTORY
761 \brief The BeOS directory.
763 \deprecated Legacy BeOS definition to be phased out, use
764 \c B_SYSTEM_DIRECTORY instead.
771 \var directory_which B_BEOS_SYSTEM_DIRECTORY
772 \brief The BeOS system directory.
774 \deprecated Legacy BeOS definition to be phased out, use
775 \c B_SYSTEM_DIRECTORY instead.
782 \var directory_which B_BEOS_ADDONS_DIRECTORY
783 \brief The BeOS Add-ons directory.
785 \deprecated Legacy BeOS definition to be phased out, use
786 \c B_SYSTEM_ADDONS_DIRECTORY instead.
793 \var directory_which B_BEOS_BOOT_DIRECTORY
794 \brief The BeOS boot directory.
796 \deprecated Legacy BeOS definition to be phased out, use
797 \c B_SYSTEM_BOOT_DIRECTORY instead.
804 \var directory_which B_BEOS_FONTS_DIRECTORY
805 \brief The BeOS fonts directory.
807 \deprecated Legacy BeOS definition to be phased out, use
808 \c B_SYSTEM_FONTS_DIRECTORY instead.
815 \var directory_which B_BEOS_LIB_DIRECTORY
816 \brief The BeOS lib directory.
818 \deprecated Legacy BeOS definition to be phased out, use
819 \c B_SYSTEM_LIB_DIRECTORY instead.
826 \var directory_which B_BEOS_SERVERS_DIRECTORY
827 \brief The BeOS servers directory.
829 \deprecated Legacy BeOS definition to be phased out, use
830 \c B_SYSTEM_SERVERS_DIRECTORY instead.
837 \var directory_which B_BEOS_APPS_DIRECTORY
838 \brief The BeOS apps directory.
840 \deprecated Legacy BeOS definition to be phased out, use
841 \c B_SYSTEM_APPS_DIRECTORY instead.
848 \var directory_which B_BEOS_BIN_DIRECTORY
849 \brief The BeOS bin directory.
851 \deprecated Legacy BeOS definition to be phased out, use
852 \c B_SYSTEM_BIN_DIRECTORY instead.
859 \var directory_which B_BEOS_ETC_DIRECTORY
860 \brief The BeOS etc directory used for Unix-like installation location-wide
861 settings (Unix "etc" directory).
863 \deprecated Legacy BeOS definition to be phased out, use
864 \c B_SYSTEM_ETC_DIRECTORY instead.
871 \var directory_which B_BEOS_DOCUMENTATION_DIRECTORY
872 \brief The BeOS documentation directory.
874 \deprecated Legacy BeOS definition to be phased out, use
875 \c B_SYSTEM_DOCUMENTATION_DIRECTORY instead.
882 \var directory_which B_BEOS_PREFERENCES_DIRECTORY
883 \brief The BeOS preferences directory.
885 \deprecated Legacy BeOS definition to be phased out, use
886 \c B_SYSTEM_PREFERENCES_DIRECTORY instead.
893 \var directory_which B_BEOS_TRANSLATORS_DIRECTORY
894 \brief The BeOS translators directory.
896 \deprecated Legacy BeOS definition to be phased out, use
897 \c B_SYSTEM_TRANSLATORS_DIRECTORY instead.
904 \var directory_which B_BEOS_MEDIA_NODES_DIRECTORY
905 \brief The BeOS media nodes directory.
907 \deprecated Legacy BeOS definition to be phased out, use
908 \c B_SYSTEM_MEDIA_NODES_DIRECTORY instead.
915 \var directory_which B_BEOS_SOUNDS_DIRECTORY
916 \brief The BeOS sounds directory.
918 \deprecated Legacy BeOS definition to be phased out, use
919 \c B_SYSTEM_SOUNDS_DIRECTORY instead.
925 //// find_path[s]() flags
929 \var B_FIND_PATH_CREATE_DIRECTORY
930 \brief Specifies that if the resulting path doesn't exist, it shall be
931 created a directory, including all missing ancestors.
933 Failure to create the path will cause the respective function to fail.
935 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
943 \var B_FIND_PATH_CREATE_PARENT_DIRECTORY
944 \brief Specifies that if the resulting path's parent doesn't exist, the
945 parent shall be created as a directory, including all missing
948 Failure to create the directory will cause the respective function to fail.
950 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
958 \var B_FIND_PATH_EXISTING_ONLY
959 \brief Specifies that if the resulting path doesn't exist, the respective
960 function shall skip it.
962 In case multiple paths shall be retrieved and none of the paths exists,
963 the function shall fail with \c B_ENTRY_NOT_FOUND.
965 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
973 \enum path_base_directory
974 \brief Path constants to use with find_path(), find_paths(), et al.
976 There are two kinds of constants. Those that are based off an installation
977 location and those that based off an image or given path. The latter are not
978 valid argument for all functions.
985 \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY
986 \brief The installation location base directory.
993 \var B_FIND_PATH_ADD_ONS_DIRECTORY
994 \brief The add-ons directory.
1001 \var B_FIND_PATH_APPS_DIRECTORY
1002 \brief The application directory.
1009 \var B_FIND_PATH_BIN_DIRECTORY
1010 \brief The command line application directory (Unix "bin" directory).
1017 \var B_FIND_PATH_BOOT_DIRECTORY
1018 \brief The directory containing booting related files.
1025 \var B_FIND_PATH_CACHE_DIRECTORY
1026 \brief The directory used for cache files.
1033 \var B_FIND_PATH_DATA_DIRECTORY
1034 \brief The base directory used for read-only data.
1041 \var B_FIND_PATH_DEVELOP_DIRECTORY
1042 \brief The directory containing development related files.
1049 \var B_FIND_PATH_DEVELOP_LIB_DIRECTORY
1050 \brief The the development library directory.
1052 This is the directory where the linker finds libraries.
1059 \var B_FIND_PATH_DOCUMENTATION_DIRECTORY
1060 \brief The base directory used for documentation.
1067 \var B_FIND_PATH_ETC_DIRECTORY
1068 \brief The directory used for Unix-like installation location wide
1069 settings (Unix "etc" directory).
1076 \var B_FIND_PATH_FONTS_DIRECTORY
1077 \brief The fonts directory.
1084 \var B_FIND_PATH_HEADERS_DIRECTORY
1085 \brief The development header files directory.
1092 \var B_FIND_PATH_LIB_DIRECTORY
1093 \brief The runtime library directory.
1095 This is where the runtime loader finds libraries.
1102 \var B_FIND_PATH_LOG_DIRECTORY
1103 \brief The directory where log files are put.
1110 \var B_FIND_PATH_MEDIA_NODES_DIRECTORY
1111 \brief The media node add-ons directory.
1118 \var B_FIND_PATH_PACKAGES_DIRECTORY
1119 \brief The directory where activated packages live.
1126 \var B_FIND_PATH_PREFERENCES_DIRECTORY
1127 \brief The preference application directory.
1134 \var B_FIND_PATH_SERVERS_DIRECTORY
1135 \brief The server and daemon program directory.
1142 \var B_FIND_PATH_SETTINGS_DIRECTORY
1143 \brief The directory used for installation location wide settings.
1145 Note that for the user's home config installation location, this is not
1146 the same as the user's settings directory. Software installed in that
1147 installation location puts their global settings files here.
1154 \var B_FIND_PATH_SOUNDS_DIRECTORY
1155 \brief The directory for sound files.
1162 \var B_FIND_PATH_SPOOL_DIRECTORY
1163 \brief The directory for spool data, e.g. pending printer jobs.
1170 \var B_FIND_PATH_TRANSLATORS_DIRECTORY
1171 \brief The translator add-ons directory.
1178 \var B_FIND_PATH_VAR_DIRECTORY
1179 \brief The directory for variable data (Unix "var" directory).
1186 \var B_FIND_PATH_IMAGE_PATH
1187 \brief The path of the image file that was identified by a pointer
1188 argument passed to the respective function.
1195 \var B_FIND_PATH_PACKAGE_PATH
1196 \brief The path of the package the file referred to by the specified path
1207 \fn status_t find_directory(directory_which which, dev_t volume,
1208 bool createIt, char* pathString, int32 length)
1209 \brief C interface to find_directory
1211 Fills up to \a length characters of \a pathString with the path to \a which
1212 on \a volume. Creates the directory if it doesn't exists if \a createIt is
1220 \fn status_t find_directory(directory_which which, BPath* path, bool createIt,
1222 \brief C++ interface to find_directory
1224 Set \a path to \a which on \a volume.
1231 \fn status_t find_path(const void* codePointer,
1232 path_base_directory baseDirectory, const char* subPath,
1233 char* pathBuffer, size_t bufferSize)
1234 \brief Retrieves a path in the file system layout based on a loaded image
1237 The function determines the path of the image (i.e. executable, library, or
1238 add-on) file associated with \a codePointer, a pointer to a location in the
1239 code or static data of an image loaded in the caller's team. Based on that,
1240 path \a baseDirectory is evaluated. In most cases that means first
1241 determining the path of the installation location from the path, then
1242 appending the relative path corresponding to the given \a baseDirectory
1243 constant, and finally appending \a subPath, if given.
1245 If \a baseDirectory specifies a path that is architecture dependent, the
1246 caller's architecture (as returned by get_architecture()) is used for
1247 constructing the path.
1249 If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are
1250 specified, \a subPath is ignored. In the former case the path of the image
1251 file is returned. In the latter case the path of the package containing the
1254 \param codePointer A pointer to code or static data belonging to the image
1255 based on which the path shall be computed. The special value
1256 \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and
1257 \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
1258 \param baseDirectory Constant indicating which path to retrieve.
1259 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1260 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1262 \param bufferSize Size of the \a pathBuffer buffer.
1263 \return A status code.
1264 \retval B_OK Everything went fine.
1265 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1266 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1267 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1268 and the image file doesn't belong to a package.
1275 \fn status_t find_path_etc(const void* codePointer, const char* dependency,
1276 const char* architecture, path_base_directory baseDirectory,
1277 const char* subPath, uint32 flags, char* pathBuffer, size_t bufferSize)
1278 \brief Retrieves a path in the file system layout based on a loaded image
1281 The function determines the path of the image (i.e. executable, library, or
1282 add-on) file associated with \a codePointer, a pointer to a location in the
1283 code or static data of an image loaded in the caller's team. Based on that,
1284 path \a baseDirectory is evaluated. In most cases that means first
1285 determining the path of the installation location from the path, then
1286 appending the relative path corresponding to the given \a baseDirectory
1287 constant, and finally appending \a subPath, if given.
1289 If \a dependency is specified, instead of determining the installation
1290 location path from the image path, the installation location path of the
1291 dependency \a dependency of the package containing the image file is used.
1293 If \a baseDirectory specifies a path that is architecture dependent,
1294 \a architecture is used for constructing the path. If \a architecture is
1295 \c NULL, the caller's architecture (as returned by get_architecture()) is
1298 If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are
1299 specified, \a dependency and \a subPath are ignored. In the former case the
1300 path of the image file is returned. In the latter case the path of the
1301 package containing the image file, if any.
1303 \param codePointer A pointer to code or static data belonging to the image
1304 based on which the path shall be computed. The special value
1305 \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and
1306 \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
1307 \param dependency The name of the package's "requires" entry to be used for
1308 resolving the installation location. Can be \c NULL.
1309 \param architecture The name of the architecture to be used for resolving
1310 architecture dependent paths. Can be \c NULL, in which case the
1311 caller's architecture is used.
1312 \param baseDirectory Constant indicating which path to retrieve.
1313 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1314 \param flags Bitwise OR of any of the following flags:
1315 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
1316 exist, create it as a directory (including all missing ancestors).
1317 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
1318 parent doesn't exist, create the parent directory (including all
1320 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
1321 fail with \c B_ENTRY_NOT_FOUND.
1322 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1324 \param bufferSize Size of the \a pathBuffer buffer.
1325 \return A status code.
1326 \retval B_OK Everything went fine.
1327 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1328 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1329 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1330 and the image file doesn't belong to a package, or \c dependency
1331 was specified, but isn't a "requires" entry of the package, or
1332 \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
1340 \fn status_t find_path_for_path(const char* path,
1341 path_base_directory baseDirectory, const char* subPath,
1342 char* pathBuffer, size_t bufferSize)
1343 \brief Retrieves a path in the file system layout based on a given path.
1345 Based on the given path \a path the function evaluates \a baseDirectory. In
1346 most cases that means first determining the path of the installation
1347 location from the given path, then appending the relative path corresponding
1348 to the given \a baseDirectory constant, and finally appending \a subPath, if
1351 If \a baseDirectory specifies a path that is architecture dependent, the
1352 architecture associated with the given path (as returned by
1353 guess_architecture_for_path()) is used for constructing the path.
1355 If \c B_FIND_PATH_PACKAGE_PATH is specified, \a subPath is ignored. In
1356 this case the path of the package containing the file referred to by \a path
1357 is returned. \c B_FIND_PATH_IMAGE_PATH is not a valid argument for this
1360 \param path A path based on which the path shall be computed.
1361 \param baseDirectory Constant indicating which path to retrieve.
1362 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1363 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1365 \param bufferSize Size of the \a pathBuffer buffer.
1366 \return A status code.
1367 \retval B_OK Everything went fine.
1368 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1369 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1370 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1371 and \a path does refer to a file that belongs to a package.
1378 \fn status_t find_path_for_path_etc(const char* path,
1379 const char* dependency, const char* architecture,
1380 path_base_directory baseDirectory, const char* subPath, uint32 flags,
1381 char* pathBuffer, size_t bufferSize)
1382 \brief Retrieves a path in the file system layout based on a given path.
1384 Based on the given path \a path the function evaluates \a baseDirectory. In
1385 most cases that means first determining the path of the installation
1386 location from the given path, then appending the relative path corresponding
1387 to the given \a baseDirectory constant, and finally appending \a subPath, if
1390 If \a dependency is specified, instead of determining the installation
1391 location path from the given path, the installation location path of the
1392 dependency \a dependency of the package containing the file referred to by
1395 If \a baseDirectory specifies a path that is architecture dependent,
1396 \a architecture is used for constructing the path. If \a architecture is
1397 \c NULL, the architecture associated with the given path (as returned by
1398 guess_architecture_for_path()) is used.
1400 If \c B_FIND_PATH_PACKAGE_PATH is specified, \a dependency and
1401 \a subPath are ignored. In this case the path of the package containing the
1402 file referred to by \a path is returned. \c B_FIND_PATH_IMAGE_PATH is not
1403 a valid argument for this function.
1405 \param path A path based on which the path shall be computed.
1406 \param dependency The name of the package's "requires" entry to be used for
1407 resolving the installation location. Can be \c NULL.
1408 \param architecture The name of the architecture to be used for resolving
1409 architecture dependent paths. Can be \c NULL, in which case the
1410 architecture associated with \a path is used.
1411 \param baseDirectory Constant indicating which path to retrieve.
1412 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1413 \param flags Bitwise OR of any of the following flags:
1414 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
1415 exist, create it as a directory (including all missing ancestors).
1416 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
1417 parent doesn't exist, create the parent directory (including all
1419 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
1420 fail with \c B_ENTRY_NOT_FOUND.
1421 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1423 \param bufferSize Size of the \a pathBuffer buffer.
1424 \return A status code.
1425 \retval B_OK Everything went fine.
1426 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1427 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1428 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1429 and \a path does refer to a file that belongs to a package, or
1430 \c dependency was specified, but isn't a "requires" entry of the
1431 package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the
1432 resulting path doesn't exist.
1439 \fn status_t find_paths(path_base_directory baseDirectory,
1440 const char* subPath, char*** _paths, size_t* _pathCount)
1441 \brief Retrieves a list of paths in the file system layout.
1443 For each installation location -- in the order most specific to most
1444 generic, non-packaged before packaged -- the function evaluates
1445 \a baseDirectory to a path and appends \a subPath, if given.
1447 If \a baseDirectory specifies a path that is architecture dependent,
1448 the caller's architecture (as returned by get_architecture()) is used for
1449 constructing each path.
1451 \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not
1452 valid arguments for this function.
1454 The array of paths retrieved is allocated on the heap and returned via
1455 \a _paths. The caller is responsible for calling free() for the returned
1458 \param baseDirectory Constant indicating which paths to retrieve.
1459 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1460 \param _paths Pointer to a pre-allocated variable where the pointer to the
1461 allocated path array shall be stored on success.
1462 \param _pathCount Pointer to a pre-allocated variable where the number of
1463 paths in the path array shall be stored on success.
1465 \return A status code.
1466 \retval B_OK Everything went fine.
1467 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1468 paths doesn't exist.
1475 \fn status_t find_paths_etc(const char* architecture,
1476 path_base_directory baseDirectory, const char* subPath, uint32 flags,
1477 char*** _paths, size_t* _pathCount)
1478 \brief Retrieves a list of paths in the file system layout.
1480 For each installation location -- in the order most specific to most
1481 generic, non-packaged before packaged -- the function evaluates
1482 \a baseDirectory to a path and appends \a subPath, if given.
1484 If \a baseDirectory specifies a path that is architecture dependent,
1485 \a architecture is used for constructing each path. If \a architecture is
1486 \c NULL, the caller's architecture (as returned by get_architecture()) is
1489 \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not
1490 valid arguments for this function.
1492 The array of paths retrieved is allocated on the heap and returned via
1493 \a _paths. The caller is responsible for calling free() for the returned
1496 \param architecture The name of the architecture to be used for resolving
1497 architecture dependent paths. Can be \c NULL, in which case the
1498 caller's architecture is used.
1499 \param baseDirectory Constant indicating which paths to retrieve.
1500 \param subPath Relative subpath that shall be appended. Can be \c NULL.
1501 \param flags Bitwise OR of any of the following flags:
1502 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
1503 exist, create it as a directory (including all missing ancestors).
1504 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
1505 parent doesn't exist, create the parent directory (including all
1507 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
1508 fail with \c B_ENTRY_NOT_FOUND.
1509 \param _paths Pointer to a pre-allocated variable where the pointer to the
1510 allocated path array shall be stored on success.
1511 \param _pathCount Pointer to a pre-allocated variable where the number of
1512 paths in the path array shall be stored on success.
1513 \return A status code.
1514 \retval B_OK Everything went fine.
1515 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1516 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was
1517 specified and none of the resulting paths do exist.