rubbos/app/httpd-2.0.64/srclib/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_READ       0x00001     /**< Open the file for reading */
  55 #define APR_WRITE      0x00002     /**< Open the file for writing */
  56 #define APR_CREATE     0x00004     /**< Create the file if not there */
  57 #define APR_APPEND     0x00008     /**< Append to the end of the file */
  58 #define APR_TRUNCATE   0x00010     /**< Open the file and truncate to 0 length */
  59 #define APR_BINARY     0x00020     /**< Open the file in binary mode */
  60 #define APR_EXCL       0x00040     /**< Open should fail if APR_CREATE and file
  61                                         exists. */
  62 #define APR_BUFFERED   0x00080     /**< Open the file for buffered I/O */
  63 #define APR_DELONCLOSE 0x00100     /**< Delete the file after close */
  64 #define APR_XTHREAD    0x00200     /**< Platform dependent tag to open the file
  65                                         for use across multiple threads */
  66 #define APR_SHARELOCK  0x00400     /**< Platform dependent support for higher
  67                                         level locked read/write access to support
  68                                         writes across process/machines */
  69 #define APR_FILE_NOCLEANUP 0x00800 /**< Do not register a cleanup when the file
  70                                         is opened */
  71 #define APR_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this file should
  72                                           support apr_sendfile operation */
  73 #define APR_LARGEFILE   0x04000    /**< Platform dependent flag to enable large file
  74                                         support; WARNING see below. */
  75
  76 /** @warning The APR_LARGEFILE flag only has effect on some platforms
  77  * where sizeof(apr_off_t) == 4.  Where implemented, it allows opening
  78  * and writing to a file which exceeds the size which can be
  79  * represented by apr_off_t (2 gigabytes).  When a file's size does
  80  * exceed 2Gb, apr_file_info_get() will fail with an error on the
  81  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
  82  * filename.  apr_dir_read() will fail with APR_INCOMPLETE on a
  83  * directory entry for a large file depending on the particular
  84  * APR_FINFO_* flags.  Generally, it is not recommended to use this
  85  * flag. */
  86
  87 /** @} */
  88
  89 /**
  90  * @defgroup apr_file_seek_flags File Seek Flags
  91  * @{
  92  */
  93
  94 /* flags for apr_file_seek */
  95 /** Set the file position */
  96 #define APR_SET SEEK_SET
  97 /** Current */
  98 #define APR_CUR SEEK_CUR
  99 /** Go to end of file */
 100 #define APR_END SEEK_END
 101 /** @} */
 102
 103 /**
 104  * @defgroup apr_file_attrs_set_flags File Attribute Flags
 105  * @{
 106  */
 107
 108 /* flags for apr_file_attrs_set */
 109 #define APR_FILE_ATTR_READONLY   0x01          /**< File is read-only */
 110 #define APR_FILE_ATTR_EXECUTABLE 0x02          /**< File is executable */
 111 #define APR_FILE_ATTR_HIDDEN     0x04          /**< File is hidden */
 112 /** @} */
 113
 114 /** File attributes */
 115 typedef apr_uint32_t apr_fileattrs_t;
 116
 117 /** should be same as whence type in lseek, POSIX defines this as int */
 118 typedef int       apr_seek_where_t;
 119
 120 /**
 121  * Structure for referencing files.
 122  */
 123 typedef struct apr_file_t         apr_file_t;
 124
 125 /* File lock types/flags */
 126 /**
 127  * @defgroup apr_file_lock_types File Lock Types
 128  * @{
 129  */
 130
 131 #define APR_FLOCK_SHARED        1       /**< Shared lock. More than one process
 132                                            or thread can hold a shared lock
 133                                            at any given time. Essentially,
 134                                            this is a "read lock", preventing
 135                                            writers from establishing an
 136                                            exclusive lock. */
 137 #define APR_FLOCK_EXCLUSIVE     2       /**< Exclusive lock. Only one process
 138                                            may hold an exclusive lock at any
 139                                            given time. This is analogous to
 140                                            a "write lock". */
 141
 142 #define APR_FLOCK_TYPEMASK      0x000F  /**< mask to extract lock type */
 143 #define APR_FLOCK_NONBLOCK      0x0010  /**< do not block while acquiring the
 144                                            file lock */
 145 /** @} */
 146
 147 /**
 148  * Open the specified file.
 149  * @param newf The opened file descriptor.
 150  * @param fname The full path to the file (using / on all systems)
 151  * @param flag Or'ed value of:
 152  * <PRE>
 153  *         APR_READ              open for reading
 154  *         APR_WRITE             open for writing
 155  *         APR_CREATE            create the file if not there
 156  *         APR_APPEND            file ptr is set to end prior to all writes
 157  *         APR_TRUNCATE          set length to zero if file exists
 158  *         APR_BINARY            not a text file (This flag is ignored on
 159  *                               UNIX because it has no meaning)
 160  *         APR_BUFFERED          buffer the data.  Default is non-buffered
 161  *         APR_EXCL              return error if APR_CREATE and file exists
 162  *         APR_DELONCLOSE        delete the file after closing.
 163  *         APR_XTHREAD           Platform dependent tag to open the file
 164  *                               for use across multiple threads
 165  *         APR_SHARELOCK         Platform dependent support for higher
 166  *                               level locked read/write access to support
 167  *                               writes across process/machines
 168  *         APR_FILE_NOCLEANUP    Do not register a cleanup with the pool
 169  *                               passed in on the <EM>cont</EM> argument (see below).
 170  *                               The apr_os_file_t handle in apr_file_t will not
 171  *                               be closed when the pool is destroyed.
 172  *         APR_SENDFILE_ENABLED  Open with appropriate platform semantics
 173  *                               for sendfile operations.  Advisory only,
 174  *                               apr_sendfile does not check this flag.
 175  * </PRE>
 176  * @param perm Access permissions for file.
 177  * @param pool The pool to use.
 178  * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate
 179  *      default permissions will be used.  *arg1 must point to a valid file_t,
 180  *      or NULL (in which case it will be allocated)
 181  */
 182 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
 183                                    apr_int32_t flag, apr_fileperms_t perm,
 184                                    apr_pool_t *pool);
 185
 186 /**
 187  * Close the specified file.
 188  * @param file The file descriptor to close.
 189  */
 190 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
 191
 192 /**
 193  * delete the specified file.
 194  * @param path The full path to the file (using / on all systems)
 195  * @param cont The pool to use.
 196  * @remark If the file is open, it won't be removed until all instances are closed.
 197  */
 198 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *cont);
 199
 200 /**
 201  * rename the specified file.
 202  * @param from_path The full path to the original file (using / on all systems)
 203  * @param to_path The full path to the new file (using / on all systems)
 204  * @param pool The pool to use.
 205  * @warning If a file exists at the new location, then it will be overwritten.
 206  *      Moving files or directories across devices may not be possible.
 207  */
 208 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
 209                                           const char *to_path,
 210                                           apr_pool_t *pool);
 211
 212 /**
 213  * copy the specified file to another file.
 214  * @param from_path The full path to the original file (using / on all systems)
 215  * @param to_path The full path to the new file (using / on all systems)
 216  * @param perms Access permissions for the new file if it is created.
 217  *     In place of the usual or'd combination of file permissions, the
 218  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
 219  *     file's permissions are copied.
 220  * @param pool The pool to use.
 221  * @remark The new file does not need to exist, it will be created if required.
 222  * @warning If the new file already exists, its contents will be overwritten.
 223  */
 224 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
 225                                         const char *to_path,
 226                                         apr_fileperms_t perms,
 227                                         apr_pool_t *pool);
 228
 229 /**
 230  * append the specified file to another file.
 231  * @param from_path The full path to the source file (using / on all systems)
 232  * @param to_path The full path to the destination file (using / on all systems)
 233  * @param perms Access permissions for the destination file if it is created.
 234  *     In place of the usual or'd combination of file permissions, the
 235  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
 236  *     file's permissions are copied.
 237  * @param pool The pool to use.
 238  * @remark The new file does not need to exist, it will be created if required.
 239  */
 240 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
 241                                           const char *to_path,
 242                                           apr_fileperms_t perms,
 243                                           apr_pool_t *pool);
 244
 245 /**
 246  * Are we at the end of the file
 247  * @param fptr The apr file we are testing.
 248  * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
 249  */
 250 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
 251
 252 /**
 253  * open standard error as an apr file pointer.
 254  * @param thefile The apr file to use as stderr.
 255  * @param cont The pool to allocate the file out of.
 256  *
 257  * @remark The only reason that the apr_file_open_std* functions exist
 258  * is that you may not always have a stderr/out/in on Windows.  This
 259  * is generally a problem with newer versions of Windows and services.
 260  *
 261  * The other problem is that the C library functions generally work
 262  * differently on Windows and Unix.  So, by using apr_file_open_std*
 263  * functions, you can get a handle to an APR struct that works with
 264  * the APR functions which are supposed to work identically on all
 265  * platforms.
 266  */
 267 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
 268                                           apr_pool_t *cont);
 269
 270 /**
 271  * open standard output as an apr file pointer.
 272  * @param thefile The apr file to use as stdout.
 273  * @param cont The pool to allocate the file out of.
 274  *
 275  * @remark The only reason that the apr_file_open_std* functions exist
 276  * is that you may not always have a stderr/out/in on Windows.  This
 277  * is generally a problem with newer versions of Windows and services.
 278  *
 279  * The other problem is that the C library functions generally work
 280  * differently on Windows and Unix.  So, by using apr_file_open_std*
 281  * functions, you can get a handle to an APR struct that works with
 282  * the APR functions which are supposed to work identically on all
 283  * platforms.
 284  */
 285 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
 286                                           apr_pool_t *cont);
 287
 288 /**
 289  * open standard input as an apr file pointer.
 290  * @param thefile The apr file to use as stdin.
 291  * @param cont The pool to allocate the file out of.
 292  *
 293  * @remark The only reason that the apr_file_open_std* functions exist
 294  * is that you may not always have a stderr/out/in on Windows.  This
 295  * is generally a problem with newer versions of Windows and services.
 296  *
 297  * The other problem is that the C library functions generally work
 298  * differently on Windows and Unix.  So, by using apr_file_open_std*
 299  * functions, you can get a handle to an APR struct that works with
 300  * the APR functions which are supposed to work identically on all
 301  * platforms.
 302  */
 303 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
 304                                               apr_pool_t *cont);
 305
 306 /**
 307  * Read data from the specified file.
 308  * @param thefile The file descriptor to read from.
 309  * @param buf The buffer to store the data to.
 310  * @param nbytes On entry, the number of bytes to read; on exit, the number of bytes read.
 311  * @remark apr_file_read will read up to the specified number of bytes, but
 312  *         never more.  If there isn't enough data to fill that number of
 313  *         bytes, all of the available data is read.  The third argument is
 314  *         modified to reflect the number of bytes read.  If a char was put
 315  *         back into the stream via ungetc, it will be the first character
 316  *         returned.
 317  *
 318  *         It is not possible for both bytes to be read and an APR_EOF or other
 319  *         error to be returned.
 320  *
 321  *         APR_EINTR is never returned.
 322  */
 323 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
 324                                    apr_size_t *nbytes);
 325
 326 /**
 327  * Write data to the specified file.
 328  * @param thefile The file descriptor to write to.
 329  * @param buf The buffer which contains the data.
 330  * @param nbytes On entry, the number of bytes to write; on exit, the number
 331  *               of bytes written.
 332  * @remark apr_file_write will write up to the specified number of bytes, but never
 333  *      more.  If the OS cannot write that many bytes, it will write as many
 334  *      as it can.  The third argument is modified to reflect the * number
 335  *      of bytes written.
 336  *
 337  *      It is possible for both bytes to be written and an error to be returned.
 338  *
 339  *      APR_EINTR is never returned.
 340  */
 341 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
 342                                     apr_size_t *nbytes);
 343
 344 /**
 345  * Write data from iovec array to the specified file.
 346  * @param thefile The file descriptor to write to.
 347  * @param vec The array from which to get the data to write to the file.
 348  * @param nvec The number of elements in the struct iovec array. This must
 349  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function
 350  *             will fail with APR_EINVAL.
 351  * @param nbytes The number of bytes written.
 352  * @remark It is possible for both bytes to be written and an error to be returned.
 353  *      APR_EINTR is never returned.
 354  *
 355  *      apr_file_writev is available even if the underlying operating system
 356  *
 357  *      doesn't provide writev().
 358  */
 359 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
 360                                      const struct iovec *vec,
 361                                      apr_size_t nvec, apr_size_t *nbytes);
 362
 363 /**
 364  * Read data from the specified file, ensuring that the buffer is filled
 365  * before returning.
 366  * @param thefile The file descriptor to read from.
 367  * @param buf The buffer to store the data to.
 368  * @param nbytes The number of bytes to read.
 369  * @param bytes_read If non-NULL, this will contain the number of bytes read.
 370  * @remark apr_file_read will read up to the specified number of bytes, but never
 371  *      more.  If there isn't enough data to fill that number of bytes,
 372  *      then the process/thread will block until it is available or EOF
 373  *      is reached.  If a char was put back into the stream via ungetc,
 374  *      it will be the first character returned.
 375  *
 376  *      It is possible for both bytes to be read and an error to be
 377  *      returned.  And if *bytes_read is less than nbytes, an
 378  *      accompanying error is _always_ returned.
 379  *
 380  *      APR_EINTR is never returned.
 381  */
 382 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
 383                                         apr_size_t nbytes,
 384                                         apr_size_t *bytes_read);
 385
 386 /**
 387  * Write data to the specified file, ensuring that all of the data is
 388  * written before returning.
 389  * @param thefile The file descriptor to write to.
 390  * @param buf The buffer which contains the data.
 391  * @param nbytes The number of bytes to write.
 392  * @param bytes_written If non-NULL, this will contain the number of bytes written.
 393  * @remark apr_file_write will write up to the specified number of bytes, but never
 394  *      more.  If the OS cannot write that many bytes, the process/thread
 395  *      will block until they can be written. Exceptional error such as
 396  *      "out of space" or "pipe closed" will terminate with an error.
 397  *
 398  *      It is possible for both bytes to be written and an error to be
 399  *      returned.  And if *bytes_written is less than nbytes, an
 400  *      accompanying error is _always_ returned.
 401  *
 402  *      APR_EINTR is never returned.
 403  */
 404 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf,
 405                                          apr_size_t nbytes,
 406                                          apr_size_t *bytes_written);
 407
 408 /**
 409  * put a character into the specified file.
 410  * @param ch The character to write.
 411  * @param thefile The file descriptor to write to
 412  */
 413 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
 414
 415 /**
 416  * get a character from the specified file.
 417  * @param ch The character to read into
 418  * @param thefile The file descriptor to read from
 419  */
 420 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
 421
 422 /**
 423  * put a character back onto a specified stream.
 424  * @param ch The character to write.
 425  * @param thefile The file descriptor to write to
 426  */
 427 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
 428
 429 /**
 430  * Get a string from a specified file.
 431  * @param str The buffer to store the string in.
 432  * @param len The length of the string
 433  * @param thefile The file descriptor to read from
 434  * @remark The buffer will be '\0'-terminated if any characters are stored.
 435  */
 436 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, apr_file_t *thefile);
 437
 438 /**
 439  * Put the string into a specified file.
 440  * @param str The string to write.
 441  * @param thefile The file descriptor to write to
 442  */
 443 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
 444
 445 /**
 446  * Flush the file's buffer.
 447  * @param thefile The file descriptor to flush
 448  */
 449 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
 450
 451 /**
 452  * duplicate the specified file descriptor.
 453  * @param new_file The structure to duplicate into.
 454  * @param old_file The file to duplicate.
 455  * @param p The pool to use for the new file.
 456  * @remark *new_file must point to a valid apr_file_t, or point to NULL
 457  */
 458 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
 459                                       apr_file_t *old_file,
 460                                       apr_pool_t *p);
 461
 462 /**
 463  * duplicate the specified file descriptor and close the original
 464  * @param new_file The old file that is to be closed and reused
 465  * @param old_file The file to duplicate
 466  * @param p        The pool to use for the new file
 467  *
 468  * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL
 469  */
 470 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
 471                                         apr_file_t *old_file,
 472                                         apr_pool_t *p);
 473
 474 /**
 475  * move the specified file descriptor to a new pool
 476  * @param new_file Pointer in which to return the new apr_file_t
 477  * @param old_file The file to move
 478  * @param p        The pool to which the descriptor is to be moved
 479  * @remark Unlike apr_file_dup2(), this function doesn't do an
 480  *         OS dup() operation on the underlying descriptor; it just
 481  *         moves the descriptor's apr_file_t wrapper to a new pool.
 482  * @remark The new pool need not be an ancestor of old_file's pool.
 483  * @remark After calling this function, old_file may not be used
 484  */
 485 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
 486                                             apr_file_t *old_file,
 487                                             apr_pool_t *p);
 488
 489 /**
 490  * Move the read/write file offset to a specified byte within a file.
 491  * @param thefile The file descriptor
 492  * @param where How to move the pointer, one of:
 493  * <PRE>
 494  *            APR_SET  --  set the offset to offset
 495  *            APR_CUR  --  add the offset to the current position
 496  *            APR_END  --  add the offset to the current file size
 497  * </PRE>
 498  * @param offset The offset to move the pointer to.
 499  * @remark The third argument is modified to be the offset the pointer
 500           was actually moved to.
 501  */
 502 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
 503                                    apr_seek_where_t where,
 504                                    apr_off_t *offset);
 505
 506 /**
 507  * Create an anonymous pipe.
 508  * @param in The file descriptor to use as input to the pipe.
 509  * @param out The file descriptor to use as output from the pipe.
 510  * @param cont The pool to operate on.
 511  */
 512 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out,
 513                                           apr_pool_t *cont);
 514
 515 /**
 516  * Create a named pipe.
 517  * @param filename The filename of the named pipe
 518  * @param perm The permissions for the newly created pipe.
 519  * @param cont The pool to operate on.
 520  */
 521 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
 522                                                apr_fileperms_t perm,
 523                                                apr_pool_t *cont);
 524
 525 /**
 526  * Get the timeout value for a pipe or manipulate the blocking state.
 527  * @param thepipe The pipe we are getting a timeout for.
 528  * @param timeout The current timeout value in microseconds.
 529  */
 530 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
 531                                                apr_interval_time_t *timeout);
 532
 533 /**
 534  * Set the timeout value for a pipe or manipulate the blocking state.
 535  * @param thepipe The pipe we are setting a timeout on.
 536  * @param timeout The timeout value in microseconds.  Values < 0 mean wait
 537  *        forever, 0 means do not wait at all.
 538  */
 539 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe,
 540                                                apr_interval_time_t timeout);
 541
 542 /** file (un)locking functions. */
 543
 544 /**
 545  * Establish a lock on the specified, open file. The lock may be advisory
 546  * or mandatory, at the discretion of the platform. The lock applies to
 547  * the file as a whole, rather than a specific range. Locks are established
 548  * on a per-thread/process basis; a second lock by the same thread will not
 549  * block.
 550  * @param thefile The file to lock.
 551  * @param type The type of lock to establish on the file.
 552  */
 553 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
 554
 555 /**
 556  * Remove any outstanding locks on the file.
 557  * @param thefile The file to unlock.
 558  */
 559 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
 560
 561 /**accessor and general file_io functions. */
 562
 563 /**
 564  * return the file name of the current file.
 565  * @param new_path The path of the file.
 566  * @param thefile The currently open file.
 567  */
 568 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
 569                                            apr_file_t *thefile);
 570
 571 /**
 572  * Return the data associated with the current file.
 573  * @param data The user data associated with the file.
 574  * @param key The key to use for retreiving data associated with this file.
 575  * @param file The currently open file.
 576  */
 577 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
 578                                            apr_file_t *file);
 579
 580 /**
 581  * Set the data associated with the current file.
 582  * @param file The currently open file.
 583  * @param data The user data to associate with the file.
 584  * @param key The key to use for assocaiteing data with the file.
 585  * @param cleanup The cleanup routine to use when the file is destroyed.
 586  */
 587 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
 588                                            const char *key,
 589                                            apr_status_t (*cleanup)(void *));
 590
 591 /**
 592  * Write a string to a file using a printf format.
 593  * @param fptr The file to write to.
 594  * @param format The format string
 595  * @param ... The values to substitute in the format string
 596  * @return The number of bytes written
 597  */
 598 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr,
 599                                         const char *format, ...)
 600         __attribute__((format(printf,2,3)));
 601
 602 /**
 603  * set the specified file's permission bits.
 604  * @param fname The file (name) to apply the permissions to.
 605  * @param perms The permission bits to apply to the file.
 606  * @warning Some platforms may not be able to apply all of the available
 607  *      permission bits; APR_INCOMPLETE will be returned if some permissions
 608  *      are specified which could not be set.
 609  *
 610  *      Platforms which do not implement this feature will return APR_ENOTIMPL.
 611  */
 612 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
 613                                            apr_fileperms_t perms);
 614
 615 /**
 616  * Set attributes of the specified file.
 617  * @param fname The full path to the file (using / on all systems)
 618  * @param attributes Or'd combination of
 619  * <PRE>
 620  *            APR_FILE_ATTR_READONLY   - make the file readonly
 621  *            APR_FILE_ATTR_EXECUTABLE - make the file executable
 622  *            APR_FILE_ATTR_HIDDEN     - make the file hidden
 623  * </PRE>
 624  * @param attr_mask Mask of valid bits in attributes.
 625  * @param cont the pool to use.
 626  * @remark This function should be used in preference to explict manipulation
 627  *      of the file permissions, because the operations to provide these
 628  *      attributes are platform specific and may involve more than simply
 629  *      setting permission bits.
 630  * @warning Platforms which do not implement this feature will return
 631  *      APR_ENOTIMPL.
 632  */
 633 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
 634                                              apr_fileattrs_t attributes,
 635                                              apr_fileattrs_t attr_mask,
 636                                              apr_pool_t *cont);
 637
 638 /**
 639  * Set the mtime of the specified file.
 640  * @param fname The full path to the file (using / on all systems)
 641  * @param mtime The mtime to apply to the file.
 642  * @param pool The pool to use.
 643  * @warning Platforms which do not implement this feature will return
 644  *      APR_ENOTIMPL.
 645  */
 646 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
 647                                              apr_time_t mtime,
 648                                              apr_pool_t *pool);
 649
 650 /**
 651  * Create a new directory on the file system.
 652  * @param path the path for the directory to be created.  (use / on all systems)
 653  * @param perm Permissions for the new direcoty.
 654  * @param cont the pool to use.
 655  */
 656 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
 657                         apr_pool_t *cont);
 658
 659 /** Creates a new directory on the file system, but behaves like
 660  * 'mkdir -p'. Creates intermediate directories as required. No error
 661  * will be reported if PATH already exists.
 662  * @param path the path for the directory to be created.  (use / on all systems)
 663  * @param perm Permissions for the new direcoty.
 664  * @param pool the pool to use.
 665  */
 666 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
 667                                                  apr_fileperms_t perm,
 668                                                  apr_pool_t *pool);
 669
 670 /**
 671  * Remove directory from the file system.
 672  * @param path the path for the directory to be removed.  (use / on all systems)
 673  * @param cont the pool to use.
 674  */
 675 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *cont);
 676
 677 /**
 678  * get the specified file's stats.
 679  * @param finfo Where to store the information about the file.
 680  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
 681  * @param thefile The file to get information about.
 682  */
 683 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
 684                                           apr_int32_t wanted,
 685                                           apr_file_t *thefile);
 686
 687
 688 /**
 689  * Truncate the file's length to the specified offset
 690  * @param fp The file to truncate
 691  * @param offset The offset to truncate to.
 692  * @remark The read/write file offset is repositioned to offset.
 693  */
 694 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
 695
 696 /**
 697  * Retrieve the flags that were passed into apr_file_open()
 698  * when the file was opened.
 699  * @return apr_int32_t the flags
 700  */
 701 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
 702
 703 /**
 704  * Get the pool used by the file.
 705  */
 706 APR_POOL_DECLARE_ACCESSOR(file);
 707
 708 /**
 709  * Set a file to be inherited by child processes.
 710  *
 711  */
 712 APR_DECLARE_INHERIT_SET(file);
 713
 714 /** @deprecated @see apr_file_inherit_set */
 715 APR_DECLARE(void) apr_file_set_inherit(apr_file_t *file);
 716
 717 /**
 718  * Unset a file from being inherited by child processes.
 719  */
 720 APR_DECLARE_INHERIT_UNSET(file);
 721
 722 /** @deprecated @see apr_file_inherit_unset */
 723 APR_DECLARE(void) apr_file_unset_inherit(apr_file_t *file);
 724
 725 /**
 726  * Open a temporary file
 727  * @param fp The apr file to use as a temporary file.
 728  * @param templ The template to use when creating a temp file.
 729  * @param flags The flags to open the file with. If this is zero,
 730  *              the file is opened with
 731  *              APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
 732  * @param p The pool to allocate the file out of.
 733  * @remark
 734  * This function  generates  a unique temporary file name from template.
 735  * The last six characters of template must be XXXXXX and these are replaced
 736  * with a string that makes the filename unique. Since it will  be  modified,
 737  * template must not be a string constant, but should be declared as a character
 738  * array.
 739  *
 740  */
 741 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
 742                                           apr_int32_t flags, apr_pool_t *p);
 743
 744
 745 /**
 746  * Find an existing directory suitable as a temporary storage location.
 747  * @param temp_dir The temp directory.
 748  * @param p The pool to use for any necessary allocations.
 749  * @remark
 750  * This function uses an algorithm to search for a directory that an
 751  * an application can use for temporary storage.  Once such a
 752  * directory is found, that location is cached by the library.  Thus,
 753  * callers only pay the cost of this algorithm once if that one time
 754  * is successful.
 755  *
 756  */
 757 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir,
 758                                            apr_pool_t *p);
 759
 760 /** @} */
 761
 762 #ifdef __cplusplus
 763 }
 764 #endif
 765
 766 #endif  /* ! APR_FILE_IO_H */