00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_FILE_INFO_H 00018 #define APR_FILE_INFO_H 00019 00020 /** 00021 * @file apr_file_info.h 00022 * @brief APR File Information 00023 */ 00024 00025 #include "apr.h" 00026 #include "apr_user.h" 00027 #include "apr_pools.h" 00028 #include "apr_tables.h" 00029 #include "apr_time.h" 00030 #include "apr_errno.h" 00031 00032 #if APR_HAVE_SYS_UIO_H 00033 #include <sys/uio.h> 00034 #endif 00035 00036 #ifdef __cplusplus 00037 extern "C" { 00038 #endif /* __cplusplus */ 00039 00040 /** 00041 * @defgroup apr_file_info File Information 00042 * @ingroup APR 00043 * @{ 00044 */ 00045 00046 /* Many applications use the type member to determine the 00047 * existance of a file or initialization of the file info, 00048 * so the APR_NOFILE value must be distinct from APR_UNKFILE. 00049 */ 00050 00051 /** apr_filetype_e values for the filetype member of the 00052 * apr_file_info_t structure 00053 * @warning: Not all of the filetypes below can be determined. 00054 * For example, a given platform might not correctly report 00055 * a socket descriptor as APR_SOCK if that type isn't 00056 * well-identified on that platform. In such cases where 00057 * a filetype exists but cannot be described by the recognized 00058 * flags below, the filetype will be APR_UNKFILE. If the 00059 * filetype member is not determined, the type will be APR_NOFILE. 00060 */ 00061 00062 typedef enum { 00063 APR_NOFILE = 0, /**< no file type determined */ 00064 APR_REG, /**< a regular file */ 00065 APR_DIR, /**< a directory */ 00066 APR_CHR, /**< a character device */ 00067 APR_BLK, /**< a block device */ 00068 APR_PIPE, /**< a FIFO / pipe */ 00069 APR_LNK, /**< a symbolic link */ 00070 APR_SOCK, /**< a [unix domain] socket */ 00071 APR_UNKFILE = 127 /**< a file of some other unknown type */ 00072 } apr_filetype_e; 00073 00074 /** 00075 * @defgroup apr_file_permissions File Permissions flags 00076 * @{ 00077 */ 00078 00079 #define APR_FPROT_USETID 0x8000 /**< Set user id */ 00080 #define APR_FPROT_UREAD 0x0400 /**< Read by user */ 00081 #define APR_FPROT_UWRITE 0x0200 /**< Write by user */ 00082 #define APR_FPROT_UEXECUTE 0x0100 /**< Execute by user */ 00083 00084 #define APR_FPROT_GSETID 0x4000 /**< Set group id */ 00085 #define APR_FPROT_GREAD 0x0040 /**< Read by group */ 00086 #define APR_FPROT_GWRITE 0x0020 /**< Write by group */ 00087 #define APR_FPROT_GEXECUTE 0x0010 /**< Execute by group */ 00088 00089 #define APR_FPROT_WSTICKY 0x2000 /**< Sticky bit */ 00090 #define APR_FPROT_WREAD 0x0004 /**< Read by others */ 00091 #define APR_FPROT_WWRITE 0x0002 /**< Write by others */ 00092 #define APR_FPROT_WEXECUTE 0x0001 /**< Execute by others */ 00093 00094 #define APR_FPROT_OS_DEFAULT 0x0FFF /**< use OS's default permissions */ 00095 00096 /* additional permission flags for apr_file_copy and apr_file_append */ 00097 #define APR_FPROT_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */ 00098 00099 /* backcompat */ 00100 #define APR_USETID APR_FPROT_USETID /**< @deprecated @see APR_FPROT_USETID */ 00101 #define APR_UREAD APR_FPROT_UREAD /**< @deprecated @see APR_FPROT_UREAD */ 00102 #define APR_UWRITE APR_FPROT_UWRITE /**< @deprecated @see APR_FPROT_UWRITE */ 00103 #define APR_UEXECUTE APR_FPROT_UEXECUTE /**< @deprecated @see APR_FPROT_UEXECUTE */ 00104 #define APR_GSETID APR_FPROT_GSETID /**< @deprecated @see APR_FPROT_GSETID */ 00105 #define APR_GREAD APR_FPROT_GREAD /**< @deprecated @see APR_FPROT_GREAD */ 00106 #define APR_GWRITE APR_FPROT_GWRITE /**< @deprecated @see APR_FPROT_GWRITE */ 00107 #define APR_GEXECUTE APR_FPROT_GEXECUTE /**< @deprecated @see APR_FPROT_GEXECUTE */ 00108 #define APR_WSTICKY APR_FPROT_WSTICKY /**< @deprecated @see APR_FPROT_WSTICKY */ 00109 #define APR_WREAD APR_FPROT_WREAD /**< @deprecated @see APR_FPROT_WREAD */ 00110 #define APR_WWRITE APR_FPROT_WWRITE /**< @deprecated @see APR_FPROT_WWRITE */ 00111 #define APR_WEXECUTE APR_FPROT_WEXECUTE /**< @deprecated @see APR_FPROT_WEXECUTE */ 00112 #define APR_OS_DEFAULT APR_FPROT_OS_DEFAULT /**< @deprecated @see APR_FPROT_OS_DEFAULT */ 00113 #define APR_FILE_SOURCE_PERMS APR_FPROT_FILE_SOURCE_PERMS /**< @deprecated @see APR_FPROT_FILE_SOURCE_PERMS */ 00114 00115 /** @} */ 00116 00117 00118 /** 00119 * Structure for referencing directories. 00120 */ 00121 typedef struct apr_dir_t apr_dir_t; 00122 /** 00123 * Structure for determining file permissions. 00124 */ 00125 typedef apr_int32_t apr_fileperms_t; 00126 #if (defined WIN32) || (defined NETWARE) 00127 /** 00128 * Structure for determining the inode of the file. 00129 */ 00130 typedef apr_uint64_t apr_ino_t; 00131 /** 00132 * Structure for determining the device the file is on. 00133 */ 00134 typedef apr_uint32_t apr_dev_t; 00135 #else 00136 /** The inode of the file. */ 00137 /* NOTE: this should be ino_t, except that in that case the ABI changes 00138 * if you compile an app with LFS defines. */ 00139 #if defined(__alpha__) || defined(__FreeBSD_kernel__) 00140 typedef unsigned int apr_ino_t; 00141 #else 00142 typedef unsigned long int apr_ino_t; 00143 #endif 00144 /** 00145 * Structure for determining the device the file is on. 00146 */ 00147 typedef dev_t apr_dev_t; 00148 #endif 00149 00150 /** 00151 * @defgroup apr_file_stat Stat Functions 00152 * @{ 00153 */ 00154 /** file info structure */ 00155 typedef struct apr_finfo_t apr_finfo_t; 00156 00157 #define APR_FINFO_LINK 0x00000001 /**< Stat the link not the file itself if it is a link */ 00158 #define APR_FINFO_MTIME 0x00000010 /**< Modification Time */ 00159 #define APR_FINFO_CTIME 0x00000020 /**< Creation or inode-changed time */ 00160 #define APR_FINFO_ATIME 0x00000040 /**< Access Time */ 00161 #define APR_FINFO_SIZE 0x00000100 /**< Size of the file */ 00162 #define APR_FINFO_CSIZE 0x00000200 /**< Storage size consumed by the file */ 00163 #define APR_FINFO_DEV 0x00001000 /**< Device */ 00164 #define APR_FINFO_INODE 0x00002000 /**< Inode */ 00165 #define APR_FINFO_NLINK 0x00004000 /**< Number of links */ 00166 #define APR_FINFO_TYPE 0x00008000 /**< Type */ 00167 #define APR_FINFO_USER 0x00010000 /**< User */ 00168 #define APR_FINFO_GROUP 0x00020000 /**< Group */ 00169 #define APR_FINFO_UPROT 0x00100000 /**< User protection bits */ 00170 #define APR_FINFO_GPROT 0x00200000 /**< Group protection bits */ 00171 #define APR_FINFO_WPROT 0x00400000 /**< World protection bits */ 00172 #define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */ 00173 #define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */ 00174 00175 #define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */ 00176 #define APR_FINFO_IDENT 0x00003000 /**< dev and inode */ 00177 #define APR_FINFO_OWNER 0x00030000 /**< user and group */ 00178 #define APR_FINFO_PROT 0x00700000 /**< all protections */ 00179 #define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */ 00180 #define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */ 00181 00182 /** 00183 * The file information structure. This is analogous to the POSIX 00184 * stat structure. 00185 */ 00186 struct apr_finfo_t { 00187 /** Allocates memory and closes lingering handles in the specified pool */ 00188 apr_pool_t *pool; 00189 /** The bitmask describing valid fields of this apr_finfo_t structure 00190 * including all available 'wanted' fields and potentially more */ 00191 apr_int32_t valid; 00192 /** The access permissions of the file. Mimics Unix access rights. */ 00193 apr_fileperms_t protection; 00194 /** The type of file. One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 00195 * APR_LNK or APR_SOCK. If the type is undetermined, the value is APR_NOFILE. 00196 * If the type cannot be determined, the value is APR_UNKFILE. 00197 */ 00198 apr_filetype_e filetype; 00199 /** The user id that owns the file */ 00200 apr_uid_t user; 00201 /** The group id that owns the file */ 00202 apr_gid_t group; 00203 /** The inode of the file. */ 00204 apr_ino_t inode; 00205 /** The id of the device the file is on. */ 00206 apr_dev_t device; 00207 /** The number of hard links to the file. */ 00208 apr_int32_t nlink; 00209 /** The size of the file */ 00210 apr_off_t size; 00211 /** The storage size consumed by the file */ 00212 apr_off_t csize; 00213 /** The time the file was last accessed */ 00214 apr_time_t atime; 00215 /** The time the file was last modified */ 00216 apr_time_t mtime; 00217 /** The time the file was created, or the inode was last changed */ 00218 apr_time_t ctime; 00219 /** The pathname of the file (possibly unrooted) */ 00220 const char *fname; 00221 /** The file's name (no path) in filesystem case */ 00222 const char *name; 00223 /** The file's handle, if accessed (can be submitted to apr_duphandle) */ 00224 struct apr_file_t *filehand; 00225 }; 00226 00227 /** 00228 * get the specified file's stats. The file is specified by filename, 00229 * instead of using a pre-opened file. 00230 * @param finfo Where to store the information about the file, which is 00231 * never touched if the call fails. 00232 * @param fname The name of the file to stat. 00233 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 00234 values 00235 * @param pool the pool to use to allocate the new file. 00236 * 00237 * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 00238 * not be filled in, and you need to check the @c finfo->valid bitmask 00239 * to verify that what you're looking for is there. 00240 */ 00241 APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname, 00242 apr_int32_t wanted, apr_pool_t *pool); 00243 00244 /** @} */ 00245 /** 00246 * @defgroup apr_dir Directory Manipulation Functions 00247 * @{ 00248 */ 00249 00250 /** 00251 * Open the specified directory. 00252 * @param new_dir The opened directory descriptor. 00253 * @param dirname The full path to the directory (use / on all systems) 00254 * @param pool The pool to use. 00255 */ 00256 APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 00257 const char *dirname, 00258 apr_pool_t *pool); 00259 00260 /** 00261 * close the specified directory. 00262 * @param thedir the directory descriptor to close. 00263 */ 00264 APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir); 00265 00266 /** 00267 * Read the next entry from the specified directory. 00268 * @param finfo the file info structure and filled in by apr_dir_read 00269 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ 00270 values 00271 * @param thedir the directory descriptor returned from apr_dir_open 00272 * @remark No ordering is guaranteed for the entries read. 00273 * 00274 * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may 00275 * not be filled in, and you need to check the @c finfo->valid bitmask 00276 * to verify that what you're looking for is there. 00277 */ 00278 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted, 00279 apr_dir_t *thedir); 00280 00281 /** 00282 * Rewind the directory to the first entry. 00283 * @param thedir the directory descriptor to rewind. 00284 */ 00285 APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); 00286 /** @} */ 00287 00288 /** 00289 * @defgroup apr_filepath Filepath Manipulation Functions 00290 * @{ 00291 */ 00292 00293 /** Cause apr_filepath_merge to fail if addpath is above rootpath */ 00294 #define APR_FILEPATH_NOTABOVEROOT 0x01 00295 00296 /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */ 00297 #define APR_FILEPATH_SECUREROOTTEST 0x02 00298 00299 /** Cause apr_filepath_merge to fail if addpath is above rootpath, 00300 * even given a rootpath /foo/bar and an addpath ../bar/bash 00301 */ 00302 #define APR_FILEPATH_SECUREROOT 0x03 00303 00304 /** Fail apr_filepath_merge if the merged path is relative */ 00305 #define APR_FILEPATH_NOTRELATIVE 0x04 00306 00307 /** Fail apr_filepath_merge if the merged path is absolute */ 00308 #define APR_FILEPATH_NOTABSOLUTE 0x08 00309 00310 /** Return the file system's native path format (e.g. path delimiters 00311 * of ':' on MacOS9, '\' on Win32, etc.) */ 00312 #define APR_FILEPATH_NATIVE 0x10 00313 00314 /** Resolve the true case of existing directories and file elements 00315 * of addpath, (resolving any aliases on Win32) and append a proper 00316 * trailing slash if a directory 00317 */ 00318 #define APR_FILEPATH_TRUENAME 0x20 00319 00320 /** 00321 * Extract the rootpath from the given filepath 00322 * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE 00323 * @param filepath the pathname to parse for its root component 00324 * @param flags the desired rules to apply, from 00325 * <PRE> 00326 * APR_FILEPATH_NATIVE Use native path seperators (e.g. '\' on Win32) 00327 * APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper 00328 * </PRE> 00329 * @param p the pool to allocate the new path string from 00330 * @remark on return, filepath points to the first non-root character in the 00331 * given filepath. In the simplest example, given a filepath of "/foo", 00332 * returns the rootpath of "/" and filepath points at "foo". This is far 00333 * more complex on other platforms, which will canonicalize the root form 00334 * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also 00335 * test for the validity of that root (e.g., that a drive d:/ or network 00336 * share //machine/foovol/). 00337 * The function returns APR_ERELATIVE if filepath isn't rooted (an 00338 * error), APR_EINCOMPLETE if the root path is ambigious (but potentially 00339 * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify 00340 * the drive letter), or APR_EBADPATH if the root is simply invalid. 00341 * APR_SUCCESS is returned if filepath is an absolute path. 00342 */ 00343 APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 00344 const char **filepath, 00345 apr_int32_t flags, 00346 apr_pool_t *p); 00347 00348 /** 00349 * Merge additional file path onto the previously processed rootpath 00350 * @param newpath the merged paths returned 00351 * @param rootpath the root file path (NULL uses the current working path) 00352 * @param addpath the path to add to the root path 00353 * @param flags the desired APR_FILEPATH_ rules to apply when merging 00354 * @param p the pool to allocate the new path string from 00355 * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 00356 * contains wildcard characters ('*', '?') on platforms that don't support 00357 * such characters within filenames, the paths will be merged, but the 00358 * result code will be APR_EPATHWILD, and all further segments will not 00359 * reflect the true filenames including the wildcard and following segments. 00360 */ 00361 APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 00362 const char *rootpath, 00363 const char *addpath, 00364 apr_int32_t flags, 00365 apr_pool_t *p); 00366 00367 /** 00368 * Split a search path into separate components 00369 * @param pathelts the returned components of the search path 00370 * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>) 00371 * @param p the pool to allocate the array and path components from 00372 * @remark empty path componenta do not become part of @a pathelts. 00373 * @remark the path separator in @a liststr is system specific; 00374 * e.g., ':' on Unix, ';' on Windows, etc. 00375 */ 00376 APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts, 00377 const char *liststr, 00378 apr_pool_t *p); 00379 00380 /** 00381 * Merge a list of search path components into a single search path 00382 * @param liststr the returned search path; may be NULL if @a pathelts is empty 00383 * @param pathelts the components of the search path 00384 * @param p the pool to allocate the search path from 00385 * @remark emtpy strings in the source array are ignored. 00386 * @remark the path separator in @a liststr is system specific; 00387 * e.g., ':' on Unix, ';' on Windows, etc. 00388 */ 00389 APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr, 00390 apr_array_header_t *pathelts, 00391 apr_pool_t *p); 00392 00393 /** 00394 * Return the default file path (for relative file names) 00395 * @param path the default path string returned 00396 * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the 00397 * default file path in os-native format. 00398 * @param p the pool to allocate the default path string from 00399 */ 00400 APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags, 00401 apr_pool_t *p); 00402 00403 /** 00404 * Set the default file path (for relative file names) 00405 * @param path the default path returned 00406 * @param p the pool to allocate any working storage 00407 */ 00408 APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); 00409 00410 /** The FilePath character encoding is unknown */ 00411 #define APR_FILEPATH_ENCODING_UNKNOWN 0 00412 00413 /** The FilePath character encoding is locale-dependent */ 00414 #define APR_FILEPATH_ENCODING_LOCALE 1 00415 00416 /** The FilePath character encoding is UTF-8 */ 00417 #define APR_FILEPATH_ENCODING_UTF8 2 00418 00419 /** 00420 * Determine the encoding used internally by the FilePath functions 00421 * @param style points to a variable which receives the encoding style flag 00422 * @param p the pool to allocate any working storage 00423 * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding 00424 * to get the name of the path encoding if it's not UTF-8. 00425 */ 00426 APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); 00427 /** @} */ 00428 00429 /** @} */ 00430 00431 #ifdef __cplusplus 00432 } 00433 #endif 00434 00435 #endif /* ! APR_FILE_INFO_H */