xref: /haiku/docs/user/storage/FindDirectory.dox (revision 99d1318ec02694fc520a0dc38ae38565db7e8c3c)
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 */
14
15
16/*!
17	\file FindDirectory.h
18	\ingroup storage
19	\brief Provides the find_directory(), find_path(), find_paths() functions
20	       as well as the \c directory_which constants.
21
22	Haiku provides a set of directories for applications to use. These can be
23	accessed using the functions find_directory(), find_path(), find_path_etc(),
24	find_paths(), find_paths_etc(), find_path_for_path(),
25	find_path_for_path_etc(). It is very important to use the functions at
26	runtime and not hardcode the path, as it may change in future versions of
27	Haiku, and already changed in past ones. Using these functions makes your
28	application more future-proof, and makes sure everyone puts data in the same
29	place, which makes the system cleaner and easier to manage.
30
31	Note that while the find_directory() function is still needed for some, it
32	is deprecated for many other use cases, like:
33	- When collecting files from all installation locations, be it data files
34	  (like fonts) or add-ons your application/library supports, use
35	  find_paths(), find_paths_etc(), or BPathFinder::FindPaths() instead.
36	  Formerly you had to use find_directory() and iterate through all possible
37	  constants manually. Not only is this less convenient, it also doesn't
38	  account for the possibility of installation locations being added or
39	  removed in a later Haiku release.
40	- If your code needs to access another file that also belongs to your
41	  software (i.e. if packaged it is included in the same package), use
42	  find_path() or BPathFinder::FindPath() instead.
43	  Formerly this case could not really be handled properly. Either you had
44	  to hard-code the installation location by using the respective directory
45	  constant or you had to manually construct a path relative to your code's
46	  image file.
47
48	Cases for which find_directory() is still useful:
49	- Getting per-volume paths like for the trash directory.
50	- Getting specific paths like for the user's home directory or the user's
51	  settings directory.
52
53	Note that these functions can be accessed from C code (they are implemented
54	in libroot), to make it easy to use also in ported applications. However,
55	there are also a C++ version of find_directory() and the BPathFinder class
56	(both implemented in libbe), which may be more convenient to use in C++
57	code.
58*/
59
60
61/*!
62	\enum directory_which
63	\brief Directory constants to use with find_directory().
64
65	There are four kind of directories. Volume-local directories exist on each
66	volume, they may be at a different location in each of them. For example
67	the location of the trash directory depends on the filesystem. System
68	directories are system-wide, they live on only one volume. System is meant
69	for internal system management and system-wide applications. User
70	directories have a different value depending on the UID of the application
71	calling the function. They are usually located in the user's home
72	directory.
73
74	Use system directories for system-wide files such as drivers and use user
75	directories are for application settings, since each user may want
76	different settings.
77
78	\remark The \c B_COMMON_* constants have been intentionally removed in
79	        Haiku R1, use the \c B_SYSTEM_* constants instead.
80
81	\since BeOS R3
82*/
83
84
85/*!
86	\var directory_which B_DESKTOP_DIRECTORY
87	\brief The desktop directory for a given volume.
88
89	\since BeOS R3
90*/
91
92
93/*!
94	\var directory_which B_TRASH_DIRECTORY
95	\brief The trash directory for a given volume.
96
97	\since BeOS R3
98*/
99
100
101/*!
102	\var directory_which B_SYSTEM_DIRECTORY
103	\brief The system directory.
104
105	\since Haiku R1
106*/
107
108
109/*!
110	\var directory_which B_SYSTEM_ADDONS_DIRECTORY
111	\brief The system add-ons directory
112
113	\since Haiku R1
114*/
115
116
117/*!
118	\var directory_which B_SYSTEM_BOOT_DIRECTORY
119	\brief The system boot directory.
120
121	Contains the minimal set of files required for booting Haiku.
122
123	\since Haiku R1
124*/
125
126
127/*!
128	\var directory_which B_SYSTEM_FONTS_DIRECTORY
129	\brief The system fonts directory.
130
131	\since Haiku R1
132*/
133
134
135/*!
136	\var directory_which B_SYSTEM_LIB_DIRECTORY
137	\brief The system lib directory.
138
139	\since Haiku R1
140*/
141
142
143/*!
144	\var directory_which B_SYSTEM_SERVERS_DIRECTORY
145	\brief The system servers directory.
146
147	\since Haiku R1
148*/
149
150
151/*!
152	\var directory_which B_SYSTEM_APPS_DIRECTORY
153	\brief The system applications directory.
154
155	Contains applications with graphical user interface.
156
157	\since Haiku R1
158*/
159
160
161/*!
162	\var directory_which B_SYSTEM_BIN_DIRECTORY
163	\brief The system bin directory.
164
165	Contains command-line applications runnable from Terminal.
166
167	\since Haiku R1
168*/
169
170
171/*!
172	\var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY
173	\brief The system documentation directory, contains e.g. man pages.
174
175	\since Haiku R1
176*/
177
178
179/*!
180	\var directory_which B_SYSTEM_PREFERENCES_DIRECTORY
181	\brief The system preferences directory.
182
183	\since Haiku R1
184*/
185
186
187/*!
188	\var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY
189	\brief The system translator directory.
190
191	\since Haiku R1
192*/
193
194
195/*!
196	\var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY
197	\brief The system media nodes directory.
198
199	\since Haiku R1
200*/
201
202
203/*!
204	\var directory_which B_SYSTEM_SOUNDS_DIRECTORY
205	\brief The system sounds directory.
206
207	\since Haiku R1
208*/
209
210
211/*!
212	\var directory_which B_SYSTEM_DATA_DIRECTORY
213	\brief The system data directory.
214
215	\since Haiku R1
216*/
217
218
219/*!
220	\var directory_which B_SYSTEM_DEVELOP_DIRECTORY
221	\brief The system directory containing development related files.
222
223	\since Haiku R1
224*/
225
226
227/*!
228	\var directory_which B_SYSTEM_PACKAGES_DIRECTORY
229	\brief The system directory where activated packages live.
230
231	\since Haiku R1
232*/
233
234
235/*!
236	\var directory_which B_SYSTEM_HEADERS_DIRECTORY
237	\brief The system directory for development header files.
238
239	\since Haiku R1
240*/
241
242
243/*!
244	\var directory_which B_SYSTEM_ETC_DIRECTORY
245	\brief The system directory used for Unix-like installation location-wide
246	       settings (Unix "etc" directory).
247
248	\since Haiku R1
249*/
250
251
252/*!
253	\var directory_which B_SYSTEM_SETTINGS_DIRECTORY
254	\brief The system directory used for installation location-wide settings.
255
256	\since Haiku R1
257*/
258
259
260/*!
261	\var directory_which B_SYSTEM_LOG_DIRECTORY
262	\brief The system directory where log files are put.
263
264	\since Haiku R1
265*/
266
267
268/*!
269	\var directory_which B_SYSTEM_SPOOL_DIRECTORY
270	\brief The system directory for spool data (e.g. pending printer jobs).
271
272	\since Haiku R1
273*/
274
275
276/*!
277	\var directory_which B_SYSTEM_TEMP_DIRECTORY
278	\brief The global directory for temporary files (Unix "tmp" directory).
279
280	\since Haiku R1
281*/
282
283
284/*!
285	\var directory_which B_SYSTEM_VAR_DIRECTORY
286	\brief The system directory for variable data (Unix "var" directory).
287
288	\since Haiku R1
289*/
290
291
292/*!
293	\var directory_which B_SYSTEM_CACHE_DIRECTORY
294	\brief The system directory used for cache files.
295
296	\since Haiku R1
297*/
298
299
300/*!
301	\var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY
302	\brief The system non-packaged installation location directory.
303
304	\since Haiku R1
305*/
306
307
308/*!
309	\var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY
310	\brief The system non-packaged add-ons directory
311
312	\since Haiku R1
313*/
314
315
316/*!
317	\var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY
318	\brief The system non-packaged translator directory.
319
320	\since Haiku R1
321*/
322
323
324/*!
325	\var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY
326	\brief The system non-packaged media nodes directory.
327
328	\since Haiku R1
329*/
330
331
332/*!
333	\var directory_which B_SYSTEM_NONPACKAGED_BIN_DIRECTORY
334	The system non-packaged bin directory. Contains command-line applications
335	\brief runnable from Terminal.
336
337	\since Haiku R1
338*/
339
340
341/*!
342	\var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY
343	\brief The system non-packaged data directory.
344
345	\since Haiku R1
346*/
347
348
349/*!
350	\var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY
351	\brief The system non-packaged fonts directory
352
353	\since Haiku R1
354*/
355
356
357/*!
358	\var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY
359	\brief The system non-packaged sounds directory.
360
361	\since Haiku R1
362*/
363
364
365/*!
366	\var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY
367	\brief The system non-packaged documentation directory. Contains e.g. man pages.
368
369	\since Haiku R1
370*/
371
372
373/*!
374	\var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY
375	\brief The system non-packaged lib directory.
376
377	\since Haiku R1
378*/
379
380
381/*!
382	\var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY
383	\brief The system non-packaged directory for development header files.
384
385	\since Haiku R1
386*/
387
388
389/*!
390	\var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY
391	\brief The system non-packaged directory containing development related
392	       files.
393
394	\since Haiku R1
395*/
396
397
398/*!
399	\var directory_which B_USER_DIRECTORY
400	\brief The user home directory.
401
402	Do NOT store application settings here as on unix, instead use
403	\c B_USER_SETTINGS_DIRECTORY.
404
405	\since BeOS R3
406*/
407
408
409/*!
410	\var directory_which B_USER_CONFIG_DIRECTORY
411	\brief The user packaged installation location directory.
412
413	\since BeOS R3
414*/
415
416
417/*!
418	\var directory_which B_USER_ADDONS_DIRECTORY
419	\brief The user add-ons directory
420
421	\since BeOS R3
422*/
423
424
425/*!
426	\var directory_which B_USER_BOOT_DIRECTORY
427	\brief The user directory containing booting related files.
428
429	\since BeOS R3
430*/
431
432
433/*!
434	\var directory_which B_USER_FONTS_DIRECTORY
435	\brief The user fonts directory.
436
437	\since BeOS R3
438*/
439
440
441/*!
442	\var directory_which B_USER_LIB_DIRECTORY
443	\brief The user lib directory.
444
445	\since BeOS R3
446*/
447
448
449/*!
450	\var directory_which B_USER_SETTINGS_DIRECTORY
451	\brief The user settings directory.
452
453	You may store your application settings here. Create a subdirectory for
454	your application if you have multiple files to store, else, put a single
455	file. The file or directory should have the same name as your
456	application, so the user knows what it's used for.
457
458	\since BeOS R3
459*/
460
461
462/*!
463	\var directory_which B_USER_DESKBAR_DIRECTORY
464	\brief The user Deskbar directory.
465
466	You may add a link to your application here, so it shows up in the user's
467	Deskbar leaf menu.
468
469	\since BeOS R3
470*/
471
472
473/*!
474	\var directory_which B_USER_PRINTERS_DIRECTORY
475	\brief The user directory for printer settings.
476
477	\since Haiku R1
478*/
479
480
481/*!
482	\var directory_which B_USER_TRANSLATORS_DIRECTORY
483	\brief The user translator directory.
484
485	\since Haiku R1
486*/
487
488
489/*!
490	\var directory_which B_USER_MEDIA_NODES_DIRECTORY
491	\brief The user media nodes directory.
492
493	\since Haiku R1
494*/
495
496
497/*!
498	\var directory_which B_USER_SOUNDS_DIRECTORY
499	\brief The user sounds directory.
500
501	\since Haiku R1
502*/
503
504
505/*!
506	\var directory_which B_USER_DATA_DIRECTORY
507	\brief The user data directory.
508
509	\since Haiku R1
510*/
511
512
513/*!
514	\var directory_which B_USER_CACHE_DIRECTORY
515	\brief The user directory used for cache files.
516
517	\since Haiku R1
518*/
519
520
521/*!
522	\var directory_which B_USER_PACKAGES_DIRECTORY
523	\brief The user directory where activated packages live.
524
525	\since Haiku R1
526*/
527
528
529/*!
530	\var directory_which B_USER_HEADERS_DIRECTORY
531	\brief The user directory for development header files.
532
533	\since Haiku R1
534*/
535
536
537/*!
538	\var directory_which B_USER_DEVELOP_DIRECTORY
539	\brief The user directory containing development related files.
540
541	\since Haiku R1
542*/
543
544
545/*!
546	\var directory_which B_USER_DOCUMENTATION_DIRECTORY
547	\brief The user documentation directory, contains e.g. man pages.
548
549	\since Haiku R1
550*/
551
552
553/*!
554	\var directory_which B_USER_SERVERS_DIRECTORY
555	\brief The user servers directory.
556
557	\since Haiku R1
558*/
559
560
561/*!
562	\var directory_which B_USER_APPS_DIRECTORY
563	\brief The user applications directory.
564
565	Contains applications with graphical user interface.
566
567	\since Haiku R1
568*/
569
570
571/*!
572	\var directory_which B_USER_BIN_DIRECTORY
573	\brief The user bin directory.
574
575	Contains command-line applications runnable from Terminal.
576
577	\since Haiku R1
578*/
579
580
581/*!
582	\var directory_which B_USER_PREFERENCES_DIRECTORY
583	\brief The user preference applications directory.
584
585	\since Haiku R1
586*/
587
588
589/*!
590	\var directory_which B_USER_ETC_DIRECTORY
591	\brief The user directory used for Unix-like installation location-wide
592	       settings (Unix "etc" directory).
593
594	\since Haiku R1
595*/
596
597
598/*!
599	\var directory_which B_USER_LOG_DIRECTORY
600	\brief The user directory where log files are put.
601
602	\since Haiku R1
603*/
604
605
606/*!
607	\var directory_which B_USER_SPOOL_DIRECTORY
608	\brief The user directory for spool data, e.g. pending printer jobs.
609
610	\since Haiku R1
611*/
612
613
614/*!
615	\var directory_which B_USER_VAR_DIRECTORY
616	\brief The user directory for variable data (Unix "var" directory).
617
618	\since Haiku R1
619*/
620
621
622/*!
623	\var directory_which B_USER_NONPACKAGED_DIRECTORY
624	\brief The user non-packaged installation location directory.
625
626	\since Haiku R1
627*/
628
629
630/*!
631	\var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY
632	\brief The user non-packaged add-ons directory
633
634	\since Haiku R1
635*/
636
637
638/*!
639	\var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY
640	\brief The user non-packaged translator directory.
641
642	\since Haiku R1
643*/
644
645
646/*!
647	\var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY
648	\brief The user non-packaged media nodes directory.
649
650	\since Haiku R1
651*/
652
653
654/*!
655	\var directory_which B_USER_NONPACKAGED_BIN_DIRECTORY
656	\brief The user non-packaged bin directory.
657
658	Contains command-line applications runnable from Terminal.
659
660	\since Haiku R1
661*/
662
663
664/*!
665	\var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY
666	\brief The user non-packaged data directory.
667
668	\since Haiku R1
669*/
670
671
672/*!
673	\var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY
674	\brief The user non-packaged fonts directory
675
676	\since Haiku R1
677*/
678
679
680/*!
681	\var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY
682	\brief The user non-packaged sounds directory.
683
684	\since Haiku R1
685*/
686
687
688/*!
689	\var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY
690	\brief The user non-packaged documentation directory, contains e.g. man
691	       pages.
692
693	\since Haiku R1
694*/
695
696
697/*!
698	\var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY
699	\brief The user non-packaged lib directory.
700
701	\since Haiku R1
702*/
703
704
705/*!
706	\var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY
707	\brief The user non-packaged directory for development header files.
708
709	\since Haiku R1
710*/
711
712
713/*!
714	\var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY
715	\brief The user non-packaged directory containing development related
716	       files.
717
718	\since Haiku R1
719*/
720
721
722/*!
723	\var directory_which B_APPS_DIRECTORY
724	\brief The global applications directory.
725
726	Contains applications with graphical user interface.
727
728	\since BeOS R3
729*/
730
731
732/*!
733	\var directory_which B_PREFERENCES_DIRECTORY
734	\brief The global preference applications directory.
735
736	\since BeOS R3
737*/
738
739
740/*!
741	\var directory_which B_UTILITIES_DIRECTORY
742	\brief The global utility applications directory.
743
744	\since Haiku R1
745*/
746
747
748/*!
749	\var directory_which B_PACKAGE_LINKS_DIRECTORY
750	\brief The global package links directory.
751
752	This is where symlink directories for all activated packages are exposed.
753
754	\since Haiku R1
755*/
756
757
758/*!
759	\var directory_which B_BEOS_DIRECTORY
760	\brief The BeOS directory.
761
762	\deprecated Legacy BeOS definition to be phased out, use
763	            \c B_SYSTEM_DIRECTORY instead.
764
765	\since BeOS R3
766*/
767
768
769/*!
770	\var directory_which B_BEOS_SYSTEM_DIRECTORY
771	\brief The BeOS system directory.
772
773	\deprecated Legacy BeOS definition to be phased out, use
774	            \c B_SYSTEM_DIRECTORY instead.
775
776	\since BeOS R3
777*/
778
779
780/*!
781	\var directory_which B_BEOS_ADDONS_DIRECTORY
782	\brief The BeOS Add-ons directory.
783
784	\deprecated Legacy BeOS definition to be phased out, use
785	            \c B_SYSTEM_ADDONS_DIRECTORY instead.
786
787	\since BeOS R3
788*/
789
790
791/*!
792	\var directory_which B_BEOS_BOOT_DIRECTORY
793	\brief The BeOS boot directory.
794
795	\deprecated Legacy BeOS definition to be phased out, use
796	            \c B_SYSTEM_BOOT_DIRECTORY instead.
797
798	\since BeOS R3
799*/
800
801
802/*!
803	\var directory_which B_BEOS_FONTS_DIRECTORY
804	\brief The BeOS fonts directory.
805
806	\deprecated Legacy BeOS definition to be phased out, use
807	            \c B_SYSTEM_FONTS_DIRECTORY instead.
808
809	\since BeOS R3
810*/
811
812
813/*!
814	\var directory_which B_BEOS_LIB_DIRECTORY
815	\brief The BeOS lib directory.
816
817	\deprecated Legacy BeOS definition to be phased out, use
818	            \c B_SYSTEM_LIB_DIRECTORY instead.
819
820	\since BeOS R3
821*/
822
823
824/*!
825	\var directory_which B_BEOS_SERVERS_DIRECTORY
826	\brief The BeOS servers directory.
827
828	\deprecated Legacy BeOS definition to be phased out, use
829	            \c B_SYSTEM_SERVERS_DIRECTORY instead.
830
831	\since BeOS R3
832*/
833
834
835/*!
836	\var directory_which B_BEOS_APPS_DIRECTORY
837	\brief The BeOS apps directory.
838
839	\deprecated Legacy BeOS definition to be phased out, use
840	            \c B_SYSTEM_APPS_DIRECTORY instead.
841
842	\since BeOS R3
843*/
844
845
846/*!
847	\var directory_which B_BEOS_BIN_DIRECTORY
848	\brief The BeOS bin directory.
849
850	\deprecated Legacy BeOS definition to be phased out, use
851	            \c B_SYSTEM_BIN_DIRECTORY instead.
852
853	\since BeOS R3
854*/
855
856
857/*!
858	\var directory_which B_BEOS_ETC_DIRECTORY
859	\brief The BeOS etc directory used for Unix-like installation location-wide
860	       settings (Unix "etc" directory).
861
862	\deprecated Legacy BeOS definition to be phased out, use
863	            \c B_SYSTEM_ETC_DIRECTORY instead.
864
865	\since BeOS R3
866*/
867
868
869/*!
870	\var directory_which B_BEOS_DOCUMENTATION_DIRECTORY
871	\brief The BeOS documentation directory.
872
873	\deprecated Legacy BeOS definition to be phased out, use
874	            \c B_SYSTEM_DOCUMENTATION_DIRECTORY instead.
875
876	\since BeOS R3
877*/
878
879
880/*!
881	\var directory_which B_BEOS_PREFERENCES_DIRECTORY
882	\brief The BeOS preferences directory.
883
884	\deprecated Legacy BeOS definition to be phased out, use
885	            \c B_SYSTEM_PREFERENCES_DIRECTORY instead.
886
887	\since BeOS R3
888*/
889
890
891/*!
892	\var directory_which B_BEOS_TRANSLATORS_DIRECTORY
893	\brief The BeOS translators directory.
894
895	\deprecated Legacy BeOS definition to be phased out, use
896	            \c B_SYSTEM_TRANSLATORS_DIRECTORY instead.
897
898	\since BeOS R3
899*/
900
901
902/*!
903	\var directory_which B_BEOS_MEDIA_NODES_DIRECTORY
904	\brief The BeOS media nodes directory.
905
906	\deprecated Legacy BeOS definition to be phased out, use
907	            \c B_SYSTEM_MEDIA_NODES_DIRECTORY instead.
908
909	\since BeOS R3
910*/
911
912
913/*!
914	\var directory_which B_BEOS_SOUNDS_DIRECTORY
915	\brief The BeOS sounds directory.
916
917	\deprecated Legacy BeOS definition to be phased out, use
918	            \c B_SYSTEM_SOUNDS_DIRECTORY instead.
919
920	\since BeOS R3
921*/
922
923
924//// find_path[s]() flags
925
926
927/*!
928	\var B_FIND_PATH_CREATE_DIRECTORY
929	\brief Specifies that if the resulting path doesn't exist, it shall be
930	       created a directory, including all missing ancestors.
931
932	Failure to create the path will cause the respective function to fail.
933
934	Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
935	and BPathFinder API.
936
937	\since Haiku R1
938*/
939
940
941/*!
942	\var B_FIND_PATH_CREATE_PARENT_DIRECTORY
943	\brief Specifies that if the resulting path's parent doesn't exist, the
944	       parent shall be created as a directory, including all missing
945	       ancestors.
946
947	Failure to create the directory will cause the respective function to fail.
948
949	Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
950	and BPathFinder API.
951
952	\since Haiku R1
953*/
954
955
956/*!
957	\var B_FIND_PATH_EXISTING_ONLY
958	\brief Specifies that if the resulting path doesn't exist, the respective
959	       function shall skip it.
960
961	In case multiple paths shall be retrieved and none of the paths exists,
962	the function shall fail with \c B_ENTRY_NOT_FOUND.
963
964	Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(),
965	and BPathFinder API.
966
967	\since Haiku R1
968*/
969
970
971/*!
972	\enum path_base_directory
973	\brief Path constants to use with find_path(), find_paths(), et al.
974
975	There are two kinds of constants. Those that are based off an installation
976	location and those that based off an image or given path. The latter are not
977	valid argument for all functions.
978
979	\since Haiku R1
980*/
981
982
983/*!
984	\var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY
985	\brief The installation location base directory.
986
987	\since Haiku R1
988*/
989
990
991/*!
992	\var B_FIND_PATH_ADD_ONS_DIRECTORY
993	\brief The add-ons directory.
994
995	\since Haiku R1
996*/
997
998
999/*!
1000	\var B_FIND_PATH_APPS_DIRECTORY
1001	\brief The application directory.
1002
1003	\since Haiku R1
1004*/
1005
1006
1007/*!
1008	\var B_FIND_PATH_BIN_DIRECTORY
1009	\brief The command line application directory (Unix "bin" directory).
1010
1011	\since Haiku R1
1012*/
1013
1014
1015/*!
1016	\var B_FIND_PATH_BOOT_DIRECTORY
1017	\brief The directory containing booting related files.
1018
1019	\since Haiku R1
1020*/
1021
1022
1023/*!
1024	\var B_FIND_PATH_CACHE_DIRECTORY
1025	\brief The directory used for cache files.
1026
1027	\since Haiku R1
1028*/
1029
1030
1031/*!
1032	\var B_FIND_PATH_DATA_DIRECTORY
1033	\brief The base directory used for read-only data.
1034
1035	\since Haiku R1
1036*/
1037
1038
1039/*!
1040	\var B_FIND_PATH_DEVELOP_DIRECTORY
1041	\brief The directory containing development related files.
1042
1043	\since Haiku R1
1044*/
1045
1046
1047/*!
1048	\var B_FIND_PATH_DEVELOP_LIB_DIRECTORY
1049	\brief The the development library directory.
1050
1051	This is the directory where the linker finds libraries.
1052
1053	\since Haiku R1
1054*/
1055
1056
1057/*!
1058	\var B_FIND_PATH_DOCUMENTATION_DIRECTORY
1059	\brief The base directory used for documentation.
1060
1061	\since Haiku R1
1062*/
1063
1064
1065/*!
1066	\var B_FIND_PATH_ETC_DIRECTORY
1067	\brief The directory used for Unix-like installation location wide
1068	       settings (Unix "etc" directory).
1069
1070	\since Haiku R1
1071*/
1072
1073
1074/*!
1075	\var B_FIND_PATH_FONTS_DIRECTORY
1076	\brief The fonts directory.
1077
1078	\since Haiku R1
1079*/
1080
1081
1082/*!
1083	\var B_FIND_PATH_HEADERS_DIRECTORY
1084	\brief The development header files directory.
1085
1086	\since Haiku R1
1087*/
1088
1089
1090/*!
1091	\var B_FIND_PATH_LIB_DIRECTORY
1092	\brief The runtime library directory.
1093
1094	This is where the runtime loader finds libraries.
1095
1096	\since Haiku R1
1097*/
1098
1099
1100/*!
1101	\var B_FIND_PATH_LOG_DIRECTORY
1102	\brief The directory where log files are put.
1103
1104	\since Haiku R1
1105*/
1106
1107
1108/*!
1109	\var B_FIND_PATH_MEDIA_NODES_DIRECTORY
1110	\brief The media node add-ons directory.
1111
1112	\since Haiku R1
1113*/
1114
1115
1116/*!
1117	\var B_FIND_PATH_PACKAGES_DIRECTORY
1118	\brief The directory where activated packages live.
1119
1120	\since Haiku R1
1121*/
1122
1123
1124/*!
1125	\var B_FIND_PATH_PREFERENCES_DIRECTORY
1126	\brief The preference application directory.
1127
1128	\since Haiku R1
1129*/
1130
1131
1132/*!
1133	\var B_FIND_PATH_SERVERS_DIRECTORY
1134	\brief The server and daemon program directory.
1135
1136	\since Haiku R1
1137*/
1138
1139
1140/*!
1141	\var B_FIND_PATH_SETTINGS_DIRECTORY
1142	\brief The directory used for installation location wide settings.
1143
1144	Note that for the user's home config installation location, this is not
1145	the same as the user's settings directory. Software installed in that
1146	installation location puts their global settings files here.
1147
1148	\since Haiku R1
1149*/
1150
1151
1152/*!
1153	\var B_FIND_PATH_SOUNDS_DIRECTORY
1154	\brief The directory for sound files.
1155
1156	\since Haiku R1
1157*/
1158
1159
1160/*!
1161	\var B_FIND_PATH_SPOOL_DIRECTORY
1162	\brief The directory for spool data, e.g. pending printer jobs.
1163
1164	\since Haiku R1
1165*/
1166
1167
1168/*!
1169	\var B_FIND_PATH_TRANSLATORS_DIRECTORY
1170	\brief The translator add-ons directory.
1171
1172	\since Haiku R1
1173*/
1174
1175
1176/*!
1177	\var B_FIND_PATH_VAR_DIRECTORY
1178	\brief The directory for variable data (Unix "var" directory).
1179
1180	\since Haiku R1
1181*/
1182
1183
1184/*!
1185	\var B_FIND_PATH_IMAGE_PATH
1186	\brief The path of the image file that was identified by a pointer
1187	       argument passed to the respective function.
1188
1189	\since Haiku R1
1190*/
1191
1192
1193/*!
1194	\var B_FIND_PATH_PACKAGE_PATH
1195	\brief The path of the package the file referred to by the specified path
1196	       belongs to.
1197
1198	\since Haiku R1
1199*/
1200
1201
1202/*!
1203	\fn status_t find_directory(directory_which which, dev_t volume,
1204		bool createIt, char* pathString, int32 length)
1205	\ingroup libroot
1206	\brief C interface to find_directory
1207
1208	Fills up to \a length characters of \a pathString with the path to \a which
1209	on \a volume. Creates the directory if it doesn't exists if \a createIt is
1210	set.
1211
1212	\since BeOS R3
1213*/
1214
1215
1216/*!
1217	\fn status_t find_directory(directory_which which, BPath* path, bool createIt,
1218		BVolume* volume)
1219	\ingroup libbe
1220	\brief C++ interface to find_directory
1221
1222	Set \a path to \a which on \a volume.
1223
1224	\since BeOS R3
1225*/
1226
1227
1228/*!
1229	\fn status_t find_path(const void* codePointer,
1230		path_base_directory baseDirectory, const char* subPath,
1231		char* pathBuffer, size_t bufferSize)
1232	\ingroup libroot
1233	\brief Retrieves a path in the file system layout based on a loaded image
1234	       file.
1235
1236	The function determines the path of the image (i.e. executable, library, or
1237	add-on) file associated with \a codePointer, a pointer to a location in the
1238	code or static data of an image loaded in the caller's team. Based on that,
1239	path \a baseDirectory is evaluated. In most cases that means first
1240	determining the path of the installation location from the path, then
1241	appending the relative path corresponding to the given \a baseDirectory
1242	constant, and finally appending \a subPath, if given.
1243
1244	If \a baseDirectory specifies a path that is architecture dependent, the
1245	caller's architecture (as returned by get_architecture()) is used for
1246	constructing the path.
1247
1248	If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are
1249	specified, \a subPath is ignored. In the former case the path of the image
1250	file is returned. In the latter case the path of the package containing the
1251	image file, if any.
1252
1253	\param codePointer A pointer to code or static data belonging to the image
1254	       based on which the path shall be computed. The special value
1255	       \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and
1256	       \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
1257	\param baseDirectory Constant indicating which path to retrieve.
1258	\param subPath Relative subpath that shall be appended. Can be \c NULL.
1259	\param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1260	       shall be stored in.
1261	\param bufferSize Size of the \a pathBuffer buffer.
1262	\return A status code.
1263	\retval B_OK Everything went fine.
1264	\retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1265	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1266	        path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1267	        and the image file doesn't belong to a package.
1268
1269	\since Haiku R1
1270*/
1271
1272
1273/*!
1274	\fn status_t find_path_etc(const void* codePointer, const char* dependency,
1275		const char* architecture, path_base_directory baseDirectory,
1276		const char* subPath, uint32 flags, char* pathBuffer, size_t bufferSize)
1277	\ingroup libroot
1278	\brief Retrieves a path in the file system layout based on a loaded image
1279	       file.
1280
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.
1288
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.
1292
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.
1297
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.
1302
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.
1334
1335	\since Haiku R1
1336*/
1337
1338
1339/*!
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	\ingroup libroot
1344	\brief Retrieves a path in the file system layout based on a given path.
1345
1346	Based on the given path \a path the function evaluates \a baseDirectory. In
1347	most cases that means first determining the path of the installation
1348	location from the given path, then appending the relative path corresponding
1349	to the given \a baseDirectory constant, and finally appending \a subPath, if
1350	given.
1351
1352	If \a baseDirectory specifies a path that is architecture dependent, the
1353	architecture associated with the given path (as returned by
1354	guess_architecture_for_path()) is used for constructing the path.
1355
1356	If \c B_FIND_PATH_PACKAGE_PATH is specified, \a subPath is ignored. In
1357	this case the path of the package containing the file referred to by \a path
1358	is returned. \c B_FIND_PATH_IMAGE_PATH is not a valid argument for this
1359	function.
1360
1361	\param path A path based on which the path shall be computed.
1362	\param baseDirectory Constant indicating which path to retrieve.
1363	\param subPath Relative subpath that shall be appended. Can be \c NULL.
1364	\param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1365	       shall be stored in.
1366	\param bufferSize Size of the \a pathBuffer buffer.
1367	\return A status code.
1368	\retval B_OK Everything went fine.
1369	\retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1370	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1371	        path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1372	        and \a path does refer to a file that belongs to a package.
1373
1374	\since Haiku R1
1375*/
1376
1377
1378/*!
1379	\fn status_t find_path_for_path_etc(const char* path,
1380		const char* dependency, const char* architecture,
1381		path_base_directory baseDirectory, const char* subPath, uint32 flags,
1382		char* pathBuffer, size_t bufferSize)
1383	\ingroup libroot
1384	\brief Retrieves a path in the file system layout based on a given path.
1385
1386	Based on the given path \a path the function evaluates \a baseDirectory. In
1387	most cases that means first determining the path of the installation
1388	location from the given path, then appending the relative path corresponding
1389	to the given \a baseDirectory constant, and finally appending \a subPath, if
1390	given.
1391
1392	If \a dependency is specified, instead of determining the installation
1393	location path from the given path, the installation location path of the
1394	dependency \a dependency of the package containing the file referred to by
1395	\a path is used.
1396
1397	If \a baseDirectory specifies a path that is architecture dependent,
1398	\a architecture is used for constructing the path. If \a architecture is
1399	\c NULL, the architecture associated with the given path (as returned by
1400	guess_architecture_for_path()) is used.
1401
1402	If \c B_FIND_PATH_PACKAGE_PATH is specified, \a dependency and
1403	\a subPath are ignored. In this case the path of the package containing the
1404	file referred to by \a path is returned. \c B_FIND_PATH_IMAGE_PATH is not
1405	a valid argument for this function.
1406
1407	\param path A path based on which the path shall be computed.
1408	\param dependency The name of the package's "requires" entry to be used for
1409	       resolving the installation location. Can be \c NULL.
1410	\param architecture The name of the architecture to be used for resolving
1411	       architecture dependent paths. Can be \c NULL, in which case the
1412	       architecture associated with \a path is used.
1413	\param baseDirectory Constant indicating which path to retrieve.
1414	\param subPath Relative subpath that shall be appended. Can be \c NULL.
1415	\param flags Bitwise OR of any of the following flags:
1416	       - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
1417	         exist, create it as a directory (including all missing ancestors).
1418	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
1419	         parent doesn't exist, create the parent directory (including all
1420	         missing ancestors).
1421	       - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
1422	         fail with \c B_ENTRY_NOT_FOUND.
1423	\param pathBuffer Pointer to a pre-allocated buffer the retrieved path
1424	       shall be stored in.
1425	\param bufferSize Size of the \a pathBuffer buffer.
1426	\return A status code.
1427	\retval B_OK Everything went fine.
1428	\retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough.
1429	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1430	        path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
1431	        and \a path does refer to a file that belongs to a package, or
1432	        \c dependency was specified, but isn't a "requires" entry of the
1433	        package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the
1434	        resulting path doesn't exist.
1435
1436	\since Haiku R1
1437*/
1438
1439
1440/*!
1441	\fn status_t find_paths(path_base_directory baseDirectory,
1442		const char* subPath, char*** _paths, size_t* _pathCount)
1443	\ingroup libroot
1444	\brief Retrieves a list of paths in the file system layout.
1445
1446	For each installation location -- in the order most specific to most
1447	generic, non-packaged before packaged -- the function evaluates
1448	\a baseDirectory to a path and appends \a subPath, if given.
1449
1450	If \a baseDirectory specifies a path that is architecture dependent,
1451	the caller's architecture (as returned by get_architecture()) is used for
1452	constructing each path.
1453
1454	\c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not
1455	valid arguments for this function.
1456
1457	The array of paths retrieved is allocated on the heap and returned via
1458	\a _paths. The caller is responsible for calling free() for the returned
1459	pointer.
1460
1461	\param baseDirectory Constant indicating which paths to retrieve.
1462	\param subPath Relative subpath that shall be appended. Can be \c NULL.
1463	\param _paths Pointer to a pre-allocated variable where the pointer to the
1464	       allocated path array shall be stored on success.
1465	\param _pathCount Pointer to a pre-allocated variable where the number of
1466	       paths in the path array shall be stored on success.
1467
1468	\return A status code.
1469	\retval B_OK Everything went fine.
1470	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1471	        paths doesn't exist.
1472
1473	\since Haiku R1
1474*/
1475
1476
1477/*!
1478	\fn status_t find_paths_etc(const char* architecture,
1479		path_base_directory baseDirectory, const char* subPath, uint32 flags,
1480		char*** _paths, size_t* _pathCount)
1481	\ingroup libroot
1482	\brief Retrieves a list of paths in the file system layout.
1483
1484	For each installation location -- in the order most specific to most
1485	generic, non-packaged before packaged -- the function evaluates
1486	\a baseDirectory to a path and appends \a subPath, if given.
1487
1488	If \a baseDirectory specifies a path that is architecture dependent,
1489	\a architecture is used for constructing each path. If \a architecture is
1490	\c NULL, the caller's architecture (as returned by get_architecture()) is
1491	used.
1492
1493	\c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not
1494	valid arguments for this function.
1495
1496	The array of paths retrieved is allocated on the heap and returned via
1497	\a _paths. The caller is responsible for calling free() for the returned
1498	pointer.
1499
1500	\param architecture The name of the architecture to be used for resolving
1501	       architecture dependent paths. Can be \c NULL, in which case the
1502	       caller's architecture is used.
1503	\param baseDirectory Constant indicating which paths to retrieve.
1504	\param subPath Relative subpath that shall be appended. Can be \c NULL.
1505	\param flags Bitwise OR of any of the following flags:
1506	       - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
1507	         exist, create it as a directory (including all missing ancestors).
1508	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
1509	         parent doesn't exist, create the parent directory (including all
1510	         missing ancestors).
1511	       - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
1512	         fail with \c B_ENTRY_NOT_FOUND.
1513	\param _paths Pointer to a pre-allocated variable where the pointer to the
1514	       allocated path array shall be stored on success.
1515	\param _pathCount Pointer to a pre-allocated variable where the number of
1516	       paths in the path array shall be stored on success.
1517	\return A status code.
1518	\retval B_OK Everything went fine.
1519	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
1520	        paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was
1521	        specified and none of the resulting paths do exist.
1522
1523	\since Haiku R1
1524*/
1525