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