/* ====================================================================
* The Apache Software License, Version 1.1
*
* Copyright (c) 2000-2003 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Apache" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
#ifndef APV_FILE_IO_H
#define APV_FILE_IO_H
/**
* @file apr_file_io.h
* @brief APV File I/O Handling
*/
/**
* @defgroup APV_APVS_File_IO_Handle I/O Handling Functions
* @ingroup APV_File_Handle
* @{
*/
#include "apr.h"
#include "apr_pools.h"
#include "apr_time.h"
#include "apr_errno.h"
#include "apr_file_info.h"
#include "apr_inherit.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* @defgroup apr_file_open File Open Flags/Routines
* @{
*/
/** @} */
/**
* Structure for referencing files.
* @defvar apv_file_t
*/
typedef struct apv_file_t apv_file_t;
/** @} */
/**
* Open the specified file.
* @param new_file 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
* 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 <EM>cont</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
* for sendfile operations. Advisory only,
* apr_sendfile does not check this flag.
* </PRE>
* @param perm Access permissions for file.
* @param cont The pool to use.
* @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)
*/
APV_DECLARE(apr_status_t) apv_file_open(apv_file_t **new_file, const char *fname,
apr_int32_t flag, apr_fileperms_t perm,
apr_pool_t *cont);
/**
* Close the specified file.
* @param file The file descriptor to close.
*/
APV_DECLARE(apr_status_t) apv_file_close(apv_file_t *file);
/**
* delete the specified file.
* @param path The full path to the file (using / on all systems)
* @param cont The pool to use.
* @remark If the file is open, it won't be removed until all instances are closed.
*/
APV_DECLARE(apr_status_t) apv_file_remove(const char *path, apr_pool_t *cont);
/**
* rename the specified file.
* @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.
* @warning If a file exists at the new location, then it will be overwritten.
* Moving files or directories across devices may not be possible.
*/
APV_DECLARE(apr_status_t) apv_file_rename(const char *from_path,
const char *to_path,
apr_pool_t *pool);
/**
* copy the specified file to another file.
* @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 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.
* @param pool The pool to use.
* @remark 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.
*/
APV_DECLARE(apr_status_t) apv_file_copy(const char *from_path,
const char *to_path,
apr_fileperms_t perms,
apr_pool_t *pool);
/**
* append the specified file to another file.
* @param from_path The full path to the source file (using / on all systems)
* @param to_path The full path to the destination file (using / 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
* 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.
*/
APV_DECLARE(apr_status_t) apv_file_append(const char *from_path,
const char *to_path,
apr_fileperms_t perms,
apr_pool_t *pool);
/**
* 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.
*/
APV_DECLARE(apr_status_t) apv_file_eof(apr_file_t *fptr);
/**
* Read data from the specified file.
* @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.
* @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.
*
* 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.
*/
APV_DECLARE(apr_status_t) apv_file_read(apv_file_t *thefile, void *buf,
apr_size_t *nbytes);
/**
* Write data to the specified file.
* @param thefile The file descriptor to write to.
* @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.
* @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.
*
* It is possible for both bytes to be written and an error to be returned.
*
* APR_EINTR is never returned.
*/
APV_DECLARE(apr_status_t) apv_file_write(apv_file_t *thefile, const void *buf,
apr_size_t *nbytes);
/**
* Write data from iovec array to the specified file.
* @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.
* @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.
*
* apr_file_writev is available even if the underlying operating system
*
* doesn't provide writev().
*/
APR_DECLARE(apr_status_t) apv_file_writev(apv_file_t *thefile,
const struct iovec *vec,
apr_size_t nvec, apr_size_t *nbytes);
/**
* Read data from the specified file, ensuring that the buffer is filled
* before returning.
* @param thefile The file descriptor to read from.
* @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.
* @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,
* 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.
*/
APV_DECLARE(apr_status_t) apv_file_read_full(apv_file_t *thefile, void *buf,
apr_size_t nbytes,
apr_size_t *bytes_read);
/**
* Write data to the specified file, ensuring that all of the data is
* written before returning.
* @param thefile The file descriptor to write to.
* @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.
* @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.
*
* 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.
*/
APV_DECLARE(apr_status_t) apv_file_write_full(apv_file_t *thefile, const void *buf,
apr_size_t nbytes,
apr_size_t *bytes_written);
/**
* put a character into the specified file.
* @param ch The character to write.
* @param thefile The file descriptor to write to
*/
APV_DECLARE(apr_status_t) apv_file_putc(char ch, apv_file_t *thefile);
/**
* get a character from the specified file.
* @param ch The character to write.
* @param thefile The file descriptor to write to
*/
APV_DECLARE(apr_status_t) apv_file_getc(char *ch, apv_file_t *thefile);
/**
* put a character back onto a specified stream.
* @param ch The character to write.
* @param thefile The file descriptor to write to
*/
APV_DECLARE(apr_status_t) apv_file_ungetc(char ch, apv_file_t *thefile);
/**
* Get a string from a specified file.
* @param str The buffer to store the string in.
* @param len The length of the string
* @param thefile The file descriptor to read from
*/
APV_DECLARE(apr_status_t) apv_file_gets(char *str, int len, apv_file_t *thefile);
/**
* Put the string into a specified file.
* @param str The string to write.
* @param thefile The file descriptor to write to
*/
APV_DECLARE(apr_status_t) apv_file_puts(const char *str, apv_file_t *thefile);
/**
* Flush the file's buffer.
* @param thefile The file descriptor to flush
*/
APV_DECLARE(apr_status_t) apv_file_flush(apv_file_t *thefile);
/**
* duplicate the specified file descriptor.
* @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.
* @remark *new_file must point to a valid apr_file_t, or point to NULL
*/
APV_DECLARE(apr_status_t) apv_file_dup(apv_file_t **new_file,
apv_file_t *old_file,
apr_pool_t *p);
/**
* duplicate the specified file descriptor and close the original
* @param new_file The old file that is to be closed and reused
* @param old_file The file to duplicate
* @param p The pool to use for the new file
*
* @remark new_file MUST point at a valid apr_file_t. It cannot be NULL
*/
APV_DECLARE(apr_status_t) apv_file_dup2(apv_file_t *new_file,
apv_file_t *old_file,
apr_pool_t *p);
/**
* move the specified file descriptor to a new pool
* @param new_file Pointer in which to return the new apr_file_t
* @param old_file The file to move
* @param p The pool to which the descriptor is to be moved
* @remark 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.
* @remark The new pool need not be an ancestor of old_file's pool.
* @remark After calling this function, old_file may not be used
*/
APV_DECLARE(apr_status_t) apv_file_setaside(apv_file_t **new_file,
apv_file_t *old_file,
apr_pool_t *p);
/**
* 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>
* @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.
*/
APV_DECLARE(apr_status_t) apv_file_seek(apv_file_t *thefile,
apr_seek_where_t where,
apr_off_t *offset);
/** file (un)locking functions. */
/**
* 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.
* @param thefile The file to lock.
* @param type The type of lock to establish on the file.
*/
APV_DECLARE(apr_status_t) apv_file_lock(apv_file_t *thefile, int type);
/**
* Remove any outstanding locks on the file.
* @param thefile The file to unlock.
*/
APV_DECLARE(apr_status_t) apv_file_unlock(apv_file_t *thefile);
/**accessor and general file_io functions. */
/**
* return the file name of the current file.
* @param new_path The path of the file.
* @param thefile The currently open file.
*/
APV_DECLARE(apr_status_t) apv_file_name_get(const char **new_path,
apv_file_t *thefile);
/**
* Return the data associated with the current file.
* @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.
*/
APV_DECLARE(apr_status_t) apv_file_data_get(void **data, const char *key,
apv_file_t *file);
/**
* Set the data associated with the current file.
* @param file The currently open file.
* @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.
*/
APV_DECLARE(apr_status_t) apv_file_data_set(apv_file_t *file, void *data,
const char *key,
apr_status_t (*cleanup)(void *));
/**
* Write a string to a file using a printf format.
* @param fptr The file to write to.
* @param format The format string
* @param ... The values to substitute in the format string
* @return The number of bytes written
*/
APV_DECLARE_NONSTD(int) apv_file_printf(apv_file_t *fptr,
const char *format, ...)
__attribute__((format(printf,2,3)));
/**
* 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.
* @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.
*/
APV_DECLARE(apr_status_t) apv_file_perms_set(const char *fname,
apr_fileperms_t perms);
/**
* 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
* </PRE>
* @param attr_mask Mask of valid bits in attributes.
* @param cont the pool to use.
* @remark 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.
*/
APV_DECLARE(apr_status_t) apv_file_attrs_set(const char *fname,
apr_fileattrs_t attributes,
apr_fileattrs_t attr_mask,
apr_pool_t *cont);
/**
* Create a new directory on the file system.
* @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.
*/
APV_DECLARE(apr_status_t) apv_dir_make(const char *path, apr_fileperms_t perm,
apr_pool_t *cont);
/** 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.
* @param path the path for the directory to be created. (use / on all systems)
* @param perm Permissions for the new direcoty.
* @param pool the pool to use.
*/
APV_DECLARE(apr_status_t) apv_dir_make_recursive(const char *path,
apr_fileperms_t perm,
apr_pool_t *pool);
/**
* 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.
*/
APV_DECLARE(apr_status_t) apv_dir_remove(const char *path, apr_pool_t *cont);
/**
* 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 thefile The file to get information about.
*/
APV_DECLARE(apr_status_t) apv_file_info_get(apr_finfo_t *finfo,
apr_int32_t wanted,
apv_file_t *thefile);
/**
* Truncate the file's length to the specified offset
* @param fp The file to truncate
* @param offset The offset to truncate to.
*/
APV_DECLARE(apr_status_t) apv_file_trunc(apv_file_t *fp, apr_off_t offset);
/**
* Retrieve the flags that were passed into apr_file_open()
* when the file was opened.
* @return apr_int32_t the flags
*/
APV_DECLARE(apr_int32_t) apv_file_flags_get(apv_file_t *f);
/**
* Get the pool used by the file.
* @return apr_pool_t the pool
*/
/**
* Set a file to be inherited by child processes.
* @param file The file to enable inheritance.
*
*/
APV_DECLARE(void) apv_file_inherit_set(apv_file_t *file);
/**
* Unset a file from being inherited by child processes.
* @param file The file to disable inheritance.
*/
APV_DECLARE(void) apv_file_inherit_unset(apv_file_t *file);
/**
* Open a temporary file
* @param fp The apr file to use as a temporary 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
* @param p The pool to allocate the file out of.
* @ingroup apr_file_open
* @remark
* 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.
*
*/
APV_DECLARE(apr_status_t) apv_file_mktemp(apv_file_t **fp, char *templ,
apr_int32_t flags, apr_pool_t *p);
/**
* get the specified file's stats. The file is specified by filename,
* instead of using a pre-opened file.
* @param finfo Where to store the information about the file, which is
* never touched if the call fails.
* @param fname The name of the file to stat.
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
* @param cont the pool to use to allocate the new file.
*/
APV_DECLARE(apr_status_t) apv_stat(apr_finfo_t *finfo, const char *fname,
apr_int32_t wanted, apr_pool_t *cont);
/**
* get the specified file's stats. The file is specified by filename,
* instead of using a pre-opened file. If the file is a symlink, this function
* will get the stats for the symlink not the file the symlink refers to.
* @param finfo Where to store the information about the file, which is
* never touched if the call fails.
* @param fname The name of the file to stat.
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
* @param cont the pool to use to allocate the new file.
* @deprecated This function is depreciated, it's equivilant to calling apr_stat with
* the wanted flag value APR_FINFO_LINK
*/
APV_DECLARE(apr_status_t) apv_lstat(apr_finfo_t *finfo, const char *fname,
apr_int32_t wanted, apr_pool_t *cont);
/** @} */
/**
* @defgroup APR_DIRECTORY Directory Manipulation Functions
* @{
*/
/**
* Open the specified directory.
* @param new_dir The opened directory descriptor.
* @param dirname The full path to the directory (use / on all systems)
* @param cont The pool to use.
*/
APV_DECLARE(apr_status_t) apv_dir_open(apv_dir_t **new_dir,
const char *dirname,
apr_pool_t *cont);
/**
* close the specified directory.
* @param thedir the directory descriptor to close.
*/
APV_DECLARE(apr_status_t) apv_dir_close(apv_dir_t *thedir);
/**
* Read the next entry from the specified directory.
* @param finfo the file info structure and filled in by apr_dir_read
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
* @param thedir the directory descriptor returned from apr_dir_open
* @remark All systems return . and .. as the first two files.
*/
APV_DECLARE(apr_status_t) apv_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
apv_dir_t *thedir);
/**
* Rewind the directory to the first entry.
* @param thedir the directory descriptor to rewind.
*/
APV_DECLARE(apr_status_t) apv_dir_rewind(apv_dir_t *thedir);
/** @} */
#ifdef __cplusplus
}
#endif
/** @} */
#endif /* ! APV_FILE_IO_H */