1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_FILE_INFO_H 18251875Speter#define APR_FILE_INFO_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_file_info.h 22251875Speter * @brief APR File Information 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_user.h" 27251875Speter#include "apr_pools.h" 28251875Speter#include "apr_tables.h" 29251875Speter#include "apr_time.h" 30251875Speter#include "apr_errno.h" 31251875Speter 32251875Speter#if APR_HAVE_SYS_UIO_H 33251875Speter#include <sys/uio.h> 34251875Speter#endif 35251875Speter 36251875Speter#ifdef __cplusplus 37251875Speterextern "C" { 38251875Speter#endif /* __cplusplus */ 39251875Speter 40251875Speter/** 41251875Speter * @defgroup apr_file_info File Information 42251875Speter * @ingroup APR 43251875Speter * @{ 44251875Speter */ 45251875Speter 46251875Speter/* Many applications use the type member to determine the 47251875Speter * existance of a file or initialization of the file info, 48251875Speter * so the APR_NOFILE value must be distinct from APR_UNKFILE. 49251875Speter */ 50251875Speter 51251875Speter/** apr_filetype_e values for the filetype member of the 52251875Speter * apr_file_info_t structure 53362181Sdim * @warning Not all of the filetypes below can be determined. 54251875Speter * For example, a given platform might not correctly report 55251875Speter * a socket descriptor as APR_SOCK if that type isn't 56251875Speter * well-identified on that platform. In such cases where 57251875Speter * a filetype exists but cannot be described by the recognized 58251875Speter * flags below, the filetype will be APR_UNKFILE. If the 59251875Speter * filetype member is not determined, the type will be APR_NOFILE. 60251875Speter */ 61251875Speter 62251875Spetertypedef enum { 63251875Speter APR_NOFILE = 0, /**< no file type determined */ 64251875Speter APR_REG, /**< a regular file */ 65251875Speter APR_DIR, /**< a directory */ 66251875Speter APR_CHR, /**< a character device */ 67251875Speter APR_BLK, /**< a block device */ 68251875Speter APR_PIPE, /**< a FIFO / pipe */ 69251875Speter APR_LNK, /**< a symbolic link */ 70251875Speter APR_SOCK, /**< a [unix domain] socket */ 71251875Speter APR_UNKFILE = 127 /**< a file of some other unknown type */ 72251875Speter} apr_filetype_e; 73251875Speter 74251875Speter/** 75251875Speter * @defgroup apr_file_permissions File Permissions flags 76251875Speter * @{ 77251875Speter */ 78251875Speter 79251875Speter#define APR_FPROT_USETID 0x8000 /**< Set user id */ 80251875Speter#define APR_FPROT_UREAD 0x0400 /**< Read by user */ 81251875Speter#define APR_FPROT_UWRITE 0x0200 /**< Write by user */ 82251875Speter#define APR_FPROT_UEXECUTE 0x0100 /**< Execute by user */ 83251875Speter 84251875Speter#define APR_FPROT_GSETID 0x4000 /**< Set group id */ 85251875Speter#define APR_FPROT_GREAD 0x0040 /**< Read by group */ 86251875Speter#define APR_FPROT_GWRITE 0x0020 /**< Write by group */ 87251875Speter#define APR_FPROT_GEXECUTE 0x0010 /**< Execute by group */ 88251875Speter 89251875Speter#define APR_FPROT_WSTICKY 0x2000 /**< Sticky bit */ 90251875Speter#define APR_FPROT_WREAD 0x0004 /**< Read by others */ 91251875Speter#define APR_FPROT_WWRITE 0x0002 /**< Write by others */ 92251875Speter#define APR_FPROT_WEXECUTE 0x0001 /**< Execute by others */ 93251875Speter 94251875Speter#define APR_FPROT_OS_DEFAULT 0x0FFF /**< use OS's default permissions */ 95251875Speter 96251875Speter/* additional permission flags for apr_file_copy and apr_file_append */ 97251875Speter#define APR_FPROT_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */ 98251875Speter 99251875Speter/* backcompat */ 100251875Speter#define APR_USETID APR_FPROT_USETID /**< @deprecated @see APR_FPROT_USETID */ 101251875Speter#define APR_UREAD APR_FPROT_UREAD /**< @deprecated @see APR_FPROT_UREAD */ 102251875Speter#define APR_UWRITE APR_FPROT_UWRITE /**< @deprecated @see APR_FPROT_UWRITE */ 103251875Speter#define APR_UEXECUTE APR_FPROT_UEXECUTE /**< @deprecated @see APR_FPROT_UEXECUTE */ 104251875Speter#define APR_GSETID APR_FPROT_GSETID /**< @deprecated @see APR_FPROT_GSETID */ 105251875Speter#define APR_GREAD APR_FPROT_GREAD /**< @deprecated @see APR_FPROT_GREAD */ 106251875Speter#define APR_GWRITE APR_FPROT_GWRITE /**< @deprecated @see APR_FPROT_GWRITE */ 107251875Speter#define APR_GEXECUTE APR_FPROT_GEXECUTE /**< @deprecated @see APR_FPROT_GEXECUTE */ 108251875Speter#define APR_WSTICKY APR_FPROT_WSTICKY /**< @deprecated @see APR_FPROT_WSTICKY */ 109251875Speter#define APR_WREAD APR_FPROT_WREAD /**< @deprecated @see APR_FPROT_WREAD */ 110251875Speter#define APR_WWRITE APR_FPROT_WWRITE /**< @deprecated @see APR_FPROT_WWRITE */ 111251875Speter#define APR_WEXECUTE APR_FPROT_WEXECUTE /**< @deprecated @see APR_FPROT_WEXECUTE */ 112251875Speter#define APR_OS_DEFAULT APR_FPROT_OS_DEFAULT /**< @deprecated @see APR_FPROT_OS_DEFAULT */ 113251875Speter#define APR_FILE_SOURCE_PERMS APR_FPROT_FILE_SOURCE_PERMS /**< @deprecated @see APR_FPROT_FILE_SOURCE_PERMS */ 114251875Speter 115251875Speter/** @} */ 116251875Speter 117251875Speter 118251875Speter/** 119251875Speter * Structure for referencing directories. 120251875Speter */ 121251875Spetertypedef struct apr_dir_t apr_dir_t; 122251875Speter/** 123251875Speter * Structure for determining file permissions. 124251875Speter */ 125251875Spetertypedef apr_int32_t apr_fileperms_t; 126251875Speter#if (defined WIN32) || (defined NETWARE) 127251875Speter/** 128251875Speter * Structure for determining the device the file is on. 129251875Speter */ 130251875Spetertypedef apr_uint32_t apr_dev_t; 131251875Speter#else 132251875Speter/** 133251875Speter * Structure for determining the device the file is on. 134251875Speter */ 135251875Spetertypedef dev_t apr_dev_t; 136251875Speter#endif 137251875Speter 138251875Speter/** 139251875Speter * @defgroup apr_file_stat Stat Functions 140251875Speter * @{ 141251875Speter */ 142251875Speter/** file info structure */ 143251875Spetertypedef struct apr_finfo_t apr_finfo_t; 144251875Speter 145251875Speter#define APR_FINFO_LINK 0x00000001 /**< Stat the link not the file itself if it is a link */ 146251875Speter#define APR_FINFO_MTIME 0x00000010 /**< Modification Time */ 147251875Speter#define APR_FINFO_CTIME 0x00000020 /**< Creation or inode-changed time */ 148251875Speter#define APR_FINFO_ATIME 0x00000040 /**< Access Time */ 149251875Speter#define APR_FINFO_SIZE 0x00000100 /**< Size of the file */ 150251875Speter#define APR_FINFO_CSIZE 0x00000200 /**< Storage size consumed by the file */ 151251875Speter#define APR_FINFO_DEV 0x00001000 /**< Device */ 152251875Speter#define APR_FINFO_INODE 0x00002000 /**< Inode */ 153251875Speter#define APR_FINFO_NLINK 0x00004000 /**< Number of links */ 154251875Speter#define APR_FINFO_TYPE 0x00008000 /**< Type */ 155251875Speter#define APR_FINFO_USER 0x00010000 /**< User */ 156251875Speter#define APR_FINFO_GROUP 0x00020000 /**< Group */ 157251875Speter#define APR_FINFO_UPROT 0x00100000 /**< User protection bits */ 158251875Speter#define APR_FINFO_GPROT 0x00200000 /**< Group protection bits */ 159251875Speter#define APR_FINFO_WPROT 0x00400000 /**< World protection bits */ 160251875Speter#define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */ 161251875Speter#define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */ 162251875Speter 163251875Speter#define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */ 164251875Speter#define APR_FINFO_IDENT 0x00003000 /**< dev and inode */ 165251875Speter#define APR_FINFO_OWNER 0x00030000 /**< user and group */ 166251875Speter#define APR_FINFO_PROT 0x00700000 /**< all protections */ 167251875Speter#define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */ 168251875Speter#define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */ 169251875Speter 170251875Speter/** 171251875Speter * The file information structure. This is analogous to the POSIX 172251875Speter * stat structure. 173251875Speter */ 174251875Speterstruct apr_finfo_t { 175251875Speter /** Allocates memory and closes lingering handles in the specified pool */ 176251875Speter apr_pool_t *pool; 177251875Speter /** The bitmask describing valid fields of this apr_finfo_t structure 178251875Speter * including all available 'wanted' fields and potentially more */ 179251875Speter apr_int32_t valid; 180251875Speter /** The access permissions of the file. Mimics Unix access rights. */ 181251875Speter apr_fileperms_t protection; 182251875Speter /** The type of file. One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 183251875Speter * APR_LNK or APR_SOCK. If the type is undetermined, the value is APR_NOFILE. 184251875Speter * If the type cannot be determined, the value is APR_UNKFILE. 185251875Speter */ 186251875Speter apr_filetype_e filetype; 187251875Speter /** The user id that owns the file */ 188251875Speter apr_uid_t user; 189251875Speter /** The group id that owns the file */ 190251875Speter apr_gid_t group; 191251875Speter /** The inode of the file. */ 192251875Speter apr_ino_t inode; 193251875Speter /** The id of the device the file is on. */ 194251875Speter apr_dev_t device; 195251875Speter /** The number of hard links to the file. */ 196251875Speter apr_int32_t nlink; 197251875Speter /** The size of the file */ 198251875Speter apr_off_t size; 199251875Speter /** The storage size consumed by the file */ 200251875Speter apr_off_t csize; 201251875Speter /** The time the file was last accessed */ 202251875Speter apr_time_t atime; 203251875Speter /** The time the file was last modified */ 204251875Speter apr_time_t mtime; 205251875Speter /** The time the file was created, or the inode was last changed */ 206251875Speter apr_time_t ctime; 207251875Speter /** The pathname of the file (possibly unrooted) */ 208251875Speter const char *fname; 209251875Speter /** The file's name (no path) in filesystem case */ 210251875Speter const char *name; 211266735Speter /** Unused */ 212251875Speter struct apr_file_t *filehand; 213251875Speter}; 214251875Speter 215251875Speter/** 216251875Speter * get the specified file's stats. The file is specified by filename, 217251875Speter * instead of using a pre-opened file. 218251875Speter * @param finfo Where to store the information about the file, which is 219251875Speter * never touched if the call fails. 220251875Speter * @param fname The name of the file to stat. 221251875Speter * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 222251875Speter values 223251875Speter * @param pool the pool to use to allocate the new file. 224251875Speter * 225251875Speter * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 226251875Speter * not be filled in, and you need to check the @c finfo->valid bitmask 227251875Speter * to verify that what you're looking for is there. 228251875Speter */ 229251875SpeterAPR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname, 230251875Speter apr_int32_t wanted, apr_pool_t *pool); 231251875Speter 232251875Speter/** @} */ 233251875Speter/** 234251875Speter * @defgroup apr_dir Directory Manipulation Functions 235251875Speter * @{ 236251875Speter */ 237251875Speter 238251875Speter/** 239251875Speter * Open the specified directory. 240251875Speter * @param new_dir The opened directory descriptor. 241251875Speter * @param dirname The full path to the directory (use / on all systems) 242251875Speter * @param pool The pool to use. 243251875Speter */ 244251875SpeterAPR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 245251875Speter const char *dirname, 246251875Speter apr_pool_t *pool); 247251875Speter 248251875Speter/** 249251875Speter * close the specified directory. 250251875Speter * @param thedir the directory descriptor to close. 251251875Speter */ 252251875SpeterAPR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir); 253251875Speter 254251875Speter/** 255251875Speter * Read the next entry from the specified directory. 256251875Speter * @param finfo the file info structure and filled in by apr_dir_read 257251875Speter * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 258251875Speter values 259251875Speter * @param thedir the directory descriptor returned from apr_dir_open 260251875Speter * @remark No ordering is guaranteed for the entries read. 261251875Speter * 262251875Speter * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 263251875Speter * not be filled in, and you need to check the @c finfo->valid bitmask 264251875Speter * to verify that what you're looking for is there. When no more 265251875Speter * entries are available, APR_ENOENT is returned. 266251875Speter */ 267251875SpeterAPR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted, 268251875Speter apr_dir_t *thedir); 269251875Speter 270251875Speter/** 271251875Speter * Rewind the directory to the first entry. 272251875Speter * @param thedir the directory descriptor to rewind. 273251875Speter */ 274251875SpeterAPR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); 275251875Speter/** @} */ 276251875Speter 277251875Speter/** 278251875Speter * @defgroup apr_filepath Filepath Manipulation Functions 279251875Speter * @{ 280251875Speter */ 281251875Speter 282251875Speter/** Cause apr_filepath_merge to fail if addpath is above rootpath 283251875Speter * @bug in APR 0.9 and 1.x, this flag's behavior is undefined 284251875Speter * if the rootpath is NULL or empty. In APR 2.0 this should be 285251875Speter * changed to imply NOTABSOLUTE if the rootpath is NULL or empty. 286251875Speter */ 287251875Speter#define APR_FILEPATH_NOTABOVEROOT 0x01 288251875Speter 289251875Speter/** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */ 290251875Speter#define APR_FILEPATH_SECUREROOTTEST 0x02 291251875Speter 292251875Speter/** Cause apr_filepath_merge to fail if addpath is above rootpath, 293251875Speter * even given a rootpath /foo/bar and an addpath ../bar/bash 294251875Speter */ 295251875Speter#define APR_FILEPATH_SECUREROOT 0x03 296251875Speter 297251875Speter/** Fail apr_filepath_merge if the merged path is relative */ 298251875Speter#define APR_FILEPATH_NOTRELATIVE 0x04 299251875Speter 300251875Speter/** Fail apr_filepath_merge if the merged path is absolute */ 301251875Speter#define APR_FILEPATH_NOTABSOLUTE 0x08 302251875Speter 303251875Speter/** Return the file system's native path format (e.g. path delimiters 304251875Speter * of ':' on MacOS9, '\' on Win32, etc.) */ 305251875Speter#define APR_FILEPATH_NATIVE 0x10 306251875Speter 307251875Speter/** Resolve the true case of existing directories and file elements 308251875Speter * of addpath, (resolving any aliases on Win32) and append a proper 309251875Speter * trailing slash if a directory 310251875Speter */ 311251875Speter#define APR_FILEPATH_TRUENAME 0x20 312251875Speter 313251875Speter/** 314251875Speter * Extract the rootpath from the given filepath 315251875Speter * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE 316251875Speter * @param filepath the pathname to parse for its root component 317251875Speter * @param flags the desired rules to apply, from 318251875Speter * <PRE> 319266735Speter * APR_FILEPATH_NATIVE Use native path separators (e.g. '\' on Win32) 320251875Speter * APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper 321251875Speter * </PRE> 322251875Speter * @param p the pool to allocate the new path string from 323251875Speter * @remark on return, filepath points to the first non-root character in the 324251875Speter * given filepath. In the simplest example, given a filepath of "/foo", 325251875Speter * returns the rootpath of "/" and filepath points at "foo". This is far 326251875Speter * more complex on other platforms, which will canonicalize the root form 327251875Speter * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also 328251875Speter * test for the validity of that root (e.g., that a drive d:/ or network 329251875Speter * share //machine/foovol/). 330251875Speter * The function returns APR_ERELATIVE if filepath isn't rooted (an 331266735Speter * error), APR_EINCOMPLETE if the root path is ambiguous (but potentially 332251875Speter * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify 333251875Speter * the drive letter), or APR_EBADPATH if the root is simply invalid. 334251875Speter * APR_SUCCESS is returned if filepath is an absolute path. 335251875Speter */ 336251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 337251875Speter const char **filepath, 338251875Speter apr_int32_t flags, 339251875Speter apr_pool_t *p); 340251875Speter 341251875Speter/** 342251875Speter * Merge additional file path onto the previously processed rootpath 343251875Speter * @param newpath the merged paths returned 344251875Speter * @param rootpath the root file path (NULL uses the current working path) 345251875Speter * @param addpath the path to add to the root path 346251875Speter * @param flags the desired APR_FILEPATH_ rules to apply when merging 347251875Speter * @param p the pool to allocate the new path string from 348251875Speter * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 349251875Speter * contains wildcard characters ('*', '?') on platforms that don't support 350251875Speter * such characters within filenames, the paths will be merged, but the 351251875Speter * result code will be APR_EPATHWILD, and all further segments will not 352251875Speter * reflect the true filenames including the wildcard and following segments. 353251875Speter */ 354251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 355251875Speter const char *rootpath, 356251875Speter const char *addpath, 357251875Speter apr_int32_t flags, 358251875Speter apr_pool_t *p); 359251875Speter 360251875Speter/** 361251875Speter * Split a search path into separate components 362251875Speter * @param pathelts the returned components of the search path 363251875Speter * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>) 364251875Speter * @param p the pool to allocate the array and path components from 365266735Speter * @remark empty path components do not become part of @a pathelts. 366251875Speter * @remark the path separator in @a liststr is system specific; 367251875Speter * e.g., ':' on Unix, ';' on Windows, etc. 368251875Speter */ 369251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts, 370251875Speter const char *liststr, 371251875Speter apr_pool_t *p); 372251875Speter 373251875Speter/** 374251875Speter * Merge a list of search path components into a single search path 375251875Speter * @param liststr the returned search path; may be NULL if @a pathelts is empty 376251875Speter * @param pathelts the components of the search path 377251875Speter * @param p the pool to allocate the search path from 378251875Speter * @remark emtpy strings in the source array are ignored. 379251875Speter * @remark the path separator in @a liststr is system specific; 380251875Speter * e.g., ':' on Unix, ';' on Windows, etc. 381251875Speter */ 382251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr, 383251875Speter apr_array_header_t *pathelts, 384251875Speter apr_pool_t *p); 385251875Speter 386251875Speter/** 387251875Speter * Return the default file path (for relative file names) 388251875Speter * @param path the default path string returned 389251875Speter * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the 390251875Speter * default file path in os-native format. 391251875Speter * @param p the pool to allocate the default path string from 392251875Speter */ 393251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags, 394251875Speter apr_pool_t *p); 395251875Speter 396251875Speter/** 397251875Speter * Set the default file path (for relative file names) 398251875Speter * @param path the default path returned 399251875Speter * @param p the pool to allocate any working storage 400251875Speter */ 401251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); 402251875Speter 403251875Speter/** The FilePath character encoding is unknown */ 404251875Speter#define APR_FILEPATH_ENCODING_UNKNOWN 0 405251875Speter 406251875Speter/** The FilePath character encoding is locale-dependent */ 407251875Speter#define APR_FILEPATH_ENCODING_LOCALE 1 408251875Speter 409251875Speter/** The FilePath character encoding is UTF-8 */ 410251875Speter#define APR_FILEPATH_ENCODING_UTF8 2 411251875Speter 412251875Speter/** 413251875Speter * Determine the encoding used internally by the FilePath functions 414251875Speter * @param style points to a variable which receives the encoding style flag 415251875Speter * @param p the pool to allocate any working storage 416362181Sdim * @remark Use apr_os_locale_encoding() and/or apr_os_default_encoding() 417251875Speter * to get the name of the path encoding if it's not UTF-8. 418251875Speter */ 419251875SpeterAPR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); 420251875Speter/** @} */ 421251875Speter 422251875Speter/** @} */ 423251875Speter 424251875Speter#ifdef __cplusplus 425251875Speter} 426251875Speter#endif 427251875Speter 428251875Speter#endif /* ! APR_FILE_INFO_H */ 429