1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef APR_FILE_INFO_H 18 #define APR_FILE_INFO_H 19 20 /** 21 * @file apr_file_info.h 22 * @brief APR File Information 23 */ 24 25 #include "apr.h" 26 #include "apr_user.h" 27 #include "apr_pools.h" 28 #include "apr_tables.h" 29 #include "apr_time.h" 30 #include "apr_errno.h" 31 32 #if APR_HAVE_SYS_UIO_H 33 #include <sys/uio.h> 34 #endif 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif /* __cplusplus */ 39 40 /** 41 * @defgroup apr_file_info File Information 42 * @ingroup APR 43 * @{ 44 */ 45 46 /* Many applications use the type member to determine the 47 * existance of a file or initialization of the file info, 48 * so the APR_NOFILE value must be distinct from APR_UNKFILE. 49 */ 50 51 /** apr_filetype_e values for the filetype member of the 52 * apr_file_info_t structure 53 * @warning: Not all of the filetypes below can be determined. 54 * For example, a given platform might not correctly report 55 * a socket descriptor as APR_SOCK if that type isn't 56 * well-identified on that platform. In such cases where 57 * a filetype exists but cannot be described by the recognized 58 * flags below, the filetype will be APR_UNKFILE. If the 59 * filetype member is not determined, the type will be APR_NOFILE. 60 */ 61 62 typedef enum { 63 APR_NOFILE = 0, /**< no file type determined */ 64 APR_REG, /**< a regular file */ 65 APR_DIR, /**< a directory */ 66 APR_CHR, /**< a character device */ 67 APR_BLK, /**< a block device */ 68 APR_PIPE, /**< a FIFO / pipe */ 69 APR_LNK, /**< a symbolic link */ 70 APR_SOCK, /**< a [unix domain] socket */ 71 APR_UNKFILE = 127 /**< a file of some other unknown type */ 72 } apr_filetype_e; 73 74 /** 75 * @defgroup apr_file_permissions File Permissions flags 76 * @{ 77 */ 78 79 #define APR_FPROT_USETID 0x8000 /**< Set user id */ 80 #define APR_FPROT_UREAD 0x0400 /**< Read by user */ 81 #define APR_FPROT_UWRITE 0x0200 /**< Write by user */ 82 #define APR_FPROT_UEXECUTE 0x0100 /**< Execute by user */ 83 84 #define APR_FPROT_GSETID 0x4000 /**< Set group id */ 85 #define APR_FPROT_GREAD 0x0040 /**< Read by group */ 86 #define APR_FPROT_GWRITE 0x0020 /**< Write by group */ 87 #define APR_FPROT_GEXECUTE 0x0010 /**< Execute by group */ 88 89 #define APR_FPROT_WSTICKY 0x2000 /**< Sticky bit */ 90 #define APR_FPROT_WREAD 0x0004 /**< Read by others */ 91 #define APR_FPROT_WWRITE 0x0002 /**< Write by others */ 92 #define APR_FPROT_WEXECUTE 0x0001 /**< Execute by others */ 93 94 #define APR_FPROT_OS_DEFAULT 0x0FFF /**< use OS's default permissions */ 95 96 /* additional permission flags for apr_file_copy and apr_file_append */ 97 #define APR_FPROT_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */ 98 99 /* backcompat */ 100 #define APR_USETID APR_FPROT_USETID /**< @deprecated @see APR_FPROT_USETID */ 101 #define APR_UREAD APR_FPROT_UREAD /**< @deprecated @see APR_FPROT_UREAD */ 102 #define APR_UWRITE APR_FPROT_UWRITE /**< @deprecated @see APR_FPROT_UWRITE */ 103 #define APR_UEXECUTE APR_FPROT_UEXECUTE /**< @deprecated @see APR_FPROT_UEXECUTE */ 104 #define APR_GSETID APR_FPROT_GSETID /**< @deprecated @see APR_FPROT_GSETID */ 105 #define APR_GREAD APR_FPROT_GREAD /**< @deprecated @see APR_FPROT_GREAD */ 106 #define APR_GWRITE APR_FPROT_GWRITE /**< @deprecated @see APR_FPROT_GWRITE */ 107 #define APR_GEXECUTE APR_FPROT_GEXECUTE /**< @deprecated @see APR_FPROT_GEXECUTE */ 108 #define APR_WSTICKY APR_FPROT_WSTICKY /**< @deprecated @see APR_FPROT_WSTICKY */ 109 #define APR_WREAD APR_FPROT_WREAD /**< @deprecated @see APR_FPROT_WREAD */ 110 #define APR_WWRITE APR_FPROT_WWRITE /**< @deprecated @see APR_FPROT_WWRITE */ 111 #define APR_WEXECUTE APR_FPROT_WEXECUTE /**< @deprecated @see APR_FPROT_WEXECUTE */ 112 #define APR_OS_DEFAULT APR_FPROT_OS_DEFAULT /**< @deprecated @see APR_FPROT_OS_DEFAULT */ 113 #define APR_FILE_SOURCE_PERMS APR_FPROT_FILE_SOURCE_PERMS /**< @deprecated @see APR_FPROT_FILE_SOURCE_PERMS */ 114 115 /** @} */ 116 117 118 /** 119 * Structure for referencing directories. 120 */ 121 typedef struct apr_dir_t apr_dir_t; 122 /** 123 * Structure for determining file permissions. 124 */ 125 typedef apr_int32_t apr_fileperms_t; 126 #if (defined WIN32) || (defined NETWARE) 127 /** 128 * Structure for determining the device the file is on. 129 */ 130 typedef apr_uint32_t apr_dev_t; 131 #else 132 /** 133 * Structure for determining the device the file is on. 134 */ 135 typedef dev_t apr_dev_t; 136 #endif 137 138 /** 139 * @defgroup apr_file_stat Stat Functions 140 * @{ 141 */ 142 /** file info structure */ 143 typedef struct apr_finfo_t apr_finfo_t; 144 145 #define APR_FINFO_LINK 0x00000001 /**< Stat the link not the file itself if it is a link */ 146 #define APR_FINFO_MTIME 0x00000010 /**< Modification Time */ 147 #define APR_FINFO_CTIME 0x00000020 /**< Creation or inode-changed time */ 148 #define APR_FINFO_ATIME 0x00000040 /**< Access Time */ 149 #define APR_FINFO_SIZE 0x00000100 /**< Size of the file */ 150 #define APR_FINFO_CSIZE 0x00000200 /**< Storage size consumed by the file */ 151 #define APR_FINFO_DEV 0x00001000 /**< Device */ 152 #define APR_FINFO_INODE 0x00002000 /**< Inode */ 153 #define APR_FINFO_NLINK 0x00004000 /**< Number of links */ 154 #define APR_FINFO_TYPE 0x00008000 /**< Type */ 155 #define APR_FINFO_USER 0x00010000 /**< User */ 156 #define APR_FINFO_GROUP 0x00020000 /**< Group */ 157 #define APR_FINFO_UPROT 0x00100000 /**< User protection bits */ 158 #define APR_FINFO_GPROT 0x00200000 /**< Group protection bits */ 159 #define APR_FINFO_WPROT 0x00400000 /**< World protection bits */ 160 #define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */ 161 #define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */ 162 163 #define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */ 164 #define APR_FINFO_IDENT 0x00003000 /**< dev and inode */ 165 #define APR_FINFO_OWNER 0x00030000 /**< user and group */ 166 #define APR_FINFO_PROT 0x00700000 /**< all protections */ 167 #define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */ 168 #define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */ 169 170 /** 171 * The file information structure. This is analogous to the POSIX 172 * stat structure. 173 */ 174 struct apr_finfo_t { 175 /** Allocates memory and closes lingering handles in the specified pool */ 176 apr_pool_t *pool; 177 /** The bitmask describing valid fields of this apr_finfo_t structure 178 * including all available 'wanted' fields and potentially more */ 179 apr_int32_t valid; 180 /** The access permissions of the file. Mimics Unix access rights. */ 181 apr_fileperms_t protection; 182 /** The type of file. One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 183 * APR_LNK or APR_SOCK. If the type is undetermined, the value is APR_NOFILE. 184 * If the type cannot be determined, the value is APR_UNKFILE. 185 */ 186 apr_filetype_e filetype; 187 /** The user id that owns the file */ 188 apr_uid_t user; 189 /** The group id that owns the file */ 190 apr_gid_t group; 191 /** The inode of the file. */ 192 apr_ino_t inode; 193 /** The id of the device the file is on. */ 194 apr_dev_t device; 195 /** The number of hard links to the file. */ 196 apr_int32_t nlink; 197 /** The size of the file */ 198 apr_off_t size; 199 /** The storage size consumed by the file */ 200 apr_off_t csize; 201 /** The time the file was last accessed */ 202 apr_time_t atime; 203 /** The time the file was last modified */ 204 apr_time_t mtime; 205 /** The time the file was created, or the inode was last changed */ 206 apr_time_t ctime; 207 /** The pathname of the file (possibly unrooted) */ 208 const char *fname; 209 /** The file's name (no path) in filesystem case */ 210 const char *name; 211 /** Unused */ 212 struct apr_file_t *filehand; 213 }; 214 215 /** 216 * get the specified file's stats. The file is specified by filename, 217 * instead of using a pre-opened file. 218 * @param finfo Where to store the information about the file, which is 219 * never touched if the call fails. 220 * @param fname The name of the file to stat. 221 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 222 values 223 * @param pool the pool to use to allocate the new file. 224 * 225 * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 226 * not be filled in, and you need to check the @c finfo->valid bitmask 227 * to verify that what you're looking for is there. 228 */ 229 APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname, 230 apr_int32_t wanted, apr_pool_t *pool); 231 232 /** @} */ 233 /** 234 * @defgroup apr_dir Directory Manipulation Functions 235 * @{ 236 */ 237 238 /** 239 * Open the specified directory. 240 * @param new_dir The opened directory descriptor. 241 * @param dirname The full path to the directory (use / on all systems) 242 * @param pool The pool to use. 243 */ 244 APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 245 const char *dirname, 246 apr_pool_t *pool); 247 248 /** 249 * close the specified directory. 250 * @param thedir the directory descriptor to close. 251 */ 252 APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir); 253 254 /** 255 * Read the next entry from the specified directory. 256 * @param finfo the file info structure and filled in by apr_dir_read 257 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 258 values 259 * @param thedir the directory descriptor returned from apr_dir_open 260 * @remark No ordering is guaranteed for the entries read. 261 * 262 * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 263 * not be filled in, and you need to check the @c finfo->valid bitmask 264 * to verify that what you're looking for is there. When no more 265 * entries are available, APR_ENOENT is returned. 266 */ 267 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted, 268 apr_dir_t *thedir); 269 270 /** 271 * Rewind the directory to the first entry. 272 * @param thedir the directory descriptor to rewind. 273 */ 274 APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); 275 /** @} */ 276 277 /** 278 * @defgroup apr_filepath Filepath Manipulation Functions 279 * @{ 280 */ 281 282 /** Cause apr_filepath_merge to fail if addpath is above rootpath 283 * @bug in APR 0.9 and 1.x, this flag's behavior is undefined 284 * if the rootpath is NULL or empty. In APR 2.0 this should be 285 * changed to imply NOTABSOLUTE if the rootpath is NULL or empty. 286 */ 287 #define APR_FILEPATH_NOTABOVEROOT 0x01 288 289 /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */ 290 #define APR_FILEPATH_SECUREROOTTEST 0x02 291 292 /** Cause apr_filepath_merge to fail if addpath is above rootpath, 293 * even given a rootpath /foo/bar and an addpath ../bar/bash 294 */ 295 #define APR_FILEPATH_SECUREROOT 0x03 296 297 /** Fail apr_filepath_merge if the merged path is relative */ 298 #define APR_FILEPATH_NOTRELATIVE 0x04 299 300 /** Fail apr_filepath_merge if the merged path is absolute */ 301 #define APR_FILEPATH_NOTABSOLUTE 0x08 302 303 /** Return the file system's native path format (e.g. path delimiters 304 * of ':' on MacOS9, '\' on Win32, etc.) */ 305 #define APR_FILEPATH_NATIVE 0x10 306 307 /** Resolve the true case of existing directories and file elements 308 * of addpath, (resolving any aliases on Win32) and append a proper 309 * trailing slash if a directory 310 */ 311 #define APR_FILEPATH_TRUENAME 0x20 312 313 /** 314 * Extract the rootpath from the given filepath 315 * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE 316 * @param filepath the pathname to parse for its root component 317 * @param flags the desired rules to apply, from 318 * <PRE> 319 * APR_FILEPATH_NATIVE Use native path separators (e.g. '\' on Win32) 320 * APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper 321 * </PRE> 322 * @param p the pool to allocate the new path string from 323 * @remark on return, filepath points to the first non-root character in the 324 * given filepath. In the simplest example, given a filepath of "/foo", 325 * returns the rootpath of "/" and filepath points at "foo". This is far 326 * more complex on other platforms, which will canonicalize the root form 327 * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also 328 * test for the validity of that root (e.g., that a drive d:/ or network 329 * share //machine/foovol/). 330 * The function returns APR_ERELATIVE if filepath isn't rooted (an 331 * error), APR_EINCOMPLETE if the root path is ambiguous (but potentially 332 * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify 333 * the drive letter), or APR_EBADPATH if the root is simply invalid. 334 * APR_SUCCESS is returned if filepath is an absolute path. 335 */ 336 APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 337 const char **filepath, 338 apr_int32_t flags, 339 apr_pool_t *p); 340 341 /** 342 * Merge additional file path onto the previously processed rootpath 343 * @param newpath the merged paths returned 344 * @param rootpath the root file path (NULL uses the current working path) 345 * @param addpath the path to add to the root path 346 * @param flags the desired APR_FILEPATH_ rules to apply when merging 347 * @param p the pool to allocate the new path string from 348 * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 349 * contains wildcard characters ('*', '?') on platforms that don't support 350 * such characters within filenames, the paths will be merged, but the 351 * result code will be APR_EPATHWILD, and all further segments will not 352 * reflect the true filenames including the wildcard and following segments. 353 */ 354 APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 355 const char *rootpath, 356 const char *addpath, 357 apr_int32_t flags, 358 apr_pool_t *p); 359 360 /** 361 * Split a search path into separate components 362 * @param pathelts the returned components of the search path 363 * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>) 364 * @param p the pool to allocate the array and path components from 365 * @remark empty path components do not become part of @a pathelts. 366 * @remark the path separator in @a liststr is system specific; 367 * e.g., ':' on Unix, ';' on Windows, etc. 368 */ 369 APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts, 370 const char *liststr, 371 apr_pool_t *p); 372 373 /** 374 * Merge a list of search path components into a single search path 375 * @param liststr the returned search path; may be NULL if @a pathelts is empty 376 * @param pathelts the components of the search path 377 * @param p the pool to allocate the search path from 378 * @remark emtpy strings in the source array are ignored. 379 * @remark the path separator in @a liststr is system specific; 380 * e.g., ':' on Unix, ';' on Windows, etc. 381 */ 382 APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr, 383 apr_array_header_t *pathelts, 384 apr_pool_t *p); 385 386 /** 387 * Return the default file path (for relative file names) 388 * @param path the default path string returned 389 * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the 390 * default file path in os-native format. 391 * @param p the pool to allocate the default path string from 392 */ 393 APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags, 394 apr_pool_t *p); 395 396 /** 397 * Set the default file path (for relative file names) 398 * @param path the default path returned 399 * @param p the pool to allocate any working storage 400 */ 401 APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); 402 403 /** The FilePath character encoding is unknown */ 404 #define APR_FILEPATH_ENCODING_UNKNOWN 0 405 406 /** The FilePath character encoding is locale-dependent */ 407 #define APR_FILEPATH_ENCODING_LOCALE 1 408 409 /** The FilePath character encoding is UTF-8 */ 410 #define APR_FILEPATH_ENCODING_UTF8 2 411 412 /** 413 * Determine the encoding used internally by the FilePath functions 414 * @param style points to a variable which receives the encoding style flag 415 * @param p the pool to allocate any working storage 416 * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding 417 * to get the name of the path encoding if it's not UTF-8. 418 */ 419 APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); 420 /** @} */ 421 422 /** @} */ 423 424 #ifdef __cplusplus 425 } 426 #endif 427 428 #endif /* ! APR_FILE_INFO_H */ 429