Loading...
Searching...
No Matches
File I/O Handling Functions
Apache Portability Runtime library
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

## Functions

apr_status_t | apr_file_open (apr_file_t **newf, const char *fname, apr_int32_t flag, apr_fileperms_t perm, apr_pool_t *pool)
apr_status_t | apr_file_close (apr_file_t *file)
apr_status_t | apr_file_remove (const char *path, apr_pool_t *pool)
apr_status_t | apr_file_rename (const char *from_path, const char *to_path, apr_pool_t *pool)
apr_status_t | apr_file_link (const char *from_path, const char *to_path)
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 *pool)
apr_status_t | apr_file_open_stdout (apr_file_t **thefile, apr_pool_t *pool)
apr_status_t | apr_file_open_stdin (apr_file_t **thefile, apr_pool_t *pool)
apr_status_t | apr_file_open_flags_stderr (apr_file_t **thefile, apr_int32_t flags, apr_pool_t *pool)
apr_status_t | apr_file_open_flags_stdout (apr_file_t **thefile, apr_int32_t flags, apr_pool_t *pool)
apr_status_t | apr_file_open_flags_stdin (apr_file_t **thefile, apr_int32_t flags, apr_pool_t *pool)
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_writev_full (apr_file_t *thefile, const struct iovec *vec, apr_size_t nvec, apr_size_t *nbytes)
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_sync (apr_file_t *thefile)
apr_status_t | apr_file_datasync (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_buffer_set (apr_file_t *thefile, char *buffer, apr_size_t bufsize)
apr_size_t | apr_file_buffer_size_get (apr_file_t *thefile)
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 *pool)
apr_status_t | apr_file_pipe_create_ex (apr_file_t **in, apr_file_t **out, apr_int32_t blocking, apr_pool_t *pool)
apr_status_t | apr_file_pipe_create_pools (apr_file_t **in, apr_file_t **out, apr_int32_t blocking, apr_pool_t *pool_in, apr_pool_t *pool_out)
apr_status_t | apr_file_namedpipe_create (const char *filename, apr_fileperms_t perm, apr_pool_t *pool)
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 *pool)
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 *pool)
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 *pool)
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_t * | apr_file_pool_get (const apr_file_t *thefile)
apr_status_t | apr_file_inherit_set (apr_file_t *thefile)
apr_status_t | apr_file_inherit_unset (apr_file_t *thefile)
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)

## Detailed Description

## Typedef Documentation

## apr_file_t

typedef struct apr_file_t apr_file_t

Structure for referencing files.

## apr_fileattrs_t

typedef apr_uint32_t apr_fileattrs_t

File attributes

## apr_seek_where_t

typedef int apr_seek_where_t

Type to pass as whence argument to apr_file_seek.

## Function Documentation

## apr_dir_make()

apr_status_t apr_dir_make | ( | const char * | path,
|  | apr_fileperms_t | perm,
|  | apr_pool_t * | pool
| ) |  |

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 directory.
  pool | the pool to use.

## apr_dir_make_recursive()

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 directory.
  pool | the pool to use.

## apr_dir_remove()

apr_status_t apr_dir_remove | ( | const char * | path,
|  | apr_pool_t * | pool
| ) |  |

Remove directory from the file system.

Parameters

  path | the path for the directory to be removed. (use / on all systems)
  pool | the 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.

## apr_file_append()

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 (use / on all systems)
  to_path | The full path to the destination file (use / 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_FPROT_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.
  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.

## apr_file_attrs_set()

apr_status_t apr_file_attrs_set | ( | const char * | fname,
|  | apr_fileattrs_t | attributes,
|  | apr_fileattrs_t | attr_mask,
|  | apr_pool_t * | pool
| ) |  |

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.
  pool | the 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.

## apr_file_buffer_set()

apr_status_t apr_file_buffer_set | ( | apr_file_t * | thefile,
|  | char * | buffer,
|  | apr_size_t | bufsize
| ) |  |

Give the specified apr file handle a new buffer

Parameters

  thefile | The file handle that is to be modified
  buffer | The buffer
  bufsize | The 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.

## apr_file_buffer_size_get()

apr_size_t apr_file_buffer_size_get | ( | apr_file_t * | thefile | ) |

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

Parameters

  thefile | The file handle

## apr_file_close()

apr_status_t apr_file_close | ( | apr_file_t * | file | ) |

Close the specified file.

Parameters

  file | The file descriptor to close.

## apr_file_copy()

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_FPROT_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_file_data_get()

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 retrieving data associated with this file.
  file | The currently open file.

## apr_file_data_set()

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

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 associating data with the file.
  cleanup | The cleanup routine to use when the file is destroyed.

## apr_file_datasync()

apr_status_t apr_file_datasync | ( | apr_file_t * | thefile | ) |

Transfer all file modified data to disk.

Parameters

  thefile | The file descriptor to sync

## apr_file_dup()

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_file_dup2()

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_file_eof()

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_file_flags_get()

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_file_flush()

apr_status_t apr_file_flush | ( | apr_file_t * | thefile | ) |

Flush the file's buffer.

Parameters

  thefile | The file descriptor to flush

## apr_file_getc()

apr_status_t apr_file_getc | ( | char * | ch,
|  | apr_file_t * | thefile
| ) |  |

Read a character from the specified file.

Parameters

  ch | The character to read into
  thefile | The file descriptor to read from

## apr_file_gets()

apr_status_t apr_file_gets | ( | char * | str,
|  | int | len,
|  | apr_file_t * | thefile
| ) |  |

Read a line from the 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 NUL-terminated if any characters are stored. The newline at the end of the line will not be stripped.

## apr_file_info_get()

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_file_inherit_set()

apr_status_t apr_file_inherit_set | ( | apr_file_t * | thefile | ) |

Set a file to be inherited by child processes.

## apr_file_inherit_unset()

apr_status_t apr_file_inherit_unset | ( | apr_file_t * | thefile | ) |

Unset a file from being inherited by child processes.

## apr_file_link()

apr_status_t apr_file_link | ( | const char * | from_path,
|  | const char * | to_path
| ) |  |

Create a hard link to 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)

Remarks
  Both files must reside on the same device.

## apr_file_lock()

apr_status_t apr_file_lock | ( | apr_file_t * | thefile,
|  | int | type
| ) |  |

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

  thefile | The file to lock.
  type | The type of lock to establish on the file.

## apr_file_mktemp()

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_FOPEN_CREATE | APR_FOPEN_READ | APR_FOPEN_WRITE | APR_FOPEN_EXCL | APR_FOPEN_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_file_mtime_set()

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_file_name_get()

apr_status_t apr_file_name_get | ( | const char ** | new_path,
|  | apr_file_t * | thefile
| ) |  |

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

Parameters

  new_path | The path of the file.
  thefile | The currently open file.

## apr_file_namedpipe_create()

apr_status_t apr_file_namedpipe_create | ( | const char * | filename,
|  | apr_fileperms_t | perm,
|  | apr_pool_t * | pool
| ) |  |

Create a named pipe.

Parameters

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

## apr_file_open()

apr_status_t apr_file_open | ( | apr_file_t ** | newf,
|  | const char * | fname,
|  | apr_int32_t | flag,
|  | apr_fileperms_t | perm,
|  | apr_pool_t * | pool
| ) |  |

Open the specified file.

Parameters

  newf | The opened file descriptor.
  fname | The full path to the file (using / on all systems)

  flag

  Or'ed value of:
  - APR_FOPEN_READ open for reading
  - APR_FOPEN_WRITE open for writing
  - APR_FOPEN_CREATE create the file if not there
  - APR_FOPEN_APPEND file ptr is set to end prior to all writes
  - APR_FOPEN_TRUNCATE set length to zero if file exists
  - APR_FOPEN_BINARY not a text file
  - APR_FOPEN_BUFFERED buffer the data. Default is non-buffered
  - APR_FOPEN_EXCL return error if APR_FOPEN_CREATE and file exists
  - APR_FOPEN_DELONCLOSE delete the file after closing
  - APR_FOPEN_XTHREAD Platform dependent tag to open the file for use across multiple threads
  - APR_FOPEN_SHARELOCK Platform dependent support for higher level locked read/write access to support writes across process/machines
  - APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool passed in on the pool argument (see below)
  - APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics for sendfile operations. Advisory only, apr_socket_sendfile does not check this flag
  - APR_FOPEN_LARGEFILE Platform dependent flag to enable large file support, see WARNING below
  - APR_FOPEN_SPARSE Platform dependent flag to enable sparse file support, see WARNING below
  - APR_FOPEN_NONBLOCK Platform dependent flag to enable non blocking file io

  perm | Access permissions for file.
  pool | The 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().

## apr_file_open_flags_stderr()

apr_status_t apr_file_open_flags_stderr | ( | apr_file_t ** | thefile,
|  | apr_int32_t | flags,
|  | apr_pool_t * | pool
| ) |  |

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

Parameters

  thefile | The apr file to use as stderr.

  flags

  The flags to open the file with. Only the
  - APR_FOPEN_EXCL
  - APR_FOPEN_BUFFERED
  - APR_FOPEN_XTHREAD
  - APR_FOPEN_SHARELOCK
  - APR_FOPEN_SENDFILE_ENABLED
  - APR_FOPEN_LARGEFILE
  flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.

  pool | The pool to allocate the file out of.

Remarks
  See remarks for apr_file_open_stderr().

## apr_file_open_flags_stdin()

apr_status_t apr_file_open_flags_stdin | ( | apr_file_t ** | thefile,
|  | apr_int32_t | flags,
|  | apr_pool_t * | pool
| ) |  |

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

Parameters

  thefile | The apr file to use as stdin.

  flags

  The flags to open the file with. Only the
  - APR_FOPEN_EXCL
  - APR_FOPEN_BUFFERED
  - APR_FOPEN_XTHREAD
  - APR_FOPEN_SHARELOCK
  - APR_FOPEN_SENDFILE_ENABLED
  - APR_FOPEN_LARGEFILE
  flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.

  pool | The pool to allocate the file out of.

Remarks
  See remarks for apr_file_open_stderr().

## apr_file_open_flags_stdout()

apr_status_t apr_file_open_flags_stdout | ( | apr_file_t ** | thefile,
|  | apr_int32_t | flags,
|  | apr_pool_t * | pool
| ) |  |

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

Parameters

  thefile | The apr file to use as stdout.

  flags

  The flags to open the file with. Only the
  - APR_FOPEN_EXCL
  - APR_FOPEN_BUFFERED
  - APR_FOPEN_XTHREAD
  - APR_FOPEN_SHARELOCK
  - APR_FOPEN_SENDFILE_ENABLED
  - APR_FOPEN_LARGEFILE
  flags should be used. The APR_FOPEN_WRITE flag will be set unconditionally.

  pool | The pool to allocate the file out of.

Remarks
  See remarks for apr_file_open_stderr().

## apr_file_open_stderr()

apr_status_t apr_file_open_stderr | ( | apr_file_t ** | thefile,
|  | apr_pool_t * | pool
| ) |  |

Open standard error as an apr file pointer.

Parameters

  thefile | The apr file to use as stderr.
  pool | 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_file_open_stdin()

apr_status_t apr_file_open_stdin | ( | apr_file_t ** | thefile,
|  | apr_pool_t * | pool
| ) |  |

open standard input as an apr file pointer.

Parameters

  thefile | The apr file to use as stdin.
  pool | The pool to allocate the file out of.

Remarks
  See remarks for apr_file_open_stderr().

## apr_file_open_stdout()

apr_status_t apr_file_open_stdout | ( | apr_file_t ** | thefile,
|  | apr_pool_t * | pool
| ) |  |

open standard output as an apr file pointer.

Parameters

  thefile | The apr file to use as stdout.
  pool | The pool to allocate the file out of.

Remarks
  See remarks for apr_file_open_stderr().

## apr_file_perms_set()

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_file_pipe_create()

apr_status_t apr_file_pipe_create | ( | apr_file_t ** | in,
|  | apr_file_t ** | out,
|  | apr_pool_t * | pool
| ) |  |

Create an anonymous pipe.

Parameters

  in | The newly created pipe's file for reading.
  out | The newly created pipe's file for writing.
  pool | The 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()

## apr_file_pipe_create_ex()

apr_status_t apr_file_pipe_create_ex | ( | apr_file_t ** | in,
|  | apr_file_t ** | out,
|  | apr_int32_t | blocking,
|  | apr_pool_t * | pool
| ) |  |

Create an anonymous pipe which portably supports async timeout options.

Parameters

  in | The newly created pipe's file for reading.
  out | The newly created pipe's file for writing.

  blocking

  one of these values defined in apr_thread_proc.h;
  - APR_FULL_BLOCK
  - APR_READ_BLOCK
  - APR_WRITE_BLOCK
  - APR_FULL_NONBLOCK

  pool | The 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()

## apr_file_pipe_create_pools()

apr_status_t apr_file_pipe_create_pools | ( | apr_file_t ** | in,
|  | apr_file_t ** | out,
|  | apr_int32_t | blocking,
|  | apr_pool_t * | pool_in,
|  | apr_pool_t * | pool_out
| ) |  |

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

Parameters

  in | The newly created pipe's file for reading.
  out | The newly created pipe's file for writing.

  blocking

  one of these values defined in apr_thread_proc.h;
  - APR_FULL_BLOCK
  - APR_READ_BLOCK
  - APR_WRITE_BLOCK
  - APR_FULL_NONBLOCK

  pool_in | The pool for the reading pipe.
  pool_out | The 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.

## apr_file_pipe_timeout_get()

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_file_pipe_timeout_set()

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_file_pool_get()

apr_pool_t * apr_file_pool_get | ( | const apr_file_t * | thefile | ) |

Get the pool used by the file.

## apr_file_printf()

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_file_putc()

apr_status_t apr_file_putc | ( | char | ch,
|  | apr_file_t * | thefile
| ) |  |

Write a character into the specified file.

Parameters

  ch | The character to write.
  thefile | The file descriptor to write to

## apr_file_puts()

apr_status_t apr_file_puts | ( | const char * | str,
|  | apr_file_t * | thefile
| ) |  |

Write the string into the specified file.

Parameters

  str | The string to write.
  thefile | The file descriptor to write to

## apr_file_read()

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_file_read_full()

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_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.

## apr_file_remove()

apr_status_t apr_file_remove | ( | const char * | path,
|  | apr_pool_t * | pool
| ) |  |

Delete the specified file.

Parameters

  path | The full path to the file (using / on all systems)
  pool | The pool to use.

Remarks
  If the file is open, it won't be removed until all instances are closed.

## apr_file_rename()

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_file_seek()

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.

## apr_file_setaside()

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_file_sync()

apr_status_t apr_file_sync | ( | apr_file_t * | thefile | ) |

Transfer all file modified data and metadata to disk.

Parameters

  thefile | The file descriptor to sync

## apr_file_trunc()

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.

Remarks
  The read/write file offset is repositioned to offset.

## apr_file_ungetc()

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_file_unlock()

apr_status_t apr_file_unlock | ( | apr_file_t * | thefile | ) |

Remove any outstanding locks on the file.

Parameters

  thefile | The file to unlock.

## apr_file_write()

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_file_write_full()

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, 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.

## apr_file_writev()

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_file_writev_full()

apr_status_t apr_file_writev_full | ( | 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, ensuring that all of the data is written before returning.

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
  apr_file_writev_full() is available even if the underlying operating system doesn't provide writev().

## apr_temp_dir_get()

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.