Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

File I/O Handling Functions
[Apache Portability Runtime library]


Modules

File Open Flags/Routines
File Seek Flags
File Attribute Flags
File Lock Types

Typedefs

typedef apr_uint32_t apr_fileattrs_t
typedef int apr_seek_where_t
typedef apr_file_t apr_file_t

Functions

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)
apr_status_t apr_file_close (apr_file_t *file)
apr_status_t apr_file_remove (const char *path, apr_pool_t *cont)
apr_status_t apr_file_rename (const char *from_path, const char *to_path, apr_pool_t *pool)
apr_status_t apr_file_copy (const char *from_path, const char *to_path, apr_fileperms_t perms, apr_pool_t *pool)
apr_status_t apr_file_append (const char *from_path, const char *to_path, apr_fileperms_t perms, apr_pool_t *pool)
apr_status_t apr_file_eof (apr_file_t *fptr)
apr_status_t apr_file_open_stderr (apr_file_t **thefile, apr_pool_t *cont)
apr_status_t apr_file_open_stdout (apr_file_t **thefile, apr_pool_t *cont)
apr_status_t apr_file_open_stdin (apr_file_t **thefile, apr_pool_t *cont)
apr_status_t apr_file_read (apr_file_t *thefile, void *buf, apr_size_t *nbytes)
apr_status_t apr_file_write (apr_file_t *thefile, const void *buf, apr_size_t *nbytes)
apr_status_t apr_file_writev (apr_file_t *thefile, const struct iovec *vec, apr_size_t nvec, apr_size_t *nbytes)
apr_status_t apr_file_read_full (apr_file_t *thefile, void *buf, apr_size_t nbytes, apr_size_t *bytes_read)
apr_status_t apr_file_write_full (apr_file_t *thefile, const void *buf, apr_size_t nbytes, apr_size_t *bytes_written)
apr_status_t apr_file_putc (char ch, apr_file_t *thefile)
apr_status_t apr_file_getc (char *ch, apr_file_t *thefile)
apr_status_t apr_file_ungetc (char ch, apr_file_t *thefile)
apr_status_t apr_file_gets (char *str, int len, apr_file_t *thefile)
apr_status_t apr_file_puts (const char *str, apr_file_t *thefile)
apr_status_t apr_file_flush (apr_file_t *thefile)
apr_status_t apr_file_dup (apr_file_t **new_file, apr_file_t *old_file, apr_pool_t *p)
apr_status_t apr_file_dup2 (apr_file_t *new_file, apr_file_t *old_file, apr_pool_t *p)
apr_status_t apr_file_setaside (apr_file_t **new_file, apr_file_t *old_file, apr_pool_t *p)
apr_status_t apr_file_seek (apr_file_t *thefile, apr_seek_where_t where, apr_off_t *offset)
apr_status_t apr_file_pipe_create (apr_file_t **in, apr_file_t **out, apr_pool_t *cont)
apr_status_t apr_file_namedpipe_create (const char *filename, apr_fileperms_t perm, apr_pool_t *cont)
apr_status_t apr_file_pipe_timeout_get (apr_file_t *thepipe, apr_interval_time_t *timeout)
apr_status_t apr_file_pipe_timeout_set (apr_file_t *thepipe, apr_interval_time_t timeout)
apr_status_t apr_file_lock (apr_file_t *thefile, int type)
apr_status_t apr_file_unlock (apr_file_t *thefile)
apr_status_t apr_file_name_get (const char **new_path, apr_file_t *thefile)
apr_status_t apr_file_data_get (void **data, const char *key, apr_file_t *file)
apr_status_t apr_file_data_set (apr_file_t *file, void *data, const char *key, apr_status_t(*cleanup)(void *))
int apr_file_printf (apr_file_t *fptr, const char *format,...)
apr_status_t apr_file_perms_set (const char *fname, apr_fileperms_t perms)
apr_status_t apr_file_attrs_set (const char *fname, apr_fileattrs_t attributes, apr_fileattrs_t attr_mask, apr_pool_t *cont)
apr_status_t apr_file_mtime_set (const char *fname, apr_time_t mtime, apr_pool_t *pool)
apr_status_t apr_dir_make (const char *path, apr_fileperms_t perm, apr_pool_t *cont)
apr_status_t apr_dir_make_recursive (const char *path, apr_fileperms_t perm, apr_pool_t *pool)
apr_status_t apr_dir_remove (const char *path, apr_pool_t *cont)
apr_status_t apr_file_info_get (apr_finfo_t *finfo, apr_int32_t wanted, apr_file_t *thefile)
apr_status_t apr_file_trunc (apr_file_t *fp, apr_off_t offset)
apr_int32_t apr_file_flags_get (apr_file_t *f)
apr_pool_tapr_file_pool_get (const apr_file_t *thefile)
apr_status_t apr_file_inherit_set (apr_file_t *thefile)
void apr_file_set_inherit (apr_file_t *file)
apr_status_t apr_file_inherit_unset (apr_file_t *thefile)
void apr_file_unset_inherit (apr_file_t *file)
apr_status_t apr_file_mktemp (apr_file_t **fp, char *templ, apr_int32_t flags, apr_pool_t *p)
apr_status_t apr_temp_dir_get (const char **temp_dir, apr_pool_t *p)

Typedef Documentation

typedef struct apr_file_t apr_file_t
 

Structure for referencing files.

typedef apr_uint32_t apr_fileattrs_t
 

File attributes

typedef int apr_seek_where_t
 

should be same as whence type in lseek, POSIX defines this as int


Function Documentation

apr_status_t apr_dir_make const char *    path,
apr_fileperms_t    perm,
apr_pool_t   cont
 

Create a new directory on the file system.

Parameters:
path  the path for the directory to be created. (use / on all systems)
perm  Permissions for the new direcoty.
cont  the pool to use.

apr_status_t apr_dir_make_recursive const char *    path,
apr_fileperms_t    perm,
apr_pool_t   pool
 

Creates a new directory on the file system, but behaves like 'mkdir -p'. Creates intermediate directories as required. No error will be reported if PATH already exists.

Parameters:
path  the path for the directory to be created. (use / on all systems)
perm  Permissions for the new direcoty.
pool  the pool to use.

apr_status_t apr_dir_remove const char *    path,
apr_pool_t   cont
 

Remove directory from the file system.

Parameters:
path  the path for the directory to be removed. (use / on all systems)
cont  the pool to use.

apr_status_t apr_file_append const char *    from_path,
const char *    to_path,
apr_fileperms_t    perms,
apr_pool_t   pool
 

append the specified file to another file.

Parameters:
from_path  The full path to the source file (using / on all systems)
to_path  The full path to the destination file (using / on all systems)
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 file's permissions are copied.
pool  The pool to use.
Remarks:
The new file does not need to exist, it will be created if required.

apr_status_t apr_file_attrs_set const char *    fname,
apr_fileattrs_t    attributes,
apr_fileattrs_t    attr_mask,
apr_pool_t   cont
 

Set attributes of the specified file.

Parameters:
fname  The full path to the file (using / on all systems)
attributes  Or'd combination of
            APR_FILE_ATTR_READONLY   - make the file readonly
            APR_FILE_ATTR_EXECUTABLE - make the file executable
            APR_FILE_ATTR_HIDDEN     - make the file hidden
 
attr_mask  Mask of valid bits in attributes.
cont  the pool to use.
Remarks:
This function should be used in preference to explict manipulation of the file permissions, because the operations to provide these 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_status_t apr_file_close apr_file_t   file
 

Close the specified file.

Parameters:
file  The file descriptor to close.

apr_status_t apr_file_copy const char *    from_path,
const char *    to_path,
apr_fileperms_t    perms,
apr_pool_t   pool
 

copy the specified file to another file.

Parameters:
from_path  The full path to the original file (using / on all systems)
to_path  The full path to the new file (using / on all systems)
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 file's permissions are copied.
pool  The pool to use.
Remarks:
The new file does not need to exist, it will be created if required.
Warning:
If the new file already exists, its contents will be overwritten.

apr_status_t apr_file_data_get void **    data,
const char *    key,
apr_file_t   file
 

Return the data associated with the current file.

Parameters:
data  The user data associated with the file.
key  The key to use for retreiving data associated with this file.
file  The currently open file.

apr_status_t apr_file_data_set apr_file_t   file,
void *    data,
const char *    key,
apr_status_t(*    cleanup)(void *)
 

Set the data associated with the current file.

Parameters:
file  The currently open file.
data  The user data to associate with the file.
key  The key to use for assocaiteing data with the file.
cleanup  The cleanup routine to use when the file is destroyed.

apr_status_t apr_file_dup apr_file_t **    new_file,
apr_file_t   old_file,
apr_pool_t   p
 

duplicate the specified file descriptor.

Parameters:
new_file  The structure to duplicate into.
old_file  The file to duplicate.
p  The pool to use for the new file.
Remarks:
*new_file must point to a valid apr_file_t, or point to NULL

apr_status_t apr_file_dup2 apr_file_t   new_file,
apr_file_t   old_file,
apr_pool_t   p
 

duplicate the specified file descriptor and close the original

Parameters:
new_file  The old file that is to be closed and reused
old_file  The file to duplicate
p  The pool to use for the new file
Remarks:
new_file MUST point at a valid apr_file_t. It cannot be NULL

apr_status_t apr_file_eof apr_file_t   fptr
 

Are we at the end of the file

Parameters:
fptr  The apr file we are testing.
Remarks:
Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.

apr_int32_t apr_file_flags_get apr_file_t   f
 

Retrieve the flags that were passed into apr_file_open() when the file was opened.

Returns:
apr_int32_t the flags

apr_status_t apr_file_flush apr_file_t   thefile
 

Flush the file's buffer.

Parameters:
thefile  The file descriptor to flush

apr_status_t apr_file_getc char *    ch,
apr_file_t   thefile
 

get a character from the specified file.

Parameters:
ch  The character to read into
thefile  The file descriptor to read from

apr_status_t apr_file_gets char *    str,
int    len,
apr_file_t   thefile
 

Get a string from a specified file.

Parameters:
str  The buffer to store the string in.
len  The length of the string
thefile  The file descriptor to read from
Remarks:
The buffer will be '\0'-terminated if any characters are stored.

apr_status_t apr_file_info_get apr_finfo_t   finfo,
apr_int32_t    wanted,
apr_file_t   thefile
 

get the specified file's stats.

Parameters:
finfo  Where to store the information about the file.
wanted  The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
thefile  The file to get information about.

apr_status_t apr_file_inherit_set apr_file_t   thefile
 

Set a file to be inherited by child processes.

apr_status_t apr_file_inherit_unset apr_file_t   thefile
 

Unset a file from being inherited by child processes.

apr_status_t apr_file_lock apr_file_t   thefile,
int    type
 

Establish a lock on the specified, open file. The lock may be advisory or mandatory, at the discretion of the platform. The lock applies to the file as a whole, rather than a specific range. Locks are established on a per-thread/process basis; a second lock by the same thread will not block.

Parameters:
thefile  The file to lock.
type  The type of lock to establish on the file.

apr_status_t apr_file_mktemp apr_file_t **    fp,
char *    templ,
apr_int32_t    flags,
apr_pool_t   p
 

Open a temporary file

Parameters:
fp  The apr file to use as a temporary file.
templ  The template to use when creating a temp file.
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
p  The pool to allocate the file out of.
Remarks:
This function generates a unique temporary file name from template. The last six characters of template must be XXXXXX and these are replaced with a string that makes the filename unique. Since it will be modified, template must not be a string constant, but should be declared as a character array.

apr_status_t apr_file_mtime_set const char *    fname,
apr_time_t    mtime,
apr_pool_t   pool
 

Set the mtime of the specified file.

Parameters:
fname  The full path to the file (using / on all systems)
mtime  The mtime to apply to the file.
pool  The pool to use.
Warning:
Platforms which do not implement this feature will return APR_ENOTIMPL.

apr_status_t apr_file_name_get const char **    new_path,
apr_file_t   thefile
 

return the file name of the current file.

Parameters:
new_path  The path of the file.
thefile  The currently open file.

apr_status_t apr_file_namedpipe_create const char *    filename,
apr_fileperms_t    perm,
apr_pool_t   cont
 

Create a named pipe.

Parameters:
filename  The filename of the named pipe
perm  The permissions for the newly created pipe.
cont  The pool to operate on.

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
 

Open the specified file.

Parameters:
new_file  The opened file descriptor.
fname  The full path to the file (using / on all systems)
flag  Or'ed value of:
         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
                               for use across multiple threads
         APR_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 cont 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
                               for sendfile operations.  Advisory only,
                               apr_sendfile does not check this flag.
 
perm  Access permissions for file.
cont  The pool to use.
Remarks:
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)

apr_status_t apr_file_open_stderr apr_file_t **    thefile,
apr_pool_t   cont
 

open standard error as an apr file pointer.

Parameters:
thefile  The apr file to use as stderr.
cont  The pool to allocate the file out of.
Remarks:
The only reason that the apr_file_open_std* functions exist is that you may not always have a stderr/out/in on Windows. This is generally a problem with newer versions of Windows and services.
The other problem is that the C library functions generally work differently on Windows and Unix. So, by using apr_file_open_std* functions, you can get a handle to an APR struct that works with the APR functions which are supposed to work identically on all platforms.

apr_status_t apr_file_open_stdin apr_file_t **    thefile,
apr_pool_t   cont
 

open standard input as an apr file pointer.

Parameters:
thefile  The apr file to use as stdin.
cont  The pool to allocate the file out of.
Remarks:
The only reason that the apr_file_open_std* functions exist is that you may not always have a stderr/out/in on Windows. This is generally a problem with newer versions of Windows and services.
The other problem is that the C library functions generally work differently on Windows and Unix. So, by using apr_file_open_std* functions, you can get a handle to an APR struct that works with the APR functions which are supposed to work identically on all platforms.

apr_status_t apr_file_open_stdout apr_file_t **    thefile,
apr_pool_t   cont
 

open standard output as an apr file pointer.

Parameters:
thefile  The apr file to use as stdout.
cont  The pool to allocate the file out of.
Remarks:
The only reason that the apr_file_open_std* functions exist is that you may not always have a stderr/out/in on Windows. This is generally a problem with newer versions of Windows and services.
The other problem is that the C library functions generally work differently on Windows and Unix. So, by using apr_file_open_std* functions, you can get a handle to an APR struct that works with the APR functions which are supposed to work identically on all platforms.

apr_status_t apr_file_perms_set const char *    fname,
apr_fileperms_t    perms
 

set the specified file's permission bits.

Parameters:
fname  The file (name) to apply the permissions to.
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 permissions are specified which could not be set.
Platforms which do not implement this feature will return APR_ENOTIMPL.

apr_status_t apr_file_pipe_create apr_file_t **    in,
apr_file_t **    out,
apr_pool_t   cont
 

Create an anonymous pipe.

Parameters:
in  The file descriptor to use as input to the pipe.
out  The file descriptor to use as output from the pipe.
cont  The pool to operate on.

apr_status_t apr_file_pipe_timeout_get apr_file_t   thepipe,
apr_interval_time_t   timeout
 

Get the timeout value for a pipe or manipulate the blocking state.

Parameters:
thepipe  The pipe we are getting a timeout for.
timeout  The current timeout value in microseconds.

apr_status_t apr_file_pipe_timeout_set apr_file_t   thepipe,
apr_interval_time_t    timeout
 

Set the timeout value for a pipe or manipulate the blocking state.

Parameters:
thepipe  The pipe we are setting a timeout on.
timeout  The timeout value in microseconds. Values < 0 mean wait forever, 0 means do not wait at all.

apr_pool_t* apr_file_pool_get const apr_file_t   thefile
 

Get the pool used by the file.

int apr_file_printf apr_file_t   fptr,
const char *    format,
...   
 

Write a string to a file using a printf format.

Parameters:
fptr  The file to write to.
format  The format string
...  The values to substitute in the format string
Returns:
The number of bytes written

apr_status_t apr_file_putc char    ch,
apr_file_t   thefile
 

put a character into the specified file.

Parameters:
ch  The character to write.
thefile  The file descriptor to write to

apr_status_t apr_file_puts const char *    str,
apr_file_t   thefile
 

Put the string into a specified file.

Parameters:
str  The string to write.
thefile  The file descriptor to write to

apr_status_t apr_file_read apr_file_t   thefile,
void *    buf,
apr_size_t *    nbytes
 

Read data from the specified file.

Parameters:
thefile  The file descriptor to read from.
buf  The buffer to store the data to.
nbytes  On entry, the number of bytes to read; on exit, the number of bytes read.
Remarks:
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.
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_status_t apr_file_read_full apr_file_t   thefile,
void *    buf,
apr_size_t    nbytes,
apr_size_t *    bytes_read
 

Read data from the specified file, ensuring that the buffer is filled before returning.

Parameters:
thefile  The file descriptor to read from.
buf  The buffer to store the data to.
nbytes  The number of bytes to read.
bytes_read  If non-NULL, this will contain the number of bytes read.
Remarks:
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, it will be the first character returned.
It is possible for both bytes to be read and an error to be returned. And if *bytes_read is less than nbytes, an accompanying error is _always_ returned.

APR_EINTR is never returned.

apr_status_t apr_file_remove const char *    path,
apr_pool_t   cont
 

delete the specified file.

Parameters:
path  The full path to the file (using / on all systems)
cont  The pool to use.
Remarks:
If the file is open, it won't be removed until all instances are closed.

apr_status_t apr_file_rename const char *    from_path,
const char *    to_path,
apr_pool_t   pool
 

rename the specified file.

Parameters:
from_path  The full path to the original file (using / on all systems)
to_path  The full path to the new file (using / on all systems)
pool  The pool to use.
Warning:
If a file exists at the new location, then it will be overwritten. Moving files or directories across devices may not be possible.

apr_status_t apr_file_seek apr_file_t   thefile,
apr_seek_where_t    where,
apr_off_t *    offset
 

Move the read/write file offset to a specified byte within a file.

Parameters:
thefile  The file descriptor
where  How to move the pointer, one of:
            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 
 
offset  The offset to move the pointer to.
Remarks:
The third argument is modified to be the offset the pointer was actually moved to.

void apr_file_set_inherit apr_file_t   file
 

Deprecated:
See also:
apr_file_inherit_set

apr_status_t apr_file_setaside apr_file_t **    new_file,
apr_file_t   old_file,
apr_pool_t   p
 

move the specified file descriptor to a new pool

Parameters:
new_file  Pointer in which to return the new apr_file_t
old_file  The file to move
p  The pool to which the descriptor is to be moved
Remarks:
Unlike apr_file_dup2(), this function doesn't do an OS dup() operation on the underlying descriptor; it just moves the descriptor's apr_file_t wrapper to a new pool.
The new pool need not be an ancestor of old_file's pool.
After calling this function, old_file may not be used

apr_status_t apr_file_trunc apr_file_t   fp,
apr_off_t    offset
 

Truncate the file's length to the specified offset

Parameters:
fp  The file to truncate
offset  The offset to truncate to.

apr_status_t apr_file_ungetc char    ch,
apr_file_t   thefile
 

put a character back onto a specified stream.

Parameters:
ch  The character to write.
thefile  The file descriptor to write to

apr_status_t apr_file_unlock apr_file_t   thefile
 

Remove any outstanding locks on the file.

Parameters:
thefile  The file to unlock.

void apr_file_unset_inherit apr_file_t   file
 

Deprecated:
See also:
apr_file_inherit_unset

apr_status_t apr_file_write apr_file_t   thefile,
const void *    buf,
apr_size_t *    nbytes
 

Write data to the specified file.

Parameters:
thefile  The file descriptor to write to.
buf  The buffer which contains the data.
nbytes  On entry, the number of bytes to write; on exit, the number of bytes written.
Remarks:
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.
It is possible for both bytes to be written and an error to be returned.

APR_EINTR is never returned.

apr_status_t apr_file_write_full apr_file_t   thefile,
const void *    buf,
apr_size_t    nbytes,
apr_size_t *    bytes_written
 

Write data to the specified file, ensuring that all of the data is written before returning.

Parameters:
thefile  The file descriptor to write to.
buf  The buffer which contains the data.
nbytes  The number of bytes to write.
bytes_written  If non-NULL, this will contain the number of bytes written.
Remarks:
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.
It is possible for both bytes to be written and an error to be returned. And if *bytes_written is less than nbytes, an accompanying error is _always_ returned.

APR_EINTR is never returned.

apr_status_t apr_file_writev apr_file_t   thefile,
const struct iovec *    vec,
apr_size_t    nvec,
apr_size_t *    nbytes
 

Write data from iovec array to the specified file.

Parameters:
thefile  The file descriptor to write to.
vec  The array from which to get the data to write to the file.
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.
nbytes  The number of bytes written.
Remarks:
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().

apr_status_t apr_temp_dir_get const char **    temp_dir,
apr_pool_t   p
 

Find an existing directory suitable as a temporary storage location.

Parameters:
temp_dir  The temp directory.
p  The pool to use for any necessary allocations.
Remarks:
This function uses an algorithm to search for a directory that an an application can use for temporary storage. Once such a directory is found, that location is cached by the library. Thus, callers only pay the cost of this algorithm once if that one time is successful.


Generated on Thu Dec 25 11:41:05 2003 for Apache Portable Runtime by doxygen1.2.18