Apache Portable Runtime
apr_file_io.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_IO_H
18 #define APR_FILE_IO_H
19 
20 /**
21  * @file apr_file_io.h
22  * @brief APR File I/O Handling
23  */
24 
25 #include "apr.h"
26 #include "apr_pools.h"
27 #include "apr_time.h"
28 #include "apr_errno.h"
29 #include "apr_file_info.h"
30 #include "apr_inherit.h"
31 
32 #define APR_WANT_STDIO /**< for SEEK_* */
33 #define APR_WANT_IOVEC /**< for apr_file_writev */
34 #include "apr_want.h"
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif /* __cplusplus */
39 
40 /**
41  * @defgroup apr_file_io File I/O Handling Functions
42  * @ingroup APR
43  * @{
44  */
45 
46 /**
47  * @defgroup apr_file_open_flags File Open Flags/Routines
48  * @{
49  */
50 
51 /* Note to implementors: Values in the range 0x00100000--0x80000000
52  are reserved for platform-specific values. */
53 
54 #define APR_FOPEN_READ 0x00001 /**< Open the file for reading */
55 #define APR_FOPEN_WRITE 0x00002 /**< Open the file for writing */
56 #define APR_FOPEN_CREATE 0x00004 /**< Create the file if not there */
57 #define APR_FOPEN_APPEND 0x00008 /**< Append to the end of the file */
58 #define APR_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate
59  to 0 length */
60 #define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode
61  (This flag is ignored on UNIX
62  because it has no meaning)*/
63 #define APR_FOPEN_EXCL 0x00040 /**< Open should fail if #APR_FOPEN_CREATE
64  and file exists. */
65 #define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */
66 #define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */
67 #define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open
68  the file for use across multiple
69  threads */
70 #define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for
71  higher level locked read/write
72  access to support writes across
73  process/machines */
74 #define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup
75  when the file is opened. The
76  apr_os_file_t handle in apr_file_t
77  will not be closed when the pool
78  is destroyed. */
79 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
80  file should support
81  apr_socket_sendfile operation */
82 #define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable
83  * large file support, see WARNING below
84  */
85 #define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable
86  * sparse file support, see WARNING below
87  */
88 #define APR_FOPEN_NONBLOCK 0x40000 /**< Platform dependent flag to enable
89  * non blocking file io */
90 
91 
92 /* backcompat */
93 #define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */
94 #define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */
95 #define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */
96 #define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */
97 #define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */
98 #define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */
99 #define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */
100 #define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */
101 #define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */
102 #define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */
103 #define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */
104 #define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */
105 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */
106 #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */
107 
108 /** @def APR_FOPEN_LARGEFILE
109  * @warning APR_FOPEN_LARGEFILE flag only has effect on some
110  * platforms where sizeof(apr_off_t) == 4. Where implemented, it
111  * allows opening and writing to a file which exceeds the size which
112  * can be represented by apr_off_t (2 gigabytes). When a file's size
113  * does exceed 2Gb, apr_file_info_get() will fail with an error on the
114  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
115  * filename. apr_dir_read() will fail with #APR_INCOMPLETE on a
116  * directory entry for a large file depending on the particular
117  * APR_FINFO_* flags. Generally, it is not recommended to use this
118  * flag.
119  *
120  * @def APR_FOPEN_SPARSE
121  * @warning APR_FOPEN_SPARSE may, depending on platform, convert a
122  * normal file to a sparse file. Some applications may be unable
123  * to decipher a sparse file, so it's critical that the sparse file
124  * flag should only be used for files accessed only by APR or other
125  * applications known to be able to decipher them. APR does not
126  * guarantee that it will compress the file into sparse segments
127  * if it was previously created and written without the sparse flag.
128  * On platforms which do not understand, or on file systems which
129  * cannot handle sparse files, the flag is ignored by apr_file_open().
130  *
131  * @def APR_FOPEN_NONBLOCK
132  * @warning APR_FOPEN_NONBLOCK is not implemented on all platforms.
133  * Callers should be prepared for it to fail with #APR_ENOTIMPL.
134  */
135 
136 /** @} */
137 
138 /**
139  * @defgroup apr_file_seek_flags File Seek Flags
140  * @{
141  */
142 
143 /* flags for apr_file_seek */
144 /** Set the file position */
145 #define APR_SET SEEK_SET
146 /** Current */
147 #define APR_CUR SEEK_CUR
148 /** Go to end of file */
149 #define APR_END SEEK_END
150 /** @} */
151 
152 /**
153  * @defgroup apr_file_attrs_set_flags File Attribute Flags
154  * @{
155  */
156 
157 /* flags for apr_file_attrs_set */
158 #define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */
159 #define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */
160 #define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */
161 /** @} */
162 
163 /**
164  * @defgroup apr_file_writev{_full} max iovec size
165  * @{
166  */
167 #if defined(DOXYGEN)
168 #define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum
169  size of an iovec array */
170 #elif defined(IOV_MAX)
171 #define APR_MAX_IOVEC_SIZE IOV_MAX
172 #elif defined(MAX_IOVEC)
173 #define APR_MAX_IOVEC_SIZE MAX_IOVEC
174 #else
175 #define APR_MAX_IOVEC_SIZE 1024
176 #endif
177 /** @} */
178 
179 /** File attributes */
180 typedef apr_uint32_t apr_fileattrs_t;
181 
182 /** Type to pass as whence argument to apr_file_seek. */
183 typedef int apr_seek_where_t;
184 
185 /**
186  * Structure for referencing files.
187  */
188 typedef struct apr_file_t apr_file_t;
189 
190 /* File lock types/flags */
191 /**
192  * @defgroup apr_file_lock_types File Lock Types
193  * @{
194  */
195 
196 #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process
197  or thread can hold a shared lock
198  at any given time. Essentially,
199  this is a "read lock", preventing
200  writers from establishing an
201  exclusive lock. */
202 #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process
203  may hold an exclusive lock at any
204  given time. This is analogous to
205  a "write lock". */
206 
207 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
208 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
209  file lock */
210 /** @} */
211 
212 /**
213  * Open the specified file.
214  * @param newf The opened file descriptor.
215  * @param fname The full path to the file (using / on all systems)
216  * @param flag Or'ed value of:
217  * @li #APR_FOPEN_READ open for reading
218  * @li #APR_FOPEN_WRITE open for writing
219  * @li #APR_FOPEN_CREATE create the file if not there
220  * @li #APR_FOPEN_APPEND file ptr is set to end prior to all writes
221  * @li #APR_FOPEN_TRUNCATE set length to zero if file exists
222  * @li #APR_FOPEN_BINARY not a text file
223  * @li #APR_FOPEN_BUFFERED buffer the data. Default is non-buffered
224  * @li #APR_FOPEN_EXCL return error if #APR_FOPEN_CREATE and file exists
225  * @li #APR_FOPEN_DELONCLOSE delete the file after closing
226  * @li #APR_FOPEN_XTHREAD Platform dependent tag to open the file
227  * for use across multiple threads
228  * @li #APR_FOPEN_SHARELOCK Platform dependent support for higher
229  * level locked read/write access to support
230  * writes across process/machines
231  * @li #APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool
232  * passed in on the @a pool argument (see below)
233  * @li #APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics
234  * for sendfile operations. Advisory only,
235  * apr_socket_sendfile does not check this flag
236  * @li #APR_FOPEN_LARGEFILE Platform dependent flag to enable large file
237  * support, see WARNING below
238  * @li #APR_FOPEN_SPARSE Platform dependent flag to enable sparse file
239  * support, see WARNING below
240  * @li #APR_FOPEN_NONBLOCK Platform dependent flag to enable
241  * non blocking file io
242  * @param perm Access permissions for file.
243  * @param pool The pool to use.
244  * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created,
245  * appropriate default permissions will be used.
246  * @remark By default, the returned file descriptor will not be
247  * inherited by child processes created by apr_proc_create(). This
248  * can be changed using apr_file_inherit_set().
249  */
250 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
251  apr_int32_t flag, apr_fileperms_t perm,
252  apr_pool_t *pool);
253 
254 /**
255  * Close the specified file.
256  * @param file The file descriptor to close.
257  */
258 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
259 
260 /**
261  * Delete the specified file.
262  * @param path The full path to the file (using / on all systems)
263  * @param pool The pool to use.
264  * @remark If the file is open, it won't be removed until all
265  * instances are closed.
266  */
267 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
268 
269 /**
270  * Rename the specified file.
271  * @param from_path The full path to the original file (using / on all systems)
272  * @param to_path The full path to the new file (using / on all systems)
273  * @param pool The pool to use.
274  * @warning If a file exists at the new location, then it will be
275  * overwritten. Moving files or directories across devices may not be
276  * possible.
277  */
278 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
279  const char *to_path,
280  apr_pool_t *pool);
281 
282 /**
283  * Create a hard link to the specified file.
284  * @param from_path The full path to the original file (using / on all systems)
285  * @param to_path The full path to the new file (using / on all systems)
286  * @remark Both files must reside on the same device.
287  */
288 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path,
289  const char *to_path);
290 
291 /**
292  * Copy the specified file to another file.
293  * @param from_path The full path to the original file (using / on all systems)
294  * @param to_path The full path to the new file (using / on all systems)
295  * @param perms Access permissions for the new file if it is created.
296  * In place of the usual or'd combination of file permissions, the
297  * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
298  * file's permissions are copied.
299  * @param pool The pool to use.
300  * @remark The new file does not need to exist, it will be created if required.
301  * @warning If the new file already exists, its contents will be overwritten.
302  */
303 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
304  const char *to_path,
305  apr_fileperms_t perms,
306  apr_pool_t *pool);
307 
308 /**
309  * Append the specified file to another file.
310  * @param from_path The full path to the source file (use / on all systems)
311  * @param to_path The full path to the destination file (use / on all systems)
312  * @param perms Access permissions for the destination file if it is created.
313  * In place of the usual or'd combination of file permissions, the
314  * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
315  * file's permissions are copied.
316  * @param pool The pool to use.
317  * @remark The new file does not need to exist, it will be created if required.
318  * @remark Note that advanced filesystem permissions such as ACLs are not
319  * duplicated by this API. The target permissions (including duplicating the
320  * source file permissions) are assigned only when the target file does not yet
321  * exist.
322  */
323 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
324  const char *to_path,
325  apr_fileperms_t perms,
326  apr_pool_t *pool);
327 
328 /**
329  * Are we at the end of the file
330  * @param fptr The apr file we are testing.
331  * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise.
332  */
333 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
334 
335 /**
336  * Open standard error as an apr file pointer.
337  * @param thefile The apr file to use as stderr.
338  * @param pool The pool to allocate the file out of.
339  *
340  * @remark The only reason that the apr_file_open_std* functions exist
341  * is that you may not always have a stderr/out/in on Windows. This
342  * is generally a problem with newer versions of Windows and services.
343  *
344  * @remark The other problem is that the C library functions generally work
345  * differently on Windows and Unix. So, by using apr_file_open_std*
346  * functions, you can get a handle to an APR struct that works with
347  * the APR functions which are supposed to work identically on all
348  * platforms.
349  */
350 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
351  apr_pool_t *pool);
352 
353 /**
354  * open standard output as an apr file pointer.
355  * @param thefile The apr file to use as stdout.
356  * @param pool The pool to allocate the file out of.
357  *
358  * @remark See remarks for apr_file_open_stderr().
359  */
360 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
361  apr_pool_t *pool);
362 
363 /**
364  * open standard input as an apr file pointer.
365  * @param thefile The apr file to use as stdin.
366  * @param pool The pool to allocate the file out of.
367  *
368  * @remark See remarks for apr_file_open_stderr().
369  */
370 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
371  apr_pool_t *pool);
372 
373 /**
374  * open standard error as an apr file pointer, with flags.
375  * @param thefile The apr file to use as stderr.
376  * @param flags The flags to open the file with. Only the
377  * @li #APR_FOPEN_EXCL
378  * @li #APR_FOPEN_BUFFERED
379  * @li #APR_FOPEN_XTHREAD
380  * @li #APR_FOPEN_SHARELOCK
381  * @li #APR_FOPEN_SENDFILE_ENABLED
382  * @li #APR_FOPEN_LARGEFILE
383  *
384  * flags should be used. The #APR_FOPEN_WRITE flag will
385  * be set unconditionally.
386  * @param pool The pool to allocate the file out of.
387  *
388  * @remark See remarks for apr_file_open_stderr().
389  */
390 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile,
391  apr_int32_t flags,
392  apr_pool_t *pool);
393 
394 /**
395  * open standard output as an apr file pointer, with flags.
396  * @param thefile The apr file to use as stdout.
397  * @param flags The flags to open the file with. Only the
398  * @li #APR_FOPEN_EXCL
399  * @li #APR_FOPEN_BUFFERED
400  * @li #APR_FOPEN_XTHREAD
401  * @li #APR_FOPEN_SHARELOCK
402  * @li #APR_FOPEN_SENDFILE_ENABLED
403  * @li #APR_FOPEN_LARGEFILE
404  *
405  * flags should be used. The #APR_FOPEN_WRITE flag will
406  * be set unconditionally.
407  * @param pool The pool to allocate the file out of.
408  *
409  * @remark See remarks for apr_file_open_stderr().
410  */
411 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile,
412  apr_int32_t flags,
413  apr_pool_t *pool);
414 
415 /**
416  * open standard input as an apr file pointer, with flags.
417  * @param thefile The apr file to use as stdin.
418  * @param flags The flags to open the file with. Only the
419  * @li #APR_FOPEN_EXCL
420  * @li #APR_FOPEN_BUFFERED
421  * @li #APR_FOPEN_XTHREAD
422  * @li #APR_FOPEN_SHARELOCK
423  * @li #APR_FOPEN_SENDFILE_ENABLED
424  * @li #APR_FOPEN_LARGEFILE
425  *
426  * flags should be used. The #APR_FOPEN_WRITE flag will
427  * be set unconditionally.
428  * @param pool The pool to allocate the file out of.
429  *
430  * @remark See remarks for apr_file_open_stderr().
431  */
432 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile,
433  apr_int32_t flags,
434  apr_pool_t *pool);
435 
436 /**
437  * Read data from the specified file.
438  * @param thefile The file descriptor to read from.
439  * @param buf The buffer to store the data to.
440  * @param nbytes On entry, the number of bytes to read; on exit, the number
441  * of bytes read.
442  *
443  * @remark apr_file_read() will read up to the specified number of
444  * bytes, but never more. If there isn't enough data to fill that
445  * number of bytes, all of the available data is read. The third
446  * argument is modified to reflect the number of bytes read. If a
447  * char was put back into the stream via ungetc, it will be the first
448  * character returned.
449  *
450  * @remark It is not possible for both bytes to be read and an #APR_EOF
451  * or other error to be returned. #APR_EINTR is never returned.
452  */
453 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
454  apr_size_t *nbytes);
455 
456 /**
457  * Write data to the specified file.
458  * @param thefile The file descriptor to write to.
459  * @param buf The buffer which contains the data.
460  * @param nbytes On entry, the number of bytes to write; on exit, the number
461  * of bytes written.
462  *
463  * @remark apr_file_write() will write up to the specified number of
464  * bytes, but never more. If the OS cannot write that many bytes, it
465  * will write as many as it can. The third argument is modified to
466  * reflect the * number of bytes written.
467  *
468  * @remark It is possible for both bytes to be written and an error to
469  * be returned. #APR_EINTR is never returned.
470  */
471 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
472  apr_size_t *nbytes);
473 
474 /**
475  * Write data from iovec array to the specified file.
476  * @param thefile The file descriptor to write to.
477  * @param vec The array from which to get the data to write to the file.
478  * @param nvec The number of elements in the struct iovec array. This must
479  * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function
480  * will fail with #APR_EINVAL.
481  * @param nbytes The number of bytes written.
482  *