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