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