Apache Portable Runtime
apr_file_info.h
Go to the documentation of this file.
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
37extern "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
62typedef 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 */
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 */
121typedef struct apr_dir_t apr_dir_t;
122/**
123 * Structure for determining file permissions.
124 */
125typedef apr_int32_t apr_fileperms_t;
126#if (defined WIN32) || (defined NETWARE)
127/**
128 * Structure for determining the device the file is on.
129 */
130typedef apr_uint32_t apr_dev_t;
131#else
132/**
133 * Structure for determining the device the file is on.
134 */
135typedef dev_t apr_dev_t;
136#endif
137
138/**
139 * @defgroup apr_file_stat Stat Functions
140 * @{
141 */
142/** file info structure */
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 */
175 /** Allocates memory and closes lingering handles in the specified 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. */
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 */
187 /** The user id that owns the file */
189 /** The group id that owns the file */
191 /** The inode of the file. */
192 apr_ino_t inode;
193 /** The id of the device the file is on. */
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 */
203 /** The time the file was last modified */
205 /** The time the file was created, or the inode was last changed */
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 /** Unused */
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 */
229APR_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 */
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 */
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 */
268 apr_dir_t *thedir);
269
270/**
271 * Rewind the directory to the first entry.
272 * @param thedir the directory descriptor to rewind.
273 */
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 separators (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 ambiguous (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 */
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 */
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 components 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 */
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 */
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 */
393APR_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 */
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 apr_os_locale_encoding() and/or apr_os_default_encoding()
417 * to get the name of the path encoding if it's not UTF-8.
418 */
420/** @} */
421
422/** @} */
423
424#ifdef __cplusplus
425}
426#endif
427
428#endif /* ! APR_FILE_INFO_H */
APR Platform Definitions.
APR Error Codes.
APR memory allocation.
APR Table library.
APR Time Library.
APR User ID Services.
apr_status_t apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted, apr_dir_t *thedir)
apr_status_t apr_dir_close(apr_dir_t *thedir)
apr_status_t apr_dir_open(apr_dir_t **new_dir, const char *dirname, apr_pool_t *pool)
apr_status_t apr_dir_rewind(apr_dir_t *thedir)
int apr_status_t
Definition: apr_errno.h:44
apr_int32_t apr_fileperms_t
Definition: apr_file_info.h:125
struct apr_dir_t apr_dir_t
Definition: apr_file_info.h:121
dev_t apr_dev_t
Definition: apr_file_info.h:135
apr_filetype_e
Definition: apr_file_info.h:62
@ APR_BLK
Definition: apr_file_info.h:67
@ APR_PIPE
Definition: apr_file_info.h:68
@ APR_LNK
Definition: apr_file_info.h:69
@ APR_UNKFILE
Definition: apr_file_info.h:71
@ APR_REG
Definition: apr_file_info.h:64
@ APR_CHR
Definition: apr_file_info.h:66
@ APR_SOCK
Definition: apr_file_info.h:70
@ APR_DIR
Definition: apr_file_info.h:65
@ APR_NOFILE
Definition: apr_file_info.h:63
struct apr_file_t apr_file_t
Definition: apr_file_io.h:188
apr_status_t apr_stat(apr_finfo_t *finfo, const char *fname, apr_int32_t wanted, apr_pool_t *pool)
apr_status_t apr_filepath_root(const char **rootpath, const char **filepath, apr_int32_t flags, apr_pool_t *p)
apr_status_t apr_filepath_list_merge(char **liststr, apr_array_header_t *pathelts, apr_pool_t *p)
apr_status_t apr_filepath_set(const char *path, apr_pool_t *p)
apr_status_t apr_filepath_get(char **path, apr_int32_t flags, apr_pool_t *p)
apr_status_t apr_filepath_encoding(int *style, apr_pool_t *p)
apr_status_t apr_filepath_merge(char **newpath, const char *rootpath, const char *addpath, apr_int32_t flags, apr_pool_t *p)
apr_status_t apr_filepath_list_split(apr_array_header_t **pathelts, const char *liststr, apr_pool_t *p)
#define APR_DECLARE(type)
Definition: apr.h:498
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
apr_int64_t apr_time_t
Definition: apr_time.h:45
gid_t apr_gid_t
Definition: apr_user.h:54
uid_t apr_uid_t
Definition: apr_user.h:45
Definition: apr_tables.h:62
Definition: apr_file_info.h:174
apr_gid_t group
Definition: apr_file_info.h:190
apr_filetype_e filetype
Definition: apr_file_info.h:186
const char * name
Definition: apr_file_info.h:210
apr_dev_t device
Definition: apr_file_info.h:194
apr_off_t size
Definition: apr_file_info.h:198
apr_pool_t * pool
Definition: apr_file_info.h:176
apr_ino_t inode
Definition: apr_file_info.h:192
struct apr_file_t * filehand
Definition: apr_file_info.h:212
apr_fileperms_t protection
Definition: apr_file_info.h:181
apr_int32_t nlink
Definition: apr_file_info.h:196
apr_uid_t user
Definition: apr_file_info.h:188
const char * fname
Definition: apr_file_info.h:208
apr_time_t atime
Definition: apr_file_info.h:202
apr_off_t csize
Definition: apr_file_info.h:200
apr_time_t ctime
Definition: apr_file_info.h:206
apr_time_t mtime
Definition: apr_file_info.h:204
apr_int32_t valid
Definition: apr_file_info.h:179