BTRFS: Reimplement TreeIterator, add some error checks and remove redundancies.
[haiku.git] / docs / user / storage / FindDirectory.dox
blobe1bad237abf405531083e58f0b387a315018f432
1 /*
2  * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3  * Distributed under the terms of the MIT License.
4  *
5  * Documentation by:
6  *              Adrien Destugues, pulkomandy@pulkomandy.ath.cx
7  *              John Scipione, jscipione@gmail.com
8  *              Ingo Weinhold, ingo_weinhold@gmx.de
9  *
10  * Corresponds to:
11  *              headers/os/storage/FindDirectory.h       hrev47402
12  *              src/kits/storage/FindDirectory.cpp       hrev47402
13  */
16 /*!
17         \file FindDirectory.h
18         \ingroup storage
19         \ingroup libbe
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
47           image file.
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
52           settings directory.
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++
58         code.
62 /*!
63         \enum directory_which
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
73         directory.
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
77         different settings.
79         \remark The \c B_COMMON_* constants have been intentionally removed in
80                 Haiku R1, use the \c B_SYSTEM_* constants instead.
82         \since BeOS R3
86 /*!
87         \var directory_which B_DESKTOP_DIRECTORY
88         \brief The desktop directory for a given volume.
90         \since BeOS R3
94 /*!
95         \var directory_which B_TRASH_DIRECTORY
96         \brief The trash directory for a given volume.
98         \since BeOS R3
103         \var directory_which B_SYSTEM_DIRECTORY
104         \brief The system directory.
106         \since Haiku R1
111         \var directory_which B_SYSTEM_ADDONS_DIRECTORY
112         \brief The system add-ons directory
114         \since Haiku R1
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.
124         \since Haiku R1
129         \var directory_which B_SYSTEM_FONTS_DIRECTORY
130         \brief The system fonts directory.
132         \since Haiku R1
137         \var directory_which B_SYSTEM_LIB_DIRECTORY
138         \brief The system lib directory.
140         \since Haiku R1
145         \var directory_which B_SYSTEM_SERVERS_DIRECTORY
146         \brief The system servers directory.
148         \since Haiku R1
153         \var directory_which B_SYSTEM_APPS_DIRECTORY
154         \brief The system applications directory.
156         Contains applications with graphical user interface.
158         \since Haiku R1
163         \var directory_which B_SYSTEM_BIN_DIRECTORY
164         \brief The system bin directory.
166         Contains command-line applications runnable from Terminal.
168         \since Haiku R1
173         \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY
174         \brief The system documentation directory, contains e.g. man pages.
176         \since Haiku R1
181         \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY
182         \brief The system preferences directory.
184         \since Haiku R1
189         \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY
190         \brief The system translator directory.
192         \since Haiku R1
197         \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY
198         \brief The system media nodes directory.
200         \since Haiku R1
205         \var directory_which B_SYSTEM_SOUNDS_DIRECTORY
206         \brief The system sounds directory.
208         \since Haiku R1
213         \var directory_which B_SYSTEM_DATA_DIRECTORY
214         \brief The system data directory.
216         \since Haiku R1
221         \var directory_which B_SYSTEM_DEVELOP_DIRECTORY
222         \brief The system directory containing development related files.
224         \since Haiku R1
229         \var directory_which B_SYSTEM_PACKAGES_DIRECTORY
230         \brief The system directory where activated packages live.
232         \since Haiku R1
237         \var directory_which B_SYSTEM_HEADERS_DIRECTORY
238         \brief The system directory for development header files.
240         \since Haiku R1
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).
249         \since Haiku R1
254         \var directory_which B_SYSTEM_SETTINGS_DIRECTORY
255         \brief The system directory used for installation location-wide settings.
257         \since Haiku R1
262         \var directory_which B_SYSTEM_LOG_DIRECTORY
263         \brief The system directory where log files are put.
265         \since Haiku R1
270         \var directory_which B_SYSTEM_SPOOL_DIRECTORY
271         \brief The system directory for spool data (e.g. pending printer jobs).
273         \since Haiku R1
278         \var directory_which B_SYSTEM_TEMP_DIRECTORY
279         \brief The global directory for temporary files (Unix "tmp" directory).
281         \since Haiku R1
286         \var directory_which B_SYSTEM_VAR_DIRECTORY
287         \brief The system directory for variable data (Unix "var" directory).
289         \since Haiku R1
294         \var directory_which B_SYSTEM_CACHE_DIRECTORY
295         \brief The system directory used for cache files.
297         \since Haiku R1
302         \var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY
303         \brief The system non-packaged installation location directory.
305         \since Haiku R1
310         \var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY
311         \brief The system non-packaged add-ons directory
313         \since Haiku R1
318         \var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY
319         \brief The system non-packaged translator directory.
321         \since Haiku R1
326         \var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY
327         \brief The system non-packaged media nodes directory.
329         \since Haiku R1
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.
338         \since Haiku R1
343         \var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY
344         \brief The system non-packaged data directory.
346         \since Haiku R1
351         \var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY
352         \brief The system non-packaged fonts directory
354         \since Haiku R1
359         \var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY
360         \brief The system non-packaged sounds directory.
362         \since Haiku R1
367         \var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY
368         \brief The system non-packaged documentation directory. Contains e.g. man pages.
370         \since Haiku R1
375         \var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY
376         \brief The system non-packaged lib directory.
378         \since Haiku R1
383         \var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY
384         \brief The system non-packaged directory for development header files.
386         \since Haiku R1
391         \var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY
392         \brief The system non-packaged directory containing development related
393                files.
395         \since Haiku R1
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.
406         \since BeOS R3
411         \var directory_which B_USER_CONFIG_DIRECTORY
412         \brief The user packaged installation location directory.
414         \since BeOS R3
419         \var directory_which B_USER_ADDONS_DIRECTORY
420         \brief The user add-ons directory
422         \since BeOS R3
427         \var directory_which B_USER_BOOT_DIRECTORY
428         \brief The user directory containing booting related files.
430         \since BeOS R3
435         \var directory_which B_USER_FONTS_DIRECTORY
436         \brief The user fonts directory.
438         \since BeOS R3
443         \var directory_which B_USER_LIB_DIRECTORY
444         \brief The user lib directory.
446         \since BeOS R3
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.
459         \since BeOS R3
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
468         Deskbar leaf menu.
470         \since BeOS R3
475         \var directory_which B_USER_PRINTERS_DIRECTORY
476         \brief The user directory for printer settings.
478         \since Haiku R1
483         \var directory_which B_USER_TRANSLATORS_DIRECTORY
484         \brief The user translator directory.
486         \since Haiku R1
491         \var directory_which B_USER_MEDIA_NODES_DIRECTORY
492         \brief The user media nodes directory.
494         \since Haiku R1
499         \var directory_which B_USER_SOUNDS_DIRECTORY
500         \brief The user sounds directory.
502         \since Haiku R1
507         \var directory_which B_USER_DATA_DIRECTORY
508         \brief The user data directory.
510         \since Haiku R1
515         \var directory_which B_USER_CACHE_DIRECTORY
516         \brief The user directory used for cache files.
518         \since Haiku R1
523         \var directory_which B_USER_PACKAGES_DIRECTORY
524         \brief The user directory where activated packages live.
526         \since Haiku R1
531         \var directory_which B_USER_HEADERS_DIRECTORY
532         \brief The user directory for development header files.
534         \since Haiku R1
539         \var directory_which B_USER_DEVELOP_DIRECTORY
540         \brief The user directory containing development related files.
542         \since Haiku R1
547         \var directory_which B_USER_DOCUMENTATION_DIRECTORY
548         \brief The user documentation directory, contains e.g. man pages.
550         \since Haiku R1
555         \var directory_which B_USER_SERVERS_DIRECTORY
556         \brief The user servers directory.
558         \since Haiku R1
563         \var directory_which B_USER_APPS_DIRECTORY
564         \brief The user applications directory.
566         Contains applications with graphical user interface.
568         \since Haiku R1
573         \var directory_which B_USER_BIN_DIRECTORY
574         \brief The user bin directory.
576         Contains command-line applications runnable from Terminal.
578         \since Haiku R1
583         \var directory_which B_USER_PREFERENCES_DIRECTORY
584         \brief The user preference applications directory.
586         \since Haiku R1
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).
595         \since Haiku R1
600         \var directory_which B_USER_LOG_DIRECTORY
601         \brief The user directory where log files are put.
603         \since Haiku R1
608         \var directory_which B_USER_SPOOL_DIRECTORY
609         \brief The user directory for spool data, e.g. pending printer jobs.
611         \since Haiku R1
616         \var directory_which B_USER_VAR_DIRECTORY
617         \brief The user directory for variable data (Unix "var" directory).
619         \since Haiku R1
624         \var directory_which B_USER_NONPACKAGED_DIRECTORY
625         \brief The user non-packaged installation location directory.
627         \since Haiku R1
632         \var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY
633         \brief The user non-packaged add-ons directory
635         \since Haiku R1
640         \var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY
641         \brief The user non-packaged translator directory.
643         \since Haiku R1
648         \var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY
649         \brief The user non-packaged media nodes directory.
651         \since Haiku R1
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.
661         \since Haiku R1
666         \var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY
667         \brief The user non-packaged data directory.
669         \since Haiku R1
674         \var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY
675         \brief The user non-packaged fonts directory
677         \since Haiku R1
682         \var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY
683         \brief The user non-packaged sounds directory.
685         \since Haiku R1
690         \var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY
691         \brief The user non-packaged documentation directory, contains e.g. man
692                pages.
694         \since Haiku R1
699         \var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY
700         \brief The user non-packaged lib directory.
702         \since Haiku R1
707         \var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY
708         \brief The user non-packaged directory for development header files.
710         \since Haiku R1
715         \var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY
716         \brief The user non-packaged directory containing development related
717                files.
719         \since Haiku R1
724         \var directory_which B_APPS_DIRECTORY
725         \brief The global applications directory.
727         Contains applications with graphical user interface.
729         \since BeOS R3
734         \var directory_which B_PREFERENCES_DIRECTORY
735         \brief The global preference applications directory.
737         \since BeOS R3
742         \var directory_which B_UTILITIES_DIRECTORY
743         \brief The global utility applications directory.
745         \since Haiku R1
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.
755         \since Haiku R1
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.
766         \since BeOS R3
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.
777         \since BeOS R3
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.
788         \since BeOS R3
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.
799         \since BeOS R3
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.
810         \since BeOS R3
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.
821         \since BeOS R3
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.
832         \since BeOS R3
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.
843         \since BeOS R3
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.
854         \since BeOS R3
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.
866         \since BeOS R3
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.
877         \since BeOS R3
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.
888         \since BeOS R3
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.
899         \since BeOS R3
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.
910         \since BeOS R3
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.
921         \since BeOS R3
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(),
936         and BPathFinder API.
938         \since Haiku R1
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
946                ancestors.
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(),
951         and BPathFinder API.
953         \since Haiku R1
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(),
966         and BPathFinder API.
968         \since Haiku R1
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.
980         \since Haiku R1
985         \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY
986         \brief The installation location base directory.
988         \since Haiku R1
993         \var B_FIND_PATH_ADD_ONS_DIRECTORY
994         \brief The add-ons directory.
996         \since Haiku R1
1001         \var B_FIND_PATH_APPS_DIRECTORY
1002         \brief The application directory.
1004         \since Haiku R1
1009         \var B_FIND_PATH_BIN_DIRECTORY
1010         \brief The command line application directory (Unix "bin" directory).
1012         \since Haiku R1
1017         \var B_FIND_PATH_BOOT_DIRECTORY
1018         \brief The directory containing booting related files.
1020         \since Haiku R1
1025         \var B_FIND_PATH_CACHE_DIRECTORY
1026         \brief The directory used for cache files.
1028         \since Haiku R1
1033         \var B_FIND_PATH_DATA_DIRECTORY
1034         \brief The base directory used for read-only data.
1036         \since Haiku R1
1041         \var B_FIND_PATH_DEVELOP_DIRECTORY
1042         \brief The directory containing development related files.
1044         \since Haiku R1
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.
1054         \since Haiku R1
1059         \var B_FIND_PATH_DOCUMENTATION_DIRECTORY
1060         \brief The base directory used for documentation.
1062         \since Haiku R1
1067         \var B_FIND_PATH_ETC_DIRECTORY
1068         \brief The directory used for Unix-like installation location wide
1069                settings (Unix "etc" directory).
1071         \since Haiku R1
1076         \var B_FIND_PATH_FONTS_DIRECTORY
1077         \brief The fonts directory.
1079         \since Haiku R1
1084         \var B_FIND_PATH_HEADERS_DIRECTORY
1085         \brief The development header files directory.
1087         \since Haiku R1
1092         \var B_FIND_PATH_LIB_DIRECTORY
1093         \brief The runtime library directory.
1095         This is where the runtime loader finds libraries.
1097         \since Haiku R1
1102         \var B_FIND_PATH_LOG_DIRECTORY
1103         \brief The directory where log files are put.
1105         \since Haiku R1
1110         \var B_FIND_PATH_MEDIA_NODES_DIRECTORY
1111         \brief The media node add-ons directory.
1113         \since Haiku R1
1118         \var B_FIND_PATH_PACKAGES_DIRECTORY
1119         \brief The directory where activated packages live.
1121         \since Haiku R1
1126         \var B_FIND_PATH_PREFERENCES_DIRECTORY
1127         \brief The preference application directory.
1129         \since Haiku R1
1134         \var B_FIND_PATH_SERVERS_DIRECTORY
1135         \brief The server and daemon program directory.
1137         \since Haiku R1
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.
1149         \since Haiku R1
1154         \var B_FIND_PATH_SOUNDS_DIRECTORY
1155         \brief The directory for sound files.
1157         \since Haiku R1
1162         \var B_FIND_PATH_SPOOL_DIRECTORY
1163         \brief The directory for spool data, e.g. pending printer jobs.
1165         \since Haiku R1
1170         \var B_FIND_PATH_TRANSLATORS_DIRECTORY
1171         \brief The translator add-ons directory.
1173         \since Haiku R1
1178         \var B_FIND_PATH_VAR_DIRECTORY
1179         \brief The directory for variable data (Unix "var" directory).
1181         \since Haiku R1
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.
1190         \since Haiku R1
1195         \var B_FIND_PATH_PACKAGE_PATH
1196         \brief The path of the package the file referred to by the specified path
1197                belongs to.
1199         \since Haiku R1
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
1213         set.
1215         \since BeOS R3
1220         \fn status_t find_directory(directory_which which, BPath* path, bool createIt,
1221                 BVolume* volume)
1222         \brief C++ interface to find_directory
1224         Set \a path to \a which on \a volume.
1226         \since BeOS R3
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
1235                file.
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
1252         image file, if any.
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
1261                shall be stored in.
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.
1270         \since Haiku R1
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
1279                file.
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
1296         used.
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
1319                  missing ancestors).
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
1323                shall be stored in.
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
1333                 doesn't exist.
1335         \since Haiku R1
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
1349         given.
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
1358         function.
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
1364                shall be stored in.
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.
1373         \since Haiku R1
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
1388         given.
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
1393         \a path is used.
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
1418                  missing ancestors).
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
1422                shall be stored in.
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.
1434         \since Haiku R1
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
1456         pointer.
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.
1470         \since Haiku R1
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
1487         used.
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
1494         pointer.
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
1506                  missing ancestors).
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.
1519         \since Haiku R1