contrib/apr/include/apr_file_io.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_FILE_IO_H
  18 #define APR_FILE_IO_H
  19
  20 /**
  21  * @file apr_file_io.h
  22  * @brief APR File I/O Handling
  23  */
  24
  25 #include "apr.h"
  26 #include "apr_pools.h"
  27 #include "apr_time.h"
  28 #include "apr_errno.h"
  29 #include "apr_file_info.h"
  30 #include "apr_inherit.h"
  31
  32 #define APR_WANT_STDIO          /**< for SEEK_* */
  33 #define APR_WANT_IOVEC          /**< for apr_file_writev */
  34 #include "apr_want.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif /* __cplusplus */
  39
  40 /**
  41  * @defgroup apr_file_io File I/O Handling Functions
  42  * @ingroup APR
  43  * @{
  44  */
  45
  46 /**
  47  * @defgroup apr_file_open_flags File Open Flags/Routines
  48  * @{
  49  */
  50
  51 /* Note to implementors: Values in the range 0x00100000--0x80000000
  52    are reserved for platform-specific values. */
  53
  54 #define APR_FOPEN_READ       0x00001  /**< Open the file for reading */
  55 #define APR_FOPEN_WRITE      0x00002  /**< Open the file for writing */
  56 #define APR_FOPEN_CREATE     0x00004  /**< Create the file if not there */
  57 #define APR_FOPEN_APPEND     0x00008  /**< Append to the end of the file */
  58 #define APR_FOPEN_TRUNCATE   0x00010  /**< Open the file and truncate
  59                                          to 0 length */
  60 #define APR_FOPEN_BINARY     0x00020  /**< Open the file in binary mode */
  61 #define APR_FOPEN_EXCL       0x00040  /**< Open should fail if APR_CREATE
  62                                          and file exists. */
  63 #define APR_FOPEN_BUFFERED   0x00080  /**< Open the file for buffered I/O */
  64 #define APR_FOPEN_DELONCLOSE 0x00100  /**< Delete the file after close */
  65 #define APR_FOPEN_XTHREAD    0x00200  /**< Platform dependent tag to open
  66                                          the file for use across multiple
  67                                          threads */
  68 #define APR_FOPEN_SHARELOCK  0x00400  /**< Platform dependent support for
  69                                          higher level locked read/write
  70                                          access to support writes across
  71                                          process/machines */
  72 #define APR_FOPEN_NOCLEANUP  0x00800  /**< Do not register a cleanup
  73                                          when the file is opened */
  74 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
  75                                              file should support
  76                                              apr_socket_sendfile operation */
  77 #define APR_FOPEN_LARGEFILE   0x04000 /**< Platform dependent flag to enable
  78                                        * large file support, see WARNING below
  79                                        */
  80 #define APR_FOPEN_SPARSE      0x08000 /**< Platform dependent flag to enable
  81                                        * sparse file support, see WARNING below
  82                                        */
  83
  84 /* backcompat */
  85 #define APR_READ             APR_FOPEN_READ       /**< @deprecated @see APR_FOPEN_READ */
  86 #define APR_WRITE            APR_FOPEN_WRITE      /**< @deprecated @see APR_FOPEN_WRITE */
  87 #define APR_CREATE           APR_FOPEN_CREATE     /**< @deprecated @see APR_FOPEN_CREATE */
  88 #define APR_APPEND           APR_FOPEN_APPEND     /**< @deprecated @see APR_FOPEN_APPEND */
  89 #define APR_TRUNCATE         APR_FOPEN_TRUNCATE   /**< @deprecated @see APR_FOPEN_TRUNCATE */
  90 #define APR_BINARY           APR_FOPEN_BINARY     /**< @deprecated @see APR_FOPEN_BINARY */
  91 #define APR_EXCL             APR_FOPEN_EXCL       /**< @deprecated @see APR_FOPEN_EXCL */
  92 #define APR_BUFFERED         APR_FOPEN_BUFFERED   /**< @deprecated @see APR_FOPEN_BUFFERED */
  93 #define APR_DELONCLOSE       APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */
  94 #define APR_XTHREAD          APR_FOPEN_XTHREAD    /**< @deprecated @see APR_FOPEN_XTHREAD */
  95 #define APR_SHARELOCK        APR_FOPEN_SHARELOCK  /**< @deprecated @see APR_FOPEN_SHARELOCK */
  96 #define APR_FILE_NOCLEANUP   APR_FOPEN_NOCLEANUP  /**< @deprecated @see APR_FOPEN_NOCLEANUP */
  97 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */
  98 #define APR_LARGEFILE        APR_FOPEN_LARGEFILE  /**< @deprecated @see APR_FOPEN_LARGEFILE */
  99
 100 /** @warning APR_FOPEN_LARGEFILE flag only has effect on some
 101  * platforms where sizeof(apr_off_t) == 4.  Where implemented, it
 102  * allows opening and writing to a file which exceeds the size which
 103  * can be represented by apr_off_t (2 gigabytes).  When a file's size
 104  * does exceed 2Gb, apr_file_info_get() will fail with an error on the
 105  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
 106  * filename.  apr_dir_read() will fail with APR_INCOMPLETE on a
 107  * directory entry for a large file depending on the particular
 108  * APR_FINFO_* flags.  Generally, it is not recommended to use this
 109  * flag.
 110  *
 111  * @warning APR_FOPEN_SPARSE may, depending on platform, convert a
 112  * normal file to a sparse file.  Some applications may be unable
 113  * to decipher a sparse file, so it's critical that the sparse file
 114  * flag should only be used for files accessed only by APR or other
 115  * applications known to be able to decipher them.  APR does not
 116  * guarantee that it will compress the file into sparse segments
 117  * if it was previously created and written without the sparse flag.
 118  * On platforms which do not understand, or on file systems which
 119  * cannot handle sparse files, the flag is ignored by apr_file_open().
 120  */
 121
 122 /** @} */
 123
 124 /**
 125  * @defgroup apr_file_seek_flags File Seek Flags
 126  * @{
 127  */
 128
 129 /* flags for apr_file_seek */
 130 /** Set the file position */
 131 #define APR_SET SEEK_SET
 132 /** Current */
 133 #define APR_CUR SEEK_CUR
 134 /** Go to end of file */
 135 #define APR_END SEEK_END
 136 /** @} */
 137
 138 /**
 139  * @defgroup apr_file_attrs_set_flags File Attribute Flags
 140  * @{
 141  */
 142
 143 /* flags for apr_file_attrs_set */
 144 #define APR_FILE_ATTR_READONLY   0x01          /**< File is read-only */
 145 #define APR_FILE_ATTR_EXECUTABLE 0x02          /**< File is executable */
 146 #define APR_FILE_ATTR_HIDDEN     0x04          /**< File is hidden */
 147 /** @} */
 148
 149 /**
 150  * @defgroup apr_file_writev{_full} max iovec size
 151  * @{
 152  */
 153 #if defined(DOXYGEN)
 154 #define APR_MAX_IOVEC_SIZE 1024                /**< System dependent maximum
 155                                                     size of an iovec array */
 156 #elif defined(IOV_MAX)
 157 #define APR_MAX_IOVEC_SIZE IOV_MAX
 158 #elif defined(MAX_IOVEC)
 159 #define APR_MAX_IOVEC_SIZE MAX_IOVEC
 160 #else
 161 #define APR_MAX_IOVEC_SIZE 1024
 162 #endif
 163 /** @} */
 164
 165 /** File attributes */
 166 typedef apr_uint32_t apr_fileattrs_t;
 167
 168 /** Type to pass as whence argument to apr_file_seek. */
 169 typedef int       apr_seek_where_t;
 170
 171 /**
 172  * Structure for referencing files.
 173  */
 174 typedef struct apr_file_t         apr_file_t;
 175
 176 /* File lock types/flags */
 177 /**
 178  * @defgroup apr_file_lock_types File Lock Types
 179  * @{
 180  */
 181
 182 #define APR_FLOCK_SHARED        1       /**< Shared lock. More than one process
 183                                            or thread can hold a shared lock
 184                                            at any given time. Essentially,
 185                                            this is a "read lock", preventing
 186                                            writers from establishing an
 187                                            exclusive lock. */
 188 #define APR_FLOCK_EXCLUSIVE     2       /**< Exclusive lock. Only one process
 189                                            may hold an exclusive lock at any
 190                                            given time. This is analogous to
 191                                            a "write lock". */
 192
 193 #define APR_FLOCK_TYPEMASK      0x000F  /**< mask to extract lock type */
 194 #define APR_FLOCK_NONBLOCK      0x0010  /**< do not block while acquiring the
 195                                            file lock */
 196 /** @} */
 197
 198 /**
 199  * Open the specified file.
 200  * @param newf The opened file descriptor.
 201  * @param fname The full path to the file (using / on all systems)
 202  * @param flag Or'ed value of:
 203  * <PRE>
 204  *         APR_READ              open for reading
 205  *         APR_WRITE             open for writing
 206  *         APR_CREATE            create the file if not there
 207  *         APR_APPEND            file ptr is set to end prior to all writes
 208  *         APR_TRUNCATE          set length to zero if file exists
 209  *         APR_BINARY            not a text file (This flag is ignored on
 210  *                               UNIX because it has no meaning)
 211  *         APR_BUFFERED          buffer the data.  Default is non-buffered
 212  *         APR_EXCL              return error if APR_CREATE and file exists
 213  *         APR_DELONCLOSE        delete the file after closing.
 214  *         APR_XTHREAD           Platform dependent tag to open the file
 215  *                               for use across multiple threads
 216  *         APR_SHARELOCK         Platform dependent support for higher
 217  *                               level locked read/write access to support
 218  *                               writes across process/machines
 219  *         APR_FILE_NOCLEANUP    Do not register a cleanup with the pool
 220  *                               passed in on the <EM>pool</EM> argument (see below).
 221  *                               The apr_os_file_t handle in apr_file_t will not
 222  *                               be closed when the pool is destroyed.
 223  *         APR_SENDFILE_ENABLED  Open with appropriate platform semantics
 224  *                               for sendfile operations.  Advisory only,
 225  *                               apr_socket_sendfile does not check this flag.
 226  * </PRE>
 227  * @param perm Access permissions for file.
 228  * @param pool The pool to use.
 229  * @remark If perm is APR_OS_DEFAULT and the file is being created,
 230  * appropriate default permissions will be used.
 231  * @remark By default, the returned file descriptor will not be
 232  * inherited by child processes created by apr_proc_create().  This
 233  * can be changed using apr_file_inherit_set().
 234  */
 235 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
 236                                         apr_int32_t flag, apr_fileperms_t perm,
 237                                         apr_pool_t *pool);
 238
 239 /**
 240  * Close the specified file.
 241  * @param file The file descriptor to close.
 242  */
 243 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
 244
 245 /**
 246  * Delete the specified file.
 247  * @param path The full path to the file (using / on all systems)
 248  * @param pool The pool to use.
 249  * @remark If the file is open, it won't be removed until all
 250  * instances are closed.
 251  */
 252 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
 253
 254 /**
 255  * Rename the specified file.
 256  * @param from_path The full path to the original file (using / on all systems)
 257  * @param to_path The full path to the new file (using / on all systems)
 258  * @param pool The pool to use.
 259  * @warning If a file exists at the new location, then it will be
 260  * overwritten.  Moving files or directories across devices may not be
 261  * possible.
 262  */
 263 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
 264                                           const char *to_path,
 265                                           apr_pool_t *pool);
 266
 267 /**
 268  * Create a hard link to the specified file.
 269  * @param from_path The full path to the original file (using / on all systems)
 270  * @param to_path The full path to the new file (using / on all systems)
 271  * @remark Both files must reside on the same device.
 272  */
 273 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path,
 274                                           const char *to_path);
 275
 276 /**
 277  * Copy the specified file to another file.
 278  * @param from_path The full path to the original file (using / on all systems)
 279  * @param to_path The full path to the new file (using / on all systems)
 280  * @param perms Access permissions for the new file if it is created.
 281  *     In place of the usual or'd combination of file permissions, the
 282  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
 283  *     file's permissions are copied.
 284  * @param pool The pool to use.
 285  * @remark The new file does not need to exist, it will be created if required.
 286  * @warning If the new file already exists, its contents will be overwritten.
 287  */
 288 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
 289                                         const char *to_path,
 290                                         apr_fileperms_t perms,
 291                                         apr_pool_t *pool);
 292
 293 /**
 294  * Append the specified file to another file.
 295  * @param from_path The full path to the source file (use / on all systems)
 296  * @param to_path The full path to the destination file (use / on all systems)
 297  * @param perms Access permissions for the destination file if it is created.
 298  *     In place of the usual or'd combination of file permissions, the
 299  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
 300  *     file's permissions are copied.
 301  * @param pool The pool to use.
 302  * @remark The new file does not need to exist, it will be created if required.
 303  */
 304 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
 305                                           const char *to_path,
 306                                           apr_fileperms_t perms,
 307                                           apr_pool_t *pool);
 308
 309 /**
 310  * Are we at the end of the file
 311  * @param fptr The apr file we are testing.
 312  * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
 313  */
 314 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
 315
 316 /**
 317  * Open standard error as an apr file pointer.
 318  * @param thefile The apr file to use as stderr.
 319  * @param pool The pool to allocate the file out of.
 320  *
 321  * @remark The only reason that the apr_file_open_std* functions exist
 322  * is that you may not always have a stderr/out/in on Windows.  This
 323  * is generally a problem with newer versions of Windows and services.
 324  *
 325  * @remark The other problem is that the C library functions generally work
 326  * differently on Windows and Unix.  So, by using apr_file_open_std*
 327  * functions, you can get a handle to an APR struct that works with
 328  * the APR functions which are supposed to work identically on all
 329  * platforms.
 330  */
 331 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
 332                                                apr_pool_t *pool);
 333
 334 /**
 335  * open standard output as an apr file pointer.
 336  * @param thefile The apr file to use as stdout.
 337  * @param pool The pool to allocate the file out of.
 338  *
 339  * @remark See remarks for apr_file_open_stderr.
 340  */
 341 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
 342                                                apr_pool_t *pool);
 343
 344 /**
 345  * open standard input as an apr file pointer.
 346  * @param thefile The apr file to use as stdin.
 347  * @param pool The pool to allocate the file out of.
 348  *
 349  * @remark See remarks for apr_file_open_stderr.
 350  */
 351 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
 352                                               apr_pool_t *pool);
 353
 354 /**
 355  * open standard error as an apr file pointer, with flags.
 356  * @param thefile The apr file to use as stderr.
 357  * @param flags The flags to open the file with. Only the APR_EXCL,
 358  *              APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
 359  *              APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
 360  *              be used. The APR_WRITE flag will be set unconditionally.
 361  * @param pool The pool to allocate the file out of.
 362  *
 363  * @remark See remarks for apr_file_open_stderr.
 364  */
 365 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile,
 366                                                      apr_int32_t flags,
 367                                                      apr_pool_t *pool);
 368
 369 /**
 370  * open standard output as an apr file pointer, with flags.
 371  * @param thefile The apr file to use as stdout.
 372  * @param flags The flags to open the file with. Only the APR_EXCL,
 373  *              APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
 374  *              APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
 375  *              be used. The APR_WRITE flag will be set unconditionally.
 376  * @param pool The pool to allocate the file out of.
 377  *
 378  * @remark See remarks for apr_file_open_stderr.
 379  */
 380 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile,
 381                                                      apr_int32_t flags,
 382                                                      apr_pool_t *pool);
 383
 384 /**
 385  * open standard input as an apr file pointer, with flags.
 386  * @param thefile The apr file to use as stdin.
 387  * @param flags The flags to open the file with. Only the APR_EXCL,
 388  *              APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
 389  *              APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
 390  *              be used. The APR_READ flag will be set unconditionally.
 391  * @param pool The pool to allocate the file out of.
 392  *
 393  * @remark See remarks for apr_file_open_stderr.
 394  */
 395 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile,
 396                                                      apr_int32_t flags,
 397                                                      apr_pool_t *pool);
 398
 399 /**
 400  * Read data from the specified file.
 401  * @param thefile The file descriptor to read from.
 402  * @param buf The buffer to store the data to.
 403  * @param nbytes On entry, the number of bytes to read; on exit, the number
 404  * of bytes read.
 405  *
 406  * @remark apr_file_read will read up to the specified number of
 407  * bytes, but never more.  If there isn't enough data to fill that
 408  * number of bytes, all of the available data is read.  The third
 409  * argument is modified to reflect the number of bytes read.  If a
 410  * char was put back into the stream via ungetc, it will be the first
 411  * character returned.
 412  *
 413  * @remark It is not possible for both bytes to be read and an APR_EOF
 414  * or other error to be returned.  APR_EINTR is never returned.
 415  */
 416 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
 417                                         apr_size_t *nbytes);
 418
 419 /**
 420  * Write data to the specified file.
 421  * @param thefile The file descriptor to write to.
 422  * @param buf The buffer which contains the data.
 423  * @param nbytes On entry, the number of bytes to write; on exit, the number
 424  *               of bytes written.
 425  *
 426  * @remark apr_file_write will write up to the specified number of
 427  * bytes, but never more.  If the OS cannot write that many bytes, it
 428  * will write as many as it can.  The third argument is modified to
 429  * reflect the * number of bytes written.
 430  *
 431  * @remark It is possible for both bytes to be written and an error to
 432  * be returned.  APR_EINTR is never returned.
 433  */
 434 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
 435                                          apr_size_t *nbytes);
 436
 437 /**
 438  * Write data from iovec array to the specified file.
 439  * @param thefile The file descriptor to write to.
 440  * @param vec The array from which to get the data to write to the file.
 441  * @param nvec The number of elements in the struct iovec array. This must
 442  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function
 443  *             will fail with APR_EINVAL.
 444  * @param nbytes The number of bytes written.
 445  *
 446  * @remark It is possible for both bytes to be written and an error to
 447  * be returned.  APR_EINTR is never returned.
 448  *
 449  * @remark apr_file_writev is available even if the underlying
 450  * operating system doesn't provide writev().
 451  */
 452 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
 453                                           const struct iovec *vec,
 454                                           apr_size_t nvec, apr_size_t *nbytes);
 455
 456 /**
 457  * Read data from the specified file, ensuring that the buffer is filled
 458  * before returning.
 459  * @param thefile The file descriptor to read from.
 460  * @param buf The buffer to store the data to.
 461  * @param nbytes The number of bytes to read.
 462  * @param bytes_read If non-NULL, this will contain the number of bytes read.
 463  *
 464  * @remark apr_file_read will read up to the specified number of
 465  * bytes, but never more.  If there isn't enough data to fill that
 466  * number of bytes, then the process/thread will block until it is
 467  * available or EOF is reached.  If a char was put back into the
 468  * stream via ungetc, it will be the first character returned.
 469  *
 470  * @remark It is possible for both bytes to be read and an error to be
 471  * returned.  And if *bytes_read is less than nbytes, an accompanying
 472  * error is _always_ returned.
 473  *
 474  * @remark APR_EINTR is never returned.
 475  */
 476 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
 477                                              apr_size_t nbytes,
 478                                              apr_size_t *bytes_read);
 479
 480 /**
 481  * Write data to the specified file, ensuring that all of the data is
 482  * written before returning.
 483  * @param thefile The file descriptor to write to.
 484  * @param buf The buffer which contains the data.
 485  * @param nbytes The number of bytes to write.
 486  * @param bytes_written If non-NULL, set to the number of bytes written.
 487  *
 488  * @remark apr_file_write will write up to the specified number of
 489  * bytes, but never more.  If the OS cannot write that many bytes, the
 490  * process/thread will block until they can be written. Exceptional
 491  * error such as "out of space" or "pipe closed" will terminate with
 492  * an error.
 493  *
 494  * @remark It is possible for both bytes to be written and an error to
 495  * be returned.  And if *bytes_written is less than nbytes, an
 496  * accompanying error is _always_ returned.
 497  *
 498  * @remark APR_EINTR is never returned.
 499  */
 500 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile,
 501                                               const void *buf,
 502                                               apr_size_t nbytes,
 503                                               apr_size_t *bytes_written);
 504
 505
 506 /**
 507  * Write data from iovec array to the specified file, ensuring that all of the
 508  * data is written before returning.
 509  * @param thefile The file descriptor to write to.
 510  * @param vec The array from which to get the data to write to the file.
 511  * @param nvec The number of elements in the struct iovec array. This must
 512  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function
 513  *             will fail with APR_EINVAL.
 514  * @param nbytes The number of bytes written.
 515  *
 516  * @remark apr_file_writev_full is available even if the underlying
 517  * operating system doesn't provide writev().
 518  */
 519 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile,
 520                                                const struct iovec *vec,
 521                                                apr_size_t nvec,
 522                                                apr_size_t *nbytes);
 523 /**
 524  * Write a character into the specified file.
 525  * @param ch The character to write.
 526  * @param thefile The file descriptor to write to
 527  */
 528 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
 529
 530 /**
 531  * Read a character from the specified file.
 532  * @param ch The character to read into
 533  * @param thefile The file descriptor to read from
 534  */
 535 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
 536
 537 /**
 538  * Put a character back onto a specified stream.
 539  * @param ch The character to write.
 540  * @param thefile The file descriptor to write to
 541  */
 542 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
 543
 544 /**
 545  * Read a line from the specified file
 546  * @param str The buffer to store the string in.
 547  * @param len The length of the string
 548  * @param thefile The file descriptor to read from
 549  * @remark The buffer will be NUL-terminated if any characters are stored.
 550  *         The newline at the end of the line will not be stripped.
 551  */
 552 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len,
 553                                         apr_file_t *thefile);
 554
 555 /**
 556  * Write the string into the specified file.
 557  * @param str The string to write.
 558  * @param thefile The file descriptor to write to
 559  */
 560 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
 561
 562 /**
 563  * Flush the file's buffer.
 564  * @param thefile The file descriptor to flush
 565  */
 566 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
 567
 568 /**
 569  * Transfer all file modified data and metadata to disk.
 570  * @param thefile The file descriptor to sync
 571  */
 572 APR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile);
 573
 574 /**
 575  * Transfer all file modified data to disk.
 576  * @param thefile The file descriptor to sync
 577  */
 578 APR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile);
 579
 580 /**
 581  * Duplicate the specified file descriptor.
 582  * @param new_file The structure to duplicate into.
 583  * @param old_file The file to duplicate.
 584  * @param p The pool to use for the new file.
 585  * @remark *new_file must point to a valid apr_file_t, or point to NULL.
 586  */
 587 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
 588                                        apr_file_t *old_file,
 589                                        apr_pool_t *p);
 590
 591 /**
 592  * Duplicate the specified file descriptor and close the original
 593  * @param new_file The old file that is to be closed and reused
 594  * @param old_file The file to duplicate
 595  * @param p        The pool to use for the new file
 596  *
 597  * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
 598  */
 599 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
 600                                         apr_file_t *old_file,
 601                                         apr_pool_t *p);
 602
 603 /**
 604  * Move the specified file descriptor to a new pool
 605  * @param new_file Pointer in which to return the new apr_file_t
 606  * @param old_file The file to move
 607  * @param p        The pool to which the descriptor is to be moved
 608  * @remark Unlike apr_file_dup2(), this function doesn't do an
 609  *         OS dup() operation on the underlying descriptor; it just
 610  *         moves the descriptor's apr_file_t wrapper to a new pool.
 611  * @remark The new pool need not be an ancestor of old_file's pool.
 612  * @remark After calling this function, old_file may not be used
 613  */
 614 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
 615                                             apr_file_t *old_file,
 616                                             apr_pool_t *p);
 617
 618 /**
 619  * Give the specified apr file handle a new buffer
 620  * @param thefile  The file handle that is to be modified
 621  * @param buffer   The buffer
 622  * @param bufsize  The size of the buffer
 623  * @remark It is possible to add a buffer to previously unbuffered
 624  *         file handles, the APR_BUFFERED flag will be added to
 625  *         the file handle's flags. Likewise, with buffer=NULL and
 626  *         bufsize=0 arguments it is possible to make a previously
 627  *         buffered file handle unbuffered.
 628  */
 629 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile,
 630                                               char * buffer,
 631                                               apr_size_t bufsize);
 632
 633 /**
 634  * Get the size of any buffer for the specified apr file handle
 635  * @param thefile  The file handle
 636  */
 637 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile);
 638
 639 /**
 640  * Move the read/write file offset to a specified byte within a file.
 641  * @param thefile The file descriptor
 642  * @param where How to move the pointer, one of:
 643  * <PRE>
 644  *            APR_SET  --  set the offset to offset
 645  *            APR_CUR  --  add the offset to the current position
 646  *            APR_END  --  add the offset to the current file size
 647  * </PRE>
 648  * @param offset The offset to move the pointer to.
 649  * @remark The third argument is modified to be the offset the pointer
 650           was actually moved to.
 651  */
 652 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
 653                                    apr_seek_where_t where,
 654                                    apr_off_t *offset);
 655
 656 /**
 657  * Create an anonymous pipe.
 658  * @param in The newly created pipe's file for reading.
 659  * @param out The newly created pipe's file for writing.
 660  * @param pool The pool to operate on.
 661  * @remark By default, the returned file descriptors will be inherited
 662  * by child processes created using apr_proc_create().  This can be
 663  * changed using apr_file_inherit_unset().
 664  * @bug  Some platforms cannot toggle between blocking and nonblocking,
 665  * and when passing a pipe as a standard handle to an application which
 666  * does not expect it, a non-blocking stream will fluxor the client app.
 667  * @deprecated @see apr_file_pipe_create_ex
 668  */
 669 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in,
 670                                                apr_file_t **out,
 671                                                apr_pool_t *pool);
 672
 673 /**
 674  * Create an anonymous pipe which portably supports async timeout options.
 675  * @param in The newly created pipe's file for reading.
 676  * @param out The newly created pipe's file for writing.
 677  * @param blocking one of these values defined in apr_thread_proc.h;
 678  * @param pool The pool to operate on.
 679  * <pre>
 680  *       APR_FULL_BLOCK
 681  *       APR_READ_BLOCK
 682  *       APR_WRITE_BLOCK
 683  *       APR_FULL_NONBLOCK
 684  * </pre>
 685  * @remark By default, the returned file descriptors will be inherited
 686  * by child processes created using apr_proc_create().  This can be
 687  * changed using apr_file_inherit_unset().
 688  * @remark Some platforms cannot toggle between blocking and nonblocking,
 689  * and when passing a pipe as a standard handle to an application which
 690  * does not expect it, a non-blocking stream will fluxor the client app.
 691  * Use this function rather than apr_file_pipe_create to create pipes
 692  * where one or both ends require non-blocking semantics.
 693  */
 694 APR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in,
 695                                                   apr_file_t **out,
 696                                                   apr_int32_t blocking,
 697                                                   apr_pool_t *pool);
 698
 699 /**
 700  * Create a named pipe.
 701  * @param filename The filename of the named pipe
 702  * @param perm The permissions for the newly created pipe.
 703  * @param pool The pool to operate on.
 704  */
 705 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
 706                                                     apr_fileperms_t perm,
 707                                                     apr_pool_t *pool);
 708
 709 /**
 710  * Get the timeout value for a pipe or manipulate the blocking state.
 711  * @param thepipe The pipe we are getting a timeout for.
 712  * @param timeout The current timeout value in microseconds.
 713  */
 714 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
 715                                                apr_interval_time_t *timeout);
 716
 717 /**
 718  * Set the timeout value for a pipe or manipulate the blocking state.
 719  * @param thepipe The pipe we are setting a timeout on.
 720  * @param timeout The timeout value in microseconds.  Values < 0 mean wait
 721  *        forever, 0 means do not wait at all.
 722  */
 723 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe,
 724                                                   apr_interval_time_t timeout);
 725
 726 /** file (un)locking functions. */
 727
 728 /**
 729  * Establish a lock on the specified, open file. The lock may be advisory
 730  * or mandatory, at the discretion of the platform. The lock applies to
 731  * the file as a whole, rather than a specific range. Locks are established
 732  * on a per-thread/process basis; a second lock by the same thread will not
 733  * block.
 734  * @param thefile The file to lock.
 735  * @param type The type of lock to establish on the file.
 736  */
 737 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
 738
 739 /**
 740  * Remove any outstanding locks on the file.
 741  * @param thefile The file to unlock.
 742  */
 743 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
 744
 745 /**accessor and general file_io functions. */
 746
 747 /**
 748  * return the file name of the current file.
 749  * @param new_path The path of the file.
 750  * @param thefile The currently open file.
 751  */
 752 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
 753                                             apr_file_t *thefile);
 754
 755 /**
 756  * Return the data associated with the current file.
 757  * @param data The user data associated with the file.
 758  * @param key The key to use for retrieving data associated with this file.
 759  * @param file The currently open file.
 760  */
 761 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
 762                                             apr_file_t *file);
 763
 764 /**
 765  * Set the data associated with the current file.
 766  * @param file The currently open file.
 767  * @param data The user data to associate with the file.
 768  * @param key The key to use for associating data with the file.
 769  * @param cleanup The cleanup routine to use when the file is destroyed.
 770  */
 771 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
 772                                             const char *key,
 773                                             apr_status_t (*cleanup)(void *));
 774
 775 /**
 776  * Write a string to a file using a printf format.
 777  * @param fptr The file to write to.
 778  * @param format The format string
 779  * @param ... The values to substitute in the format string
 780  * @return The number of bytes written
 781  */
 782 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr,
 783                                         const char *format, ...)
 784         __attribute__((format(printf,2,3)));
 785
 786 /**
 787  * set the specified file's permission bits.
 788  * @param fname The file (name) to apply the permissions to.
 789  * @param perms The permission bits to apply to the file.
 790  *
 791  * @warning Some platforms may not be able to apply all of the
 792  * available permission bits; APR_INCOMPLETE will be returned if some
 793  * permissions are specified which could not be set.
 794  *
 795  * @warning Platforms which do not implement this feature will return
 796  * APR_ENOTIMPL.
 797  */
 798 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
 799                                              apr_fileperms_t perms);
 800
 801 /**
 802  * Set attributes of the specified file.
 803  * @param fname The full path to the file (using / on all systems)
 804  * @param attributes Or'd combination of
 805  * <PRE>
 806  *            APR_FILE_ATTR_READONLY   - make the file readonly
 807  *            APR_FILE_ATTR_EXECUTABLE - make the file executable
 808  *            APR_FILE_ATTR_HIDDEN     - make the file hidden
 809  * </PRE>
 810  * @param attr_mask Mask of valid bits in attributes.
 811  * @param pool the pool to use.
 812  * @remark This function should be used in preference to explicit manipulation
 813  *      of the file permissions, because the operations to provide these
 814  *      attributes are platform specific and may involve more than simply
 815  *      setting permission bits.
 816  * @warning Platforms which do not implement this feature will return
 817  *      APR_ENOTIMPL.
 818  */
 819 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
 820                                              apr_fileattrs_t attributes,
 821                                              apr_fileattrs_t attr_mask,
 822                                              apr_pool_t *pool);
 823
 824 /**
 825  * Set the mtime of the specified file.
 826  * @param fname The full path to the file (using / on all systems)
 827  * @param mtime The mtime to apply to the file.
 828  * @param pool The pool to use.
 829  * @warning Platforms which do not implement this feature will return
 830  *      APR_ENOTIMPL.
 831  */
 832 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
 833                                              apr_time_t mtime,
 834                                              apr_pool_t *pool);
 835
 836 /**
 837  * Create a new directory on the file system.
 838  * @param path the path for the directory to be created. (use / on all systems)
 839  * @param perm Permissions for the new directory.
 840  * @param pool the pool to use.
 841  */
 842 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
 843                                        apr_pool_t *pool);
 844
 845 /** Creates a new directory on the file system, but behaves like
 846  * 'mkdir -p'. Creates intermediate directories as required. No error
 847  * will be reported if PATH already exists.
 848  * @param path the path for the directory to be created. (use / on all systems)
 849  * @param perm Permissions for the new directory.
 850  * @param pool the pool to use.
 851  */
 852 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
 853                                                  apr_fileperms_t perm,
 854                                                  apr_pool_t *pool);
 855
 856 /**
 857  * Remove directory from the file system.
 858  * @param path the path for the directory to be removed. (use / on all systems)
 859  * @param pool the pool to use.
 860  * @remark Removing a directory which is in-use (e.g., the current working
 861  * directory, or during apr_dir_read, or with an open file) is not portable.
 862  */
 863 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
 864
 865 /**
 866  * get the specified file's stats.
 867  * @param finfo Where to store the information about the file.
 868  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
 869  * @param thefile The file to get information about.
 870  */
 871 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
 872                                             apr_int32_t wanted,
 873                                             apr_file_t *thefile);
 874
 875
 876 /**
 877  * Truncate the file's length to the specified offset
 878  * @param fp The file to truncate
 879  * @param offset The offset to truncate to.
 880  * @remark The read/write file offset is repositioned to offset.
 881  */
 882 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
 883
 884 /**
 885  * Retrieve the flags that were passed into apr_file_open()
 886  * when the file was opened.
 887  * @return apr_int32_t the flags
 888  */
 889 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
 890
 891 /**
 892  * Get the pool used by the file.
 893  */
 894 APR_POOL_DECLARE_ACCESSOR(file);
 895
 896 /**
 897  * Set a file to be inherited by child processes.
 898  *
 899  */
 900 APR_DECLARE_INHERIT_SET(file);
 901
 902 /**
 903  * Unset a file from being inherited by child processes.
 904  */
 905 APR_DECLARE_INHERIT_UNSET(file);
 906
 907 /**
 908  * Open a temporary file
 909  * @param fp The apr file to use as a temporary file.
 910  * @param templ The template to use when creating a temp file.
 911  * @param flags The flags to open the file with. If this is zero,
 912  *              the file is opened with
 913  *              APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
 914  * @param p The pool to allocate the file out of.
 915  * @remark
 916  * This function  generates  a unique temporary file name from template.
 917  * The last six characters of template must be XXXXXX and these are replaced
 918  * with a string that makes the filename unique. Since it will  be  modified,
 919  * template must not be a string constant, but should be declared as a character
 920  * array.
 921  *
 922  */
 923 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
 924                                           apr_int32_t flags, apr_pool_t *p);
 925
 926
 927 /**
 928  * Find an existing directory suitable as a temporary storage location.
 929  * @param temp_dir The temp directory.
 930  * @param p The pool to use for any necessary allocations.
 931  * @remark
 932  * This function uses an algorithm to search for a directory that an
 933  * an application can use for temporary storage.
 934  *
 935  */
 936 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir,
 937                                            apr_pool_t *p);
 938
 939 /** @} */
 940
 941 #ifdef __cplusplus
 942 }
 943 #endif
 944
 945 #endif  /* ! APR_FILE_IO_H */