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