home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Servidores / apache_2.2.8-win32-x86-no_ssl.msi / Data1.cab / _1C1B99FEC02732D2856010798CB1A356 < prev    next >
Text File  |  2007-10-23  |  18KB  |  432 lines
  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. /* See apr.h.in (.hw or .hnw) for the declaration of apr_ino_t,
  139.  * but as we don't want to break users who author for 1.2.x, we
  140.  * can't present this type until they have included apr_file_info.h
  141.  * where it was originally declared in release 1.2.0.
  142.  * Unmask it for use here.
  143.  */
  144. #undef apr_ino_t
  145.  
  146. /**
  147.  * @defgroup apr_file_stat Stat Functions
  148.  * @{
  149.  */
  150. /** file info structure */
  151. typedef struct apr_finfo_t        apr_finfo_t;
  152.  
  153. #define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file itself if it is a link */
  154. #define APR_FINFO_MTIME  0x00000010 /**< Modification Time */
  155. #define APR_FINFO_CTIME  0x00000020 /**< Creation or inode-changed time */
  156. #define APR_FINFO_ATIME  0x00000040 /**< Access Time */
  157. #define APR_FINFO_SIZE   0x00000100 /**< Size of the file */
  158. #define APR_FINFO_CSIZE  0x00000200 /**< Storage size consumed by the file */
  159. #define APR_FINFO_DEV    0x00001000 /**< Device */
  160. #define APR_FINFO_INODE  0x00002000 /**< Inode */
  161. #define APR_FINFO_NLINK  0x00004000 /**< Number of links */
  162. #define APR_FINFO_TYPE   0x00008000 /**< Type */
  163. #define APR_FINFO_USER   0x00010000 /**< User */
  164. #define APR_FINFO_GROUP  0x00020000 /**< Group */
  165. #define APR_FINFO_UPROT  0x00100000 /**< User protection bits */
  166. #define APR_FINFO_GPROT  0x00200000 /**< Group protection bits */
  167. #define APR_FINFO_WPROT  0x00400000 /**< World protection bits */
  168. #define APR_FINFO_ICASE  0x01000000 /**< if dev is case insensitive */
  169. #define APR_FINFO_NAME   0x02000000 /**< ->name in proper case */
  170.  
  171. #define APR_FINFO_MIN    0x00008170 /**< type, mtime, ctime, atime, size */
  172. #define APR_FINFO_IDENT  0x00003000 /**< dev and inode */
  173. #define APR_FINFO_OWNER  0x00030000 /**< user and group */
  174. #define APR_FINFO_PROT   0x00700000 /**<  all protections */
  175. #define APR_FINFO_NORM   0x0073b170 /**<  an atomic unix apr_stat() */
  176. #define APR_FINFO_DIRENT 0x02000000 /**<  an atomic unix apr_dir_read() */
  177.  
  178. /**
  179.  * The file information structure.  This is analogous to the POSIX
  180.  * stat structure.
  181.  */
  182. struct apr_finfo_t {
  183.     /** Allocates memory and closes lingering handles in the specified pool */
  184.     apr_pool_t *pool;
  185.     /** The bitmask describing valid fields of this apr_finfo_t structure 
  186.      *  including all available 'wanted' fields and potentially more */
  187.     apr_int32_t valid;
  188.     /** The access permissions of the file.  Mimics Unix access rights. */
  189.     apr_fileperms_t protection;
  190.     /** The type of file.  One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 
  191.      * APR_LNK or APR_SOCK.  If the type is undetermined, the value is APR_NOFILE.
  192.      * If the type cannot be determined, the value is APR_UNKFILE.
  193.      */
  194.     apr_filetype_e filetype;
  195.     /** The user id that owns the file */
  196.     apr_uid_t user;
  197.     /** The group id that owns the file */
  198.     apr_gid_t group;
  199.     /** The inode of the file. */
  200.     apr_ino_t inode;
  201.     /** The id of the device the file is on. */
  202.     apr_dev_t device;
  203.     /** The number of hard links to the file. */
  204.     apr_int32_t nlink;
  205.     /** The size of the file */
  206.     apr_off_t size;
  207.     /** The storage size consumed by the file */
  208.     apr_off_t csize;
  209.     /** The time the file was last accessed */
  210.     apr_time_t atime;
  211.     /** The time the file was last modified */
  212.     apr_time_t mtime;
  213.     /** The time the file was created, or the inode was last changed */
  214.     apr_time_t ctime;
  215.     /** The pathname of the file (possibly unrooted) */
  216.     const char *fname;
  217.     /** The file's name (no path) in filesystem case */
  218.     const char *name;
  219.     /** The file's handle, if accessed (can be submitted to apr_duphandle) */
  220.     struct apr_file_t *filehand;
  221. };
  222.  
  223. /**
  224.  * get the specified file's stats.  The file is specified by filename, 
  225.  * instead of using a pre-opened file.
  226.  * @param finfo Where to store the information about the file, which is
  227.  * never touched if the call fails.
  228.  * @param fname The name of the file to stat.
  229.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
  230.                  values 
  231.  * @param pool the pool to use to allocate the new file. 
  232.  *
  233.  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
  234.  *       not be filled in, and you need to check the @c finfo->valid bitmask
  235.  *       to verify that what you're looking for is there.
  236.  */ 
  237. APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
  238.                                    apr_int32_t wanted, apr_pool_t *pool);
  239.  
  240. /** @} */
  241. /**
  242.  * @defgroup apr_dir Directory Manipulation Functions
  243.  * @{
  244.  */
  245.  
  246. /**
  247.  * Open the specified directory.
  248.  * @param new_dir The opened directory descriptor.
  249.  * @param dirname The full path to the directory (use / on all systems)
  250.  * @param pool The pool to use.
  251.  */                        
  252. APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 
  253.                                        const char *dirname, 
  254.                                        apr_pool_t *pool);
  255.  
  256. /**
  257.  * close the specified directory. 
  258.  * @param thedir the directory descriptor to close.
  259.  */                        
  260. APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
  261.  
  262. /**
  263.  * Read the next entry from the specified directory. 
  264.  * @param finfo the file info structure and filled in by apr_dir_read
  265.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
  266.                  values 
  267.  * @param thedir the directory descriptor returned from apr_dir_open
  268.  * @remark No ordering is guaranteed for the entries read.
  269.  *
  270.  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
  271.  *       not be filled in, and you need to check the @c finfo->valid bitmask
  272.  *       to verify that what you're looking for is there.
  273.  */                        
  274. APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
  275.                                        apr_dir_t *thedir);
  276.  
  277. /**
  278.  * Rewind the directory to the first entry.
  279.  * @param thedir the directory descriptor to rewind.
  280.  */                        
  281. APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
  282. /** @} */
  283.  
  284. /**
  285.  * @defgroup apr_filepath Filepath Manipulation Functions
  286.  * @{
  287.  */
  288.  
  289. /** Cause apr_filepath_merge to fail if addpath is above rootpath */
  290. #define APR_FILEPATH_NOTABOVEROOT   0x01
  291.  
  292. /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
  293. #define APR_FILEPATH_SECUREROOTTEST 0x02
  294.  
  295. /** Cause apr_filepath_merge to fail if addpath is above rootpath,
  296.  * even given a rootpath /foo/bar and an addpath ../bar/bash
  297.  */
  298. #define APR_FILEPATH_SECUREROOT     0x03
  299.  
  300. /** Fail apr_filepath_merge if the merged path is relative */
  301. #define APR_FILEPATH_NOTRELATIVE    0x04
  302.  
  303. /** Fail apr_filepath_merge if the merged path is absolute */
  304. #define APR_FILEPATH_NOTABSOLUTE    0x08
  305.  
  306. /** Return the file system's native path format (e.g. path delimiters
  307.  * of ':' on MacOS9, '\' on Win32, etc.) */
  308. #define APR_FILEPATH_NATIVE         0x10
  309.  
  310. /** Resolve the true case of existing directories and file elements
  311.  * of addpath, (resolving any aliases on Win32) and append a proper 
  312.  * trailing slash if a directory
  313.  */
  314. #define APR_FILEPATH_TRUENAME       0x20
  315.  
  316. /**
  317.  * Extract the rootpath from the given filepath
  318.  * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
  319.  * @param filepath the pathname to parse for its root component
  320.  * @param flags the desired rules to apply, from
  321.  * <PRE>
  322.  *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
  323.  *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
  324.  * </PRE>
  325.  * @param p the pool to allocate the new path string from
  326.  * @remark on return, filepath points to the first non-root character in the
  327.  * given filepath.  In the simplest example, given a filepath of "/foo", 
  328.  * returns the rootpath of "/" and filepath points at "foo".  This is far 
  329.  * more complex on other platforms, which will canonicalize the root form
  330.  * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
  331.  * test for the validity of that root (e.g., that a drive d:/ or network 
  332.  * share //machine/foovol/). 
  333.  * The function returns APR_ERELATIVE if filepath isn't rooted (an
  334.  * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
  335.  * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
  336.  * the drive letter), or APR_EBADPATH if the root is simply invalid.
  337.  * APR_SUCCESS is returned if filepath is an absolute path.
  338.  */
  339. APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 
  340.                                             const char **filepath, 
  341.                                             apr_int32_t flags,
  342.                                             apr_pool_t *p);
  343.  
  344. /**
  345.  * Merge additional file path onto the previously processed rootpath
  346.  * @param newpath the merged paths returned
  347.  * @param rootpath the root file path (NULL uses the current working path)
  348.  * @param addpath the path to add to the root path
  349.  * @param flags the desired APR_FILEPATH_ rules to apply when merging
  350.  * @param p the pool to allocate the new path string from
  351.  * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 
  352.  * contains wildcard characters ('*', '?') on platforms that don't support 
  353.  * such characters within filenames, the paths will be merged, but the 
  354.  * result code will be APR_EPATHWILD, and all further segments will not
  355.  * reflect the true filenames including the wildcard and following segments.
  356.  */                        
  357. APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 
  358.                                              const char *rootpath,
  359.                                              const char *addpath, 
  360.                                              apr_int32_t flags,
  361.                                              apr_pool_t *p);
  362.  
  363. /**
  364.  * Split a search path into separate components
  365.  * @param pathelts the returned components of the search path
  366.  * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
  367.  * @param p the pool to allocate the array and path components from
  368.  * @remark empty path componenta do not become part of @a pathelts.
  369.  * @remark the path separator in @a liststr is system specific;
  370.  * e.g., ':' on Unix, ';' on Windows, etc.
  371.  */
  372. APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts,
  373.                                                   const char *liststr,
  374.                                                   apr_pool_t *p);
  375.  
  376. /**
  377.  * Merge a list of search path components into a single search path
  378.  * @param liststr the returned search path; may be NULL if @a pathelts is empty
  379.  * @param pathelts the components of the search path
  380.  * @param p the pool to allocate the search path from
  381.  * @remark emtpy strings in the source array are ignored.
  382.  * @remark the path separator in @a liststr is system specific;
  383.  * e.g., ':' on Unix, ';' on Windows, etc.
  384.  */
  385. APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr,
  386.                                                   apr_array_header_t *pathelts,
  387.                                                   apr_pool_t *p);
  388.  
  389. /**
  390.  * Return the default file path (for relative file names)
  391.  * @param path the default path string returned
  392.  * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
  393.  *              default file path in os-native format.
  394.  * @param p the pool to allocate the default path string from
  395.  */
  396. APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
  397.                                            apr_pool_t *p);
  398.  
  399. /**
  400.  * Set the default file path (for relative file names)
  401.  * @param path the default path returned
  402.  * @param p the pool to allocate any working storage
  403.  */
  404. APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
  405.  
  406. /** The FilePath character encoding is unknown */
  407. #define APR_FILEPATH_ENCODING_UNKNOWN  0
  408.  
  409. /** The FilePath character encoding is locale-dependent */
  410. #define APR_FILEPATH_ENCODING_LOCALE   1
  411.  
  412. /** The FilePath character encoding is UTF-8 */
  413. #define APR_FILEPATH_ENCODING_UTF8     2
  414.  
  415. /**
  416.  * Determine the encoding used internally by the FilePath functions
  417.  * @param style points to a variable which receives the encoding style flag
  418.  * @param p the pool to allocate any working storage
  419.  * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding
  420.  * to get the name of the path encoding if it's not UTF-8.
  421.  */
  422. APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p);
  423. /** @} */
  424.  
  425. /** @} */
  426.  
  427. #ifdef __cplusplus
  428. }
  429. #endif
  430.  
  431. #endif  /* ! APR_FILE_INFO_H */
  432.