1
/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
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.
17
#ifndef APR_FILE_INFO_H
18
#define APR_FILE_INFO_H
21
* @file apr_file_info.h
22
* @brief APR File Information
27
#include "apr_pools.h"
28
#include "apr_tables.h"
30
#include "apr_errno.h"
32
#if APR_HAVE_SYS_UIO_H
38
#endif /* __cplusplus */
41
* @defgroup apr_file_info File Information
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.
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.
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 */
75
* @defgroup apr_file_permissions File Permissions flags
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 */
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 */
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 */
94
#define APR_FPROT_OS_DEFAULT 0x0FFF /**< use OS's default permissions */
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 */
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 */
119
* Structure for referencing directories.
121
typedef struct apr_dir_t apr_dir_t;
123
* Structure for determining file permissions.
125
typedef apr_int32_t apr_fileperms_t;
126
#if (defined WIN32) || (defined NETWARE)
128
* Structure for determining the inode of the file.
130
typedef apr_uint64_t apr_ino_t;
132
* Structure for determining the device the file is on.
134
typedef apr_uint32_t apr_dev_t;
136
/** The inode of the file. */
137
typedef ino_t apr_ino_t;
139
* Structure for determining the device the file is on.
141
typedef dev_t apr_dev_t;
145
* @defgroup apr_file_stat Stat Functions
148
/** file info structure */
149
typedef struct apr_finfo_t apr_finfo_t;
151
#define APR_FINFO_LINK 0x00000001 /**< Stat the link not the file itself if it is a link */
152
#define APR_FINFO_MTIME 0x00000010 /**< Modification Time */
153
#define APR_FINFO_CTIME 0x00000020 /**< Creation or inode-changed time */
154
#define APR_FINFO_ATIME 0x00000040 /**< Access Time */
155
#define APR_FINFO_SIZE 0x00000100 /**< Size of the file */
156
#define APR_FINFO_CSIZE 0x00000200 /**< Storage size consumed by the file */
157
#define APR_FINFO_DEV 0x00001000 /**< Device */
158
#define APR_FINFO_INODE 0x00002000 /**< Inode */
159
#define APR_FINFO_NLINK 0x00004000 /**< Number of links */
160
#define APR_FINFO_TYPE 0x00008000 /**< Type */
161
#define APR_FINFO_USER 0x00010000 /**< User */
162
#define APR_FINFO_GROUP 0x00020000 /**< Group */
163
#define APR_FINFO_UPROT 0x00100000 /**< User protection bits */
164
#define APR_FINFO_GPROT 0x00200000 /**< Group protection bits */
165
#define APR_FINFO_WPROT 0x00400000 /**< World protection bits */
166
#define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */
167
#define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */
169
#define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */
170
#define APR_FINFO_IDENT 0x00003000 /**< dev and inode */
171
#define APR_FINFO_OWNER 0x00030000 /**< user and group */
172
#define APR_FINFO_PROT 0x00700000 /**< all protections */
173
#define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */
174
#define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */
177
* The file information structure. This is analogous to the POSIX
181
/** Allocates memory and closes lingering handles in the specified pool */
183
/** The bitmask describing valid fields of this apr_finfo_t structure
184
* including all available 'wanted' fields and potentially more */
186
/** The access permissions of the file. Mimics Unix access rights. */
187
apr_fileperms_t protection;
188
/** The type of file. One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE,
189
* APR_LNK or APR_SOCK. If the type is undetermined, the value is APR_NOFILE.
190
* If the type cannot be determined, the value is APR_UNKFILE.
192
apr_filetype_e filetype;
193
/** The user id that owns the file */
195
/** The group id that owns the file */
197
/** The inode of the file. */
199
/** The id of the device the file is on. */
201
/** The number of hard links to the file. */
203
/** The size of the file */
205
/** The storage size consumed by the file */
207
/** The time the file was last accessed */
209
/** The time the file was last modified */
211
/** The time the file was created, or the inode was last changed */
213
/** The pathname of the file (possibly unrooted) */
215
/** The file's name (no path) in filesystem case */
217
/** The file's handle, if accessed (can be submitted to apr_duphandle) */
218
struct apr_file_t *filehand;
222
* get the specified file's stats. The file is specified by filename,
223
* instead of using a pre-opened file.
224
* @param finfo Where to store the information about the file, which is
225
* never touched if the call fails.
226
* @param fname The name of the file to stat.
227
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
229
* @param pool the pool to use to allocate the new file.
231
* @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
232
* not be filled in, and you need to check the @c finfo->valid bitmask
233
* to verify that what you're looking for is there.
235
APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
236
apr_int32_t wanted, apr_pool_t *pool);
240
* @defgroup apr_dir Directory Manipulation Functions
245
* Open the specified directory.
246
* @param new_dir The opened directory descriptor.
247
* @param dirname The full path to the directory (use / on all systems)
248
* @param pool The pool to use.
250
APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir,
255
* close the specified directory.
256
* @param thedir the directory descriptor to close.
258
APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
261
* Read the next entry from the specified directory.
262
* @param finfo the file info structure and filled in by apr_dir_read
263
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
265
* @param thedir the directory descriptor returned from apr_dir_open
266
* @remark No ordering is guaranteed for the entries read.
268
* @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
269
* not be filled in, and you need to check the @c finfo->valid bitmask
270
* to verify that what you're looking for is there.
272
APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
276
* Rewind the directory to the first entry.
277
* @param thedir the directory descriptor to rewind.
279
APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
283
* @defgroup apr_filepath Filepath Manipulation Functions
287
/** Cause apr_filepath_merge to fail if addpath is above rootpath */
288
#define APR_FILEPATH_NOTABOVEROOT 0x01
290
/** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
291
#define APR_FILEPATH_SECUREROOTTEST 0x02
293
/** Cause apr_filepath_merge to fail if addpath is above rootpath,
294
* even given a rootpath /foo/bar and an addpath ../bar/bash
296
#define APR_FILEPATH_SECUREROOT 0x03
298
/** Fail apr_filepath_merge if the merged path is relative */
299
#define APR_FILEPATH_NOTRELATIVE 0x04
301
/** Fail apr_filepath_merge if the merged path is absolute */
302
#define APR_FILEPATH_NOTABSOLUTE 0x08
304
/** Return the file system's native path format (e.g. path delimiters
305
* of ':' on MacOS9, '\' on Win32, etc.) */
306
#define APR_FILEPATH_NATIVE 0x10
308
/** Resolve the true case of existing directories and file elements
309
* of addpath, (resolving any aliases on Win32) and append a proper
310
* trailing slash if a directory
312
#define APR_FILEPATH_TRUENAME 0x20
315
* Extract the rootpath from the given filepath
316
* @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
317
* @param filepath the pathname to parse for its root component
318
* @param flags the desired rules to apply, from
320
* APR_FILEPATH_NATIVE Use native path seperators (e.g. '\' on Win32)
321
* APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper
323
* @param p the pool to allocate the new path string from
324
* @remark on return, filepath points to the first non-root character in the
325
* given filepath. In the simplest example, given a filepath of "/foo",
326
* returns the rootpath of "/" and filepath points at "foo". This is far
327
* more complex on other platforms, which will canonicalize the root form
328
* to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
329
* test for the validity of that root (e.g., that a drive d:/ or network
330
* share //machine/foovol/).
331
* The function returns APR_ERELATIVE if filepath isn't rooted (an
332
* error), APR_EINCOMPLETE if the root path is ambigious (but potentially
333
* legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
334
* the drive letter), or APR_EBADPATH if the root is simply invalid.
335
* APR_SUCCESS is returned if filepath is an absolute path.
337
APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath,
338
const char **filepath,
343
* Merge additional file path onto the previously processed rootpath
344
* @param newpath the merged paths returned
345
* @param rootpath the root file path (NULL uses the current working path)
346
* @param addpath the path to add to the root path
347
* @param flags the desired APR_FILEPATH_ rules to apply when merging
348
* @param p the pool to allocate the new path string from
349
* @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath
350
* contains wildcard characters ('*', '?') on platforms that don't support
351
* such characters within filenames, the paths will be merged, but the
352
* result code will be APR_EPATHWILD, and all further segments will not
353
* reflect the true filenames including the wildcard and following segments.
355
APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath,
356
const char *rootpath,
362
* Split a search path into separate components
363
* @param pathelts the returned components of the search path
364
* @param liststr the search path (e.g., <tt>getenv("PATH")</tt>)
365
* @param p the pool to allocate the array and path components from
366
* @remark empty path componenta do not become part of @a pathelts.
367
* @remark the path separator in @a liststr is system specific;
368
* e.g., ':' on Unix, ';' on Windows, etc.
370
APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts,
375
* Merge a list of search path components into a single search path
376
* @param liststr the returned search path; may be NULL if @a pathelts is empty
377
* @param pathelts the components of the search path
378
* @param p the pool to allocate the search path from
379
* @remark emtpy strings in the source array are ignored.
380
* @remark the path separator in @a liststr is system specific;
381
* e.g., ':' on Unix, ';' on Windows, etc.
383
APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr,
384
apr_array_header_t *pathelts,
388
* Return the default file path (for relative file names)
389
* @param path the default path string returned
390
* @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
391
* default file path in os-native format.
392
* @param p the pool to allocate the default path string from
394
APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
398
* Set the default file path (for relative file names)
399
* @param path the default path returned
400
* @param p the pool to allocate any working storage
402
APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
404
/** The FilePath character encoding is unknown */
405
#define APR_FILEPATH_ENCODING_UNKNOWN 0
407
/** The FilePath character encoding is locale-dependent */
408
#define APR_FILEPATH_ENCODING_LOCALE 1
410
/** The FilePath character encoding is UTF-8 */
411
#define APR_FILEPATH_ENCODING_UTF8 2
414
* Determine the encoding used internally by the FilePath functions
415
* @param style points to a variable which receives the encoding style flag
416
* @param p the pool to allocate any working storage
417
* @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding
418
* to get the name of the path encoding if it's not UTF-8.
420
APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p);
429
#endif /* ! APR_FILE_INFO_H */
added
removed
srclib/apr/include/apr_file_info.h
