apr_file_io.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_FILE_IO_H 00018 #define APR_FILE_IO_H 00019 00020 /** 00021 * @file apr_file_io.h 00022 * @brief APR File I/O Handling 00023 */ 00024 00025 #include "apr.h" 00026 #include "apr_pools.h" 00027 #include "apr_time.h" 00028 #include "apr_errno.h" 00029 #include "apr_file_info.h" 00030 #include "apr_inherit.h" 00031 00032 #define APR_WANT_STDIO /**< for SEEK_* */ 00033 #define APR_WANT_IOVEC /**< for apr_file_writev */ 00034 #include "apr_want.h" 00035 00036 #ifdef __cplusplus 00037 extern "C" { 00038 #endif /* __cplusplus */ 00039 00040 /** 00041 * @defgroup apr_file_io File I/O Handling Functions 00042 * @ingroup APR 00043 * @{ 00044 */ 00045 00046 /** 00047 * @defgroup apr_file_open_flags File Open Flags/Routines 00048 * @{ 00049 */ 00050 00051 /* Note to implementors: Values in the range 0x00100000--0x80000000 00052 are reserved for platform-specific values. */ 00053 00054 #define APR_FOPEN_READ 0x00001 /**< Open the file for reading */ 00055 #define APR_FOPEN_WRITE 0x00002 /**< Open the file for writing */ 00056 #define APR_FOPEN_CREATE 0x00004 /**< Create the file if not there */ 00057 #define APR_FOPEN_APPEND 0x00008 /**< Append to the end of the file */ 00058 #define APR_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate 00059 to 0 length */ 00060 #define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode */ 00061 #define APR_FOPEN_EXCL 0x00040 /**< Open should fail if APR_CREATE 00062 and file exists. */ 00063 #define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */ 00064 #define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */ 00065 #define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open 00066 the file for use across multiple 00067 threads */ 00068 #define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for 00069 higher level locked read/write 00070 access to support writes across 00071 process/machines */ 00072 #define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup 00073 when the file is opened */ 00074 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this 00075 file should support 00076 apr_socket_sendfile operation */ 00077 #define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable 00078 * large file support, see WARNING below 00079 */ 00080 #define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable 00081 * sparse file support, see WARNING below 00082 */ 00083 00084 /* backcompat */ 00085 #define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */ 00086 #define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */ 00087 #define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */ 00088 #define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */ 00089 #define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */ 00090 #define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */ 00091 #define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */ 00092 #define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */ 00093 #define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */ 00094 #define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */ 00095 #define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */ 00096 #define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */ 00097 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */ 00098 #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */ 00099 00100 /** @warning APR_FOPEN_LARGEFILE flag only has effect on some 00101 * platforms where sizeof(apr_off_t) == 4. Where implemented, it 00102 * allows opening and writing to a file which exceeds the size which 00103 * can be represented by apr_off_t (2 gigabytes). When a file's size 00104 * does exceed 2Gb, apr_file_info_get() will fail with an error on the 00105 * descriptor, likewise apr_stat()/apr_lstat() will fail on the 00106 * filename. apr_dir_read() will fail with APR_INCOMPLETE on a 00107 * directory entry for a large file depending on the particular 00108 * APR_FINFO_* flags. Generally, it is not recommended to use this 00109 * flag. 00110 * 00111 * @warning APR_FOPEN_SPARSE may, depending on platform, convert a 00112 * normal file to a sparse file. Some applications may be unable 00113 * to decipher a sparse file, so it's critical that the sparse file 00114 * flag should only be used for files accessed only by APR or other 00115 * applications known to be able to decipher them. APR does not 00116 * guarantee that it will compress the file into sparse segments 00117 * if it was previously created and written without the sparse flag. 00118 * On platforms which do not understand, or on file systems which 00119 * cannot handle sparse files, the flag is ignored by apr_file_open(). 00120 */ 00121 00122 /** @} */ 00123 00124 /** 00125 * @defgroup apr_file_seek_flags File Seek Flags 00126 * @{ 00127 */ 00128 00129 /* flags for apr_file_seek */ 00130 /** Set the file position */ 00131 #define APR_SET SEEK_SET 00132 /** Current */ 00133 #define APR_CUR SEEK_CUR 00134 /** Go to end of file */ 00135 #define APR_END SEEK_END 00136 /** @} */ 00137 00138 /** 00139 * @defgroup apr_file_attrs_set_flags File Attribute Flags 00140 * @{ 00141 */ 00142 00143 /* flags for apr_file_attrs_set */ 00144 #define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */ 00145 #define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */ 00146 #define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */ 00147 /** @} */ 00148 00149 /** 00150 * @defgroup apr_file_writev{_full} max iovec size 00151 * @{ 00152 */ 00153 #if defined(DOXYGEN) 00154 #define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum 00155 size of an iovec array */ 00156 #elif defined(IOV_MAX) 00157 #define APR_MAX_IOVEC_SIZE IOV_MAX 00158 #elif defined(MAX_IOVEC) 00159 #define APR_MAX_IOVEC_SIZE MAX_IOVEC 00160 #else 00161 #define APR_MAX_IOVEC_SIZE 1024 00162 #endif 00163 /** @} */ 00164 00165 /** File attributes */ 00166 typedef apr_uint32_t apr_fileattrs_t; 00167 00168 /** Type to pass as whence argument to apr_file_seek. */ 00169 typedef int apr_seek_where_t; 00170 00171 /** 00172 * Structure for referencing files. 00173 */ 00174 typedef struct apr_file_t apr_file_t; 00175 00176 /* File lock types/flags */ 00177 /** 00178 * @defgroup apr_file_lock_types File Lock Types 00179 * @{ 00180 */ 00181 00182 #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process 00183 or thread can hold a shared lock 00184 at any given time. Essentially, 00185 this is a "read lock", preventing 00186 writers from establishing an 00187 exclusive lock. */ 00188 #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process 00189 may hold an exclusive lock at any 00190 given time. This is analogous to 00191 a "write lock". */ 00192 00193 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */ 00194 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the 00195 file lock */ 00196 /** @} */ 00197 00198 /** 00199 * Open the specified file. 00200 * @param newf The opened file descriptor. 00201 * @param fname The full path to the file (using / on all systems) 00202 * @param flag Or'ed value of: 00203 * <PRE> 00204 * APR_READ open for reading 00205 * APR_WRITE open for writing 00206 * APR_CREATE create the file if not there 00207 * APR_APPEND file ptr is set to end prior to all writes 00208 * APR_TRUNCATE set length to zero if file exists 00209 * APR_BINARY not a text file (This flag is ignored on 00210 * UNIX because it has no meaning) 00211 * APR_BUFFERED buffer the data. Default is non-buffered 00212 * APR_EXCL return error if APR_CREATE and file exists 00213 * APR_DELONCLOSE delete the file after closing. 00214 * APR_XTHREAD Platform dependent tag to open the file 00215 * for use across multiple threads 00216 * APR_SHARELOCK Platform dependent support for higher 00217 * level locked read/write access to support 00218 * writes across process/machines 00219 * APR_FILE_NOCLEANUP Do not register a cleanup with the pool 00220 * passed in on the <EM>pool</EM> argument (see below). 00221 * The apr_os_file_t handle in apr_file_t will not 00222 * be closed when the pool is destroyed. 00223 * APR_SENDFILE_ENABLED Open with appropriate platform semantics 00224 * for sendfile operations. Advisory only, 00225 * apr_socket_sendfile does not check this flag. 00226 * </PRE> 00227 * @param perm Access permissions for file. 00228 * @param pool The pool to use. 00229 * @remark If perm is APR_OS_DEFAULT and the file is being created, 00230 * appropriate default permissions will be used. 00231 * @remark By default, the returned file descriptor will not be 00232 * inherited by child processes created by apr_proc_create(). This 00233 * can be changed using apr_file_inherit_set(). 00234 */ 00235 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname, 00236 apr_int32_t flag, apr_fileperms_t perm, 00237 apr_pool_t *pool); 00238 00239 /** 00240 * Close the specified file. 00241 * @param file The file descriptor to close. 00242 */ 00243 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file); 00244 00245 /** 00246 * Delete the specified file. 00247 * @param path The full path to the file (using / on all systems) 00248 * @param pool The pool to use. 00249 * @remark If the file is open, it won't be removed until all 00250 * instances are closed. 00251 */ 00252 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool); 00253 00254 /** 00255 * Rename the specified file. 00256 * @param from_path The full path to the original file (using / on all systems) 00257 * @param to_path The full path to the new file (using / on all systems) 00258 * @param pool The pool to use. 00259 * @warning If a file exists at the new location, then it will be 00260 * overwritten. Moving files or directories across devices may not be 00261 * possible. 00262 */ 00263 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 00264 const char *to_path, 00265 apr_pool_t *pool); 00266 00267 /** 00268 * Create a hard link to the specified file. 00269 * @param from_path The full path to the original file (using / on all systems) 00270 * @param to_path The full path to the new file (using / on all systems) 00271 * @remark Both files must reside on the same device. 00272 */ 00273 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path, 00274 const char *to_path); 00275 00276 /** 00277 * Copy the specified file to another file. 00278 * @param from_path The full path to the original file (using / on all systems) 00279 * @param to_path The full path to the new file (using / on all systems) 00280 * @param perms Access permissions for the new file if it is created. 00281 * In place of the usual or'd combination of file permissions, the 00282 * value APR_FILE_SOURCE_PERMS may be given, in which case the source 00283 * file's permissions are copied. 00284 * @param pool The pool to use. 00285 * @remark The new file does not need to exist, it will be created if required. 00286 * @warning If the new file already exists, its contents will be overwritten. 00287 */ 00288 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 00289 const char *to_path, 00290 apr_fileperms_t perms, 00291 apr_pool_t *pool); 00292 00293 /** 00294 * Append the specified file to another file. 00295 * @param from_path The full path to the source file (use / on all systems) 00296 * @param to_path The full path to the destination file (use / on all systems) 00297 * @param perms Access permissions for the destination file if it is created. 00298 * In place of the usual or'd combination of file permissions, the 00299 * value APR_FILE_SOURCE_PERMS may be given, in which case the source 00300 * file's permissions are copied. 00301 * @param pool The pool to use. 00302 * @remark The new file does not need to exist, it will be created if required. 00303 */ 00304 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 00305 const char *to_path, 00306 apr_fileperms_t perms, 00307 apr_pool_t *pool); 00308 00309 /** 00310 * Are we at the end of the file 00311 * @param fptr The apr file we are testing. 00312 * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise. 00313 */ 00314 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); 00315 00316 /** 00317 * Open standard error as an apr file pointer. 00318 * @param thefile The apr file to use as stderr. 00319 * @param pool The pool to allocate the file out of. 00320 * 00321 * @remark The only reason that the apr_file_open_std* functions exist 00322 * is that you may not always have a stderr/out/in on Windows. This 00323 * is generally a problem with newer versions of Windows and services. 00324 * 00325 * @remark The other problem is that the C library functions generally work 00326 * differently on Windows and Unix. So, by using apr_file_open_std* 00327 * functions, you can get a handle to an APR struct that works with 00328 * the APR functions which are supposed to work identically on all 00329 * platforms. 00330 */ 00331 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, 00332 apr_pool_t *pool); 00333 00334 /** 00335 * open standard output as an apr file pointer. 00336 * @param thefile The apr file to use as stdout. 00337 * @param pool The pool to allocate the file out of. 00338 * 00339 * @remark See remarks for apr_file_open_stderr. 00340 */ 00341 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, 00342 apr_pool_t *pool); 00343 00344 /** 00345 * open standard input as an apr file pointer. 00346 * @param thefile The apr file to use as stdin. 00347 * @param pool The pool to allocate the file out of. 00348 * 00349 * @remark See remarks for apr_file_open_stderr. 00350 */ 00351 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, 00352 apr_pool_t *pool); 00353 00354 /** 00355 * open standard error as an apr file pointer, with flags. 00356 * @param thefile The apr file to use as stderr. 00357 * @param flags The flags to open the file with. Only the APR_EXCL, 00358 * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, 00359 * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should 00360 * be used. The APR_WRITE flag will be set unconditionally. 00361 * @param pool The pool to allocate the file out of. 00362 * 00363 * @remark See remarks for apr_file_open_stderr. 00364 */ 00365 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile, 00366 apr_int32_t flags, 00367 apr_pool_t *pool); 00368 00369 /** 00370 * open standard output as an apr file pointer, with flags. 00371 * @param thefile The apr file to use as stdout. 00372 * @param flags The flags to open the file with. Only the APR_EXCL, 00373 * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, 00374 * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should 00375 * be used. The APR_WRITE flag will be set unconditionally. 00376 * @param pool The pool to allocate the file out of. 00377 * 00378 * @remark See remarks for apr_file_open_stderr. 00379 */ 00380 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile, 00381 apr_int32_t flags, 00382 apr_pool_t *pool); 00383 00384 /** 00385 * open standard input as an apr file pointer, with flags. 00386 * @param thefile The apr file to use as stdin. 00387 * @param flags The flags to open the file with. Only the APR_EXCL, 00388 * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, 00389 * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should 00390 * be used. The APR_READ flag will be set unconditionally. 00391 * @param pool The pool to allocate the file out of. 00392 * 00393 * @remark See remarks for apr_file_open_stderr. 00394 */ 00395 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile, 00396 apr_int32_t flags, 00397 apr_pool_t *pool); 00398 00399 /** 00400 * Read data from the specified file. 00401 * @param thefile The file descriptor to read from. 00402 * @param buf The buffer to store the data to. 00403 * @param nbytes On entry, the number of bytes to read; on exit, the number 00404 * of bytes read. 00405 * 00406 * @remark apr_file_read will read up to the specified number of 00407 * bytes, but never more. If there isn't enough data to fill that 00408 * number of bytes, all of the available data is read. The third 00409 * argument is modified to reflect the number of bytes read. If a 00410 * char was put back into the stream via ungetc, it will be the first 00411 * character returned. 00412 * 00413 * @remark It is not possible for both bytes to be read and an APR_EOF 00414 * or other error to be returned. APR_EINTR is never returned. 00415 */ 00416 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, 00417 apr_size_t *nbytes); 00418 00419 /** 00420 * Write data to the specified file. 00421 * @param thefile The file descriptor to write to. 00422 * @param buf The buffer which contains the data. 00423 * @param nbytes On entry, the number of bytes to write; on exit, the number 00424 * of bytes written. 00425 * 00426 * @remark apr_file_write will write up to the specified number of 00427 * bytes, but never more. If the OS cannot write that many bytes, it 00428 * will write as many as it can. The third argument is modified to 00429 * reflect the * number of bytes written. 00430 * 00431 * @remark It is possible for both bytes to be written and an error to 00432 * be returned. APR_EINTR is never returned. 00433 */ 00434 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, 00435 apr_size_t *nbytes); 00436 00437 /** 00438 * Write data from iovec array to the specified file. 00439 * @param thefile The file descriptor to write to. 00440 * @param vec The array from which to get the data to write to the file. 00441 * @param nvec The number of elements in the struct iovec array. This must 00442 * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function 00443 * will fail with APR_EINVAL. 00444 * @param nbytes The number of bytes written. 00445 * 00446 * @remark It is possible for both bytes to be written and an error to 00447 * be returned. APR_EINTR is never returned. 00448 * 00449 * @remark apr_file_writev is available even if the underlying 00450 * operating system doesn't provide writev(). 00451 */ 00452 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, 00453 const struct iovec *vec, 00454 apr_size_t nvec, apr_size_t *nbytes); 00455 00456 /** 00457 * Read data from the specified file, ensuring that the buffer is filled 00458 * before returning. 00459 * @param thefile The file descriptor to read from. 00460 * @param buf The buffer to store the data to. 00461 * @param nbytes The number of bytes to read. 00462 * @param bytes_read If non-NULL, this will contain the number of bytes read. 00463 * 00464 * @remark apr_file_read will read up to the specified number of 00465 * bytes, but never more. If there isn't enough data to fill that 00466 * number of bytes, then the process/thread will block until it is 00467 * available or EOF is reached. If a char was put back into the 00468 * stream via ungetc, it will be the first character returned. 00469 * 00470 * @remark It is possible for both bytes to be read and an error to be 00471 * returned. And if *bytes_read is less than nbytes, an accompanying 00472 * error is _always_ returned. 00473 * 00474 * @remark APR_EINTR is never returned. 00475 */ 00476 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, 00477 apr_size_t nbytes, 00478 apr_size_t *bytes_read); 00479 00480 /** 00481 * Write data to the specified file, ensuring that all of the data is 00482 * written before returning. 00483 * @param thefile The file descriptor to write to. 00484 * @param buf The buffer which contains the data. 00485 * @param nbytes The number of bytes to write. 00486 * @param bytes_written If non-NULL, set to the number of bytes written. 00487 * 00488 * @remark apr_file_write will write up to the specified number of 00489 * bytes, but never more. If the OS cannot write that many bytes, the 00490 * process/thread will block until they can be written. Exceptional 00491 * error such as "out of space" or "pipe closed" will terminate with 00492 * an error. 00493 * 00494 * @remark It is possible for both bytes to be written and an error to 00495 * be returned. And if *bytes_written is less than nbytes, an 00496 * accompanying error is _always_ returned. 00497 * 00498 * @remark APR_EINTR is never returned. 00499 */ 00500 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 00501 const void *buf, 00502 apr_size_t nbytes, 00503 apr_size_t *bytes_written); 00504 00505 00506 /** 00507 * Write data from iovec array to the specified file, ensuring that all of the 00508 * data is written before returning. 00509 * @param thefile The file descriptor to write to. 00510 * @param vec The array from which to get the data to write to the file. 00511 * @param nvec The number of elements in the struct iovec array. This must 00512 * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function 00513 * will fail with APR_EINVAL. 00514 * @param nbytes The number of bytes written. 00515 * 00516 * @remark apr_file_writev_full is available even if the underlying 00517 * operating system doesn't provide writev(). 00518 */ 00519 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile, 00520 const struct iovec *vec, 00521 apr_size_t nvec, 00522 apr_size_t *nbytes); 00523 /** 00524 * Write a character into the specified file. 00525 * @param ch The character to write. 00526 * @param thefile The file descriptor to write to 00527 */ 00528 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile); 00529 00530 /** 00531 * Read a character from the specified file. 00532 * @param ch The character to read into 00533 * @param thefile The file descriptor to read from 00534 */ 00535 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile); 00536 00537 /** 00538 * Put a character back onto a specified stream. 00539 * @param ch The character to write. 00540 * @param thefile The file descriptor to write to 00541 */ 00542 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile); 00543 00544 /** 00545 * Read a string from the specified file. 00546 * @param str The buffer to store the string in. 00547 * @param len The length of the string 00548 * @param thefile The file descriptor to read from 00549 * @remark The buffer will be NUL-terminated if any characters are stored. 00550 */ 00551 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 00552 apr_file_t *thefile); 00553 00554 /** 00555 * Write the string into the specified file. 00556 * @param str The string to write. 00557 * @param thefile The file descriptor to write to 00558 */ 00559 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile); 00560 00561 /** 00562 * Flush the file's buffer. 00563 * @param thefile The file descriptor to flush 00564 */ 00565 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile); 00566 00567 /** 00568 * Transfer all file modified data and metadata to disk. 00569 * @param thefile The file descriptor to sync 00570 */ 00571 APR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile); 00572 00573 /** 00574 * Transfer all file modified data to disk. 00575 * @param thefile The file descriptor to sync 00576 */ 00577 APR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile); 00578 00579 /** 00580 * Duplicate the specified file descriptor. 00581 * @param new_file The structure to duplicate into. 00582 * @param old_file The file to duplicate. 00583 * @param p The pool to use for the new file. 00584 * @remark *new_file must point to a valid apr_file_t, or point to NULL. 00585 */ 00586 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file, 00587 apr_file_t *old_file, 00588 apr_pool_t *p); 00589 00590 /** 00591 * Duplicate the specified file descriptor and close the original 00592 * @param new_file The old file that is to be closed and reused 00593 * @param old_file The file to duplicate 00594 * @param p The pool to use for the new file 00595 * 00596 * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL. 00597 */ 00598 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file, 00599 apr_file_t *old_file, 00600 apr_pool_t *p); 00601 00602 /** 00603 * Move the specified file descriptor to a new pool 00604 * @param new_file Pointer in which to return the new apr_file_t 00605 * @param old_file The file to move 00606 * @param p The pool to which the descriptor is to be moved 00607 * @remark Unlike apr_file_dup2(), this function doesn't do an 00608 * OS dup() operation on the underlying descriptor; it just 00609 * moves the descriptor's apr_file_t wrapper to a new pool. 00610 * @remark The new pool need not be an ancestor of old_file's pool. 00611 * @remark After calling this function, old_file may not be used 00612 */ 00613 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00629 char * buffer, 00630 apr_size_t bufsize); 00631 00632 /** 00633 * Get the size of any buffer for the specified apr file handle 00634 * @param thefile The file handle 00635 */ 00636 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00637 00638 /** 00639 * Move the read/write file offset to a specified byte within a file. 00640 * @param thefile The file descriptor 00641 * @param where How to move the pointer, one of: 00642 * <PRE> 00643 * APR_SET -- set the offset to offset 00644 * APR_CUR -- add the offset to the current position 00645 * APR_END -- add the offset to the current file size 00646 * </PRE> 00647 * @param offset The offset to move the pointer to. 00648 * @remark The third argument is modified to be the offset the pointer 00649 was actually moved to. 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00652 apr_seek_where_t where, 00653 apr_off_t *offset); 00654 00655 /** 00656 * Create an anonymous pipe. 00657 * @param in The newly created pipe's file for reading. 00658 * @param out The newly created pipe's file for writing. 00659 * @param pool The pool to operate on. 00660 * @remark By default, the returned file descriptors will be inherited 00661 * by child processes created using apr_proc_create(). This can be 00662 * changed using apr_file_inherit_unset(). 00663 * @bug Some platforms cannot toggle between blocking and nonblocking, 00664 * and when passing a pipe as a standard handle to an application which 00665 * does not expect it, a non-blocking stream will fluxor the client app. 00666 * @deprecated @see apr_file_pipe_create_ex 00667 */ 00668 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00669 apr_file_t **out, 00670 apr_pool_t *pool); 00671 00672 /** 00673 * Create an anonymous pipe which portably supports async timeout options. 00674 * @param in The newly created pipe's file for reading. 00675 * @param out The newly created pipe's file for writing. 00676 * @param blocking one of these values defined in apr_thread_proc.h; 00677 * @param pool The pool to operate on. 00678 * <pre> 00679 * APR_FULL_BLOCK 00680 * APR_READ_BLOCK 00681 * APR_Gss="code" href="group__apr__file__io.html#gaa46e4763ac375ea3c7a43ba6f6099e22">apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00629 char * buffer, 00630 apr_size_t bufsize); 00631 00632 /** 00633 * Get the size of any buffer for the specified apr file handle 00634 * @param thefile The file handle 00635 */ 00636 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00637 00638 /** 00639 * Move the read/write file offset to a specified byte within a file. 00640 * @param thefile The file descriptor 00641 * @param where How to move the pointer, one of: 00642 * <PRE> 00643 * APR_SET -- set the offset to offset 00644 * APR_CUR -- add the offset to the current position 00645 * APR_END -- add the offset to the current file size 00646 * </PRE> 00647 * @param offset The offset to move the pointer to. 00648 * @remark The third argument is modified to be the offset the pointer 00649 was actually moved to. 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00652 apr_seek_where_t where, 00653 apr_off_t *offset); 00654 00655 /** 00656 * Create an anonymous pipe. 00657 * @param in The newly created pipe's file for reading. 00658 * @param out The newly created pipe's file for writing. 00659 * @param pool The pool to operate on. 00660 * @remark By default, the returned file descriptors will be inherited 00661 * by child processes created using apr_proc_create(). This can be 00662 * changed using apr_file_inherit_unset(). 00663 * @bug Some platforms cannot toggle between blocking and nonblocking, 00664 * and when passing a pipe as a standard handle to an application which 00665 * does not expect it, a non-blocking stream will fluxor the client app. 00666 * @deprecated @see apr_file_pipe_create_ex 00667 */ 00668 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00669 apr_file_t **out, 00670 apr_pool_t *pool); 00671 00672 /** 00673 * Create an anonymous pipe which portably supports async timeout options. 00674 * @param in The newly created pipe's file for reading. 00675 * @param out The newly created pipe's file for writing. 00676 * @param blocking one of these values defined in apr_thread_proc.h; 00677 * @param pool The pool to operate on. 00678 * <pre> 00679 * APR_FULL_BLOCK 00680 * APR_READ_BLOCK 00681 * APR_Gss="code" href="group__apr__file__io.html#gaa46e4763ac375ea3c7a43ba6f6099e22">apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00629 char * buffer, 00630 apr_size_t bufsize); 00631 00632 /** 00633 * Get the size of any buffer for the specified apr file handle 00634 * @param thefile The file handle 00635 */ 00636 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00637 00638 /** 00639 * Move the read/write file offset to a specified byte within a file. 00640 * @param thefile The file descriptor 00641 * @param where How to move the pointer, one of: 00642 * <PRE> 00643 * APR_SET -- set the offset to offset 00644 * APR_CUR -- add the offset to the current position 00645 * APR_END -- add the offset to the current file size 00646 * </PRE> 00647 * @param offset The offset to move the pointer to. 00648 * @remark The third argument is modified to be the offset the pointer 00649 was actually moved to. 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00652 apr_seek_where_t where, 00653 apr_off_t *offset); 00654 00655 /** 00656 * Create an anonymous pipe. 00657 * @param in The newly created pipe's file for reading. 00658 * @param out The newly created pipe's file for writing. 00659 * @param pool The pool to operate on. 00660 * @remark By default, the returned file descriptors will be inherited 00661 * by child processes created using apr_proc_create(). This can be 00662 * changed using apr_file_inherit_unset(). 00663 * @bug Some platforms cannot toggle between blocking and nonblocking, 00664 * and when passing a pipe as a standard handle to an application which 00665 * does not expect it, a non-blocking stream will fluxor the client app. 00666 * @deprecated @see apr_file_pipe_create_ex 00667 */ 00668 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00669 apr_file_t **out, 00670 apr_pool_t *pool); 00671 00672 /** 00673 * Create an anonymous pipe which portably supports async timeout options. 00674 * @param in The newly created pipe's file for reading. 00675 * @param out The newly created pipe's file for writing. 00676 * @param blocking one of these values defined in apr_thread_proc.h; 00677 * @param pool The pool to operate on. 00678 * <pre> 00679 * APR_FULL_BLOCK 00680 * APR_READ_BLOCK 00681 * APR_Gss="code" href="group__apr__file__io.html#gaa46e4763ac375ea3c7a43ba6f6099e22">apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00629 char * buffer, 00630 apr_size_t bufsize); 00631 00632 /** 00633 * Get the size of any buffer for the specified apr file handle 00634 * @param thefile The file handle 00635 */ 00636 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00637 00638 /** 00639 * Move the read/write file offset to a specified byte within a file. 00640 * @param thefile The file descriptor 00641 * @param where How to move the pointer, one of: 00642 * <PRE> 00643 * APR_SET -- set the offset to offset 00644 * APR_CUR -- add the offset to the current position 00645 * APR_END -- add the offset to the current file size 00646 * </PRE> 00647 * @param offset The offset to move the pointer to. 00648 * @remark The third argument is modified to be the offset the pointer 00649 was actually moved to. 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00652 apr_seek_where_t where, 00653 apr_off_t *offset); 00654 00655 /** 00656 * Create an anonymous pipe. 00657 * @param in The newly created pipe's file for reading. 00658 * @param out The newly created pipe's file for writing. 00659 * @param pool The pool to operate on. 00660 * @remark By default, the returned file descriptors will be inherited 00661 * by child processes created using apr_proc_create(). This can be 00662 * changed using apr_file_inherit_unset(). 00663 * @bug Some platforms cannot toggle between blocking and nonblocking, 00664 * and when passing a pipe as a standard handle to an application which 00665 * does not expect it, a non-blocking stream will fluxor the client app. 00666 * @deprecated @see apr_file_pipe_create_ex 00667 */ 00668 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00669 apr_file_t **out, 00670 apr_pool_t *pool); 00671 00672 /** 00673 * Create an anonymous pipe which portably supports async timeout options. 00674 * @param in The newly created pipe's file for reading. 00675 * @param out The newly created pipe's file for writing. 00676 * @param blocking one of these values defined in apr_thread_proc.h; 00677 * @param pool The pool to operate on. 00678 * <pre> 00679 * APR_FULL_BLOCK 00680 * APR_READ_BLOCK 00681 * APR_Gss="code" href="group__apr__file__io.html#gaa46e4763ac375ea3c7a43ba6f6099e22">apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00629 char * buffer, 00630 apr_size_t bufsize); 00631 00632 /** 00633 * Get the size of any buffer for the specified apr file handle 00634 * @param thefile The file handle 00635 */ 00636 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00637 00638 /** 00639 * Move the read/write file offset to a specified byte within a file. 00640 * @param thefile The file descriptor 00641 * @param where How to move the pointer, one of: 00642 * <PRE> 00643 * APR_SET -- set the offset to offset 00644 * APR_CUR -- add the offset to the current position 00645 * APR_END -- add the offset to the current file size 00646 * </PRE> 00647 * @param offset The offset to move the pointer to. 00648 * @remark The third argument is modified to be the offset the pointer 00649 was actually moved to. 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00652 apr_seek_where_t where, 00653 apr_off_t *offset); 00654 00655 /** 00656 * Create an anonymous pipe. 00657 * @param in The newly created pipe's file for reading. 00658 * @param out The newly created pipe's file for writing. 00659 * @param pool The pool to operate on. 00660 * @remark By default, the returned file descriptors will be inherited 00661 * by child processes created using apr_proc_create(). This can be 00662 * changed using apr_file_inherit_unset(). 00663 * @bug Some platforms cannot toggle between blocking and nonblocking, 00664 * and when passing a pipe as a standard handle to an application which 00665 * does not expect it, a non-blocking stream will fluxor the client app. 00666 * @deprecated @see apr_file_pipe_create_ex 00667 */ 00668 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00669 apr_file_t **out, 00670 apr_pool_t *pool); 00671 00672 /** 00673 * Create an anonymous pipe which portably supports async timeout options. 00674 * @param in The newly created pipe's file for reading. 00675 * @param out The newly created pipe's file for writing. 00676 * @param blocking one of these values defined in apr_thread_proc.h; 00677 * @param pool The pool to operate on. 00678 * <pre> 00679 * APR_FULL_BLOCK 00680 * APR_READ_BLOCK 00681 * APR_Gss="code" href="group__apr__file__io.html#gaa46e4763ac375ea3c7a43ba6f6099e22">apr_file_t **new_file, 00614 apr_file_t *old_file, 00615 apr_pool_t *p); 00616 00617 /** 00618 * Give the specified apr file handle a new buffer 00619 * @param thefile The file handle that is to be modified 00620 * @param buffer The buffer 00621 * @param bufsize The size of the buffer 00622 * @remark It is possible to add a buffer to previously unbuffered 00623 * file handles, the APR_BUFFERED flag will be added to 00624 * the file handle's flags. Likewise, with buffer=NULL and 00625 * bufsize=0 arguments it is possible to make a previously 00626 * buffered file handle unbuffered. 00627 */ 00628 APR_DECLARE(apr_st