1/* 2 * Copyright 2011-2013, 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 hrev46390 12 * src/kits/storage/FindDirectory.cpp hrev46390 13 */ 14 15 16/*! 17 \file FindDirectory.h 18 \ingroup storage 19 \ingroup libbe 20 \brief Provides the find_directory(), find_path(), find_paths(), etc. 21 functions. 22 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. 31 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. 48 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. 53 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. 59*/ 60 61 62/*! 63 \enum directory_which 64 \brief Directory constants to use with find_directory. 65 66 There are four kind of directories. Volume-local directories exist on each 67 volume. They may be at a different place in each of them, for example the 68 trash location depends on the filesystem. System and common directories are 69 system-wide. They live on only one volume. The difference is system is 70 only meant for internal system management and shouldn't be used by 71 applications. The common directories have a similar hierarchy, and they are 72 ignored when the user disable user add-ons in the boot menu. User 73 directories have a different value depending on the UID of the application 74 calling the function. They are usually located in the user home directory. 75 76 Use common directories for system-wide files such as drivers. Use user 77 directories for application settings, since each user may want different 78 settings. 79*/ 80 81 82/*! 83 \var directory_which B_DESKTOP_DIRECTORY 84 The desktop for a given volume. 85 86 \var directory_which B_TRASH_DIRECTORY 87 The trash for a given volume. 88 89 \var directory_which B_SYSTEM_DIRECTORY 90 The system directory. 91 92 \var directory_which B_SYSTEM_ADDONS_DIRECTORY 93 The system add-ons directory 94 95 \var directory_which B_SYSTEM_BOOT_DIRECTORY 96 The system boot directory. Contains the minimal set of files required for 97 booting Haiku. 98 99 \var directory_which B_SYSTEM_FONTS_DIRECTORY 100 The system fonts directory 101 102 \var directory_which B_SYSTEM_LIB_DIRECTORY 103 The system lib directory. 104 105 \var directory_which B_SYSTEM_SERVERS_DIRECTORY 106 The system servers directory. 107 108 \var directory_which B_SYSTEM_APPS_DIRECTORY 109 The system applications directory. Contains applications with graphical 110 user interface. 111 112 \var directory_which B_SYSTEM_BIN_DIRECTORY 113 The system bin directory. Contains command-line applications runnable from 114 Terminal. 115 116 \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY 117 The system documentation directory. Contains e.g. man pages. 118 119 \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY 120 The system preferences directory. 121 122 \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY 123 The system translator directory. 124 125 \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY 126 The system media nodes directory. 127 128 \var directory_which B_SYSTEM_SOUNDS_DIRECTORY 129 The system sounds directory. 130 131 \var directory_which B_SYSTEM_DATA_DIRECTORY 132 The system data directory. 133 134 \var directory_which B_SYSTEM_DEVELOP_DIRECTORY 135 The system directory containing development related files. 136 137 \var directory_which B_SYSTEM_PACKAGES_DIRECTORY 138 The system directory where activated packages live. 139 140 \var directory_which B_SYSTEM_HEADERS_DIRECTORY 141 The system directory for development header files. 142 143 \var directory_which B_SYSTEM_ETC_DIRECTORY 144 The system directory used for Unix-like installation location wide settings 145 (Unix "etc" directory). 146 147 \var directory_which B_SYSTEM_SETTINGS_DIRECTORY 148 The system directory used for installation location wide settings. 149 150 \var directory_which B_SYSTEM_LOG_DIRECTORY 151 The system directory where log files are put. 152 153 \var directory_which B_SYSTEM_SPOOL_DIRECTORY 154 The system directory for spool data (e.g. pending printer jobs). 155 156 \var directory_which B_SYSTEM_TEMP_DIRECTORY 157 The global directory for temporary files. 158 159 \var directory_which B_SYSTEM_VAR_DIRECTORY 160 The system directory for variable data (Unix "var" directory). 161 162 \var directory_which B_SYSTEM_CACHE_DIRECTORY 163 The system directory used for cache files. 164 165 \var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY 166 The system non-packaged installation location directory. 167 168 \var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY 169 The system non-packaged add-ons directory 170 171 \var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY 172 The system non-packaged translator directory. 173 174 \var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY 175 The system non-packaged media nodes directory. 176 177 \var directory_which B_SYSTEM_NONPACKAGED_BIN_DIRECTORY 178 The system non-packaged bin directory. Contains command-line applications 179 runnable from Terminal. 180 181 \var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY 182 The system non-packaged data directory. 183 184 \var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY 185 The system non-packaged fonts directory 186 187 \var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY 188 The system non-packaged sounds directory. 189 190 \var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY 191 The system non-packaged documentation directory. Contains e.g. man pages. 192 193 \var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY 194 The system non-packaged lib directory. 195 196 \var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY 197 The system non-packaged directory for development header files. 198 199 \var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY 200 The system non-packaged directory containing development related files. 201*/ 202 203 204/*! 205 \var directory_which B_USER_DIRECTORY 206 The user home directory. Do NOT store application settings here as on unix, 207 instead use B_USER_SETTINGS_DIRECTORY. 208 209 \var directory_which B_USER_CONFIG_DIRECTORY 210 The user's packaged installation location directory. 211 212 \var directory_which B_USER_ADDONS_DIRECTORY 213 The user add-ons directory 214 215 \var directory_which B_USER_BOOT_DIRECTORY 216 The user directory containing booting related files. 217 218 \var directory_which B_USER_FONTS_DIRECTORY 219 The user fonts directory 220 221 \var directory_which B_USER_LIB_DIRECTORY 222 The user lib directory. 223 224 \var directory_which B_USER_SETTINGS_DIRECTORY 225 The user settings directory. You may store your application settings here. 226 Create a subdirectory for your application if you have multiple files to 227 store, else, put a single file. The file or directory should have the same 228 name as your application, so the user knows what it's used for. 229 230 \var directory_which B_USER_DESKBAR_DIRECTORY 231 The user deskbar directory. You may add a link to your application here, so 232 it shows up in the user deskbar's leaf menu. 233 234 \var directory_which B_USER_PRINTERS_DIRECTORY 235 The user directory for printer settings. 236 237 \var directory_which B_USER_TRANSLATORS_DIRECTORY 238 The user translator directory. 239 240 \var directory_which B_USER_MEDIA_NODES_DIRECTORY 241 The user media nodes directory. 242 243 \var directory_which B_USER_SOUNDS_DIRECTORY 244 The user sounds directory. 245 246 \var directory_which B_USER_DATA_DIRECTORY 247 The user data directory. 248 249 \var directory_which B_USER_CACHE_DIRECTORY 250 The system directory used for cache files. 251 252 \var directory_which B_USER_PACKAGES_DIRECTORY 253 The user directory where activated packages live. 254 255 \var directory_which B_USER_HEADERS_DIRECTORY 256 The user directory for development header files. 257 258 \var directory_which B_USER_DEVELOP_DIRECTORY 259 The user directory containing development related files. 260 261 \var directory_which B_USER_DOCUMENTATION_DIRECTORY 262 The user documentation directory. Contains e.g. man pages. 263 264 \var directory_which B_USER_SERVERS_DIRECTORY 265 The user servers directory. 266 267 \var directory_which B_USER_APPS_DIRECTORY 268 The user applications directory. Contains applications with graphical 269 user interface. 270 271 \var directory_which B_USER_BIN_DIRECTORY 272 The user bin directory. Contains command-line applications runnable from 273 Terminal. 274 275 \var directory_which B_USER_PREFERENCES_DIRECTORY 276 The user preference applications directory. 277 278 \var directory_which B_USER_ETC_DIRECTORY 279 The user directory used for Unix-like installation location wide settings 280 (Unix "etc" directory). 281 282 \var directory_which B_USER_LOG_DIRECTORY 283 The user directory where log files are put. 284 285 \var directory_which B_USER_SPOOL_DIRECTORY 286 The user directory for spool data (e.g. pending printer jobs). 287 288 \var directory_which B_USER_VAR_DIRECTORY 289 The user directory for variable data (Unix "var" directory). 290 291 \var directory_which B_USER_NONPACKAGED_DIRECTORY 292 The user non-packaged installation location directory. 293 294 \var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY 295 The user non-packaged add-ons directory 296 297 \var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY 298 The user non-packaged translator directory. 299 300 \var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY 301 The user non-packaged media nodes directory. 302 303 \var directory_which B_USER_NONPACKAGED_BIN_DIRECTORY 304 The user non-packaged bin directory. Contains command-line applications 305 runnable from Terminal. 306 307 \var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY 308 The user non-packaged data directory. 309 310 \var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY 311 The user non-packaged fonts directory 312 313 \var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY 314 The user non-packaged sounds directory. 315 316 \var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY 317 The user non-packaged documentation directory. Contains e.g. man pages. 318 319 \var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY 320 The user non-packaged lib directory. 321 322 \var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY 323 The user non-packaged directory for development header files. 324 325 \var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY 326 The user non-packaged directory containing development related files. 327*/ 328 329 330/*! 331 \var directory_which B_APPS_DIRECTORY 332 The global applications directory. Contains applications with graphical 333 user interface. 334 335 \var directory_which B_PREFERENCES_DIRECTORY 336 The global preference applications directory. 337 338 \var directory_which B_UTILITIES_DIRECTORY 339 The global utility applications directory. 340 341 \var directory_which B_PACKAGE_LINKS_DIRECTORY 342 The global package links directory. This is where symlink directories for 343 all activated packages are exposed. 344*/ 345 346 347/* find_path[s]() flags */ 348 349 350/*! 351 \var B_FIND_PATH_CREATE_DIRECTORY 352 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), 353 and BPathFinder API. Specifies that, if the resulting path doesn't exist, 354 it shall be created as a directory, including all missing ancestors. Failure 355 to create the path will cause the respective function to fail. 356 357 \var B_FIND_PATH_CREATE_PARENT_DIRECTORY 358 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), 359 and BPathFinder API. Specifies that, if the resulting path's parent doesn't 360 exist, the parent shall be created as a directory, including all missing 361 ancestors. Failure to create the directory will cause the respective 362 function to fail. 363 364 \var B_FIND_PATH_EXISTING_ONLY 365 Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), 366 and BPathFinder API. Specifies that, if the resulting path doesn't exist, 367 the respective function shall skip it. In case multiple paths shall be 368 retrieved and none of the paths exists, the function shall fail with 369 \c B_ENTRY_NOT_FOUND. 370*/ 371 372 373/*! 374 \enum path_base_directory 375 \brief Path constants to use with find_path(), find_paths(), et al. 376 377 There are two kinds of constants. Those that are based off an installation 378 location and those that based off an image or given path. The latter are not 379 valid argument for all functions. 380 381 \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY 382 The installation location base directory. 383 384 \var B_FIND_PATH_ADD_ONS_DIRECTORY 385 The add-ons directory. 386 387 \var B_FIND_PATH_APPS_DIRECTORY 388 The application directory. 389 390 \var B_FIND_PATH_BIN_DIRECTORY 391 The command line application directory (Unix "bin" directory). 392 393 \var B_FIND_PATH_BOOT_DIRECTORY 394 The directory containing booting related files. 395 396 \var B_FIND_PATH_CACHE_DIRECTORY 397 The directory used for cache files. 398 399 \var B_FIND_PATH_DATA_DIRECTORY 400 The base directory used for read-only data. 401 402 \var B_FIND_PATH_DEVELOP_DIRECTORY 403 The directory containing development related files. 404 405 \var B_FIND_PATH_DEVELOP_LIB_DIRECTORY 406 The the development library directory. This is the directory where the 407 linker finds libraries. 408 409 \var B_FIND_PATH_DOCUMENTATION_DIRECTORY 410 The base directory used for documentation. 411 412 \var B_FIND_PATH_ETC_DIRECTORY 413 The directory used for Unix-like installation location wide settings (Unix 414 "etc" directory). 415 416 \var B_FIND_PATH_FONTS_DIRECTORY 417 The fonts directory. 418 419 \var B_FIND_PATH_HEADERS_DIRECTORY 420 The development header files directory. 421 422 \var B_FIND_PATH_LIB_DIRECTORY 423 The runtime library directory. This is where the runtime loader finds 424 libraries. 425 426 \var B_FIND_PATH_LOG_DIRECTORY 427 The directory where log files are put. 428 429 \var B_FIND_PATH_MEDIA_NODES_DIRECTORY 430 The media node add-ons directory. 431 432 \var B_FIND_PATH_PACKAGES_DIRECTORY 433 The directory where activated packages live. 434 435 \var B_FIND_PATH_PREFERENCES_DIRECTORY 436 The preference application directory. 437 438 \var B_FIND_PATH_SERVERS_DIRECTORY 439 The server and daemon program directory. 440 441 \var B_FIND_PATH_SETTINGS_DIRECTORY 442 The directory used for installation location wide settings. Note that for 443 the user's home config installation location, this is not the same as the 444 user's settings directory. Software installed in that installation location 445 puts their global settings files here. 446 447 \var B_FIND_PATH_SOUNDS_DIRECTORY 448 The directory for sound files. 449 450 \var B_FIND_PATH_SPOOL_DIRECTORY 451 The directory for spool data (e.g. pending printer jobs). 452 453 \var B_FIND_PATH_TRANSLATORS_DIRECTORY 454 The translator add-ons directory. 455 456 \var B_FIND_PATH_VAR_DIRECTORY 457 The directory for variable data (Unix "var" directory). 458 459 \var B_FIND_PATH_IMAGE_PATH 460 The path of the image file that was identified by a pointer argument passed 461 to the respective function. 462 463 \var B_FIND_PATH_PACKAGE_PATH 464 The path of the package the file referred to by the specified path belongs 465 to. 466*/ 467 468 469/*! 470 \fn status_t find_directory(directory_which which, dev_t volume, 471 bool createIt, char* pathString, int32 length) 472 \brief C interface to find_directory 473 474 Fills up to \a length characters of \a pathString with the path to \a which 475 on \a volume. Creates the directory if it doesn't exists if \a createIt is 476 set. 477*/ 478 479 480/*! 481 \fn status_t find_directory(directory_which which, BPath* path, bool createIt, 482 BVolume* volume) 483 \brief C++ interface to find_directory 484 485 Set \a path to \a which on \a volume. 486*/ 487 488 489/*! 490 \fn status_t find_path(const void* codePointer, 491 path_base_directory baseDirectory, const char* subPath, 492 char* pathBuffer, size_t bufferSize) 493 \brief Retrieves a path in the file system layout based on a loaded image 494 file. 495 496 The function determines the path of the image (i.e. executable, library, or 497 add-on) file associated with \a codePointer, a pointer to a location in the 498 code or static data of an image loaded in the caller's team. Based on that, 499 path \a baseDirectory is evaluated. In most cases that means first 500 determining the path of the installation location from the path, then 501 appending the relative path corresponding to the given \a baseDirectory 502 constant, and finally appending \a subPath, if given. 503 504 If \a baseDirectory specifies a path that is architecture dependent, the 505 caller's architecture (as returned by get_architecture()) is used for 506 constructing the path. 507 508 If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are 509 specified, \a subPath is ignored. In the former case the path of the image 510 file is returned. In the latter case the path of the package containing the 511 image file, if any. 512 513 \param codePointer A pointer to code or static data belonging to the image 514 based on which the path shall be computed. The special value 515 \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and 516 \c B_CURRENT_IMAGE_SYMBOL for the caller's image. 517 \param baseDirectory Constant indicating which path to retrieve. 518 \param subPath Relative subpath that shall be appended. Can be \c NULL. 519 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path 520 shall be stored in. 521 \param bufferSize Size of the \a pathBuffer buffer. 522 \return A status code. 523 \retval B_OK Everything went fine. 524 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. 525 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 526 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 527 and the image file doesn't belong to a package. 528*/ 529 530 531/*! 532 \fn status_t find_path_etc(const void* codePointer, const char* dependency, 533 const char* architecture, path_base_directory baseDirectory, 534 const char* subPath, uint32 flags, char* pathBuffer, size_t bufferSize) 535 \brief Retrieves a path in the file system layout based on a loaded image 536 file. 537 538 The function determines the path of the image (i.e. executable, library, or 539 add-on) file associated with \a codePointer, a pointer to a location in the 540 code or static data of an image loaded in the caller's team. Based on that, 541 path \a baseDirectory is evaluated. In most cases that means first 542 determining the path of the installation location from the path, then 543 appending the relative path corresponding to the given \a baseDirectory 544 constant, and finally appending \a subPath, if given. 545 546 If \a dependency is specified, instead of determining the installation 547 location path from the image path, the installation location path of the 548 dependency \a dependency of the package containing the image file is used. 549 550 If \a baseDirectory specifies a path that is architecture dependent, 551 \a architecture is used for constructing the path. If \a architecture is 552 \c NULL, the caller's architecture (as returned by get_architecture()) is 553 used. 554 555 If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are 556 specified, \a dependency and \a subPath are ignored. In the former case the 557 path of the image file is returned. In the latter case the path of the 558 package containing the image file, if any. 559 560 \param codePointer A pointer to code or static data belonging to the image 561 based on which the path shall be computed. The special value 562 \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and 563 \c B_CURRENT_IMAGE_SYMBOL for the caller's image. 564 \param dependency The name of the package's "requires" entry to be used for 565 resolving the installation location. Can be \c NULL. 566 \param architecture The name of the architecture to be used for resolving 567 architecture dependent paths. Can be \c NULL, in which case the caller's 568 architecture is used. 569 \param baseDirectory Constant indicating which path to retrieve. 570 \param subPath Relative subpath that shall be appended. Can be \c NULL. 571 \param flags Bitwise OR of any of the following flags: 572 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, 573 create it as a directory (including all missing ancestors). 574 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent 575 doesn't exist, create the parent directory (including all missing 576 ancestors). 577 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, 578 fail with \c B_ENTRY_NOT_FOUND. 579 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path 580 shall be stored in. 581 \param bufferSize Size of the \a pathBuffer buffer. 582 \return A status code. 583 \retval B_OK Everything went fine. 584 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. 585 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 586 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 587 and the image file doesn't belong to a package, or \c dependency was 588 specified, but isn't a "requires" entry of the package, or 589 \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path 590 doesn't exist. 591*/ 592 593 594/*! 595 \fn status_t find_path_for_path(const char* path, 596 path_base_directory baseDirectory, const char* subPath, 597 char* pathBuffer, size_t bufferSize) 598 \brief Retrieves a path in the file system layout based on a given path. 599 600 Based on the given path \a path the function evaluates \a baseDirectory. In 601 most cases that means first determining the path of the installation 602 location from the given path, then appending the relative path corresponding 603 to the given \a baseDirectory constant, and finally appending \a subPath, if 604 given. 605 606 If \a baseDirectory specifies a path that is architecture dependent, the 607 architecture associated with the given path (as returned by 608 guess_architecture_for_path()) is used for constructing the path. 609 610 If \c B_FIND_PATH_PACKAGE_PATH is specified, \a subPath is ignored. In 611 this case the path of the package containing the file referred to by \a path 612 is returned. \c B_FIND_PATH_IMAGE_PATH is not a valid argument for this 613 function. 614 615 \param path A path based on which the path shall be computed. 616 \param baseDirectory Constant indicating which path to retrieve. 617 \param subPath Relative subpath that shall be appended. Can be \c NULL. 618 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path 619 shall be stored in. 620 \param bufferSize Size of the \a pathBuffer buffer. 621 \return A status code. 622 \retval B_OK Everything went fine. 623 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. 624 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 625 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 626 and \a path does refer to a file that belongs to a package. 627*/ 628 629 630/*! 631 \fn status_t find_path_for_path_etc(const char* path, 632 const char* dependency, const char* architecture, 633 path_base_directory baseDirectory, const char* subPath, uint32 flags, 634 char* pathBuffer, size_t bufferSize) 635 \brief Retrieves a path in the file system layout based on a given path. 636 637 Based on the given path \a path the function evaluates \a baseDirectory. In 638 most cases that means first determining the path of the installation 639 location from the given path, then appending the relative path corresponding 640 to the given \a baseDirectory constant, and finally appending \a subPath, if 641 given. 642 643 If \a dependency is specified, instead of determining the installation 644 location path from the given path, the installation location path of the 645 dependency \a dependency of the package containing the file referred to by 646 \a path is used. 647 648 If \a baseDirectory specifies a path that is architecture dependent, 649 \a architecture is used for constructing the path. If \a architecture is 650 \c NULL, the architecture associated with the given path (as returned by 651 guess_architecture_for_path()) is used. 652 653 If \c B_FIND_PATH_PACKAGE_PATH is specified, \a dependency and 654 \a subPath are ignored. In this case the path of the package containing the 655 file referred to by \a path is returned. \c B_FIND_PATH_IMAGE_PATH is not 656 a valid argument for this function. 657 658 \param path A path based on which the path shall be computed. 659 \param dependency The name of the package's "requires" entry to be used for 660 resolving the installation location. Can be \c NULL. 661 \param architecture The name of the architecture to be used for resolving 662 architecture dependent paths. Can be \c NULL, in which case the 663 architecture associated with \a path is used. 664 \param baseDirectory Constant indicating which path to retrieve. 665 \param subPath Relative subpath that shall be appended. Can be \c NULL. 666 \param flags Bitwise OR of any of the following flags: 667 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, 668 create it as a directory (including all missing ancestors). 669 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent 670 doesn't exist, create the parent directory (including all missing 671 ancestors). 672 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, 673 fail with \c B_ENTRY_NOT_FOUND. 674 \param pathBuffer Pointer to a pre-allocated buffer the retrieved path 675 shall be stored in. 676 \param bufferSize Size of the \a pathBuffer buffer. 677 \return A status code. 678 \retval B_OK Everything went fine. 679 \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. 680 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 681 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 682 and \a path does refer to a file that belongs to a package, or 683 \c dependency was specified, but isn't a "requires" entry of the 684 package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting 685 path doesn't exist. 686*/ 687 688 689/*! 690 \fn status_t find_paths(path_base_directory baseDirectory, 691 const char* subPath, char*** _paths, size_t* _pathCount) 692 \brief Retrieves a list of paths in the file system layout. 693 694 For each installation location -- in the order most specific to most 695 generic, non-packaged before packaged -- the function evaluates 696 \a baseDirectory to a path and appends \a subPath, if given. 697 698 If \a baseDirectory specifies a path that is architecture dependent, 699 the caller's architecture (as returned by get_architecture()) is used for 700 constructing each path. 701 702 \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not 703 valid arguments for this function. 704 705 The array of paths retrieved is allocated on the heap and returned via 706 \a _paths. The caller is responsible for calling free() for the returned 707 pointer. 708 709 \param baseDirectory Constant indicating which paths to retrieve. 710 \param subPath Relative subpath that shall be appended. Can be \c NULL. 711 \param _paths Pointer to a pre-allocated variable where the pointer to the 712 allocated path array shall be stored on success. 713 \param _pathCount Pointer to a pre-allocated variable where the number of 714 paths in the path array shall be stored on success. 715 \return A status code. 716 \retval B_OK Everything went fine. 717 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 718 paths doesn't exist. 719*/ 720 721 722/*! 723 \fn status_t find_paths_etc(const char* architecture, 724 path_base_directory baseDirectory, const char* subPath, uint32 flags, 725 char*** _paths, size_t* _pathCount) 726 \brief Retrieves a list of paths in the file system layout. 727 728 For each installation location -- in the order most specific to most 729 generic, non-packaged before packaged -- the function evaluates 730 \a baseDirectory to a path and appends \a subPath, if given. 731 732 If \a baseDirectory specifies a path that is architecture dependent, 733 \a architecture is used for constructing each path. If \a architecture is 734 \c NULL, the caller's architecture (as returned by get_architecture()) is 735 used. 736 737 \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not 738 valid arguments for this function. 739 740 The array of paths retrieved is allocated on the heap and returned via 741 \a _paths. The caller is responsible for calling free() for the returned 742 pointer. 743 744 \param architecture The name of the architecture to be used for resolving 745 architecture dependent paths. Can be \c NULL, in which case the caller's 746 architecture is used. 747 \param baseDirectory Constant indicating which paths to retrieve. 748 \param subPath Relative subpath that shall be appended. Can be \c NULL. 749 \param flags Bitwise OR of any of the following flags: 750 - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, 751 create it as a directory (including all missing ancestors). 752 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent 753 doesn't exist, create the parent directory (including all missing 754 ancestors). 755 - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip 756 it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. 757 \param _paths Pointer to a pre-allocated variable where the pointer to the 758 allocated path array shall be stored on success. 759 \param _pathCount Pointer to a pre-allocated variable where the number of 760 paths in the path array shall be stored on success. 761 \return A status code. 762 \retval B_OK Everything went fine. 763 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 764 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and 765 none of the resulting paths do exist. 766*/ 767