include/apr-0/apr_file_info.h

   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_USETID      0x8000 /**< Set user id */
  80 #define APR_UREAD       0x0400 /**< Read by user */
  81 #define APR_UWRITE      0x0200 /**< Write by user */
  82 #define APR_UEXECUTE    0x0100 /**< Execute by user */
  83
  84 #define APR_GSETID      0x4000 /**< Set group id */
  85 #define APR_GREAD       0x0040 /**< Read by group */
  86 #define APR_GWRITE      0x0020 /**< Write by group */
  87 #define APR_GEXECUTE    0x0010 /**< Execute by group */
  88
  89 #define APR_WSTICKY     0x2000 /**< Sticky bit */
  90 #define APR_WREAD       0x0004 /**< Read by others */
  91 #define APR_WWRITE      0x0002 /**< Write by others */
  92 #define APR_WEXECUTE    0x0001 /**< Execute by others */
  93
  94 #define APR_OS_DEFAULT  0x0FFF /**< use OS's default permissions */
  95
  96 /* additional permission flags for apr_file_copy  and apr_file_append */
  97 #define APR_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */
  98
  99 /** @} */
 100
 101
 102 /**
 103  * Structure for referencing directories.
 104  */
 105 typedef struct apr_dir_t          apr_dir_t;
 106 /**
 107  * Structure for determining file permissions.
 108  */
 109 typedef apr_int32_t               apr_fileperms_t;
 110 #if (defined WIN32) || (defined NETWARE)
 111 /**
 112  * Structure for determining the device the file is on.
 113  */
 114 typedef apr_uint32_t              apr_dev_t;
 115 #else
 116 /**
 117  * Structure for determining the device the file is on.
 118  */
 119 typedef dev_t                     apr_dev_t;
 120 #endif
 121
 122 /**
 123  * @defgroup apr_file_stat Stat Functions
 124  * @{
 125  */
 126 /** file info structure */
 127 typedef struct apr_finfo_t        apr_finfo_t;
 128
 129 #define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file itself if it is a link */
 130 #define APR_FINFO_MTIME  0x00000010 /**< Modification Time */
 131 #define APR_FINFO_CTIME  0x00000020 /**< Creation Time */
 132 #define APR_FINFO_ATIME  0x00000040 /**< Access Time */
 133 #define APR_FINFO_SIZE   0x00000100 /**< Size of the file */
 134 #define APR_FINFO_CSIZE  0x00000200 /**< Storage size consumed by the file */
 135 #define APR_FINFO_DEV    0x00001000 /**< Device */
 136 #define APR_FINFO_INODE  0x00002000 /**< Inode */
 137 #define APR_FINFO_NLINK  0x00004000 /**< Number of links */
 138 #define APR_FINFO_TYPE   0x00008000 /**< Type */
 139 #define APR_FINFO_USER   0x00010000 /**< User */
 140 #define APR_FINFO_GROUP  0x00020000 /**< Group */
 141 #define APR_FINFO_UPROT  0x00100000 /**< User protection bits */
 142 #define APR_FINFO_GPROT  0x00200000 /**< Group protection bits */
 143 #define APR_FINFO_WPROT  0x00400000 /**< World protection bits */
 144 #define APR_FINFO_ICASE  0x01000000 /**< if dev is case insensitive */
 145 #define APR_FINFO_NAME   0x02000000 /**< ->name in proper case */
 146
 147 #define APR_FINFO_MIN    0x00008170 /**< type, mtime, ctime, atime, size */
 148 #define APR_FINFO_IDENT  0x00003000 /**< dev and inode */
 149 #define APR_FINFO_OWNER  0x00030000 /**< user and group */
 150 #define APR_FINFO_PROT   0x00700000 /**<  all protections */
 151 #define APR_FINFO_NORM   0x0073b170 /**<  an atomic unix apr_stat() */
 152 #define APR_FINFO_DIRENT 0x02000000 /**<  an atomic unix apr_dir_read() */
 153
 154 /**
 155  * The file information structure.  This is analogous to the POSIX
 156  * stat structure.
 157  */
 158 struct apr_finfo_t {
 159     /** Allocates memory and closes lingering handles in the specified pool */
 160     apr_pool_t *pool;
 161     /** The bitmask describing valid fields of this apr_finfo_t structure
 162      *  including all available 'wanted' fields and potentially more */
 163     apr_int32_t valid;
 164     /** The access permissions of the file.  Mimics Unix access rights. */
 165     apr_fileperms_t protection;
 166     /** The type of file.  One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE,
 167      * APR_LNK or APR_SOCK.  If the type is undetermined, the value is APR_NOFILE.
 168      * If the type cannot be determined, the value is APR_UNKFILE.
 169      */
 170     apr_filetype_e filetype;
 171     /** The user id that owns the file */
 172     apr_uid_t user;
 173     /** The group id that owns the file */
 174     apr_gid_t group;
 175     /** The inode of the file. */
 176     apr_ino_t inode;
 177     /** The id of the device the file is on. */
 178     apr_dev_t device;
 179     /** The number of hard links to the file. */
 180     apr_int32_t nlink;
 181     /** The size of the file */
 182     apr_off_t size;
 183     /** The storage size consumed by the file */
 184     apr_off_t csize;
 185     /** The time the file was last accessed */
 186     apr_time_t atime;
 187     /** The time the file was last modified */
 188     apr_time_t mtime;
 189     /** The time the file was last changed */
 190     apr_time_t ctime;
 191     /** The pathname of the file (possibly unrooted) */
 192     const char *fname;
 193     /** The file's name (no path) in filesystem case */
 194     const char *name;
 195     /** The file's handle, if accessed (can be submitted to apr_duphandle) */
 196     struct apr_file_t *filehand;
 197 };
 198
 199 /**
 200  * get the specified file's stats.  The file is specified by filename,
 201  * instead of using a pre-opened file.
 202  * @param finfo Where to store the information about the file, which is
 203  * never touched if the call fails.
 204  * @param fname The name of the file to stat.
 205  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
 206                  values
 207  * @param cont the pool to use to allocate the new file.
 208  *
 209  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
 210  *       not be filled in, and you need to check the @c finfo->valid bitmask
 211  *       to verify that what you're looking for is there.
 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_
 256                  values
 257  * @param thedir the directory descriptor returned from apr_dir_open
 258  * @remark No ordering is guaranteed for the entries read.
 259  *
 260  * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
 261  *       not be filled in, and you need to check the @c finfo->valid bitmask
 262  *       to verify that what you're looking for is there.
 263  */
 264 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
 265                                        apr_dir_t *thedir);
 266
 267 /**
 268  * Rewind the directory to the first entry.
 269  * @param thedir the directory descriptor to rewind.
 270  */
 271 APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
 272 /** @} */
 273
 274 /**
 275  * @defgroup apr_filepath Filepath Manipulation Functions
 276  * @{
 277  */
 278
 279 /** Cause apr_filepath_merge to fail if addpath is above rootpath */
 280 #define APR_FILEPATH_NOTABOVEROOT   0x01
 281
 282 /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
 283 #define APR_FILEPATH_SECUREROOTTEST 0x02
 284
 285 /** Cause apr_filepath_merge to fail if addpath is above rootpath,
 286  * even given a rootpath /foo/bar and an addpath ../bar/bash
 287  */
 288 #define APR_FILEPATH_SECUREROOT     0x03
 289
 290 /** Fail apr_filepath_merge if the merged path is relative */
 291 #define APR_FILEPATH_NOTRELATIVE    0x04
 292
 293 /** Fail apr_filepath_merge if the merged path is absolute */
 294 #define APR_FILEPATH_NOTABSOLUTE    0x08
 295
 296 /** Return the file system's native path format (e.g. path delimiters
 297  * of ':' on MacOS9, '\' on Win32, etc.) */
 298 #define APR_FILEPATH_NATIVE         0x10
 299
 300 /** Resolve the true case of existing directories and file elements
 301  * of addpath, (resolving any aliases on Win32) and append a proper
 302  * trailing slash if a directory
 303  */
 304 #define APR_FILEPATH_TRUENAME       0x20
 305
 306 /**
 307  * Extract the rootpath from the given filepath
 308  * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
 309  * @param filepath the pathname to parse for its root component
 310  * @param flags the desired rules to apply, from
 311  * <PRE>
 312  *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
 313  *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
 314  * </PRE>
 315  * @param p the pool to allocate the new path string from
 316  * @remark on return, filepath points to the first non-root character in the
 317  * given filepath.  In the simplest example, given a filepath of "/foo",
 318  * returns the rootpath of "/" and filepath points at "foo".  This is far
 319  * more complex on other platforms, which will canonicalize the root form
 320  * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
 321  * test for the validity of that root (e.g., that a drive d:/ or network
 322  * share //machine/foovol/).
 323  * The function returns APR_ERELATIVE if filepath isn't rooted (an
 324  * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
 325  * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
 326  * the drive letter), or APR_EBADPATH if the root is simply invalid.
 327  * APR_SUCCESS is returned if filepath is an absolute path.
 328  */
 329 APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath,
 330                                             const char **filepath,
 331                                             apr_int32_t flags,
 332                                             apr_pool_t *p);
 333
 334 /**
 335  * Merge additional file path onto the previously processed rootpath
 336  * @param newpath the merged paths returned
 337  * @param rootpath the root file path (NULL uses the current working path)
 338  * @param addpath the path to add to the root path
 339  * @param flags the desired APR_FILEPATH_ rules to apply when merging
 340  * @param p the pool to allocate the new path string from
 341  * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath
 342  * contains wildcard characters ('*', '?') on platforms that don't support
 343  * such characters within filenames, the paths will be merged, but the
 344  * result code will be APR_EPATHWILD, and all further segments will not
 345  * reflect the true filenames including the wildcard and following segments.
 346  */
 347 APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath,
 348                                              const char *rootpath,
 349                                              const char *addpath,
 350                                              apr_int32_t flags,
 351                                              apr_pool_t *p);
 352
 353 /**
 354  * Split a search path into separate components
 355  * @param pathelts the returned components of the search path
 356  * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
 357  * @param p the pool to allocate the array and path components from
 358  * @remark empty path componenta do not become part of @a pathelts.
 359  * @remark the path separator in @a liststr is system specific;
 360  * e.g., ':' on Unix, ';' on Windows, etc.
 361  */
 362 APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts,
 363                                                   const char *liststr,
 364                                                   apr_pool_t *p);
 365
 366 /**
 367  * Merge a list of search path components into a single search path
 368  * @param liststr the returned search path; may be NULL if @a pathelts is empty
 369  * @param pathelts the components of the search path
 370  * @param p the pool to allocate the search path from
 371  * @remark emtpy strings in the source array are ignored.
 372  * @remark the path separator in @a liststr is system specific;
 373  * e.g., ':' on Unix, ';' on Windows, etc.
 374  */
 375 APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr,
 376                                                   apr_array_header_t *pathelts,
 377                                                   apr_pool_t *p);
 378
 379 /**
 380  * Return the default file path (for relative file names)
 381  * @param path the default path string returned
 382  * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
 383  *              default file path in os-native format.
 384  * @param p the pool to allocate the default path string from
 385  */
 386 APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
 387                                            apr_pool_t *p);
 388
 389 /**
 390  * Set the default file path (for relative file names)
 391  * @param path the default path returned
 392  * @param p the pool to allocate any working storage
 393  */
 394 APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
 395
 396 /** The FilePath character encoding is unknown */
 397 #define APR_FILEPATH_ENCODING_UNKNOWN  0
 398
 399 /** The FilePath character encoding is locale-dependent */
 400 #define APR_FILEPATH_ENCODING_LOCALE   1
 401
 402 /** The FilePath character encoding is UTF-8 */
 403 #define APR_FILEPATH_ENCODING_UTF8     2
 404
 405 /**
 406  * Determine the encoding used internally by the FilePath functions
 407  * @param style points to a variable which receives the encoding style flag
 408  * @param p the pool to allocate any working storage
 409  * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding
 410  * to get the name of the path encoding if it's not UTF-8.
 411  */
 412 APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p);
 413 /** @} */
 414
 415 /** @} */
 416
 417 #ifdef __cplusplus
 418 }
 419 #endif
 420
 421 #endif  /* ! APR_FILE_INFO_H */