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