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