apr  1.7.0
About: APR (Apache Portable Runtime) project offers software libraries that provide a predictable and consistent interface to underlying platform-specific implementations (APR core library).
  Fossies Dox: apr-1.7.0.tar.bz2  ("inofficial" and yet experimental doxygen-generated source code documentation)  

File I/O Handling Functions
Collaboration diagram for File I/O Handling Functions:

Modules

 File Open Flags/Routines
 
 File Seek Flags
 
 File Attribute Flags
 
 {_full} max iovec size
 
 File Lock Types
 

Typedefs

typedef apr_uint32_t apr_fileattrs_t
 
typedef int apr_seek_where_t
 
typedef struct apr_file_t apr_file_t
 
typedef IN ULONG IN INT timeout
 

Functions

 APR_DECLARE (apr_status_t) apr_file_open(apr_file_t **newf
 
 APR_DECLARE (apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile)
 
 APR_DECLARE_NONSTD (int) apr_file_printf(apr_file_t *fptr
 
const char __attribute__ ((format(printf, 2, 3)))
 
 APR_DECLARE (apr_int32_t) apr_file_flags_get(apr_file_t *f)
 
 APR_DECLARE (apr_pool_t *) apr_file_pool_get(const apr_file_t *thefile)
 

Variables

const char * fname
 
const char apr_int32_t flag
 
const char apr_int32_t apr_fileperms_t perm
 
const char apr_int32_t apr_fileperms_t apr_pool_tpool
 
const char * to_path
 
const char apr_fileperms_t perms
 
apr_int32_t flags
 
void * buf
 
void apr_size_t * nbytes
 
const struct iovec * vec
 
const struct iovec apr_size_t nvec
 
void apr_size_t apr_size_t * bytes_read
 
const void apr_size_t apr_size_t * bytes_written
 
apr_file_tthefile
 
int len
 
apr_file_told_file
 
apr_file_t apr_pool_tp
 
char * buffer
 
char apr_size_t bufsize
 
apr_seek_where_t where
 
apr_seek_where_t apr_off_t * offset
 
apr_file_t ** out
 
apr_file_t apr_int32_t blocking
 
apr_file_t apr_int32_t apr_pool_tpool_in
 
apr_file_t apr_int32_t apr_pool_t apr_pool_tpool_out
 
apr_interval_time_ttimeout
 
int type
 
const char * key
 
const char apr_file_tfile
 
void * data
 
void const char apr_status_t(* cleanup )(void *))
 
const char * format
 
apr_fileattrs_t attributes
 
apr_fileattrs_t apr_fileattrs_t attr_mask
 
apr_time_t mtime
 
apr_int32_t wanted
 
char * templ
 

Detailed Description

Typedef Documentation

◆ apr_file_t

typedef struct apr_file_t apr_file_t

Structure for referencing files.

Definition at line 208 of file apr_file_io.h.

◆ apr_fileattrs_t

typedef apr_uint32_t apr_fileattrs_t

File attributes

Definition at line 200 of file apr_file_io.h.

◆ apr_seek_where_t

Type to pass as whence argument to apr_file_seek.

Definition at line 203 of file apr_file_io.h.

◆ timeout

Definition at line 477 of file apr_arch_misc.h.

Function Documentation

◆ __attribute__()

const char __attribute__ ( (format(printf, 2, 3))  )

◆ APR_DECLARE() [1/4]

APR_DECLARE ( apr_int32_t  )

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

Returns
apr_int32_t the flags

Definition at line 29 of file fileacc.c.

References apr_file_t::flags.

◆ APR_DECLARE() [2/4]

APR_DECLARE ( apr_pool_t ) const

Get the pool used by the file.

◆ APR_DECLARE() [3/4]

APR_DECLARE ( apr_size_t  )

Get the size of any buffer for the specified apr file handle

Parameters
thefileThe file handle

Get the true size that would be allocated for the given size (including the header and alignment).

Parameters
allocatorThe allocator from which to the memory would be allocated
sizeThe size to align
Returns
The aligned size (or zero on apr_size_t overflow)

Definition at line 56 of file buffer.c.

References allocator, allocator_align(), apr_file_t::bufsize, file, flags, m, and size.

◆ APR_DECLARE() [4/4]

APR_DECLARE ( apr_status_t  )

Open the specified file.

Parameters
newfThe opened file descriptor.
fnameThe full path to the file (using / on all systems)
flagOr'ed value of:
permAccess permissions for file.
poolThe pool to use.
Remarks
If perm is APR_FPROT_OS_DEFAULT and the file is being created, appropriate default permissions will be used.
By default, the returned file descriptor will not be inherited by child processes created by apr_proc_create(). This can be changed using apr_file_inherit_set().

Close the specified file.

Parameters
fileThe file descriptor to close.

Delete the specified file.

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

Rename the specified file.

Parameters
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
poolThe 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.

Create a hard link to the specified file.

Parameters
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
Remarks
Both files must reside on the same device.

Copy the specified file to another file.

Parameters
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
permsAccess permissions for the new file if it is created. In place of the usual or'd combination of file permissions, the value APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
poolThe 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.

Append the specified file to another file.

Parameters
from_pathThe full path to the source file (use / on all systems)
to_pathThe full path to the destination file (use / on all systems)
permsAccess permissions for the destination file if it is created. In place of the usual or'd combination of file permissions, the value APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
poolThe pool to use.
Remarks
The new file does not need to exist, it will be created if required.
Note that advanced filesystem permissions such as ACLs are not duplicated by this API. The target permissions (including duplicating the source file permissions) are assigned only when the target file does not yet exist.

Are we at the end of the file

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

Open standard error as an apr file pointer.

Parameters
thefileThe apr file to use as stderr.
poolThe 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.

open standard output as an apr file pointer.

Parameters
thefileThe apr file to use as stdout.
poolThe pool to allocate the file out of.
Remarks
See remarks for apr_file_open_stderr().

open standard input as an apr file pointer.

Parameters
thefileThe apr file to use as stdin.
poolThe pool to allocate the file out of.
Remarks
See remarks for apr_file_open_stderr().

open standard error as an apr file pointer, with flags.

Parameters
thefileThe apr file to use as stderr.
flagsThe flags to open the file with. Only the flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks
See remarks for apr_file_open_stderr().

open standard output as an apr file pointer, with flags.

Parameters
thefileThe apr file to use as stdout.
flagsThe flags to open the file with. Only the flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks
See remarks for apr_file_open_stderr().

open standard input as an apr file pointer, with flags.

Parameters
thefileThe apr file to use as stdin.
flagsThe flags to open the file with. Only the flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks
See remarks for apr_file_open_stderr().

Read data from the specified file.

Parameters
thefileThe file descriptor to read from.
bufThe buffer to store the data to.
nbytesOn 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.

Write data to the specified file.

Parameters
thefileThe file descriptor to write to.
bufThe buffer which contains the data.
nbytesOn 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.

Write data from iovec array to the specified file.

Parameters
thefileThe file descriptor to write to.
vecThe array from which to get the data to write to the file.
nvecThe 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.
nbytesThe 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().

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

Parameters
thefileThe file descriptor to read from.
bufThe buffer to store the data to.
nbytesThe number of bytes to read.
bytes_readIf non-NULL, this will contain the number of bytes read.
Remarks
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 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.

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

Parameters
thefileThe file descriptor to write to.
bufThe buffer which contains the data.
nbytesThe number of bytes to write.
bytes_writtenIf non-NULL, set to the number of bytes written.
Remarks
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 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.

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

Parameters
thefileThe file descriptor to write to.
vecThe array from which to get the data to write to the file.
nvecThe 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.
nbytesThe number of bytes written.
Remarks
apr_file_writev_full() is available even if the underlying operating system doesn't provide writev().

Write a character into the specified file.

Parameters
chThe character to write.
thefileThe file descriptor to write to

Read a character from the specified file.

Parameters
chThe character to read into
thefileThe file descriptor to read from

Put a character back onto a specified stream.

Parameters
chThe character to write.
thefileThe file descriptor to write to

Read a line from the specified file

Parameters
strThe buffer to store the string in.
lenThe length of the string
thefileThe file descriptor to read from
Remarks
The buffer will be NUL-terminated if any characters are stored. The newline at the end of the line will not be stripped.

Write the string into the specified file.

Parameters
strThe string to write.
thefileThe file descriptor to write to

Flush the file's buffer.

Parameters
thefileThe file descriptor to flush

Transfer all file modified data and metadata to disk.

Parameters
thefileThe file descriptor to sync

Transfer all file modified data to disk.

Parameters
thefileThe file descriptor to sync

Duplicate the specified file descriptor.

Parameters
new_fileThe structure to duplicate into.
old_fileThe file to duplicate.
pThe pool to use for the new file.
Remarks
*new_file must point to a valid apr_file_t, or point to NULL.

Duplicate the specified file descriptor and close the original

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

Move the specified file descriptor to a new pool

Parameters
new_filePointer in which to return the new apr_file_t
old_fileThe file to move
pThe 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

Give the specified apr file handle a new buffer

Parameters
thefileThe file handle that is to be modified
bufferThe buffer
bufsizeThe size of the buffer
Remarks
It is possible to add a buffer to previously unbuffered 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.

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

Parameters
thefileThe file descriptor
whereHow 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
offsetThe offset to move the pointer to.
Remarks
The third argument is modified to be the offset the pointer was actually moved to.

Create an anonymous pipe.

Parameters
inThe newly created pipe's file for reading.
outThe newly created pipe's file for writing.
poolThe pool to operate on.
Remarks
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().
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 also
apr_file_pipe_create_pools()

Create an anonymous pipe which portably supports async timeout options.

Parameters
inThe newly created pipe's file for reading.
outThe newly created pipe's file for writing.
blockingone of these values defined in apr_thread_proc.h;
poolThe pool to operate on.
Remarks
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().
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 where one or both ends require non-blocking semantics.
Deprecated:
See also
apr_file_pipe_create_pools()

Create an anonymous pipe which portably supports async timeout options, placing each side of the pipe in a different pool.

Parameters
inThe newly created pipe's file for reading.
outThe newly created pipe's file for writing.
blockingone of these values defined in apr_thread_proc.h;
pool_inThe pool for the reading pipe.
pool_outThe pool for the writing pipe.
Remarks
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().
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 where one or both ends require non-blocking semantics.

Create a named pipe.

Parameters
filenameThe filename of the named pipe
permThe permissions for the newly created pipe.
poolThe pool to operate on.

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

Parameters
thepipeThe pipe we are getting a timeout for.
timeoutThe current timeout value in microseconds.

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

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

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.

Parameters
thefileThe file to lock.
typeThe type of lock to establish on the file.

Remove any outstanding locks on the file.

Parameters
thefileThe file to unlock.

accessor and general file_io functions. return the file name of the current file.

Parameters
new_pathThe path of the file.
thefileThe currently open file.

Return the data associated with the current file.

Parameters
dataThe user data associated with the file.
keyThe key to use for retrieving data associated with this file.
fileThe currently open file.

Set the data associated with the current file.

Parameters
fileThe currently open file.
dataThe user data to associate with the file.
keyThe key to use for associating data with the file.
cleanupThe cleanup routine to use when the file is destroyed.

set the specified file's permission bits.

Parameters
fnameThe file (name) to apply the permissions to.
permsThe 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.

Set attributes of the specified file.

Parameters
fnameThe full path to the file (using / on all systems)
attributesOr'd combination of
attr_maskMask of valid bits in attributes.
poolthe pool to use.
Remarks
This function should be used in preference to explicit 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.

Set the mtime of the specified file.

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

Create a new directory on the file system.

Parameters
paththe path for the directory to be created. (use / on all systems)
permPermissions for the new directory.
poolthe pool to use.

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
paththe path for the directory to be created. (use / on all systems)
permPermissions for the new directory.
poolthe pool to use.

Remove directory from the file system.

Parameters
paththe path for the directory to be removed. (use / on all systems)
poolthe pool to use.
Remarks
Removing a directory which is in-use (e.g., the current working directory, or during apr_dir_read, or with an open file) is not portable.

get the specified file's stats.

Parameters
finfoWhere to store the information about the file.
wantedThe desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values
thefileThe file to get information about.

Truncate the file's length to the specified offset

Parameters
fpThe file to truncate
offsetThe offset to truncate to.
Remarks
The read/write file offset is repositioned to offset.

Set a file to be inherited by child processes.

Unset a file from being inherited by child processes.

Open a temporary file

Parameters
fpThe apr file to use as a temporary file.
templThe template to use when creating a temp file.
flagsThe flags to open the file with. If this is zero, the file is opened with APR_FOPEN_CREATE | APR_FOPEN_READ | APR_FOPEN_WRITE | APR_FOPEN_EXCL | APR_FOPEN_DELONCLOSE
pThe 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.

Find an existing directory suitable as a temporary storage location.

Parameters
temp_dirThe temp directory.
pThe 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.

The problem with trying to output the entire iovec is that we cannot maintain the behaviour that a real writev would have. If we iterate over the iovec one at a time, we lose the atomic properties of writev(). The other option is to combine the entire iovec into one buffer that we could then send in one call to write(). This is not reasonable since we do not know how much data an iovec could contain.

The only reasonable option, that maintains the semantics of a real writev(), is to only write the first iovec. Callers of file_writev() must deal with partial writes as they normally would. If you want to ensure an entire iovec is written, use apr_file_writev_full().

Definition at line 21 of file apr_atomic.c.

◆ APR_DECLARE_NONSTD()

APR_DECLARE_NONSTD ( int  )

Write a string to a file using a printf format.

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

Definition at line 353 of file readwrite.c.

Variable Documentation

◆ attr_mask

Definition at line 908 of file apr_file_io.h.

◆ attributes

apr_fileattrs_t attributes

Definition at line 908 of file apr_file_io.h.

Referenced by APR_DECLARE().

◆ blocking

apr_file_t apr_int32_t blocking

Definition at line 758 of file apr_file_io.h.

Referenced by file_pipe_block().

◆ buf

const void* buf

Definition at line 482 of file apr_file_io.h.

◆ buffer

char* buffer

Definition at line 696 of file apr_file_io.h.

Referenced by apr__SHA256_End(), APR_DECLARE(), main(), and nameof().

◆ bufsize

char apr_size_t bufsize

Definition at line 696 of file apr_file_io.h.

◆ bytes_read

void apr_size_t apr_size_t* bytes_read

Definition at line 542 of file apr_file_io.h.

Referenced by APR_DECLARE().

◆ bytes_written

const void apr_size_t apr_size_t* bytes_written

Definition at line 567 of file apr_file_io.h.

◆ cleanup

const void apr_status_t(* cleanup

◆ data

◆ file

◆ flag

const char apr_int32_t flag

Definition at line 279 of file apr_file_io.h.

Referenced by APR_DECLARE().

◆ flags

char apr_int32_t flags

Definition at line 420 of file apr_file_io.h.

◆ fname

const char* fname

Definition at line 279 of file apr_file_io.h.

◆ format

apr_size_t const char * format

◆ key

◆ len

int len

Definition at line 618 of file apr_file_io.h.

◆ mtime

apr_time_t mtime

Definition at line 921 of file apr_file_io.h.

◆ nbytes

const struct iovec apr_size_t apr_size_t * nbytes

Definition at line 482 of file apr_file_io.h.

Referenced by APR_DECLARE(), file_read_buffered(), and read_with_timeout().

◆ nvec

const struct iovec apr_size_t nvec

Definition at line 519 of file apr_file_io.h.

Referenced by apr_socket_sendv().

◆ offset

apr_off_t offset

Definition at line 717 of file apr_file_io.h.

Referenced by APR_DECLARE(), apr_file_trunc(), and explode_time().

◆ old_file

apr_file_t * old_file

Definition at line 654 of file apr_file_io.h.

Referenced by APR_DECLARE(), and file_dup().

◆ out

apr_size_t char * out

◆ p

Definition at line 654 of file apr_file_io.h.

◆ perm

◆ perms

◆ pool

apr_pool_t* pool

Definition at line 279 of file apr_file_io.h.

◆ pool_in

apr_file_t apr_int32_t apr_pool_t* pool_in

Definition at line 784 of file apr_file_io.h.

Referenced by file_pipe_create().

◆ pool_out

apr_file_t apr_int32_t apr_pool_t apr_pool_t* pool_out

Definition at line 784 of file apr_file_io.h.

Referenced by file_pipe_create().

◆ templ

char* templ

Definition at line 1012 of file apr_file_io.h.

◆ thefile

◆ timeout

Definition at line 805 of file apr_file_io.h.

◆ to_path

const char * to_path

Definition at line 308 of file apr_file_io.h.

Referenced by APR_DECLARE(), and apr_file_transfer_contents().

◆ type

◆ vec

const struct iovec * vec

Definition at line 519 of file apr_file_io.h.

Referenced by apr_socket_sendv().

◆ wanted

apr_int32_t wanted

Definition at line 960 of file apr_file_io.h.

◆ where

Definition at line 717 of file apr_file_io.h.

Referenced by APR_DECLARE(), apr_socket_sendto(), and c2x().