Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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
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 */
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 */
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  */
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. */
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 */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
420 /** @} */
421 
422 /** @} */
423 
424 #ifdef __cplusplus
425 }
426 #endif
427 
428 #endif /* ! APR_FILE_INFO_H */