Apache Portable Runtime
apr_file_io.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_FILE_IO_H
00018 #define APR_FILE_IO_H
00019 
00020 /**
00021  * @file apr_file_io.h
00022  * @brief APR File I/O Handling
00023  */
00024 
00025 #include "apr.h"
00026 #include "apr_pools.h"
00027 #include "apr_time.h"
00028 #include "apr_errno.h"
00029 #include "apr_file_info.h"
00030 #include "apr_inherit.h"
00031 
00032 #define APR_WANT_STDIO          /**< for SEEK_* */
00033 #define APR_WANT_IOVEC          /**< for apr_file_writev */
00034 #include "apr_want.h"
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif /* __cplusplus */
00039 
00040 /**
00041  * @defgroup apr_file_io File I/O Handling Functions
00042  * @ingroup APR 
00043  * @{
00044  */
00045 
00046 /**
00047  * @defgroup apr_file_open_flags File Open Flags/Routines
00048  * @{
00049  */
00050 
00051 /* Note to implementors: Values in the range 0x00100000--0x80000000
00052    are reserved for platform-specific values. */
00053 
00054 #define APR_FOPEN_READ       0x00001  /**< Open the file for reading */
00055 #define APR_FOPEN_WRITE      0x00002  /**< Open the file for writing */
00056 #define APR_FOPEN_CREATE     0x00004  /**< Create the file if not there */
00057 #define APR_FOPEN_APPEND     0x00008  /**< Append to the end of the file */
00058 #define APR_FOPEN_TRUNCATE   0x00010  /**< Open the file and truncate
00059                                          to 0 length */
00060 #define APR_FOPEN_BINARY     0x00020  /**< Open the file in binary mode
00061                                          (This flag is ignored on UNIX 
00062                                          because it has no meaning)*/
00063 #define APR_FOPEN_EXCL       0x00040  /**< Open should fail if #APR_FOPEN_CREATE
00064                                          and file exists. */
00065 #define APR_FOPEN_BUFFERED   0x00080  /**< Open the file for buffered I/O */
00066 #define APR_FOPEN_DELONCLOSE 0x00100  /**< Delete the file after close */
00067 #define APR_FOPEN_XTHREAD    0x00200  /**< Platform dependent tag to open
00068                                          the file for use across multiple
00069                                          threads */
00070 #define APR_FOPEN_SHARELOCK  0x00400  /**< Platform dependent support for
00071                                          higher level locked read/write
00072                                          access to support writes across
00073                                          process/machines */
00074 #define APR_FOPEN_NOCLEANUP  0x00800  /**< Do not register a cleanup
00075                                          when the file is opened. The
00076                                          apr_os_file_t handle in apr_file_t
00077                                          will not be closed when the pool
00078                                          is destroyed. */
00079 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
00080                                              file should support
00081                                              apr_socket_sendfile operation */
00082 #define APR_FOPEN_LARGEFILE   0x04000 /**< Platform dependent flag to enable
00083                                        * large file support, see WARNING below 
00084                                        */
00085 
00086 #define APR_FOPEN_SPARSE      0x08000 /**< Platform dependent flag to enable
00087                                        * sparse file support, see WARNING below
00088                                        */
00089 
00090 #define APR_FOPEN_ROTATING  0x10000 /**< Do file file rotation checking */
00091  
00092 #define APR_FOPEN_MANUAL_ROTATE  0x20000 /**< Enable Manual rotation */
00093 
00094 #define APR_FOPEN_NONBLOCK    0x40000 /**< Platform dependent flag to enable
00095                                        * non blocking file io */
00096 
00097  
00098 
00099 /* backcompat */
00100 #define APR_READ             APR_FOPEN_READ       /**< @deprecated @see APR_FOPEN_READ */
00101 #define APR_WRITE            APR_FOPEN_WRITE      /**< @deprecated @see APR_FOPEN_WRITE */   
00102 #define APR_CREATE           APR_FOPEN_CREATE     /**< @deprecated @see APR_FOPEN_CREATE */   
00103 #define APR_APPEND           APR_FOPEN_APPEND     /**< @deprecated @see APR_FOPEN_APPEND */   
00104 #define APR_TRUNCATE         APR_FOPEN_TRUNCATE   /**< @deprecated @see APR_FOPEN_TRUNCATE */   
00105 #define APR_BINARY           APR_FOPEN_BINARY     /**< @deprecated @see APR_FOPEN_BINARY */   
00106 #define APR_EXCL             APR_FOPEN_EXCL       /**< @deprecated @see APR_FOPEN_EXCL */   
00107 #define APR_BUFFERED         APR_FOPEN_BUFFERED   /**< @deprecated @see APR_FOPEN_BUFFERED */   
00108 #define APR_DELONCLOSE       APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */   
00109 #define APR_XTHREAD          APR_FOPEN_XTHREAD    /**< @deprecated @see APR_FOPEN_XTHREAD */   
00110 #define APR_SHARELOCK        APR_FOPEN_SHARELOCK  /**< @deprecated @see APR_FOPEN_SHARELOCK */   
00111 #define APR_FILE_NOCLEANUP   APR_FOPEN_NOCLEANUP  /**< @deprecated @see APR_FOPEN_NOCLEANUP */   
00112 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */   
00113 #define APR_LARGEFILE        APR_FOPEN_LARGEFILE  /**< @deprecated @see APR_FOPEN_LARGEFILE */   
00114 
00115 /** @def APR_FOPEN_LARGEFILE 
00116  * @warning APR_FOPEN_LARGEFILE flag only has effect on some
00117  * platforms where sizeof(apr_off_t) == 4.  Where implemented, it
00118  * allows opening and writing to a file which exceeds the size which
00119  * can be represented by apr_off_t (2 gigabytes).  When a file's size
00120  * does exceed 2Gb, apr_file_info_get() will fail with an error on the
00121  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
00122  * filename.  apr_dir_read() will fail with #APR_INCOMPLETE on a
00123  * directory entry for a large file depending on the particular
00124  * APR_FINFO_* flags.  Generally, it is not recommended to use this
00125  * flag.
00126  *
00127  * @def APR_FOPEN_SPARSE
00128  * @warning APR_FOPEN_SPARSE may, depending on platform, convert a
00129  * normal file to a sparse file.  Some applications may be unable
00130  * to decipher a sparse file, so it's critical that the sparse file
00131  * flag should only be used for files accessed only by APR or other
00132  * applications known to be able to decipher them.  APR does not
00133  * guarantee that it will compress the file into sparse segments
00134  * if it was previously created and written without the sparse flag.
00135  * On platforms which do not understand, or on file systems which
00136  * cannot handle sparse files, the flag is ignored by apr_file_open().
00137  */
00138 
00139 /** @} */
00140 
00141 /**
00142  * @defgroup apr_file_seek_flags File Seek Flags
00143  * @{
00144  */
00145 
00146 /* flags for apr_file_seek */
00147 /** Set the file position */
00148 #define APR_SET SEEK_SET
00149 /** Current */
00150 #define APR_CUR SEEK_CUR
00151 /** Go to end of file */
00152 #define APR_END SEEK_END
00153 /** @} */
00154 
00155 /**
00156  * @defgroup apr_file_attrs_set_flags File Attribute Flags
00157  * @{
00158  */
00159 
00160 /* flags for apr_file_attrs_set */
00161 #define APR_FILE_ATTR_READONLY   0x01          /**< File is read-only */
00162 #define APR_FILE_ATTR_EXECUTABLE 0x02          /**< File is executable */
00163 #define APR_FILE_ATTR_HIDDEN     0x04          /**< File is hidden */
00164 /** @} */
00165 
00166 /**
00167  * @defgroup apr_file_writev{_full} max iovec size
00168  * @{
00169  */
00170 #if defined(DOXYGEN)
00171 #define APR_MAX_IOVEC_SIZE 1024                /**< System dependent maximum 
00172                                                     size of an iovec array */
00173 #elif defined(IOV_MAX)
00174 #define APR_MAX_IOVEC_SIZE IOV_MAX
00175 #elif defined(MAX_IOVEC)
00176 #define APR_MAX_IOVEC_SIZE MAX_IOVEC
00177 #else
00178 #define APR_MAX_IOVEC_SIZE 1024
00179 #endif
00180 /** @} */
00181 
00182 /** File attributes */
00183 typedef apr_uint32_t apr_fileattrs_t;
00184 
00185 /** Type to pass as whence argument to apr_file_seek. */
00186 typedef int       apr_seek_where_t;
00187 
00188 /**
00189  * Structure for referencing files.
00190  */
00191 typedef struct apr_file_t         apr_file_t;
00192 
00193 /* File lock types/flags */
00194 /**
00195  * @defgroup apr_file_lock_types File Lock Types
00196  * @{
00197  */
00198 
00199 #define APR_FLOCK_SHARED        1       /**< Shared lock. More than one process
00200                                            or thread can hold a shared lock
00201                                            at any given time. Essentially,
00202                                            this is a "read lock", preventing
00203                                            writers from establishing an
00204                                            exclusive lock. */
00205 #define APR_FLOCK_EXCLUSIVE     2       /**< Exclusive lock. Only one process
00206                                            may hold an exclusive lock at any
00207                                            given time. This is analogous to
00208                                            a "write lock". */
00209 
00210 #define APR_FLOCK_TYPEMASK      0x000F  /**< mask to extract lock type */
00211 #define APR_FLOCK_NONBLOCK      0x0010  /**< do not block while acquiring the
00212                                            file lock */
00213 /** @} */
00214 
00215 /**
00216  * Open the specified file.
00217  * @param newf The opened file descriptor.
00218  * @param fname The full path to the file (using / on all systems)
00219  * @param flag Or'ed value of:
00220  * @li #APR_FOPEN_READ           open for reading
00221  * @li #APR_FOPEN_WRITE          open for writing
00222  * @li #APR_FOPEN_CREATE         create the file if not there
00223  * @li #APR_FOPEN_APPEND         file ptr is set to end prior to all writes
00224  * @li #APR_FOPEN_TRUNCATE       set length to zero if file exists
00225  * @li #APR_FOPEN_BINARY         not a text file
00226  * @li #APR_FOPEN_BUFFERED       buffer the data.  Default is non-buffered
00227  * @li #APR_FOPEN_EXCL           return error if #APR_FOPEN_CREATE and file exists
00228  * @li #APR_FOPEN_DELONCLOSE     delete the file after closing
00229  * @li #APR_FOPEN_XTHREAD        Platform dependent tag to open the file
00230  *                               for use across multiple threads
00231  * @li #APR_FOPEN_SHARELOCK      Platform dependent support for higher
00232  *                               level locked read/write access to support
00233  *                               writes across process/machines
00234  * @li #APR_FOPEN_NOCLEANUP      Do not register a cleanup with the pool 
00235  *                               passed in on the @a pool argument (see below)
00236  * @li #APR_FOPEN_SENDFILE_ENABLED  Open with appropriate platform semantics
00237  *                               for sendfile operations.  Advisory only,
00238  *                               apr_socket_sendfile does not check this flag
00239  * @li #APR_FOPEN_LARGEFILE      Platform dependent flag to enable large file
00240  *                               support, see WARNING below 
00241  * @li #APR_FOPEN_SPARSE         Platform dependent flag to enable sparse file
00242  *                               support, see WARNING below
00243  * @li #APR_FOPEN_ROTATING       Do file file rotation checking
00244  * @li #APR_FOPEN_MANUAL_ROTATE  Enable Manual rotation
00245  * @li #APR_FOPEN_NONBLOCK       Platform dependent flag to enable
00246  *                               non blocking file io
00247  * @param perm Access permissions for file.
00248  * @param pool The pool to use.
00249  * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created,
00250  * appropriate default permissions will be used.
00251  * @remark By default, the returned file descriptor will not be
00252  * inherited by child processes created by apr_proc_create().  This
00253  * can be changed using apr_file_inherit_set().
00254  */
00255 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
00256                                         apr_int32_t flag, apr_fileperms_t perm,
00257                                         apr_pool_t *pool);
00258 
00259 /**
00260  * Close the specified file.
00261  * @param file The file descriptor to close.
00262  */
00263 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
00264 
00265 /**
00266  * Delete the specified file.
00267  * @param path The full path to the file (using / on all systems)
00268  * @param pool The pool to use.
00269  * @remark If the file is open, it won't be removed until all
00270  * instances are closed.
00271  */
00272 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
00273 
00274 /**
00275  * Rename the specified file.
00276  * @param from_path The full path to the original file (using / on all systems)
00277  * @param to_path The full path to the new file (using / on all systems)
00278  * @param pool The pool to use.
00279  * @warning If a file exists at the new location, then it will be
00280  * overwritten.  Moving files or directories across devices may not be
00281  * possible.
00282  */
00283 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 
00284                                           const char *to_path,
00285                                           apr_pool_t *pool);
00286 
00287 /**
00288  * Create a hard link to the specified file.
00289  * @param from_path The full path to the original file (using / on all systems)
00290  * @param to_path The full path to the new file (using / on all systems)
00291  * @remark Both files must reside on the same device.
00292  */
00293 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path, 
00294                                           const char *to_path);
00295 
00296 /**
00297  * Copy the specified file to another file.
00298  * @param from_path The full path to the original file (using / on all systems)
00299  * @param to_path The full path to the new file (using / on all systems)
00300  * @param perms Access permissions for the new file if it is created.
00301  *     In place of the usual or'd combination of file permissions, the
00302  *     value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
00303  *     file's permissions are copied.
00304  * @param pool The pool to use.
00305  * @remark The new file does not need to exist, it will be created if required.
00306  * @warning If the new file already exists, its contents will be overwritten.
00307  */
00308 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 
00309                                         const char *to_path,
00310                                         apr_fileperms_t perms,
00311                                         apr_pool_t *pool);
00312 
00313 /**
00314  * Append the specified file to another file.
00315  * @param from_path The full path to the source file (use / on all systems)
00316  * @param to_path The full path to the destination file (use / on all systems)
00317  * @param perms Access permissions for the destination file if it is created.
00318  *     In place of the usual or'd combination of file permissions, the
00319  *     value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
00320  *     file's permissions are copied.
00321  * @param pool The pool to use.
00322  * @remark The new file does not need to exist, it will be created if required.
00323  */
00324 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 
00325                                           const char *to_path,
00326                                           apr_fileperms_t perms,
00327                                           apr_pool_t *pool);
00328 
00329 /**
00330  * Are we at the end of the file
00331  * @param fptr The apr file we are testing.
00332  * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise.
00333  */
00334 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
00335 
00336 /**
00337  * Open standard error as an apr file pointer.
00338  * @param thefile The apr file to use as stderr.
00339  * @param pool The pool to allocate the file out of.
00340  * 
00341  * @remark The only reason that the apr_file_open_std* functions exist
00342  * is that you may not always have a stderr/out/in on Windows.  This
00343  * is generally a problem with newer versions of Windows and services.
00344  * 
00345  * @remark The other problem is that the C library functions generally work
00346  * differently on Windows and Unix.  So, by using apr_file_open_std*
00347  * functions, you can get a handle to an APR struct that works with
00348  * the APR functions which are supposed to work identically on all
00349  * platforms.
00350  */
00351 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
00352                                                apr_pool_t *pool);
00353 
00354 /**
00355  * open standard output as an apr file pointer.
00356  * @param thefile The apr file to use as stdout.
00357  * @param pool The pool to allocate the file out of.
00358  * 
00359  * @remark See remarks for apr_file_open_stderr().
00360  */
00361 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
00362                                                apr_pool_t *pool);
00363 
00364 /**
00365  * open standard input as an apr file pointer.
00366  * @param thefile The apr file to use as stdin.
00367  * @param pool The pool to allocate the file out of.
00368  * 
00369  * @remark See remarks for apr_file_open_stderr().
00370  */
00371 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
00372                                               apr_pool_t *pool);
00373 
00374 /**
00375  * open standard error as an apr file pointer, with flags.
00376  * @param thefile The apr file to use as stderr.
00377  * @param flags The flags to open the file with. Only the 
00378  *              @li #APR_FOPEN_EXCL
00379  *              @li #APR_FOPEN_BUFFERED
00380  *              @li #APR_FOPEN_XTHREAD
00381  *              @li #APR_FOPEN_SHARELOCK 
00382  *              @li #APR_FOPEN_SENDFILE_ENABLED
00383  *              @li #APR_FOPEN_LARGEFILE
00384  *
00385  *              flags should be used. The #APR_FOPEN_WRITE flag will
00386  *              be set unconditionally.
00387  * @param pool The pool to allocate the file out of.
00388  * 
00389  * @remark See remarks for apr_file_open_stderr().
00390  */
00391 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile,
00392                                                      apr_int32_t flags,
00393                                                      apr_pool_t *pool);
00394 
00395 /**
00396  * open standard output as an apr file pointer, with flags.
00397  * @param thefile The apr file to use as stdout.
00398  * @param flags The flags to open the file with. Only the 
00399  *              @li #APR_FOPEN_EXCL
00400  *              @li #APR_FOPEN_BUFFERED
00401  *              @li #APR_FOPEN_XTHREAD
00402  *              @li #APR_FOPEN_SHARELOCK 
00403  *              @li #APR_FOPEN_SENDFILE_ENABLED
00404  *              @li #APR_FOPEN_LARGEFILE
00405  *
00406  *              flags should be used. The #APR_FOPEN_WRITE flag will
00407  *              be set unconditionally.
00408  * @param pool The pool to allocate the file out of.
00409  * 
00410  * @remark See remarks for apr_file_open_stderr().
00411  */
00412 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile,
00413                                                      apr_int32_t flags,
00414                                                      apr_pool_t *pool);
00415 
00416 /**
00417  * open standard input as an apr file pointer, with flags.
00418  * @param thefile The apr file to use as stdin.
00419  * @param flags The flags to open the file with. Only the 
00420  *              @li #APR_FOPEN_EXCL
00421  *              @li #APR_FOPEN_BUFFERED
00422  *              @li #APR_FOPEN_XTHREAD
00423  *              @li #APR_FOPEN_SHARELOCK 
00424  *              @li #APR_FOPEN_SENDFILE_ENABLED
00425  *              @li #APR_FOPEN_LARGEFILE
00426  *
00427  *              flags should be used. The #APR_FOPEN_WRITE flag will
00428  *              be set unconditionally.
00429  * @param pool The pool to allocate the file out of.
00430  * 
00431  * @remark See remarks for apr_file_open_stderr().
00432  */
00433 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile,
00434                                                      apr_int32_t flags,
00435                                                      apr_pool_t *pool);
00436 
00437 /**
00438  * Read data from the specified file.
00439  * @param thefile The file descriptor to read from.
00440  * @param buf The buffer to store the data to.
00441  * @param nbytes On entry, the number of bytes to read; on exit, the number
00442  * of bytes read.
00443  *
00444  * @remark apr_file_read() will read up to the specified number of
00445  * bytes, but never more.  If there isn't enough data to fill that
00446  * number of bytes, all of the available data is read.  The third
00447  * argument is modified to reflect the number of bytes read.  If a
00448  * char was put back into the stream via ungetc, it will be the first
00449  * character returned.
00450  *
00451  * @remark It is not possible for both bytes to be read and an #APR_EOF
00452  * or other error to be returned.  #APR_EINTR is never returned.
00453  */
00454 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
00455                                         apr_size_t *nbytes);
00456 
00457 /**
00458  * Write data to the specified file.
00459  * @param thefile The file descriptor to write to.
00460  * @param buf The buffer which contains the data.
00461  * @param nbytes On entry, the number of bytes to write; on exit, the number 
00462  *               of bytes written.
00463  *
00464  * @remark apr_file_write() will write up to the specified number of
00465  * bytes, but never more.  If the OS cannot write that many bytes, it
00466  * will write as many as it can.  The third argument is modified to
00467  * reflect the * number of bytes written.
00468  *
00469  * @remark It is possible for both bytes to be written and an error to
00470  * be returned.  #APR_EINTR is never returned.
00471  */
00472 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
00473                                          apr_size_t *nbytes);
00474 
00475 /**
00476  * Write data from iovec array to the specified file.
00477  * @param thefile The file descriptor to write to.
00478  * @param vec The array from which to get the data to write to the file.
00479  * @param nvec The number of elements in the struct iovec array. This must 
00480  *             be smaller than #APR_MAX_IOVEC_SIZE.  If it isn't, the function 
00481  *             will fail with #APR_EINVAL.
00482  * @param nbytes The number of bytes written.
00483  *
00484  * @remark It is possible for both bytes to be written and an error to
00485  * be returned.  #APR_EINTR is never returned.
00486  *
00487  * @remark apr_file_writev() is available even if the underlying
00488  * operating system doesn't provide writev().
00489  */
00490 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
00491                                           const struct iovec *vec,
00492                                           apr_size_t nvec, apr_size_t *nbytes);
00493 
00494 /**
00495  * Read data from the specified file, ensuring that the buffer is filled
00496  * before returning.
00497  * @param thefile The file descriptor to read from.
00498  * @param buf The buffer to store the data to.
00499  * @param nbytes The number of bytes to read.
00500  * @param bytes_read If non-NULL, this will contain the number of bytes read.
00501  *
00502  * @remark apr_file_read_full() will read up to the specified number of
00503  * bytes, but never more.  If there isn't enough data to fill that
00504  * number of bytes, then the process/thread will block until it is
00505  * available or EOF is reached.  If a char was put back into the
00506  * stream via ungetc, it will be the first character returned.
00507  *
00508  * @remark It is possible for both bytes to be read and an error to be
00509  * returned.  And if *bytes_read is less than nbytes, an accompanying
00510  * error is _always_ returned.
00511  *
00512  * @remark #APR_EINTR is never returned.
00513  */
00514 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
00515                                              apr_size_t nbytes,
00516                                              apr_size_t *bytes_read);
00517 
00518 /**
00519  * Write data to the specified file, ensuring that all of the data is
00520  * written before returning.
00521  * @param thefile The file descriptor to write to.
00522  * @param buf The buffer which contains the data.
00523  * @param nbytes The number of bytes to write.
00524  * @param bytes_written If non-NULL, set to the number of bytes written.
00525  * 
00526  * @remark apr_file_write_full() will write up to the specified number of
00527  * bytes, but never more.  If the OS cannot write that many bytes, the
00528  * process/thread will block until they can be written. Exceptional
00529  * error such as "out of space" or "pipe closed" will terminate with
00530  * an error.
00531  *
00532  * @remark It is possible for both bytes to be written and an error to
00533  * be returned.  And if *bytes_written is less than nbytes, an
00534  * accompanying error is _always_ returned.
00535  *
00536  * @remark #APR_EINTR is never returned.
00537  */
00538 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 
00539                                               const void *buf,
00540                                               apr_size_t nbytes, 
00541                                               apr_size_t *bytes_written);
00542 
00543 
00544 /**
00545  * Write data from iovec array to the specified file, ensuring that all of the
00546  * data is written before returning.
00547  * @param thefile The file descriptor to write to.
00548  * @param vec The array from which to get the data to write to the file.
00549  * @param nvec The number of elements in the struct iovec array. This must 
00550  *             be smaller than #APR_MAX_IOVEC_SIZE.  If it isn't, the function 
00551  *             will fail with #APR_EINVAL.
00552  * @param nbytes The number of bytes written.
00553  *
00554  * @remark apr_file_writev_full() is available even if the underlying
00555  * operating system doesn't provide writev().
00556  */
00557 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile,
00558                                                const struct iovec *vec,
00559                                                apr_size_t nvec,
00560                                                apr_size_t *nbytes);
00561 /**
00562  * Write a character into the specified file.
00563  * @param ch The character to write.
00564  * @param thefile The file descriptor to write to
00565  */
00566 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
00567 
00568 /**
00569  * Read a character from the specified file.
00570  * @param ch The character to read into
00571  * @param thefile The file descriptor to read from
00572  */
00573 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
00574 
00575 /**
00576  * Put a character back onto a specified stream.
00577  * @param ch The character to write.
00578  * @param thefile The file descriptor to write to
00579  */
00580 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
00581 
00582 /**
00583  * Read a line from the specified file
00584  * @param str The buffer to store the string in. 
00585  * @param len The length of the string
00586  * @param thefile The file descriptor to read from
00587  * @remark The buffer will be NUL-terminated if any characters are stored.
00588  *         The newline at the end of the line will not be stripped.
00589  */
00590 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 
00591                                         apr_file_t *thefile);
00592 
00593 /**
00594  * Write the string into the specified file.
00595  * @param str The string to write. 
00596  * @param thefile The file descriptor to write to
00597  */
00598 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
00599 
00600 /**
00601  * Wait for a pipe to be ready for input or output
00602  * @param thepipe the pipe to wait on
00603  * @param direction whether to wait for reading or writing to be ready
00604  *        Can be either #APR_WAIT_READ or #APR_WAIT_WRITE
00605  * @remark Will time out if thepipe has a time out set for it
00606  */
00607 APR_DECLARE(apr_status_t) apr_file_pipe_wait(apr_file_t *thepipe,
00608                                              apr_wait_type_t direction);
00609 
00610 /**
00611  * Flush the file's buffer.
00612  * @param thefile The file descriptor to flush
00613  */
00614 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
00615 
00616 /**
00617  * Transfer all file modified data and metadata to disk.
00618  * @param thefile The file descriptor to sync
00619  */
00620 APR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile);
00621 
00622 /**
00623  * Transfer all file modified data to disk.
00624  * @param thefile The file descriptor to sync
00625  */
00626 APR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile);
00627 
00628 /**
00629  * Duplicate the specified file descriptor.
00630  * @param new_file The structure to duplicate into. 
00631  * @param old_file The file to duplicate.
00632  * @param p The pool to use for the new file.
00633  * @remark *new_file must point to a valid apr_file_t, or point to NULL.
00634  */         
00635 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
00636                                        apr_file_t *old_file,
00637                                        apr_pool_t *p);
00638 
00639 /**
00640  * Duplicate the specified file descriptor and close the original
00641  * @param new_file The old file that is to be closed and reused
00642  * @param old_file The file to duplicate
00643  * @param p        The pool to use for the new file
00644  *
00645  * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
00646  */
00647 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
00648                                         apr_file_t *old_file,
00649                                         apr_pool_t *p);
00650 
00651 /**
00652  * Move the specified file descriptor to a new pool
00653  * @param new_file Pointer in which to return the new apr_file_t
00654  * @param old_file The file to move
00655  * @param p        The pool to which the descriptor is to be moved
00656  * @remark Unlike apr_file_dup2(), this function doesn't do an
00657  *         OS dup() operation on the underlying descriptor; it just
00658  *         moves the descriptor's apr_file_t wrapper to a new pool.
00659  * @remark The new pool need not be an ancestor of old_file's pool.
00660  * @remark After calling this function, old_file may not be used
00661  */
00662 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
00663                                             apr_file_t *old_file,
00664                                             apr_pool_t *p);
00665 
00666 /**
00667  * Give the specified apr file handle a new buffer 
00668  * @param thefile  The file handle that is to be modified
00669  * @param buffer   The buffer
00670  * @param bufsize  The size of the buffer
00671  * @remark It is possible to add a buffer to previously unbuffered
00672  *         file handles, the #APR_FOPEN_BUFFERED flag will be added to
00673  *         the file handle's flags. Likewise, with buffer=NULL and
00674  *         bufsize=0 arguments it is possible to make a previously
00675  *         buffered file handle unbuffered.
00676  */
00677 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile,
00678                                               char * buffer,
00679                                               apr_size_t bufsize);
00680 
00681 /**
00682  * Get the size of any buffer for the specified apr file handle 
00683  * @param thefile  The file handle 
00684  */
00685 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile);
00686 
00687 /**
00688  * Move the read/write file offset to a specified byte within a file.
00689  * @param thefile The file descriptor
00690  * @param where How to move the pointer, one of:
00691  *              @li #APR_SET  --  set the offset to offset
00692  *              @li #APR_CUR  --  add the offset to the current position 
00693  *              @li #APR_END  --  add the offset to the current file size 
00694  * @param offset The offset to move the pointer to.
00695  * @remark The third argument is modified to be the offset the pointer
00696           was actually moved to.
00697  */
00698 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 
00699                                    apr_seek_where_t where,
00700                                    apr_off_t *offset);
00701 
00702 /**
00703  * Create an anonymous pipe.
00704  * @param in The newly created pipe's file for reading.
00705  * @param out The newly created pipe's file for writing.
00706  * @param pool The pool to operate on.
00707  * @remark By default, the returned file descriptors will be inherited
00708  * by child processes created using apr_proc_create().  This can be
00709  * changed using apr_file_inherit_unset().
00710  * @bug  Some platforms cannot toggle between blocking and nonblocking,
00711  * and when passing a pipe as a standard handle to an application which
00712  * does not expect it, a non-blocking stream will fluxor the client app.
00713  * @deprecated @see apr_file_pipe_create_ex()
00714  */
00715 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 
00716                                                apr_file_t **out,
00717                                                apr_pool_t *pool);
00718 
00719 /**
00720  * Create an anonymous pipe which portably supports async timeout options.
00721  * @param in The newly created pipe's file for reading.
00722  * @param out The newly created pipe's file for writing.
00723  * @param blocking one of these values defined in apr_thread_proc.h;
00724  *                 @li #APR_FULL_BLOCK
00725  *                 @li #APR_READ_BLOCK
00726  *                 @li #APR_WRITE_BLOCK
00727  *                 @li #APR_FULL_NONBLOCK
00728  * @param pool The pool to operate on.
00729  * @remark By default, the returned file descriptors will be inherited
00730  * by child processes created using apr_proc_create().  This can be
00731  * changed using apr_file_inherit_unset().
00732  * @remark Some platforms cannot toggle between blocking and nonblocking,
00733  * and when passing a pipe as a standard handle to an application which
00734  * does not expect it, a non-blocking stream will fluxor the client app.
00735  * Use this function rather than apr_file_pipe_create() to create pipes 
00736  * where one or both ends require non-blocking semantics.
00737  */
00738 APR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in, 
00739                                                   apr_file_t **out, 
00740                                                   apr_int32_t blocking, 
00741                                                   apr_pool_t *pool);
00742 
00743 /**
00744  * Create a named pipe.
00745  * @param filename The filename of the named pipe
00746  * @param perm The permissions for the newly created pipe.
00747  * @param pool The pool to operate on.
00748  */
00749 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 
00750                                                     apr_fileperms_t perm, 
00751                                                     apr_pool_t *pool);
00752 
00753 /**
00754  * Get the timeout value for a pipe or manipulate the blocking state.
00755  * @param thepipe The pipe we are getting a timeout for.
00756  * @param timeout The current timeout value in microseconds. 
00757  */
00758 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 
00759                                                apr_interval_time_t *timeout);
00760 
00761 /**
00762  * Set the timeout value for a pipe or manipulate the blocking state.
00763  * @param thepipe The pipe we are setting a timeout on.
00764  * @param timeout The timeout value in microseconds.  Values < 0 mean wait 
00765  *        forever, 0 means do not wait at all.
00766  */
00767 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 
00768                                                   apr_interval_time_t timeout);
00769 
00770 /** file (un)locking functions. */
00771 
00772 /**
00773  * Establish a lock on the specified, open file. The lock may be advisory
00774  * or mandatory, at the discretion of the platform. The lock applies to
00775  * the file as a whole, rather than a specific range. Locks are established
00776  * on a per-thread/process basis; a second lock by the same thread will not
00777  * block.
00778  * @param thefile The file to lock.
00779  * @param type The type of lock to establish on the file.
00780  */
00781 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
00782 
00783 /**
00784  * Remove any outstanding locks on the file.
00785  * @param thefile The file to unlock.
00786  */
00787 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
00788 
00789 /**accessor and general file_io functions. */
00790 
00791 /**
00792  * return the file name of the current file.
00793  * @param new_path The path of the file.  
00794  * @param thefile The currently open file.
00795  */                     
00796 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 
00797                                             apr_file_t *thefile);
00798     
00799 /**
00800  * Return the data associated with the current file.
00801  * @param data The user data associated with the file.  
00802  * @param key The key to use for retrieving data associated with this file.
00803  * @param file The currently open file.
00804  */                     
00805 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 
00806                                             apr_file_t *file);
00807 
00808 /**
00809  * Set the data associated with the current file.
00810  * @param file The currently open file.
00811  * @param data The user data to associate with the file.  
00812  * @param key The key to use for associating data with the file.
00813  * @param cleanup The cleanup routine to use when the file is destroyed.
00814  */                     
00815 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
00816                                             const char *key,
00817                                             apr_status_t (*cleanup)(void *));
00818 
00819 /**
00820  * Write a string to a file using a printf format.
00821  * @param fptr The file to write to.
00822  * @param format The format string
00823  * @param ... The values to substitute in the format string
00824  * @return The number of bytes written
00825  */ 
00826 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, 
00827                                         const char *format, ...)
00828         __attribute__((format(printf,2,3)));
00829 
00830 /**
00831  * set the specified file's permission bits.
00832  * @param fname The file (name) to apply the permissions to.
00833  * @param perms The permission bits to apply to the file.
00834  *
00835  * @warning Some platforms may not be able to apply all of the
00836  * available permission bits; #APR_INCOMPLETE will be returned if some
00837  * permissions are specified which could not be set.
00838  *
00839  * @warning Platforms which do not implement this feature will return
00840  * #APR_ENOTIMPL.
00841  */
00842 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
00843                                              apr_fileperms_t perms);
00844 
00845 /**
00846  * Set attributes of the specified file.
00847  * @param fname The full path to the file (using / on all systems)
00848  * @param attributes Or'd combination of
00849  *            @li #APR_FILE_ATTR_READONLY   - make the file readonly
00850  *            @li #APR_FILE_ATTR_EXECUTABLE - make the file executable
00851  *            @li #APR_FILE_ATTR_HIDDEN     - make the file hidden
00852  * @param attr_mask Mask of valid bits in attributes.
00853  * @param pool the pool to use.
00854  * @remark This function should be used in preference to explicit manipulation
00855  *      of the file permissions, because the operations to provide these
00856  *      attributes are platform specific and may involve more than simply
00857  *      setting permission bits.
00858  * @warning Platforms which do not implement this feature will return
00859  *      #APR_ENOTIMPL.
00860  */
00861 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
00862                                              apr_fileattrs_t attributes,
00863                                              apr_fileattrs_t attr_mask,
00864                                              apr_pool_t *pool);
00865 
00866 /**
00867  * Set the mtime of the specified file.
00868  * @param fname The full path to the file (using / on all systems)
00869  * @param mtime The mtime to apply to the file.
00870  * @param pool The pool to use.
00871  * @warning Platforms which do not implement this feature will return
00872  *      #APR_ENOTIMPL.
00873  */
00874 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
00875                                              apr_time_t mtime,
00876                                              apr_pool_t *pool);
00877 
00878 /**
00879  * Create a new directory on the file system.
00880  * @param path the path for the directory to be created. (use / on all systems)
00881  * @param perm Permissions for the new directory.
00882  * @param pool the pool to use.
00883  */                        
00884 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 
00885                                        apr_pool_t *pool);
00886 
00887 /** Creates a new directory on the file system, but behaves like
00888  * 'mkdir -p'. Creates intermediate directories as required. No error
00889  * will be reported if PATH already exists.
00890  * @param path the path for the directory to be created. (use / on all systems)
00891  * @param perm Permissions for the new directory.
00892  * @param pool the pool to use.
00893  */
00894 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
00895                                                  apr_fileperms_t perm,
00896                                                  apr_pool_t *pool);
00897 
00898 /**
00899  * Remove directory from the file system.
00900  * @param path the path for the directory to be removed. (use / on all systems)
00901  * @param pool the pool to use.
00902  * @remark Removing a directory which is in-use (e.g., the current working
00903  * directory, or during apr_dir_read, or with an open file) is not portable.
00904  */                        
00905 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
00906 
00907 /**
00908  * get the specified file's stats.
00909  * @param finfo Where to store the information about the file.
00910  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values 
00911  * @param thefile The file to get information about.
00912  */ 
00913 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 
00914                                             apr_int32_t wanted,
00915                                             apr_file_t *thefile);
00916     
00917 
00918 /**
00919  * Truncate the file's length to the specified offset
00920  * @param fp The file to truncate
00921  * @param offset The offset to truncate to.
00922  * @remark The read/write file offset is repositioned to offset.
00923  */
00924 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
00925 
00926 /**
00927  * Retrieve the flags that were passed into apr_file_open()
00928  * when the file was opened.
00929  * @return apr_int32_t the flags
00930  */
00931 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
00932 
00933 /**
00934  * Get the pool used by the file.
00935  */
00936 APR_POOL_DECLARE_ACCESSOR(file);
00937 
00938 /**
00939  * Set a file to be inherited by child processes.
00940  *
00941  */
00942 APR_DECLARE_INHERIT_SET(file);
00943 
00944 /**
00945  * Unset a file from being inherited by child processes.
00946  */
00947 APR_DECLARE_INHERIT_UNSET(file);
00948 
00949 /**
00950  * Open a temporary file
00951  * @param fp The apr file to use as a temporary file.
00952  * @param templ The template to use when creating a temp file.
00953  * @param flags The flags to open the file with. If this is zero,
00954  *              the file is opened with 
00955  *              #APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE |
00956  *              #APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE
00957  * @param p The pool to allocate the file out of.
00958  * @remark   
00959  * This function  generates  a unique temporary file name from template.  
00960  * The last six characters of template must be XXXXXX and these are replaced 
00961  * with a string that makes the filename unique. Since it will  be  modified,
00962  * template must not be a string constant, but should be declared as a character
00963  * array.  
00964  *
00965  */
00966 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
00967                                           apr_int32_t flags, apr_pool_t *p);
00968 
00969 
00970 /**
00971  * Find an existing directory suitable as a temporary storage location.
00972  * @param temp_dir The temp directory.
00973  * @param p The pool to use for any necessary allocations.
00974  * @remark   
00975  * This function uses an algorithm to search for a directory that an
00976  * an application can use for temporary storage.
00977  *
00978  */
00979 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir, 
00980                                            apr_pool_t *p);
00981 
00982 
00983 APR_DECLARE(apr_status_t) apr_file_rotating_check(apr_file_t *thefile);
00984 APR_DECLARE(apr_status_t) apr_file_rotating_manual_check(apr_file_t *thefile, apr_time_t time);
00985 
00986 /** @} */
00987 
00988 
00989 #ifdef __cplusplus
00990 }
00991 #endif
00992 
00993 #endif  /* ! APR_FILE_IO_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines