Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_file_io.h

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

Generated on Sun Mar 20 19:52:26 2005 for Apache Portable Runtime by  doxygen 1.3.9.1