1/* 2 * Copyright 2011, Haiku inc. 3 * Distributed under the terms of the MIT Licence. 4 * 5 * Documentation by: 6 * Adrien Destugues <pulkomandy@pulkomandy.ath.cx> 7 * Corresponds to: 8 * /trunk/headers/os/storage/FindDirectory.h rev 42600 9 * /trunk/src/kits/storage/FindDirectory.cpp rev 42600 10 */ 11 12 13/*! 14 \file FindDirectory.h 15 \ingroup storage 16 \brief Provides the find_directory function. 17 18 Haiku provides a set of directories for applications to use. These can be 19 accessed using the find_directory function. It is very important to use the 20 function at runtime and not hardcode the path, as it may change in future 21 versions of Haiku, and already changed in past ones. Using this function 22 makes your application more future-proof, and makes sure everyone puts data 23 in the same place, which makes the system cleaner and easier to manage. 24 25 Note this function can be accessed from C code, to make it easy to use also 26 in ported applications. 27*/ 28 29 30/*! 31 \enum directory_which 32 \brief Directory constants to use with find_directory. 33 34 There are four kind of directories. Volume-local directories exist on each 35 volume. They may be at a different place in each of them, for example the 36 trash location depends on the filesystem. System and common directories are 37 system-wide. They live on only one volume. The difference is system is 38 only meant for internal system management and shouldn't be used by 39 applications. The common directories have a similar hierarchy, and they are 40 ignored when the user disable user add-ons in the boot menu. User 41 directories have a different value depending on the UID of the application 42 calling the function. They are usually located in the user home directory. 43 44 Use common directories for system-wide filessuch as drivers. Use user 45 directories for application settings, since each user may want different 46 settings. 47*/ 48 49 50/*! 51 \var directory_which B_DESKTOP_DIRECTORY 52 The desktop for a given volume. 53 54 \var directory_which B_TRASH_DIRECTORY 55 The trash for a given volume. 56 57 \var directory_which B_SYSTEM_DIRECTORY 58 The system directory. 59 60 \var directory_which B_SYSTEM_ADDONS_DIRECTORY 61 The system add-ons directory 62 63 \var directory_which B_SYSTEM_BOOT_DIRECTORY 64 The system boot directory. Contains the minimal set of files required for 65 booting Haiku. 66 67 \var directory_which B_SYSTEM_FONTS_DIRECTORY 68 The system fonts directory 69 70 \var directory_which B_SYSTEM_LIB_DIRECTORY 71 The system lib directory. 72 73 \var directory_which B_SYSTEM_SERVERS_DIRECTORY 74 The system servers directory. 75 76 \var directory_which B_SYSTEM_APPS_DIRECTORY 77 The system applications direcotry. Contains applications executable from 78 Tracker. 79 80 \var directory_which B_SYSTEM_BIN_DIRECTORY 81 The system bin directory. Contains command-line applications runnable from 82 Terminal. 83 84 \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY 85 The system documentation directory. Contains manpages. 86 87 \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY 88 The system preferences directory. 89 90 \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY 91 The system translator directory. 92 93 \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY 94 The system media nodes directory. 95 96 \var directory_which B_SYSTEM_SOUNDS_DIRECTORY 97 The system sounds directory. 98 99 \var directory_which B_SYSTEM_DATA_DIRECTORY 100 The system data directory. 101 102 \var directory_which B_COMMON_DIRECTORY 103 The common directory. 104 105 \var directory_which B_COMMON_SYSTEM_DIRECTORY 106 \var directory_which B_COMMON_ADDONS_DIRECTORY 107 \var directory_which B_COMMON_BOOT_DIRECTORY 108 \var directory_which B_COMMON_FONTS_DIRECTORY 109 \var directory_which B_COMMON_LIB_DIRECTORY 110 \var directory_which B_COMMON_SERVERS_DIRECTORY 111 \var directory_which B_COMMON_BIN_DIRECTORY 112 \var directory_which B_COMMON_ETC_DIRECTORY 113 \var directory_which B_COMMON_DOCUMENTATION_DIRECTORY 114 \var directory_which B_COMMON_SETTINGS_DIRECTORY 115 \var directory_which B_COMMON_DEVELOP_DIRECTORY 116 The common development directory. Contains toolchains, include files, 117 and other tools related to application development. 118 119 \var directory_which B_COMMON_LOG_DIRECTORY 120 The common log directory. Log files are stored here. 121 122 \var directory_which B_COMMON_SPOOL_DIRECTORY 123 \var directory_which B_COMMON_TEMP_DIRECTORY 124 \var directory_which B_COMMON_VAR_DIRECTORY 125 \var directory_which B_COMMON_TRANSLATORS_DIRECTORY 126 \var directory_which B_COMMON_MEDIA_NODES_DIRECTORY 127 \var directory_which B_COMMON_SOUNDS_DIRECTORY 128 \var directory_which B_COMMON_DATA_DIRECTORY 129 The common data directory. You may store application data here, such as 130 resources (graphics, music) for your application. 131 132 \var directory_which B_COMMON_CACHE_DIRECTORY 133 The common cache directory. You may store temporary data here, such as 134 thumbnails for a picture viewer application, or a web browser data cache. 135 136 \var directory_which B_USER_DIRECTORY 137 The user home directory. Do NOT store application settings here as on unix, 138 instead use B_USER_SETTINGS_DIRECTORY. 139 140 \var directory_which B_USER_CONFIG_DIRECTORY 141 \var directory_which B_USER_ADDONS_DIRECTORY 142 \var directory_which B_USER_BOOT_DIRECTORY 143 \var directory_which B_USER_FONTS_DIRECTORY 144 \var directory_which B_USER_LIB_DIRECTORY 145 \var directory_which B_USER_SETTINGS_DIRECTORY 146 The user settings directory. You may store your application settings here. 147 Create a subdirectory for your application if you have multiple files to 148 store, else, put a single file. The file or directory should have the same 149 name as your application, so the user knows what it's used for. 150 151 \var directory_which B_USER_DESKBAR_DIRECTORY 152 The user deskbar directory. You may add a link to your application here, so 153 it shows up in the user deskbar's leaf menu. 154 155 \var directory_which B_USER_PRINTERS_DIRECTORY 156 \var directory_which B_USER_TRANSLATORS_DIRECTORY 157 \var directory_which B_USER_MEDIA_NODES_DIRECTORY 158 \var directory_which B_USER_SOUNDS_DIRECTORY 159 \var directory_which B_USER_DATA_DIRECTORY 160 \var directory_which B_USER_CACHE_DIRECTORY 161 162 \var directory_which B_APPS_DIRECTORY 163 \var directory_which B_PREFERENCES_DIRECTORY 164 \var directory_which B_UTILITIES_DIRECTORY 165*/ 166 167 168/*! 169 \fn status_t find_directory(directory_which which, dev_t volume, bool createIt, char* pathString, int32 length) 170 \brief C interface to find_directory 171 172 Fills up to \a length characters of \a pathString with the path to \a which 173 on \a volume. Creates the directory if it doesn't exists and \a creqteIt is 174 set. 175*/ 176 177 178/*! 179 \fn status_t find_directory(directory_which which, BPath* path, bool createIt = false, BVolume* volume = NULL) 180 \brief C++ interface to find_directory 181 182 Set \a path to \a which on \a volume. 183*/ 184