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
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.
22 * @brief APR File I/O Handling
26 #include "apr_pools.h"
28 #include "apr_errno.h"
29 #include "apr_file_info.h"
30 #include "apr_inherit.h"
32 #define APR_WANT_STDIO /**< for SEEK_* */
33 #define APR_WANT_IOVEC /**< for apr_file_writev */
38 #endif /* __cplusplus */
41 * @defgroup apr_file_io File I/O Handling Functions
47 * @defgroup apr_file_open_flags File Open Flags/Routines
51 /* Note to implementors: Values in the range 0x00100000--0x80000000
52 are reserved for platform-specific values. */
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
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
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
70 #define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for
71 higher level locked read/write
72 access to support writes across
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
79 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
81 apr_socket_sendfile operation */
82 #define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable
83 * large file support, see WARNING below
85 #define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable
86 * sparse file support, see WARNING below
88 #define APR_FOPEN_NONBLOCK 0x40000 /**< Platform dependent flag to enable
89 * non blocking file io */
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 */
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
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().
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.
139 * @defgroup apr_file_seek_flags File Seek Flags
143 /* flags for apr_file_seek */
144 /** Set the file position */
145 #define APR_SET SEEK_SET
147 #define APR_CUR SEEK_CUR
148 /** Go to end of file */
149 #define APR_END SEEK_END
153 * @defgroup apr_file_attrs_set_flags File Attribute Flags
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 */
164 * @defgroup apr_file_writev{_full} max iovec size
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
175 #define APR_MAX_IOVEC_SIZE 1024
179 /** File attributes */
180 typedef apr_uint32_t apr_fileattrs_t;
182 /** Type to pass as whence argument to apr_file_seek. */
183 typedef int apr_seek_where_t;
186 * Structure for referencing files.
188 typedef struct apr_file_t apr_file_t;
190 /* File lock types/flags */
192 * @defgroup apr_file_lock_types File Lock Types
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
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
207 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
208 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
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_ROTATING Do file file rotation checking
241 * @li #APR_FOPEN_MANUAL_ROTATE Enable Manual rotation
242 * @li #APR_FOPEN_NONBLOCK Platform dependent flag to enable
243 * non blocking file io
244 * @param perm Access permissions for file.
245 * @param pool The pool to use.
246 * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created,
247 * appropriate default permissions will be used.
248 * @remark By default, the returned file descriptor will not be
249 * inherited by child processes created by apr_proc_create(). This
250 * can be changed using apr_file_inherit_set().
252 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
253 apr_int32_t flag, apr_fileperms_t perm,
257 * Close the specified file.
258 * @param file The file descriptor to close.
260 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
263 * Delete the specified file.
264 * @param path The full path to the file (using / on all systems)
265 * @param pool The pool to use.
266 * @remark If the file is open, it won't be removed until all
267 * instances are closed.
269 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
272 * Rename the specified file.
273 * @param from_path The full path to the original file (using / on all systems)
274 * @param to_path The full path to the new file (using / on all systems)
275 * @param pool The pool to use.
276 * @warning If a file exists at the new location, then it will be
277 * overwritten. Moving files or directories across devices may not be
280 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
285 * Create a hard link to the specified file.
286 * @param from_path The full path to the original file (using / on all systems)
287 * @param to_path The full path to the new file (using / on all systems)
288 * @remark Both files must reside on the same device.
290 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path,
291 const char *to_path);
294 * Copy the specified file to another file.
295 * @param from_path The full path to the original file (using / on all systems)
296 * @param to_path The full path to the new file (using / on all systems)
297 * @param perms Access permissions for the new file if it is created.
298 * In place of the usual or'd combination of file permissions, the
299 * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
300 * file's permissions are copied.
301 * @param pool The pool to use.
302 * @remark The new file does not need to exist, it will be created if required.
303 * @warning If the new file already exists, its contents will be overwritten.
305 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
307 apr_fileperms_t perms,
311 * Append the specified file to another file.
312 * @param from_path The full path to the source file (use / on all systems)
313 * @param to_path The full path to the destination file (use / on all systems)
314 * @param perms Access permissions for the destination file if it is created.
315 * In place of the usual or'd combination of file permissions, the
316 * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
317 * file's permissions are copied.
318 * @param pool The pool to use.
319 * @remark The new file does not need to exist, it will be created if required.
321 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
323 apr_fileperms_t perms,
327 * Are we at the end of the file
328 * @param fptr The apr file we are testing.
329 * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise.
331 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
334 * Open standard error as an apr file pointer.
335 * @param thefile The apr file to use as stderr.
336 * @param pool The pool to allocate the file out of.
338 * @remark The only reason that the apr_file_open_std* functions exist
339 * is that you may not always have a stderr/out/in on Windows. This
340 * is generally a problem with newer versions of Windows and services.
342 * @remark The other problem is that the C library functions generally work
343 * differently on Windows and Unix. So, by using apr_file_open_std*
344 * functions, you can get a handle to an APR struct that works with
345 * the APR functions which are supposed to work identically on all
348 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
352 * open standard output as an apr file pointer.
353 * @param thefile The apr file to use as stdout.
354 * @param pool The pool to allocate the file out of.
356 * @remark See remarks for apr_file_open_stderr().
358 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
362 * open standard input as an apr file pointer.
363 * @param thefile The apr file to use as stdin.
364 * @param pool The pool to allocate the file out of.
366 * @remark See remarks for apr_file_open_stderr().
368 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
372 * open standard error as an apr file pointer, with flags.
373 * @param thefile The apr file to use as stderr.
374 * @param flags The flags to open the file with. Only the
375 * @li #APR_FOPEN_EXCL
376 * @li #APR_FOPEN_BUFFERED
377 * @li #APR_FOPEN_XTHREAD
378 * @li #APR_FOPEN_SHARELOCK
379 * @li #APR_FOPEN_SENDFILE_ENABLED
380 * @li #APR_FOPEN_LARGEFILE
382 * flags should be used. The #APR_FOPEN_WRITE flag will
383 * be set unconditionally.
384 * @param pool The pool to allocate the file out of.
386 * @remark See remarks for apr_file_open_stderr().
388 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile,
393 * open standard output as an apr file pointer, with flags.
394 * @param thefile The apr file to use as stdout.
395 * @param flags The flags to open the file with. Only the
396 * @li #APR_FOPEN_EXCL
397 * @li #APR_FOPEN_BUFFERED
398 * @li #APR_FOPEN_XTHREAD
399 * @li #APR_FOPEN_SHARELOCK
400 * @li #APR_FOPEN_SENDFILE_ENABLED
401 * @li #APR_FOPEN_LARGEFILE
403 * flags should be used. The #APR_FOPEN_WRITE flag will
404 * be set unconditionally.
405 * @param pool The pool to allocate the file out of.
407 * @remark See remarks for apr_file_open_stderr().
409 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile,
414 * open standard input as an apr file pointer, with flags.
415 * @param thefile The apr file to use as stdin.
416 * @param flags The flags to open the file with. Only the
417 * @li #APR_FOPEN_EXCL
418 * @li #APR_FOPEN_BUFFERED
419 * @li #APR_FOPEN_XTHREAD
420 * @li #APR_FOPEN_SHARELOCK
421 * @li #APR_FOPEN_SENDFILE_ENABLED
422 * @li #APR_FOPEN_LARGEFILE
424 * flags should be used. The #APR_FOPEN_WRITE flag will
425 * be set unconditionally.
426 * @param pool The pool to allocate the file out of.
428 * @remark See remarks for apr_file_open_stderr().
430 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile,
435 * Read data from the specified file.
436 * @param thefile The file descriptor to read from.
437 * @param buf The buffer to store the data to.
438 * @param nbytes On entry, the number of bytes to read; on exit, the number
441 * @remark apr_file_read() will read up to the specified number of
442 * bytes, but never more. If there isn't enough data to fill that
443 * number of bytes, all of the available data is read. The third
444 * argument is modified to reflect the number of bytes read. If a
445 * char was put back into the stream via ungetc, it will be the first
446 * character returned.
448 * @remark It is not possible for both bytes to be read and an #APR_EOF
449 * or other error to be returned. #APR_EINTR is never returned.
451 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
455 * Write data to the specified file.
456 * @param thefile The file descriptor to write to.
457 * @param buf The buffer which contains the data.
458 * @param nbytes On entry, the number of bytes to write; on exit, the number
461 * @remark apr_file_write() will write up to the specified number of
462 * bytes, but never more. If the OS cannot write that many bytes, it
463 * will write as many as it can. The third argument is modified to
464 * reflect the * number of bytes written.
466 * @remark It is possible for both bytes to be written and an error to
467 * be returned. #APR_EINTR is never returned.
469 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
473 * Write data from iovec array to the specified file.
474 * @param thefile The file descriptor to write to.
475 * @param vec The array from which to get the data to write to the file.
476 * @param nvec The number of elements in the struct iovec array. This must
477 * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function
478 * will fail with #APR_EINVAL.
479 * @param nbytes The number of bytes written.
481 * @remark It is possible for both bytes to be written and an error to
482 * be returned. #APR_EINTR is never returned.
484 * @remark apr_file_writev() is available even if the underlying
485 * operating system doesn't provide writev().
487 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
488 const struct iovec *vec,
489 apr_size_t nvec, apr_size_t *nbytes);
492 * Read data from the specified file, ensuring that the buffer is filled
494 * @param thefile The file descriptor to read from.
495 * @param buf The buffer to store the data to.
496 * @param nbytes The number of bytes to read.
497 * @param bytes_read If non-NULL, this will contain the number of bytes read.
499 * @remark apr_file_read_full() will read up to the specified number of
500 * bytes, but never more. If there isn't enough data to fill that
501 * number of bytes, then the process/thread will block until it is
502 * available or EOF is reached. If a char was put back into the
503 * stream via ungetc, it will be the first character returned.
505 * @remark It is possible for both bytes to be read and an error to be
506 * returned. And if *bytes_read is less than nbytes, an accompanying
507 * error is _always_ returned.
509 * @remark #APR_EINTR is never returned.
511 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
513 apr_size_t *bytes_read);
516 * Write data to the specified file, ensuring that all of the data is
517 * written before returning.
518 * @param thefile The file descriptor to write to.
519 * @param buf The buffer which contains the data.
520 * @param nbytes The number of bytes to write.
521 * @param bytes_written If non-NULL, set to the number of bytes written.
523 * @remark apr_file_write_full() will write up to the specified number of
524 * bytes, but never more. If the OS cannot write that many bytes, the
525 * process/thread will block until they can be written. Exceptional
526 * error such as "out of space" or "pipe closed" will terminate with
529 * @remark It is possible for both bytes to be written and an error to
530 * be returned. And if *bytes_written is less than nbytes, an
531 * accompanying error is _always_ returned.
533 * @remark #APR_EINTR is never returned.
535 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile,
538 apr_size_t *bytes_written);
542 * Write data from iovec array to the specified file, ensuring that all of the
543 * data is written before returning.
544 * @param thefile The file descriptor to write to.
545 * @param vec The array from which to get the data to write to the file.
546 * @param nvec The number of elements in the struct iovec array. This must
547 * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function
548 * will fail with #APR_EINVAL.
549 * @param nbytes The number of bytes written.
551 * @remark apr_file_writev_full() is available even if the underlying
552 * operating system doesn't provide writev().
554 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile,
555 const struct iovec *vec,
559 * Write a character into the specified file.
560 * @param ch The character to write.
561 * @param thefile The file descriptor to write to
563 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
566 * Read a character from the specified file.
567 * @param ch The character to read into
568 * @param thefile The file descriptor to read from
570 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
573 * Put a character back onto a specified stream.
574 * @param ch The character to write.
575 * @param thefile The file descriptor to write to
577 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
580 * Read a line from the specified file
581 * @param str The buffer to store the string in.
582 * @param len The length of the string
583 * @param thefile The file descriptor to read from
584 * @remark The buffer will be NUL-terminated if any characters are stored.
585 * The newline at the end of the line will not be stripped.
587 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len,
588 apr_file_t *thefile);
591 * Write the string into the specified file.
592 * @param str The string to write.
593 * @param thefile The file descriptor to write to
595 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
598 * Flush the file's buffer.
599 * @param thefile The file descriptor to flush
601 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
604 * Transfer all file modified data and metadata to disk.
605 * @param thefile The file descriptor to sync
607 APR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile);
610 * Transfer all file modified data to disk.
611 * @param thefile The file descriptor to sync
613 APR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile);
616 * Duplicate the specified file descriptor.
617 * @param new_file The structure to duplicate into.
618 * @param old_file The file to duplicate.
619 * @param p The pool to use for the new file.
620 * @remark *new_file must point to a valid apr_file_t, or point to NULL.
622 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
623 apr_file_t *old_file,
627 * Duplicate the specified file descriptor and close the original
628 * @param new_file The old file that is to be closed and reused
629 * @param old_file The file to duplicate
630 * @param p The pool to use for the new file
632 * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
634 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
635 apr_file_t *old_file,
639 * Move the specified file descriptor to a new pool
640 * @param new_file Pointer in which to return the new apr_file_t
641 * @param old_file The file to move
642 * @param p The pool to which the descriptor is to be moved
643 * @remark Unlike apr_file_dup2(), this function doesn't do an
644 * OS dup() operation on the underlying descriptor; it just
645 * moves the descriptor's apr_file_t wrapper to a new pool.
646 * @remark The new pool need not be an ancestor of old_file's pool.
647 * @remark After calling this function, old_file may not be used
649 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
650 apr_file_t *old_file,
654 * Give the specified apr file handle a new buffer
655 * @param thefile The file handle that is to be modified
656 * @param buffer The buffer
657 * @param bufsize The size of the buffer
658 * @remark It is possible to add a buffer to previously unbuffered
659 * file handles, the #APR_FOPEN_BUFFERED flag will be added to
660 * the file handle's flags. Likewise, with buffer=NULL and
661 * bufsize=0 arguments it is possible to make a previously
662 * buffered file handle unbuffered.
664 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile,
669 * Get the size of any buffer for the specified apr file handle
670 * @param thefile The file handle
672 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile);
675 * Move the read/write file offset to a specified byte within a file.
676 * @param thefile The file descriptor
677 * @param where How to move the pointer, one of:
678 * @li #APR_SET -- set the offset to offset
679 * @li #APR_CUR -- add the offset to the current position
680 * @li #APR_END -- add the offset to the current file size
681 * @param offset The offset to move the pointer to.
682 * @remark The third argument is modified to be the offset the pointer
683 was actually moved to.
685 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
686 apr_seek_where_t where,
690 * Create an anonymous pipe.
691 * @param in The newly created pipe's file for reading.
692 * @param out The newly created pipe's file for writing.
693 * @param pool The pool to operate on.
694 * @remark By default, the returned file descriptors will be inherited
695 * by child processes created using apr_proc_create(). This can be
696 * changed using apr_file_inherit_unset().
697 * @bug Some platforms cannot toggle between blocking and nonblocking,
698 * and when passing a pipe as a standard handle to an application which
699 * does not expect it, a non-blocking stream will fluxor the client app.
700 * @deprecated @see apr_file_pipe_create_ex()
702 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in,
707 * Create an anonymous pipe which portably supports async timeout options.
708 * @param in The newly created pipe's file for reading.
709 * @param out The newly created pipe's file for writing.
710 * @param blocking one of these values defined in apr_thread_proc.h;
711 * @li #APR_FULL_BLOCK
712 * @li #APR_READ_BLOCK
713 * @li #APR_WRITE_BLOCK
714 * @li #APR_FULL_NONBLOCK
715 * @param pool The pool to operate on.
716 * @remark By default, the returned file descriptors will be inherited
717 * by child processes created using apr_proc_create(). This can be
718 * changed using apr_file_inherit_unset().
719 * @remark Some platforms cannot toggle between blocking and nonblocking,
720 * and when passing a pipe as a standard handle to an application which
721 * does not expect it, a non-blocking stream will fluxor the client app.
722 * Use this function rather than apr_file_pipe_create() to create pipes
723 * where one or both ends require non-blocking semantics.
725 APR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in,
727 apr_int32_t blocking,
731 * Create a named pipe.
732 * @param filename The filename of the named pipe
733 * @param perm The permissions for the newly created pipe.
734 * @param pool The pool to operate on.
736 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
737 apr_fileperms_t perm,
741 * Get the timeout value for a pipe or manipulate the blocking state.
742 * @param thepipe The pipe we are getting a timeout for.
743 * @param timeout The current timeout value in microseconds.
745 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
746 apr_interval_time_t *timeout);
749 * Set the timeout value for a pipe or manipulate the blocking state.
750 * @param thepipe The pipe we are setting a timeout on.
751 * @param timeout The timeout value in microseconds. Values < 0 mean wait
752 * forever, 0 means do not wait at all.
754 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe,
755 apr_interval_time_t timeout);
757 /** file (un)locking functions. */
760 * Establish a lock on the specified, open file. The lock may be advisory
761 * or mandatory, at the discretion of the platform. The lock applies to
762 * the file as a whole, rather than a specific range. Locks are established
763 * on a per-thread/process basis; a second lock by the same thread will not
765 * @param thefile The file to lock.
766 * @param type The type of lock to establish on the file.
768 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
771 * Remove any outstanding locks on the file.
772 * @param thefile The file to unlock.
774 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
776 /**accessor and general file_io functions. */
779 * return the file name of the current file.
780 * @param new_path The path of the file.
781 * @param thefile The currently open file.
783 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
784 apr_file_t *thefile);
787 * Return the data associated with the current file.
788 * @param data The user data associated with the file.
789 * @param key The key to use for retrieving data associated with this file.
790 * @param file The currently open file.
792 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
796 * Set the data associated with the current file.
797 * @param file The currently open file.
798 * @param data The user data to associate with the file.
799 * @param key The key to use for associating data with the file.
800 * @param cleanup The cleanup routine to use when the file is destroyed.
802 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
804 apr_status_t (*cleanup)(void *));
807 * Write a string to a file using a printf format.
808 * @param fptr The file to write to.
809 * @param format The format string
810 * @param ... The values to substitute in the format string
811 * @return The number of bytes written
813 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr,
814 const char *format, ...)
815 __attribute__((format(printf,2,3)));
818 * set the specified file's permission bits.
819 * @param fname The file (name) to apply the permissions to.
820 * @param perms The permission bits to apply to the file.
822 * @warning Some platforms may not be able to apply all of the
823 * available permission bits; #APR_INCOMPLETE will be returned if some
824 * permissions are specified which could not be set.
826 * @warning Platforms which do not implement this feature will return
829 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
830 apr_fileperms_t perms);
833 * Set attributes of the specified file.
834 * @param fname The full path to the file (using / on all systems)
835 * @param attributes Or'd combination of
836 * @li #APR_FILE_ATTR_READONLY - make the file readonly
837 * @li #APR_FILE_ATTR_EXECUTABLE - make the file executable
838 * @li #APR_FILE_ATTR_HIDDEN - make the file hidden
839 * @param attr_mask Mask of valid bits in attributes.
840 * @param pool the pool to use.
841 * @remark This function should be used in preference to explicit manipulation
842 * of the file permissions, because the operations to provide these
843 * attributes are platform specific and may involve more than simply
844 * setting permission bits.
845 * @warning Platforms which do not implement this feature will return
848 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
849 apr_fileattrs_t attributes,
850 apr_fileattrs_t attr_mask,
854 * Set the mtime of the specified file.
855 * @param fname The full path to the file (using / on all systems)
856 * @param mtime The mtime to apply to the file.
857 * @param pool The pool to use.
858 * @warning Platforms which do not implement this feature will return
861 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
866 * Create a new directory on the file system.
867 * @param path the path for the directory to be created. (use / on all systems)
868 * @param perm Permissions for the new directory.
869 * @param pool the pool to use.
871 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
874 /** Creates a new directory on the file system, but behaves like
875 * 'mkdir -p'. Creates intermediate directories as required. No error
876 * will be reported if PATH already exists.
877 * @param path the path for the directory to be created. (use / on all systems)
878 * @param perm Permissions for the new directory.
879 * @param pool the pool to use.
881 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
882 apr_fileperms_t perm,
886 * Remove directory from the file system.
887 * @param path the path for the directory to be removed. (use / on all systems)
888 * @param pool the pool to use.
889 * @remark Removing a directory which is in-use (e.g., the current working
890 * directory, or during apr_dir_read, or with an open file) is not portable.
892 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
895 * get the specified file's stats.
896 * @param finfo Where to store the information about the file.
897 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values
898 * @param thefile The file to get information about.
900 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
902 apr_file_t *thefile);
906 * Truncate the file's length to the specified offset
907 * @param fp The file to truncate
908 * @param offset The offset to truncate to.
909 * @remark The read/write file offset is repositioned to offset.
911 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
914 * Retrieve the flags that were passed into apr_file_open()
915 * when the file was opened.
916 * @return apr_int32_t the flags
918 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
921 * Get the pool used by the file.
923 APR_POOL_DECLARE_ACCESSOR(file);
926 * Set a file to be inherited by child processes.
929 APR_DECLARE_INHERIT_SET(file);
932 * Unset a file from being inherited by child processes.
934 APR_DECLARE_INHERIT_UNSET(file);
937 * Open a temporary file
938 * @param fp The apr file to use as a temporary file.
939 * @param templ The template to use when creating a temp file.
940 * @param flags The flags to open the file with. If this is zero,
941 * the file is opened with
942 * #APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE |
943 * #APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE
944 * @param p The pool to allocate the file out of.
946 * This function generates a unique temporary file name from template.
947 * The last six characters of template must be XXXXXX and these are replaced
948 * with a string that makes the filename unique. Since it will be modified,
949 * template must not be a string constant, but should be declared as a character
953 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
954 apr_int32_t flags, apr_pool_t *p);
958 * Find an existing directory suitable as a temporary storage location.
959 * @param temp_dir The temp directory.
960 * @param p The pool to use for any necessary allocations.
962 * This function uses an algorithm to search for a directory that an
963 * an application can use for temporary storage.
966 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir,
975 #endif /* ! APR_FILE_IO_H */