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