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