diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/apr_file_io.h | 197 |
1 files changed, 110 insertions, 87 deletions
diff --git a/include/apr_file_io.h b/include/apr_file_io.h index 5ea3d59c5..e2dffec73 100644 --- a/include/apr_file_io.h +++ b/include/apr_file_io.h @@ -57,8 +57,10 @@ extern "C" { #define APR_FOPEN_APPEND 0x00008 /**< Append to the end of the file */ #define APR_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate to 0 length */ -#define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode */ -#define APR_FOPEN_EXCL 0x00040 /**< Open should fail if APR_CREATE +#define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode + (This flag is ignored on UNIX + because it has no meaning)*/ +#define APR_FOPEN_EXCL 0x00040 /**< Open should fail if #APR_FOPEN_CREATE and file exists. */ #define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */ #define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */ @@ -70,7 +72,10 @@ extern "C" { access to support writes across process/machines */ #define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup - when the file is opened */ + when the file is opened. The + apr_os_file_t handle in apr_file_t + will not be closed when the pool + is destroyed. */ #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this file should support apr_socket_sendfile operation */ @@ -100,17 +105,19 @@ extern "C" { #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */ #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */ -/** @warning APR_FOPEN_LARGEFILE flag only has effect on some +/** @def APR_FOPEN_LARGEFILE + * @warning APR_FOPEN_LARGEFILE flag only has effect on some * platforms where sizeof(apr_off_t) == 4. Where implemented, it * allows opening and writing to a file which exceeds the size which * can be represented by apr_off_t (2 gigabytes). When a file's size * does exceed 2Gb, apr_file_info_get() will fail with an error on the * descriptor, likewise apr_stat()/apr_lstat() will fail on the - * filename. apr_dir_read() will fail with APR_INCOMPLETE on a + * filename. apr_dir_read() will fail with #APR_INCOMPLETE on a * directory entry for a large file depending on the particular * APR_FINFO_* flags. Generally, it is not recommended to use this * flag. * + * @def APR_FOPEN_SPARSE * @warning APR_FOPEN_SPARSE may, depending on platform, convert a * normal file to a sparse file. Some applications may be unable * to decipher a sparse file, so it's critical that the sparse file @@ -203,33 +210,36 @@ typedef struct apr_file_t apr_file_t; * @param newf The opened file descriptor. * @param fname The full path to the file (using / on all systems) * @param flag Or'ed value of: - * <PRE> - * APR_READ open for reading - * APR_WRITE open for writing - * APR_CREATE create the file if not there - * APR_APPEND file ptr is set to end prior to all writes - * APR_TRUNCATE set length to zero if file exists - * APR_BINARY not a text file (This flag is ignored on - * UNIX because it has no meaning) - * APR_BUFFERED buffer the data. Default is non-buffered - * APR_EXCL return error if APR_CREATE and file exists - * APR_DELONCLOSE delete the file after closing. - * APR_XTHREAD Platform dependent tag to open the file + * @li #APR_FOPEN_READ open for reading + * @li #APR_FOPEN_WRITE open for writing + * @li #APR_FOPEN_CREATE create the file if not there + * @li #APR_FOPEN_APPEND file ptr is set to end prior to all writes + * @li #APR_FOPEN_TRUNCATE set length to zero if file exists + * @li #APR_FOPEN_BINARY not a text file + * @li #APR_FOPEN_BUFFERED buffer the data. Default is non-buffered + * @li #APR_FOPEN_EXCL return error if #APR_FOPEN_CREATE and file exists + * @li #APR_FOPEN_DELONCLOSE delete the file after closing + * @li #APR_FOPEN_XTHREAD Platform dependent tag to open the file * for use across multiple threads - * APR_SHARELOCK Platform dependent support for higher + * @li #APR_FOPEN_SHARELOCK Platform dependent support for higher * level locked read/write access to support * writes across process/machines - * APR_FILE_NOCLEANUP Do not register a cleanup with the pool - * passed in on the <EM>pool</EM> argument (see below). - * The apr_os_file_t handle in apr_file_t will not - * be closed when the pool is destroyed. - * APR_SENDFILE_ENABLED Open with appropriate platform semantics + * @li #APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool + * passed in on the @a pool argument (see below) + * @li #APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics * for sendfile operations. Advisory only, - * apr_socket_sendfile does not check this flag. - * </PRE> + * apr_socket_sendfile does not check this flag + * @li #APR_FOPEN_LARGEFILE Platform dependent flag to enable large file + * support, see WARNING below + * @li #APR_FOPEN_SPARSE Platform dependent flag to enable sparse file + * support, see WARNING below + * @li #APR_FOPEN_ROTATING Do file file rotation checking + * @li #APR_FOPEN_MANUAL_ROTATE Enable Manual rotation + * @li #APR_FOPEN_NONBLOCK Platform dependent flag to enable + * non blocking file io * @param perm Access permissions for file. * @param pool The pool to use. - * @remark If perm is APR_OS_DEFAULT and the file is being created, + * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created, * appropriate default permissions will be used. * @remark By default, the returned file descriptor will not be * inherited by child processes created by apr_proc_create(). This @@ -282,7 +292,7 @@ APR_DECLARE(apr_status_t) apr_file_link(const char *from_path, * @param to_path The full path to the new file (using / on all systems) * @param perms Access permissions for the new file if it is created. * In place of the usual or'd combination of file permissions, the - * value APR_FILE_SOURCE_PERMS may be given, in which case the source + * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source * file's permissions are copied. * @param pool The pool to use. * @remark The new file does not need to exist, it will be created if required. @@ -299,7 +309,7 @@ APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, * @param to_path The full path to the destination file (use / on all systems) * @param perms Access permissions for the destination file if it is created. * In place of the usual or'd combination of file permissions, the - * value APR_FILE_SOURCE_PERMS may be given, in which case the source + * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source * file's permissions are copied. * @param pool The pool to use. * @remark The new file does not need to exist, it will be created if required. @@ -312,7 +322,7 @@ APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, /** * Are we at the end of the file * @param fptr The apr file we are testing. - * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise. + * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise. */ APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); @@ -339,7 +349,7 @@ APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, * @param thefile The apr file to use as stdout. * @param pool The pool to allocate the file out of. * - * @remark See remarks for apr_file_open_stderr. + * @remark See remarks for apr_file_open_stderr(). */ APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, apr_pool_t *pool); @@ -349,7 +359,7 @@ APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, * @param thefile The apr file to use as stdin. * @param pool The pool to allocate the file out of. * - * @remark See remarks for apr_file_open_stderr. + * @remark See remarks for apr_file_open_stderr(). */ APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, apr_pool_t *pool); @@ -357,13 +367,19 @@ APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, /** * open standard error as an apr file pointer, with flags. * @param thefile The apr file to use as stderr. - * @param flags The flags to open the file with. Only the APR_EXCL, - * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, - * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should - * be used. The APR_WRITE flag will be set unconditionally. + * @param flags The flags to open the file with. Only the + * @li #APR_FOPEN_EXCL + * @li #APR_FOPEN_BUFFERED + * @li #APR_FOPEN_XTHREAD + * @li #APR_FOPEN_SHARELOCK + * @li #APR_FOPEN_SENDFILE_ENABLED + * @li #APR_FOPEN_LARGEFILE + * + * flags should be used. The #APR_FOPEN_WRITE flag will + * be set unconditionally. * @param pool The pool to allocate the file out of. * - * @remark See remarks for apr_file_open_stderr. + * @remark See remarks for apr_file_open_stderr(). */ APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile, apr_int32_t flags, @@ -372,13 +388,19 @@ APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile, /** * open standard output as an apr file pointer, with flags. * @param thefile The apr file to use as stdout. - * @param flags The flags to open the file with. Only the APR_EXCL, - * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, - * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should - * be used. The APR_WRITE flag will be set unconditionally. + * @param flags The flags to open the file with. Only the + * @li #APR_FOPEN_EXCL + * @li #APR_FOPEN_BUFFERED + * @li #APR_FOPEN_XTHREAD + * @li #APR_FOPEN_SHARELOCK + * @li #APR_FOPEN_SENDFILE_ENABLED + * @li #APR_FOPEN_LARGEFILE + * + * flags should be used. The #APR_FOPEN_WRITE flag will + * be set unconditionally. * @param pool The pool to allocate the file out of. * - * @remark See remarks for apr_file_open_stderr. + * @remark See remarks for apr_file_open_stderr(). */ APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile, apr_int32_t flags, @@ -387,13 +409,19 @@ APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile, /** * open standard input as an apr file pointer, with flags. * @param thefile The apr file to use as stdin. - * @param flags The flags to open the file with. Only the APR_EXCL, - * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, - * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should - * be used. The APR_READ flag will be set unconditionally. + * @param flags The flags to open the file with. Only the + * @li #APR_FOPEN_EXCL + * @li #APR_FOPEN_BUFFERED + * @li #APR_FOPEN_XTHREAD + * @li #APR_FOPEN_SHARELOCK + * @li #APR_FOPEN_SENDFILE_ENABLED + * @li #APR_FOPEN_LARGEFILE + * + * flags should be used. The #APR_FOPEN_WRITE flag will + * be set unconditionally. * @param pool The pool to allocate the file out of. * - * @remark See remarks for apr_file_open_stderr. + * @remark See remarks for apr_file_open_stderr(). */ APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile, apr_int32_t flags, @@ -406,15 +434,15 @@ APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile, * @param nbytes On entry, the number of bytes to read; on exit, the number * of bytes read. * - * @remark apr_file_read will read up to the specified number of + * @remark apr_file_read() will read up to the specified number of * bytes, but never more. If there isn't enough data to fill that * number of bytes, all of the available data is read. The third * argument is modified to reflect the number of bytes read. If a * char was put back into the stream via ungetc, it will be the first * character returned. * - * @remark It is not possible for both bytes to be read and an APR_EOF - * or other error to be returned. APR_EINTR is never returned. + * @remark It is not possible for both bytes to be read and an #APR_EOF + * or other error to be returned. #APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, apr_size_t *nbytes); @@ -426,13 +454,13 @@ APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, * @param nbytes On entry, the number of bytes to write; on exit, the number * of bytes written. * - * @remark apr_file_write will write up to the specified number of + * @remark apr_file_write() will write up to the specified number of * bytes, but never more. If the OS cannot write that many bytes, it * will write as many as it can. The third argument is modified to * reflect the * number of bytes written. * * @remark It is possible for both bytes to be written and an error to - * be returned. APR_EINTR is never returned. + * be returned. #APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, apr_size_t *nbytes); @@ -442,14 +470,14 @@ APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, * @param thefile The file descriptor to write to. * @param vec The array from which to get the data to write to the file. * @param nvec The number of elements in the struct iovec array. This must - * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function - * will fail with APR_EINVAL. + * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function + * will fail with #APR_EINVAL. * @param nbytes The number of bytes written. * * @remark It is possible for both bytes to be written and an error to - * be returned. APR_EINTR is never returned. + * be returned. #APR_EINTR is never returned. * - * @remark apr_file_writev is available even if the underlying + * @remark apr_file_writev() is available even if the underlying * operating system doesn't provide writev(). */ APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, @@ -464,7 +492,7 @@ APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, * @param nbytes The number of bytes to read. * @param bytes_read If non-NULL, this will contain the number of bytes read. * - * @remark apr_file_read will read up to the specified number of + * @remark apr_file_read_full() will read up to the specified number of * bytes, but never more. If there isn't enough data to fill that * number of bytes, then the process/thread will block until it is * available or EOF is reached. If a char was put back into the @@ -474,7 +502,7 @@ APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, * returned. And if *bytes_read is less than nbytes, an accompanying * error is _always_ returned. * - * @remark APR_EINTR is never returned. + * @remark #APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, apr_size_t nbytes, @@ -488,7 +516,7 @@ APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, * @param nbytes The number of bytes to write. * @param bytes_written If non-NULL, set to the number of bytes written. * - * @remark apr_file_write will write up to the specified number of + * @remark apr_file_write_full() will write up to the specified number of * bytes, but never more. If the OS cannot write that many bytes, the * process/thread will block until they can be written. Exceptional * error such as "out of space" or "pipe closed" will terminate with @@ -498,7 +526,7 @@ APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, * be returned. And if *bytes_written is less than nbytes, an * accompanying error is _always_ returned. * - * @remark APR_EINTR is never returned. + * @remark #APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf, @@ -512,11 +540,11 @@ APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, * @param thefile The file descriptor to write to. * @param vec The array from which to get the data to write to the file. * @param nvec The number of elements in the struct iovec array. This must - * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function - * will fail with APR_EINVAL. + * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function + * will fail with #APR_EINVAL. * @param nbytes The number of bytes written. * - * @remark apr_file_writev_full is available even if the underlying + * @remark apr_file_writev_full() is available even if the underlying * operating system doesn't provide writev(). */ APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile, @@ -624,7 +652,7 @@ APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file, * @param buffer The buffer * @param bufsize The size of the buffer * @remark It is possible to add a buffer to previously unbuffered - * file handles, the APR_BUFFERED flag will be added to + * file handles, the #APR_FOPEN_BUFFERED flag will be added to * the file handle's flags. Likewise, with buffer=NULL and * bufsize=0 arguments it is possible to make a previously * buffered file handle unbuffered. @@ -643,11 +671,9 @@ APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); * Move the read/write file offset to a specified byte within a file. * @param thefile The file descriptor * @param where How to move the pointer, one of: - * <PRE> - * APR_SET -- set the offset to offset - * APR_CUR -- add the offset to the current position - * APR_END -- add the offset to the current file size - * </PRE> + * @li #APR_SET -- set the offset to offset + * @li #APR_CUR -- add the offset to the current position + * @li #APR_END -- add the offset to the current file size * @param offset The offset to move the pointer to. * @remark The third argument is modified to be the offset the pointer was actually moved to. @@ -667,7 +693,7 @@ APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, * @bug Some platforms cannot toggle between blocking and nonblocking, * and when passing a pipe as a standard handle to an application which * does not expect it, a non-blocking stream will fluxor the client app. - * @deprecated @see apr_file_pipe_create_ex + * @deprecated @see apr_file_pipe_create_ex() */ APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out, @@ -678,20 +704,18 @@ APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, * @param in The newly created pipe's file for reading. * @param out The newly created pipe's file for writing. * @param blocking one of these values defined in apr_thread_proc.h; + * @li #APR_FULL_BLOCK + * @li #APR_READ_BLOCK + * @li #APR_WRITE_BLOCK + * @li #APR_FULL_NONBLOCK * @param pool The pool to operate on. - * <pre> - * APR_FULL_BLOCK - * APR_READ_BLOCK - * APR_WRITE_BLOCK - * APR_FULL_NONBLOCK - * </pre> * @remark By default, the returned file descriptors will be inherited * by child processes created using apr_proc_create(). This can be * changed using apr_file_inherit_unset(). * @remark Some platforms cannot toggle between blocking and nonblocking, * and when passing a pipe as a standard handle to an application which * does not expect it, a non-blocking stream will fluxor the client app. - * Use this function rather than apr_file_pipe_create to create pipes + * Use this function rather than apr_file_pipe_create() to create pipes * where one or both ends require non-blocking semantics. */ APR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in, @@ -792,11 +816,11 @@ APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, * @param perms The permission bits to apply to the file. * * @warning Some platforms may not be able to apply all of the - * available permission bits; APR_INCOMPLETE will be returned if some + * available permission bits; #APR_INCOMPLETE will be returned if some * permissions are specified which could not be set. * * @warning Platforms which do not implement this feature will return - * APR_ENOTIMPL. + * #APR_ENOTIMPL. */ APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, apr_fileperms_t perms); @@ -805,11 +829,9 @@ APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, * Set attributes of the specified file. * @param fname The full path to the file (using / on all systems) * @param attributes Or'd combination of - * <PRE> - * APR_FILE_ATTR_READONLY - make the file readonly - * APR_FILE_ATTR_EXECUTABLE - make the file executable - * APR_FILE_ATTR_HIDDEN - make the file hidden - * </PRE> + * @li #APR_FILE_ATTR_READONLY - make the file readonly + * @li #APR_FILE_ATTR_EXECUTABLE - make the file executable + * @li #APR_FILE_ATTR_HIDDEN - make the file hidden * @param attr_mask Mask of valid bits in attributes. * @param pool the pool to use. * @remark This function should be used in preference to explicit manipulation @@ -817,7 +839,7 @@ APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, * attributes are platform specific and may involve more than simply * setting permission bits. * @warning Platforms which do not implement this feature will return - * APR_ENOTIMPL. + * #APR_ENOTIMPL. */ APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname, apr_fileattrs_t attributes, @@ -830,7 +852,7 @@ APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname, * @param mtime The mtime to apply to the file. * @param pool The pool to use. * @warning Platforms which do not implement this feature will return - * APR_ENOTIMPL. + * #APR_ENOTIMPL. */ APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname, apr_time_t mtime, @@ -868,7 +890,7 @@ APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool); /** * get the specified file's stats. * @param finfo Where to store the information about the file. - * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values + * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values * @param thefile The file to get information about. */ APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, @@ -913,7 +935,8 @@ APR_DECLARE_INHERIT_UNSET(file); * @param templ The template to use when creating a temp file. * @param flags The flags to open the file with. If this is zero, * the file is opened with - * APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE + * #APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE | + * #APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE * @param p The pool to allocate the file out of. * @remark * This function generates a unique temporary file name from template. |