apr_file_info.h

Go to the documentation of this file.
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 device the file is on.
00129  */
00130 typedef apr_uint32_t              apr_dev_t;
00131 #else
00132 /**
00133  * Structure for determining the device the file is on.
00134  */
00135 typedef dev_t                     apr_dev_t;
00136 #endif
00137 
00138 /* See apr.h.in (.hw or .hnw) for the declaration of apr_ino_t,
00139  * but as we don't want to break users who author for 1.2.x, we
00140  * can't present this type until they have included apr_file_info.h
00141  * where it was originally declared in release 1.2.0.
00142  * Unmask it for use here.
00143  */
00144 #undef apr_ino_t
00145 
00146 /**
00147  * @defgroup apr_file_stat Stat Functions
00148  * @{
00149  */
00150 /** file info structure */
00151 typedef struct apr_finfo_t        apr_finfo_t;
00152 
00153 #define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file itself if it is a link */
00154 #define APR_FINFO_MTIME  0x00000010 /**< Modification Time */
00155 #define APR_FINFO_CTIME  0x00000020 /**< Creation or inode-changed time */
00156 #define APR_FINFO_ATIME  0x00000040 /**< Access Time */
00157 #define APR_FINFO_SIZE   0x00000100 /**< Size of the file */
00158 #define APR_FINFO_CSIZE  0x00000200 /**< Storage size consumed by the file */
00159 #define APR_FINFO_DEV    0x00001000 /**< Device */
00160 #define APR_FINFO_INODE  0x00002000 /**< Inode */
00161 #define APR_FINFO_NLINK  0x00004000 /**< Number of links */
00162 #define APR_FINFO_TYPE   0x00008000 /**< Type */
00163 #define APR_FINFO_USER   0x00010000 /**< User */
00164 #define APR_FINFO_GROUP  0x00020000 /**< Group */
00165 #define APR_FINFO_UPROT  0x00100000 /**< User protection bits */
00166 #define APR_FINFO_GPROT  0x00200000 /**< Group protection bits */
00167 #define APR_FINFO_WPROT  0x00400000 /**< World protection bits */
00168 #define APR_FINFO_ICASE  0x01000000 /**< if dev is case insensitive */
00169 #define APR_FINFO_NAME   0x02000000 /**< ->name in proper case */
00170 
00171 #define APR_FINFO_MIN    0x00008170 /**< type, mtime, ctime, atime, size */
00172 #define APR_FINFO_IDENT  0x00003000 /**< dev and inode */
00173 #define APR_FINFO_OWNER  0x00030000 /**< user and group */
00174 #define APR_FINFO_PROT   0x00700000 /**<  all protections */
00175 #define APR_FINFO_NORM   0x0073b170 /**<  an atomic unix apr_stat() */
00176 #define APR_FINFO_DIRENT 0x02000000 /**<  an atomic unix apr_dir_read() */
00177 
00178 /**
00179  * The file information structure.  This is analogous to the POSIX
00180  * stat structure.
00181  */
00182 struct apr_finfo_t {
00183     /** Allocates memory and closes lingering handles in the specified pool */
00184     apr_pool_t *pool;
00185     /** The bitmask describing valid fields of this apr_finfo_t structure 
00186      *  including all available 'wanted' fields and potentially more */
00187     apr_int32_t valid;
00188     /** The access permissions of the file.  Mimics Unix access rights. */
00189     apr_fileperms_t protection;
00190     /** The type of file.  One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 
00191      * APR_LNK or APR_SOCK.  If the type is undetermined, the value is APR_NOFILE.
00192      * If the type cannot be determined, the value is APR_UNKFILE.
00193      */
00194     apr_filetype_e filetype;
00195     /** The user id that owns the file */
00196     apr_uid_t user;
00197     /** The group id that owns the file */
00198     apr_gid_t group;
00199     /** The inode of the file. */
00200     apr_ino_t inode;
00201     /** The id of the device the file is on. */
00202     apr_dev_t device;
00203     /** The number of hard links to the file. */
00204     apr_int32_t nlink;
00205     /** The size of the file */
00206     apr_off_t size;
00207     /** The storage size consumed by the file */
00208     apr_off_t csize;
00209     /** The time the file was last accessed */
00210     apr_time_t atime;
00211     /** The time the file was last modified */
00212     apr_time_t mtime;
00213     /** The time the file was created, or the inode was last changed */
00214     apr_time_t ctime;
00215     /** The pathname of the file (possibly unrooted) */
00216     const char *fname;
00217     /** The file's name (no path) in filesystem case */
00218     const char *name;
00219     /** The file's handle, if accessed (can be submitted to apr_duphandle) */
00220     struct apr_file_t *filehand;
00221 };
00222 
00223 /**
00224  * get the specified file's stats.  The file is specified by filename, 
00225  * instead of using a pre-opened file.
00226  * @param finfo Where to store the information about the file, which is
00227  * never touched if the call fails.
00228  * @param fname The name of the file to stat.
00229  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
00230                  values 
00231  * @param pool the pool to use to allocate the new file. 
00232  *
00233  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
00234  *       not be filled in, and you need to check the @c finfo->valid bitmask
00235  *       to verify that what you're looking for is there.
00236  */ 
00237 APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
00238                                    apr_int32_t wanted, apr_pool_t *pool);
00239 
00240 /** @} */
00241 /**
00242  * @defgroup apr_dir Directory Manipulation Functions
00243  * @{
00244  */
00245 
00246 /**
00247  * Open the specified directory.
00248  * @param new_dir The opened directory descriptor.
00249  * @param dirname The full path to the directory (use / on all systems)
00250  * @param pool The pool to use.
00251  */                        
00252 APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 
00253                                        const char *dirname, 
00254                                        apr_pool_t *pool);
00255 
00256 /**
00257  * close the specified directory. 
00258  * @param thedir the directory descriptor to close.
00259  */                        
00260 APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
00261 
00262 /**
00263  * Read the next entry from the specified directory. 
00264  * @param finfo the file info structure and filled in by apr_dir_read
00265  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
00266                  values 
00267  * @param thedir the directory descriptor returned from apr_dir_open
00268  * @remark No ordering is guaranteed for the entries read.
00269  *
00270  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
00271  *       not be filled in, and you need to check the @c finfo->valid bitmask
00272  *       to verify that what you're looking for is there.
00273  */                        
00274 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
00275                                        apr_dir_t *thedir);
00276 
00277 /**
00278  * Rewind the directory to the first entry.
00279  * @param thedir the directory descriptor to rewind.
00280  */                        
00281 APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
00282 /** @} */
00283 
00284 /**
00285  * @defgroup apr_filepath Filepath Manipulation Functions
00286  * @{
00287  */
00288 
00289 /** Cause apr_filepath_merge to fail if addpath is above rootpath */
00290 #define APR_FILEPATH_NOTABOVEROOT   0x01
00291 
00292 /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
00293 #define APR_FILEPATH_SECUREROOTTEST 0x02
00294 
00295 /** Cause apr_filepath_merge to fail if addpath is above rootpath,
00296  * even given a rootpath /foo/bar and an addpath ../bar/bash
00297  */
00298 #define APR_FILEPATH_SECUREROOT     0x03
00299 
00300 /** Fail apr_filepath_merge if the merged path is relative */
00301 #define APR_FILEPATH_NOTRELATIVE    0x04
00302 
00303 /** Fail apr_filepath_merge if the merged path is absolute */
00304 #define APR_FILEPATH_NOTABSOLUTE    0x08
00305 
00306 /** Return the file system's native path format (e.g. path delimiters
00307  * of ':' on MacOS9, '\' on Win32, etc.) */
00308 #define APR_FILEPATH_NATIVE         0x10
00309 
00310 /** Resolve the true case of existing directories and file elements
00311  * of addpath, (resolving any aliases on Win32) and append a proper 
00312  * trailing slash if a directory
00313  */
00314 #define APR_FILEPATH_TRUENAME       0x20
00315 
00316 /**
00317  * Extract the rootpath from the given filepath
00318  * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
00319  * @param filepath the pathname to parse for its root component
00320  * @param flags the desired rules to apply, from
00321  * <PRE>
00322  *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
00323  *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
00324  * </PRE>
00325  * @param p the pool to allocate the new path string from
00326  * @remark on return, filepath points to the first non-root character in the
00327  * given filepath.  In the simplest example, given a filepath of "/foo", 
00328  * returns the rootpath of "/" and filepath points at "foo".  This is far 
00329  * more complex on other platforms, which will canonicalize the root form
00330  * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
00331  * test for the validity of that root (e.g., that a drive d:/ or network 
00332  * share //machine/foovol/). 
00333  * The function returns APR_ERELATIVE if filepath isn't rooted (an
00334  * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
00335  * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
00336  * the drive letter), or APR_EBADPATH if the root is simply invalid.
00337  * APR_SUCCESS is returned if filepath is an absolute path.
00338  */
00339 APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 
00340                                             const char **filepath, 
00341                                             apr_int32_t flags,
00342                                             apr_pool_t *p);
00343 
00344 /**
00345  * Merge additional file path onto the previously processed rootpath
00346  * @param newpath the merged paths returned
00347  * @param rootpath the root file path (NULL uses the current working path)
00348  * @param addpath the path to add to the root path
00349  * @param flags the desired APR_FILEPATH_ rules to apply when merging
00350  * @param p the pool to allocate the new path string from
00351  * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 
00352  * contains wildcard characters ('*', '?') on platforms that don't support 
00353  * such characters within filenames, the paths will be merged, but the 
00354  * result code will be APR_EPATHWILD, and all further segments will not
00355  * reflect the true filenames including the wildcard and following segments.
00356  */                        
00357 APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 
00358                                              const char *rootpath,
00359                                              const char *addpath, 
00360                                              apr_int32_t flags,
00361                                              apr_pool_t *p);
00362 
00363 /**
00364  * Split a search path into separate components
00365  * @param pathelts the returned components of the search path
00366  * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
00367  * @param p the pool to allocate the array and path components from
00368  * @remark empty path componenta do not become part of @a pathelts.
00369  * @remark the path separator in @a liststr is system specific;
00370  * e.g., ':' on Unix, ';' on Windows, etc.
00371  */
00372 APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts,
00373                                                   const char *liststr,
00374                                                   apr_pool_t *p);
00375 
00376 /**
00377  * Merge a list of search path components into a single search path
00378  * @param liststr the returned search path; may be NULL if @a pathelts is empty
00379  * @param pathelts the components of the search path
00380  * @param p the pool to allocate the search path from
00381  * @remark emtpy strings in the source array are ignored.
00382  * @remark the path separator in @a liststr is system specific;
00383  * e.g., ':' on Unix, ';' on Windows, etc.
00384  */
00385 APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr,
00386                                                   apr_array_header_t *pathelts,
00387                                                   apr_pool_t *p);
00388 
00389 /**
00390  * Return the default file path (for relative file names)
00391  * @param path the default path string returned
00392  * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
00393  *              default file path in os-native format.
00394  * @param p the pool to allocate the default path string from
00395  */
00396 APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
00397                                            apr_pool_t *p);
00398 
00399 /**
00400  * Set the default file path (for relative file names)
00401  * @param path the default path returned
00402  * @param p the pool to allocate any working storage
00403  */
00404 APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
00405 
00406 /** The FilePath character encoding is unknown */
00407 #define APR_FILEPATH_ENCODING_UNKNOWN  0
00408 
00409 /** The FilePath character encoding is locale-dependent */
00410 #define APR_FILEPATH_ENCODING_LOCALE   1
00411 
00412 /** The FilePath character encoding is UTF-8 */
00413 #define APR_FILEPATH_ENCODING_UTF8     2
00414 
00415 /**
00416  * Determine the encoding used internally by the FilePath functions
00417  * @param style points to a variable which receives the encoding style flag
00418  * @param p the pool to allocate any working storage
00419  * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding
00420  * to get the name of the path encoding if it's not UTF-8.
00421  */
00422 APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p);
00423 /** @} */
00424 
00425 /** @} */
00426 
00427 #ifdef __cplusplus
00428 }
00429 #endif
00430 
00431 #endif  /* ! APR_FILE_INFO_H */

Generated on Mon Nov 26 11:23:52 2007 for Apache Portable Runtime by  doxygen 1.5.2