You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Ian Holsman <ia...@cnet.com> on 2001/08/12 05:08:12 UTC
[DOX] apr_file_io
Index: apr_file_io.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_file_io.h,v
retrieving revision 1.106
diff -u -r1.106 apr_file_io.h
--- apr_file_io.h 2001/07/26 15:39:25 1.106
+++ apr_file_io.h 2001/08/12 03:03:59
@@ -54,7 +54,18 @@
#ifndef APR_FILE_IO_H
#define APR_FILE_IO_H
+/**
+ * @file apr_file_io.h
+ * @brief APR File I/O Handling
+ */
+/**
+ * @defgroup APR_File_IO_Handle I/O Handling Functions
+ * @ingroup APR_File_Handle
+ * @{
+ */
+
+
#include "apr.h"
#include "apr_pools.h"
#include "apr_time.h"
@@ -71,32 +82,40 @@
#endif /* __cplusplus */
/**
- * @package APR File handling
+ * @defgroup apr_file_open File Open Flags/Routines
+ * @{
*/
-/* Flags for apr_file_open */
-#define APR_READ 1 /* Open the file for reading */
-#define APR_WRITE 2 /* Open the file for writing */
-#define APR_CREATE 4 /* Create the file if not there */
-#define APR_APPEND 8 /* Append to the end of the file */
-#define APR_TRUNCATE 16 /* Open the file and truncate to 0
length */
-#define APR_BINARY 32 /* Open the file in binary mode */
-#define APR_EXCL 64 /* Open should fail if APR_CREATE
and file
+#define APR_READ 1 /**< Open the file for reading */
+#define APR_WRITE 2 /**< Open the file for writing */
+#define APR_CREATE 4 /**< Create the file if not there */
+#define APR_APPEND 8 /**< Append to the end of the file */
+#define APR_TRUNCATE 16 /**< Open the file and truncate to 0
length */
+#define APR_BINARY 32 /**< Open the file in binary mode */
+#define APR_EXCL 64 /**< Open should fail if APR_CREATE
and file
exists. */
-#define APR_BUFFERED 128 /* Open the file for buffered I/O */
-#define APR_DELONCLOSE 256 /* Delete the file after close */
-#define APR_XTHREAD 512 /* Platform dependent tag to open
the file
+#define APR_BUFFERED 128 /**< Open the file for buffered I/O */
+#define APR_DELONCLOSE 256 /**< Delete the file after close */
+#define APR_XTHREAD 512 /**< Platform dependent tag to open
the file
for use across multiple threads */
-#define APR_SHARELOCK 1024 /* Platform dependent support for higher
+#define APR_SHARELOCK 1024 /**< Platform dependent support for
higher
level locked read/write access to
support
writes across process/machines */
+/** @} */
+
+/**
+ * @defgroup APR_file_seek_flags File Seek Flags
+ * @{
+ */
+
/* flags for apr_file_seek */
#define APR_SET SEEK_SET
#define APR_CUR SEEK_CUR
#define APR_END SEEK_END
+/** @} */
-/* should be same as whence type in lseek, POSIX defines this as int */
+/** should be same as whence type in lseek, POSIX defines this as int */
typedef int apr_seek_where_t;
/**
@@ -106,21 +125,26 @@
typedef struct apr_file_t apr_file_t;
/* File lock types/flags */
-#define APR_FLOCK_SHARED 1 /* Shared lock. More than one
process
+/**
+ * @defgroup APR_file_lock_types File Lock Types
+ * @{
+ */
+
+#define APR_FLOCK_SHARED 1 /**< Shared lock. More than one
process
or thread can hold a shared lock
at any given time. Essentially,
this is a "read lock",
preventing
writers from establishing an
exclusive lock. */
-#define APR_FLOCK_EXCLUSIVE 2 /* Exclusive lock. Only one process
+#define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one
process
may hold an exclusive lock
at any
given time. This is analogous to
a "write lock". */
-#define APR_FLOCK_TYPEMASK 0x000F /* mask to extract lock type */
-#define APR_FLOCK_NONBLOCK 0x0010 /* do not block while acquiring the
+#define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
+#define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while
acquiring the
file lock */
-
+/** @} */
/**
* Open the specified file.
* @param new_file The opened file descriptor.
@@ -145,8 +169,8 @@
* </PRE>
* @param perm Access permissions for file.
* @param cont The pool to use.
- * @deffunc apr_status_t apr_file_open(apr_file_t **new_file, const
char *fname, apr_int32_t flag, apr_fileperms_t perm, apr_pool_t *cont)
- * @tip If perm is APR_OS_DEFAULT and the file is being created,
appropriate
+ * @ingroup apr_file_open
+ * @remark If perm is APR_OS_DEFAULT and the file is being created,
appropriate
* default permissions will be used. *arg1 must point to a valid
file_t,
* or NULL (in which case it will be allocated)
*/
@@ -157,7 +181,6 @@
/**
* Close the specified file.
* @param file The file descriptor to close.
- * @deffunc apr_status_t apr_file_close(apr_file_t *file)
*/
APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
@@ -165,8 +188,7 @@
* delete the specified file.
* @param path The full path to the file (using / on all systems)
* @param cont The pool to use.
- * @deffunc apr_status_t apr_file_remove(const char *path, apr_pool_t
*cont)
- * @tip If the file is open, it won't be removed until all instances
are closed.
+ * @remark If the file is open, it won't be removed until all instances
are closed.
*/
APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t
*cont);
@@ -175,9 +197,8 @@
* @param from_path The full path to the original file (using / on all
systems)
* @param to_path The full path to the new file (using / on all systems)
* @param pool The pool to use.
- * @tip If a file exists at the new location, then it will be
overwritten.
+ * @warning If a file exists at the new location, then it will be
overwritten.
* Moving files or directories across devices may not be possible.
- * @deffunc apr_status_t apr_file_rename(const char *from_path, const
char *to_path, apr_pool_t *pool)
*/
APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
const char *to_path,
@@ -186,8 +207,7 @@
/**
* Are we at the end of the file
* @param fptr The apr file we are testing.
- * @tip Returns APR_EOF if we are at the end of file, APR_SUCCESS
otherwise.
- * @deffunc apr_status_t apr_file_eof(apr_file_t *fptr)
+ * @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);
@@ -195,7 +215,7 @@
* open standard error as an apr file pointer.
* @param thefile The apr file to use as stderr.
* @param cont The pool to allocate the file out of.
- * @deffunc apr_status_t apr_file_open_stderr(apr_file_t **thefile,
apr_pool_t *cont)
+ * @ingroup apr_file_open
*/
APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
apr_pool_t *cont);
@@ -204,7 +224,7 @@
* open standard output as an apr file pointer.
* @param thefile The apr file to use as stdout.
* @param cont The pool to allocate the file out of.
- * @deffunc apr_status_t apr_file_open_stdout(apr_file_t **thefile,
apr_pool_t *cont)
+ * @ingroup apr_file_open
*/
APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
apr_pool_t *cont);
@@ -213,7 +233,7 @@
* open standard input as an apr file pointer.
* @param thefile The apr file to use as stdin.
* @param cont The pool to allocate the file out of.
- * @deffunc apr_status_t apr_file_open_stdin(apr_file_t **thefile,
apr_pool_t *cont)
+ * @ingroup apr_file_open
*/
APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
apr_pool_t *cont);
@@ -223,7 +243,7 @@
* @param thefile The file descriptor to read from.
* @param buf The buffer to store the data to.
* @param nbytes On entry, the number of bytes to read; on exit, the
number of bytes read.
- * @tip apr_file_read will read up to the specified number of bytes,
but never
+ * @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
@@ -233,7 +253,6 @@
* error to be returned.
*
* APR_EINTR is never returned.
- * @deffunc apr_status_t apr_file_read(apr_file_t *thefile, void *buf,
apr_size_t *nbytes)
*/
APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
apr_size_t *nbytes);
@@ -244,7 +263,7 @@
* @param buf The buffer which contains the data.
* @param nbytes On entry, the number of bytes to write; on exit, the
number
* of bytes written.
- * @tip apr_file_write will write up to the specified number of bytes,
but never
+ * @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.
@@ -252,7 +271,6 @@
* It is possible for both bytes to be written and an error to be
returned.
*
* APR_EINTR is never returned.
- * @deffunc apr_status_t apr_file_write(apr_file_t *thefile, const void
*buf, apr_size_t *nbytes)
*/
APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const
void *buf,
apr_size_t *nbytes);
@@ -265,13 +283,12 @@
* 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.
- * @tip It is possible for both bytes to be written and an error to be
returned.
+ * @remark It is possible for both bytes to be written and an error to
be returned.
* APR_EINTR is never returned.
*
* apr_file_writev is available even if the underlying operating
system
*
* doesn't provide writev().
- * @deffunc apr_status_t apr_file_writev(apr_file_t *thefile, const
struct iovec *vec, apr_size_t nvec, apr_size_t *nbytes)
*/
APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
const struct iovec *vec,
@@ -284,7 +301,7 @@
* @param buf The buffer to store the data to.
* @param nbytes The number of bytes to read.
* @param bytes_read If non-NULL, this will contain the number of bytes
read.
- * @tip apr_file_read will read up to the specified number of bytes,
but never
+ * @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,
* then the process/thread will block until it is available or EOF
* is reached. If a char was put back into the stream via ungetc,
@@ -294,7 +311,6 @@
* error to be returned.
*
* APR_EINTR is never returned.
- * @deffunc apr_status_t apr_file_read_full(apr_file_t *thefile, void
*buf, apr_size_t nbytes, apr_size_t *bytes_read)
*/
APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void
*buf,
apr_size_t nbytes,
@@ -307,7 +323,7 @@
* @param buf The buffer which contains the data.
* @param nbytes The number of bytes to write.
* @param bytes_written If non-NULL, this will contain the number of
bytes written.
- * @tip apr_file_write will write up to the specified number of bytes,
but never
+ * @remark apr_file_write 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 an error.
@@ -315,7 +331,6 @@
* It is possible for both bytes to be written and an error to be
returned.
*
* APR_EINTR is never returned.
- * @deffunc apr_status_t apr_file_write_full(apr_file_t *thefile, const
void *buf, apr_size_t nbytes, apr_size_t *bytes_written)
*/
APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile,
const void *buf,
apr_size_t nbytes,
@@ -325,7 +340,6 @@
* put a character into the specified file.
* @param ch The character to write.
* @param thefile The file descriptor to write to
- * @deffunc apr_status_t apr_file_putc(char ch, apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
@@ -333,7 +347,6 @@
* get a character from the specified file.
* @param ch The character to write.
* @param thefile The file descriptor to write to
- * @deffunc apr_status_t apr_file_getc(char *ch, apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
@@ -341,7 +354,6 @@
* put a character back onto a specified stream.
* @param ch The character to write.
* @param thefile The file descriptor to write to
- * @deffunc apr_status_t apr_file_ungetc(char ch, apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
@@ -350,7 +362,6 @@
* @param str The buffer to store the string in.
* @param len The length of the string
* @param thefile The file descriptor to read from
- * @deffunc apr_status_t apr_file_gets(char *str, int len, apr_file_t
*thefile)
*/
APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, apr_file_t
*thefile);
@@ -358,14 +369,12 @@
* Put the string into a specified file.
* @param str The string to write.
* @param thefile The file descriptor to write to
- * @deffunc apr_status_t apr_file_puts(const char *str, apr_file_t
*thefile)
*/
APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t
*thefile);
/**
* Flush the file's buffer.
* @param thefile The file descriptor to flush
- * @deffunc apr_status_t apr_file_flush(apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
@@ -374,8 +383,7 @@
* @param new_file The structure to duplicate into.
* @param old_file The file to duplicate.
* @param p The pool to use for the new file.
- * @tip *arg1 must point to a valid apr_file_t, or point to NULL
- * @deffunc apr_status_t apr_file_dup(apr_file_t **new_file, apr_file_t
*old_file, apr_pool_t *p)
+ * @remark *arg1 must point to a valid apr_file_t, or point to NULL
*/
APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
apr_file_t *old_file,
@@ -391,9 +399,8 @@
* APR_END -- add the offset to the current file size
* </PRE>
* @param offset The offset to move the pointer to.
- * @tip The third argument is modified to be the offset the pointer
+ * @remark The third argument is modified to be the offset the pointer
was actually moved to.
- * @deffunc apr_status_t apr_file_seek(apr_file_t *thefile,
apr_seek_where_t where, apr_off_t *offset)
*/
APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
apr_seek_where_t where,
@@ -404,7 +411,6 @@
* @param in The file descriptor to use as input to the pipe.
* @param out The file descriptor to use as output from the pipe.
* @param cont The pool to operate on.
- * @deffunc apr_status_t apr_file_pipe_create(apr_file_t **in,
apr_file_t **out, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in,
apr_file_t **out,
apr_pool_t *cont);
@@ -414,7 +420,6 @@
* @param filename The filename of the named pipe
* @param perm The permissions for the newly created pipe.
* @param cont The pool to operate on.
- * @deffunc apr_status_t apr_file_namedpipe_create(const char
*filename, apr_fileperms_t perm, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
apr_fileperms_t perm,
@@ -424,7 +429,6 @@
* Get the timeout value for a pipe or manipulate the blocking state.
* @param thepipe The pipe we are getting a timeout for.
* @param timeout The current timeout value in microseconds.
- * @deffunc apr_status_t apr_file_pipe_timeout_get(apr_file_t *thepipe,
apr_interval_time_t *timeout)
*/
APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
apr_interval_time_t
*timeout);
@@ -434,7 +438,6 @@
* @param thepipe The pipe we are setting a timeout on.
* @param timeout The timeout value in microseconds. Values < 0 mean wait
* forever, 0 means do not wait at all.
- * @deffunc apr_status_t apr_file_pipe_timeout_set(apr_file_t *thepipe,
apr_interval_time_t timeout)
*/
APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe,
apr_interval_time_t
timeout);
@@ -449,14 +452,12 @@
* block.
* @param thefile The file to lock.
* @param type The type of lock to establish on the file.
- * @deffunc apr_status_t apr_file_lock(apr_file_t *thefile, int type)
*/
APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
/**
* Remove any outstanding locks on the file.
* @param thefile The file to unlock.
- * @deffunc apr_status_t apr_file_unlock(apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
@@ -466,7 +467,6 @@
* return the file name of the current file.
* @param new_path The path of the file.
* @param thefile The currently open file.
- * @deffunc apr_status_t apr_file_name_get(const char **new_path,
apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
apr_file_t *thefile);
@@ -476,7 +476,6 @@
* @param data The user data associated with the file.
* @param key The key to use for retreiving data associated with this file.
* @param file The currently open file.
- * @deffunc apr_status_t apr_file_data_get(void **data, const char
*key, apr_file_t *file)
*/
APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
apr_file_t *file);
@@ -487,7 +486,6 @@
* @param data The user data to associate with the file.
* @param key The key to use for assocaiteing data with the file.
* @param cleanup The cleanup routine to use when the file is destroyed.
- * @deffunc apr_status_t apr_file_data_set(apr_file_t *file, void
*data, const char *key, apr_status_t (*cleanup)(void *))
*/
APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
const char *key,
@@ -499,7 +497,6 @@
* @param format The format string
* @param ... The values to substitute in the format string
* @return The number of bytes written
- * @deffunc int apr_file_printf(apr_file_t *fptr, const char *format, ...)
*/
APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, const char
*format, ...)
__attribute__((format(printf,2,3)));
@@ -508,12 +505,11 @@
* set the specified file's permission bits.
* @param fname The file (name) to apply the permissions to.
* @param perms The permission bits to apply to the file.
- * @tip Some platforms may not be able to apply all of the available
+ * @warning Some platforms may not be able to apply all of the available
* permission bits; APR_INCOMPLETE will be returned if some
permissions
* are specified which could not be set.
*
* Platforms which do not implement this feature will return
APR_ENOTIMPL.
- * @deffunc apr_status_t apr_file_perms_set(const char *fname,
apr_fileperms_t perms)
*/
APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
apr_fileperms_t perms);
@@ -523,7 +519,6 @@
* @param path the path for the directory to be created. (use / on all
systems)
* @param perm Permissions for the new direcoty.
* @param cont the pool to use.
- * @deffunc apr_status_t apr_dir_make(const char *path, apr_fileperms_t
perm, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_dir_make(const char *path,
apr_fileperms_t perm,
apr_pool_t *cont);
@@ -532,7 +527,6 @@
* Remove directory from the file system.
* @param path the path for the directory to be removed. (use / on all
systems)
* @param cont the pool to use.
- * @deffunc apr_status_t apr_dir_remove(const char *path, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t
*cont);
@@ -541,7 +535,6 @@
* @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 thefile The file to get information about.
- * @deffunc apr_status_t apr_file_info_get(apr_finfo_t *finfo,
apr_int32_t wanted, apr_file_t *thefile)
*/
APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
apr_int32_t wanted,
@@ -559,33 +552,23 @@
* Retrieve the flags that were passed into apr_file_open()
* when the file was opened.
* @return apr_int32_t the flags
- * @deffunc apr_int32_t apr_file_flags_get(apr_file_t *f)
*/
APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
/**
* Get the pool used by the file.
* @return apr_pool_t the pool
- * @deffunc apr_pool_t apr_file_pool_get(apr_file_t *f)
*/
-APR_POOL_DECLARE_ACCESSOR(file);
-
-/**
- * Set a file to be inherited by child processes.
- * @param file The file to enable inheritance.
- * @deffunc void apr_file_set_inherit(apr_file_t *file)
- */
APR_DECLARE(void) apr_file_set_inherit(apr_file_t *file);
/**
* Unset a file from being inherited by child processes.
* @param file The file to disable inheritance.
- * @deffunc void apr_file_unset_inherit(apr_file_t *file)
*/
APR_DECLARE(void) apr_file_unset_inherit(apr_file_t *file);
#ifdef __cplusplus
}
#endif
-
+/** @} */
#endif /* ! APR_FILE_IO_H */