apr_file_io.h revision 251875
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 37extern "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 */ 166typedef apr_uint32_t apr_fileattrs_t; 167 168/** Type to pass as whence argument to apr_file_seek. */ 169typedef int apr_seek_where_t; 170 171/** 172 * Structure for referencing files. 173 */ 174typedef 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 */ 235APR_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 */ 243APR_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 */ 252APR_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 */ 263APR_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 */ 273APR_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 */ 288APR_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 */ 304APR_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 */ 314APR_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 */ 331APR_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 */ 341APR_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 */ 351APR_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 */ 365APR_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 */ 380APR_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 */ 395APR_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 */ 416APR_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 */ 434APR_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 */ 452APR_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 */ 476APR_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 */ 500APR_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 */ 519APR_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 */ 528APR_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 */ 535APR_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 */ 542APR_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 */ 552APR_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 */ 560APR_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 */ 566APR_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 */ 572APR_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 */ 578APR_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 */ 587APR_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 */ 599APR_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 */ 614APR_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 */ 629APR_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 */ 637APR_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 */ 652APR_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 */ 669APR_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 */ 694APR_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 */ 705APR_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 */ 714APR_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 */ 723APR_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 */ 737APR_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 */ 743APR_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 */ 752APR_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 */ 761APR_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 */ 771APR_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 */ 782APR_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 */ 798APR_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 */ 819APR_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 */ 832APR_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 */ 842APR_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 */ 852APR_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 */ 863APR_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 */ 871APR_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 */ 882APR_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 */ 889APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f); 890 891/** 892 * Get the pool used by the file. 893 */ 894APR_POOL_DECLARE_ACCESSOR(file); 895 896/** 897 * Set a file to be inherited by child processes. 898 * 899 */ 900APR_DECLARE_INHERIT_SET(file); 901 902/** 903 * Unset a file from being inherited by child processes. 904 */ 905APR_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 */ 923APR_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 */ 936APR_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 */ 946