text: /* Licensed to the Apache Software Foundation (ASF) under one or more
   * contributor license agreements.  See the NOTICE file distributed with
   * this work for additional information regarding copyright ownership.
   * The ASF licenses this file to You under the Apache License, Version 2.0
   * (the "License"); you may not use this file except in compliance with
   * the License.  You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  #ifndef APR_FILE_INFO_H
  #define APR_FILE_INFO_H
  
  /**
   * @file apr_file_info.h
   * @brief APR File Information
   */
  
  #include "apr.h"
  #include "apr_user.h"
  #include "apr_pools.h"
  #include "apr_tables.h"
  #include "apr_time.h"
  #include "apr_errno.h"
  
  #if APR_HAVE_SYS_UIO_H
  #include <sys/uio.h>
  #endif
  
  #ifdef __cplusplus
  extern "C" {
  #endif /* __cplusplus */
  
  /**
   * @defgroup apr_file_info File Information
   * @ingroup APR 
   * @{
   */
  
  /* Many applications use the type member to determine the
   * existance of a file or initialization of the file info,
   * so the APR_NOFILE value must be distinct from APR_UNKFILE.
   */
  
  /** apr_filetype_e values for the filetype member of the 
   * apr_file_info_t structure
   * @warning: Not all of the filetypes below can be determined.
   * For example, a given platform might not correctly report 
   * a socket descriptor as APR_SOCK if that type isn't 
   * well-identified on that platform.  In such cases where
   * a filetype exists but cannot be described by the recognized
   * flags below, the filetype will be APR_UNKFILE.  If the
   * filetype member is not determined, the type will be APR_NOFILE.
   */
  
  typedef enum {
      APR_NOFILE = 0,     /**< no file type determined */
      APR_REG,            /**< a regular file */
      APR_DIR,            /**< a directory */
      APR_CHR,            /**< a character device */
      APR_BLK,            /**< a block device */
      APR_PIPE,           /**< a FIFO / pipe */
      APR_LNK,            /**< a symbolic link */
      APR_SOCK,           /**< a [unix domain] socket */
      APR_UNKFILE = 127   /**< a file of some other unknown type */
  } apr_filetype_e; 
  
  /**
   * @defgroup apr_file_permissions File Permissions flags 
   * @{
   */
  
  #define APR_USETID      0x8000 /**< Set user id */
  #define APR_UREAD       0x0400 /**< Read by user */
  #define APR_UWRITE      0x0200 /**< Write by user */
  #define APR_UEXECUTE    0x0100 /**< Execute by user */
  
  #define APR_GSETID      0x4000 /**< Set group id */
  #define APR_GREAD       0x0040 /**< Read by group */
  #define APR_GWRITE      0x0020 /**< Write by group */
  #define APR_GEXECUTE    0x0010 /**< Execute by group */
  
  #define APR_WSTICKY     0x2000 /**< Sticky bit */
  #define APR_WREAD       0x0004 /**< Read by others */
  #define APR_WWRITE      0x0002 /**< Write by others */
  #define APR_WEXECUTE    0x0001 /**< Execute by others */
  
  #define APR_OS_DEFAULT  0x0FFF /**< use OS's default permissions */
  
  /* additional permission flags for apr_file_copy  and apr_file_append */
  #define APR_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */
  
  /** @} */
  
  
  /**
   * Structure for referencing directories.
   */
  typedef struct apr_dir_t          apr_dir_t;
  /**
   * Structure for determining file permissions.
   */
  typedef apr_int32_t               apr_fileperms_t;
  #if (defined WIN32) || (defined NETWARE)
  /**
   * Structure for determining the inode of the file.
   */
  typedef apr_uint64_t              apr_ino_t;
  /**
   * Structure for determining the device the file is on.
   */
  typedef apr_uint32_t              apr_dev_t;
  #else
  /** The inode of the file. */
  typedef ino_t                     apr_ino_t;
  /**
   * Structure for determining the device the file is on.
   */
  typedef dev_t                     apr_dev_t;
  #endif
  
  /**
   * @defgroup apr_file_stat Stat Functions
   * @{
   */
  /** file info structure */
  typedef struct apr_finfo_t        apr_finfo_t;
  
  #define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file itself if it is a link */
  #define APR_FINFO_MTIME  0x00000010 /**< Modification Time */
  #define APR_FINFO_CTIME  0x00000020 /**< Creation Time */
  #define APR_FINFO_ATIME  0x00000040 /**< Access Time */
  #define APR_FINFO_SIZE   0x00000100 /**< Size of the file */
  #define APR_FINFO_CSIZE  0x00000200 /**< Storage size consumed by the file */
  #define APR_FINFO_DEV    0x00001000 /**< Device */
  #define APR_FINFO_INODE  0x00002000 /**< Inode */
  #define APR_FINFO_NLINK  0x00004000 /**< Number of links */
  #define APR_FINFO_TYPE   0x00008000 /**< Type */
  #define APR_FINFO_USER   0x00010000 /**< User */
  #define APR_FINFO_GROUP  0x00020000 /**< Group */
  #define APR_FINFO_UPROT  0x00100000 /**< User protection bits */
  #define APR_FINFO_GPROT  0x00200000 /**< Group protection bits */
  #define APR_FINFO_WPROT  0x00400000 /**< World protection bits */
  #define APR_FINFO_ICASE  0x01000000 /**< if dev is case insensitive */
  #define APR_FINFO_NAME   0x02000000 /**< ->name in proper case */
  
  #define APR_FINFO_MIN    0x00008170 /**< type, mtime, ctime, atime, size */
  #define APR_FINFO_IDENT  0x00003000 /**< dev and inode */
  #define APR_FINFO_OWNER  0x00030000 /**< user and group */
  #define APR_FINFO_PROT   0x00700000 /**<  all protections */
  #define APR_FINFO_NORM   0x0073b170 /**<  an atomic unix apr_stat() */
  #define APR_FINFO_DIRENT 0x02000000 /**<  an atomic unix apr_dir_read() */
  
  /**
   * The file information structure.  This is analogous to the POSIX
   * stat structure.
   */
  struct apr_finfo_t {
      /** Allocates memory and closes lingering handles in the specified pool */
      apr_pool_t *pool;
      /** The bitmask describing valid fields of this apr_finfo_t structure 
       *  including all available 'wanted' fields and potentially more */
      apr_int32_t valid;
      /** The access permissions of the file.  Mimics Unix access rights. */
      apr_fileperms_t protection;
      /** The type of file.  One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, 
       * APR_LNK or APR_SOCK.  If the type is undetermined, the value is APR_NOFILE.
       * If the type cannot be determined, the value is APR_UNKFILE.
       */
      apr_filetype_e filetype;
      /** The user id that owns the file */
      apr_uid_t user;
      /** The group id that owns the file */
      apr_gid_t group;
      /** The inode of the file. */
      apr_ino_t inode;
      /** The id of the device the file is on. */
      apr_dev_t device;
      /** The number of hard links to the file. */
      apr_int32_t nlink;
      /** The size of the file */
      apr_off_t size;
      /** The storage size consumed by the file */
      apr_off_t csize;
      /** The time the file was last accessed */
      apr_time_t atime;
      /** The time the file was last modified */
      apr_time_t mtime;
      /** The time the file was last changed */
      apr_time_t ctime;
      /** The pathname of the file (possibly unrooted) */
      const char *fname;
      /** The file's name (no path) in filesystem case */
      const char *name;
      /** The file's handle, if accessed (can be submitted to apr_duphandle) */
      struct apr_file_t *filehand;
  };
  
  /**
   * get the specified file's stats.  The file is specified by filename, 
   * instead of using a pre-opened file.
   * @param finfo Where to store the information about the file, which is
   * never touched if the call fails.
   * @param fname The name of the file to stat.
   * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
                   values 
   * @param cont the pool to use to allocate the new file. 
   *
   * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
   *       not be filled in, and you need to check the @c finfo->valid bitmask
   *       to verify that what you're looking for is there.
   */ 
  APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
                                     apr_int32_t wanted, apr_pool_t *cont);
  
  /**
   * get the specified file's stats.  The file is specified by filename, 
   * instead of using a pre-opened file.  If the file is a symlink, this function
   * will get the stats for the symlink not the file the symlink refers to.
   * @param finfo Where to store the information about the file, which is
   * never touched if the call fails.
   * @param fname The name of the file to stat.
   * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
   * @param cont the pool to use to allocate the new file. 
   * @deprecated This function is deprecated, it's equivalent to calling apr_stat with 
   * the wanted flag value APR_FINFO_LINK
   */ 
  APR_DECLARE(apr_status_t) apr_lstat(apr_finfo_t *finfo, const char *fname,
                                      apr_int32_t wanted, apr_pool_t *cont);
  /** @} */
  /**
   * @defgroup apr_dir Directory Manipulation Functions
   * @{
   */
  
  /**
   * Open the specified directory.
   * @param new_dir The opened directory descriptor.
   * @param dirname The full path to the directory (use / on all systems)
   * @param cont The pool to use.
   */                        
  APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 
                                         const char *dirname, 
                                         apr_pool_t *cont);
  
  /**
   * close the specified directory. 
   * @param thedir the directory descriptor to close.
   */                        
  APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
  
  /**
   * Read the next entry from the specified directory. 
   * @param finfo the file info structure and filled in by apr_dir_read
   * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
                   values 
   * @param thedir the directory descriptor returned from apr_dir_open
   * @remark No ordering is guaranteed for the entries read.
   *
   * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
   *       not be filled in, and you need to check the @c finfo->valid bitmask
   *       to verify that what you're looking for is there.
   */                        
  APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
                                         apr_dir_t *thedir);
  
  /**
   * Rewind the directory to the first entry.
   * @param thedir the directory descriptor to rewind.
   */                        
  APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
  /** @} */
  
  /**
   * @defgroup apr_filepath Filepath Manipulation Functions
   * @{
   */
  
  /** Cause apr_filepath_merge to fail if addpath is above rootpath */
  #define APR_FILEPATH_NOTABOVEROOT   0x01
  
  /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
  #define APR_FILEPATH_SECUREROOTTEST 0x02
  
  /** Cause apr_filepath_merge to fail if addpath is above rootpath,
   * even given a rootpath /foo/bar and an addpath ../bar/bash
   */
  #define APR_FILEPATH_SECUREROOT     0x03
  
  /** Fail apr_filepath_merge if the merged path is relative */
  #define APR_FILEPATH_NOTRELATIVE    0x04
  
  /** Fail apr_filepath_merge if the merged path is absolute */
  #define APR_FILEPATH_NOTABSOLUTE    0x08
  
  /** Return the file system's native path format (e.g. path delimiters
   * of ':' on MacOS9, '\' on Win32, etc.) */
  #define APR_FILEPATH_NATIVE         0x10
  
  /** Resolve the true case of existing directories and file elements
   * of addpath, (resolving any aliases on Win32) and append a proper 
   * trailing slash if a directory
   */
  #define APR_FILEPATH_TRUENAME       0x20
  
  /**
   * Extract the rootpath from the given filepath
   * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
   * @param filepath the pathname to parse for its root component
   * @param flags the desired rules to apply, from
   * <PRE>
   *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
   *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
   * </PRE>
   * @param p the pool to allocate the new path string from
   * @remark on return, filepath points to the first non-root character in the
   * given filepath.  In the simplest example, given a filepath of "/foo", 
   * returns the rootpath of "/" and filepath points at "foo".  This is far 
   * more complex on other platforms, which will canonicalize the root form
   * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
   * test for the validity of that root (e.g., that a drive d:/ or network 
   * share //machine/foovol/). 
   * The function returns APR_ERELATIVE if filepath isn't rooted (an
   * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
   * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
   * the drive letter), or APR_EBADPATH if the root is simply invalid.
   * APR_SUCCESS is returned if filepath is an absolute path.
   */
  APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 
                                              const char **filepath, 
                                              apr_int32_t flags,
                                              apr_pool_t *p);
  
  /**
   * Merge additional file path onto the previously processed rootpath
   * @param newpath the merged paths returned
   * @param rootpath the root file path (NULL uses the current working path)
   * @param addpath the path to add to the root path
   * @param flags the desired APR_FILEPATH_ rules to apply when merging
   * @param p the pool to allocate the new path string from
   * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath 
   * contains wildcard characters ('*', '?') on platforms that don't support 
   * such characters within filenames, the paths will be merged, but the 
   * result code will be APR_EPATHWILD, and all further segments will not
   * reflect the true filenames including the wildcard and following segments.
   */                        
  APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 
                                               const char *rootpath,
                                               const char *addpath, 
                                               apr_int32_t flags,
                                               apr_pool_t *p);
  
  /**
   * Split a search path into separate components
   * @param pathelts the returned components of the search path
   * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
   * @param p the pool to allocate the array and path components from
   * @remark empty path componenta do not become part of @a pathelts.
   * @remark the path separator in @a liststr is system specific;
   * e.g., ':' on Unix, ';' on Windows, etc.
   */
  APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts,
                                                    const char *liststr,
                                                    apr_pool_t *p);
  
  /**
   * Merge a list of search path components into a single search path
   * @param liststr the returned search path; may be NULL if @a pathelts is empty
   * @param pathelts the components of the search path
   * @param p the pool to allocate the search path from
   * @remark emtpy strings in the source array are ignored.
   * @remark the path separator in @a liststr is system specific;
   * e.g., ':' on Unix, ';' on Windows, etc.
   */
  APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr,
                                                    apr_array_header_t *pathelts,
                                                    apr_pool_t *p);
  
  /**
   * Return the default file path (for relative file names)
   * @param path the default path string returned
   * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
   *              default file path in os-native format.
   * @param p the pool to allocate the default path string from
   */
  APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
                                             apr_pool_t *p);
  
  /**
   * Set the default file path (for relative file names)
   * @param path the default path returned
   * @param p the pool to allocate any working storage
   */
  APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
  
  /** The FilePath character encoding is unknown */
  #define APR_FILEPATH_ENCODING_UNKNOWN  0
  
  /** The FilePath character encoding is locale-dependent */
  #define APR_FILEPATH_ENCODING_LOCALE   1
  
  /** The FilePath character encoding is UTF-8 */
  #define APR_FILEPATH_ENCODING_UTF8     2
  
  /**
   * Determine the encoding used internally by the FilePath functions
   * @param style points to a variable which receives the encoding style flag
   * @param p the pool to allocate any working storage
   * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding
   * to get the name of the path encoding if it's not UTF-8.
   */
  APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p);
  /** @} */
  
  /** @} */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif  /* ! APR_FILE_INFO_H */
  