00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * 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; WARNING see 00079 below. */ 00080 /* backcompat */ 00081 #define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */ 00082 #define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */ 00083 #define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */ 00084 #define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */ 00085 #define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */ 00086 #define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */ 00087 #define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */ 00088 #define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */ 00089 #define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */ 00090 #define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */ 00091 #define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */ 00092 #define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */ 00093 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */ 00094 #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */ 00095 00096 /** @warning The APR_LARGEFILE flag only has effect on some platforms 00097 * where sizeof(apr_off_t) == 4. Where implemented, it allows opening 00098 * and writing to a file which exceeds the size which can be 00099 * represented by apr_off_t (2 gigabytes). When a file's size does 00100 * exceed 2Gb, apr_file_info_get() will fail with an error on the 00101 * descriptor, likewise apr_stat()/apr_lstat() will fail on the 00102 * filename. apr_dir_read() will fail with APR_INCOMPLETE on a 00103 * directory entry for a large file depending on the particular 00104 * APR_FINFO_* flags. Generally, it is not recommended to use this 00105 * flag. */ 00106 00107 /** @} */ 00108 00109 /** 00110 * @defgroup apr_file_seek_flags File Seek Flags 00111 * @{ 00112 */ 00113 00114 /* flags for apr_file_seek */ 00115 /** Set the file position */ 00116 #define APR_SET SEEK_SET 00117 /** Current */ 00118 #define APR_CUR SEEK_CUR 00119 /** Go to end of file */ 00120 #define APR_END SEEK_END 00121 /** @} */ 00122 00123 /** 00124 * @defgroup apr_file_attrs_set_flags File Attribute Flags 00125 * @{ 00126 */ 00127 00128 /* flags for apr_file_attrs_set */ 00129 #define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */ 00130 #define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */ 00131 #define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */ 00132 /** @} */ 00133 00134 /** 00135 * @defgroup apr_file_writev{_full} max iovec size 00136 * @{ 00137 */ 00138 #if defined(DOXYGEN) 00139 #define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum 00140 size of an iovec array */ 00141 #elif defined(IOV_MAX) 00142 #define APR_MAX_IOVEC_SIZE IOV_MAX 00143 #elif defined(MAX_IOVEC) 00144 #define APR_MAX_IOVEC_SIZE MAX_IOVEC 00145 #else 00146 #define APR_MAX_IOVEC_SIZE 1024 00147 #endif 00148 /** @} */ 00149 00150 /** File attributes */ 00151 typedef apr_uint32_t apr_fileattrs_t; 00152 00153 /** Type to pass as whence argument to apr_file_seek. */ 00154 typedef int apr_seek_where_t; 00155 00156 /** 00157 * Structure for referencing files. 00158 */ 00159 typedef struct apr_file_t apr_file_t; 00160 00161 /* File lock types/flags */ 00162 /** 00163 * @defgroup apr_file_lock_types File Lock Types 00164 * @{ 00165 */ 00166 00167 #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process 00168 or thread can hold a shared lock 00169 at any given time. Essentially, 00170 this is a "read lock", preventing 00171 writers from establishing an 00172 exclusive lock. */ 00173 #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process 00174 may hold an exclusive lock at any 00175 given time. This is analogous to 00176 a "write lock". */ 00177 00178 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */ 00179 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the 00180 file lock */ 00181 /** @} */ 00182 00183 /** 00184 * Open the specified file. 00185 * @param newf The opened file descriptor. 00186 * @param fname The full path to the file (using / on all systems) 00187 * @param flag Or'ed value of: 00188 * <PRE> 00189 * APR_READ open for reading 00190 * APR_WRITE open for writing 00191 * APR_CREATE create the file if not there 00192 * APR_APPEND file ptr is set to end prior to all writes 00193 * APR_TRUNCATE set length to zero if file exists 00194 * APR_BINARY not a text file (This flag is ignored on 00195 * UNIX because it has no meaning) 00196 * APR_BUFFERED buffer the data. Default is non-buffered 00197 * APR_EXCL return error if APR_CREATE and file exists 00198 * APR_DELONCLOSE delete the file after closing. 00199 * APR_XTHREAD Platform dependent tag to open the file 00200 * for use across multiple threads 00201 * APR_SHARELOCK Platform dependent support for higher 00202 * level locked read/write access to support 00203 * writes across process/machines 00204 * APR_FILE_NOCLEANUP Do not register a cleanup with the pool 00205 * passed in on the <EM>pool</EM> argument (see below). 00206 * The apr_os_file_t handle in apr_file_t will not 00207 * be closed when the pool is destroyed. 00208 * APR_SENDFILE_ENABLED Open with appropriate platform semantics 00209 * for sendfile operations. Advisory only, 00210 * apr_socket_sendfile does not check this flag. 00211 * </PRE> 00212 * @param perm Access permissions for file. 00213 * @param pool The pool to use. 00214 * @remark If perm is APR_OS_DEFAULT and the file is being created, 00215 * appropriate default permissions will be used. 00216 */ 00217 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname, 00218 apr_int32_t flag, apr_fileperms_t perm, 00219 apr_pool_t *pool); 00220 00221 /** 00222 * Close the specified file. 00223 * @param file The file descriptor to close. 00224 */ 00225 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file); 00226 00227 /** 00228 * Delete the specified file. 00229 * @param path The full path to the file (using / on all systems) 00230 * @param pool The pool to use. 00231 * @remark If the file is open, it won't be removed until all 00232 * instances are closed. 00233 */ 00234 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool); 00235 00236 /** 00237 * Rename the specified file. 00238 * @param from_path The full path to the original file (using / on all systems) 00239 * @param to_path The full path to the new file (using / on all systems) 00240 * @param pool The pool to use. 00241 * @warning If a file exists at the new location, then it will be 00242 * overwritten. Moving files or directories across devices may not be 00243 * possible. 00244 */ 00245 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 00246 const char *to_path, 00247 apr_pool_t *pool); 00248 00249 /** 00250 * Copy the specified file to another file. 00251 * @param from_path The full path to the original file (using / on all systems) 00252 * @param to_path The full path to the new file (using / on all systems) 00253 * @param perms Access permissions for the new file if it is created. 00254 * In place of the usual or'd combination of file permissions, the 00255 * value APR_FILE_SOURCE_PERMS may be given, in which case the source 00256 * file's permissions are copied. 00257 * @param pool The pool to use. 00258 * @remark The new file does not need to exist, it will be created if required. 00259 * @warning If the new file already exists, its contents will be overwritten. 00260 */ 00261 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 00262 const char *to_path, 00263 apr_fileperms_t perms, 00264 apr_pool_t *pool); 00265 00266 /** 00267 * Append the specified file to another file. 00268 * @param from_path The full path to the source file (use / on all systems) 00269 * @param to_path The full path to the destination file (use / on all systems) 00270 * @param perms Access permissions for the destination file if it is created. 00271 * In place of the usual or'd combination of file permissions, the 00272 * value APR_FILE_SOURCE_PERMS may be given, in which case the source 00273 * file's permissions are copied. 00274 * @param pool The pool to use. 00275 * @remark The new file does not need to exist, it will be created if required. 00276 */ 00277 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 00278 const char *to_path, 00279 apr_fileperms_t perms, 00280 apr_pool_t *pool); 00281 00282 /** 00283 * Are we at the end of the file 00284 * @param fptr The apr file we are testing. 00285 * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise. 00286 */ 00287 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); 00288 00289 /** 00290 * Open standard error as an apr file pointer. 00291 * @param thefile The apr file to use as stderr. 00292 * @param pool The pool to allocate the file out of. 00293 * 00294 * @remark The only reason that the apr_file_open_std* functions exist 00295 * is that you may not always have a stderr/out/in on Windows. This 00296 * is generally a problem with newer versions of Windows and services. 00297 * 00298 * @remark The other problem is that the C library functions generally work 00299 * differently on Windows and Unix. So, by using apr_file_open_std* 00300 * functions, you can get a handle to an APR struct that works with 00301 * the APR functions which are supposed to work identically on all 00302 * platforms. 00303 */ 00304 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, 00305 apr_pool_t *pool); 00306 00307 /** 00308 * open standard output as an apr file pointer. 00309 * @param thefile The apr file to use as stdout. 00310 * @param pool The pool to allocate the file out of. 00311 * 00312 * @remark See remarks for apr_file_open_stdout. 00313 */ 00314 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, 00315 apr_pool_t *pool); 00316 00317 /** 00318 * open standard input as an apr file pointer. 00319 * @param thefile The apr file to use as stdin. 00320 * @param pool The pool to allocate the file out of. 00321 * 00322 * @remark See remarks for apr_file_open_stdout. 00323 */ 00324 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, 00325 apr_pool_t *pool); 00326 00327 /** 00328 * Read data from the specified file. 00329 * @param thefile The file descriptor to read from. 00330 * @param buf The buffer to store the data to. 00331 * @param nbytes On entry, the number of bytes to read; on exit, the number 00332 * of bytes read. 00333 * 00334 * @remark apr_file_read will read up to the specified number of 00335 * bytes, but never more. If there isn't enough data to fill that 00336 * number of bytes, all of the available data is read. The third 00337 * argument is modified to reflect the number of bytes read. If a 00338 * char was put back into the stream via ungetc, it will be the first 00339 * character returned. 00340 * 00341 * @remark It is not possible for both bytes to be read and an APR_EOF 00342 * or other error to be returned. APR_EINTR is never returned. 00343 */ 00344 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, 00345 apr_size_t *nbytes); 00346 00347 /** 00348 * Write data to the specified file. 00349 * @param thefile The file descriptor to write to. 00350 * @param buf The buffer which contains the data. 00351 * @param nbytes On entry, the number of bytes to write; on exit, the number 00352 * of bytes written. 00353 * 00354 * @remark apr_file_write will write up to the specified number of 00355 * bytes, but never more. If the OS cannot write that many bytes, it 00356 * will write as many as it can. The third argument is modified to 00357 * reflect the * number of bytes written. 00358 * 00359 * @remark It is possible for both bytes to be written and an error to 00360 * be returned. APR_EINTR is never returned. 00361 */ 00362 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, 00363 apr_size_t *nbytes); 00364 00365 /** 00366 * Write data from iovec array to the specified file. 00367 * @param thefile The file descriptor to write to. 00368 * @param vec The array from which to get the data to write to the file. 00369 * @param nvec The number of elements in the struct iovec array. This must 00370 * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function 00371 * will fail with APR_EINVAL. 00372 * @param nbytes The number of bytes written. 00373 * 00374 * @remark It is possible for both bytes to be written and an error to 00375 * be returned. APR_EINTR is never returned. 00376 * 00377 * @remark apr_file_writev is available even if the underlying 00378 * operating system doesn't provide writev(). 00379 */ 00380 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, 00381 const struct iovec *vec, 00382 apr_size_t nvec, apr_size_t *nbytes); 00383 00384 /** 00385 * Read data from the specified file, ensuring that the buffer is filled 00386 * before returning. 00387 * @param thefile The file descriptor to read from. 00388 * @param buf The buffer to store the data to. 00389 * @param nbytes The number of bytes to read. 00390 * @param bytes_read If non-NULL, this will contain the number of bytes read. 00391 * 00392 * @remark apr_file_read will read up to the specified number of 00393 * bytes, but never more. If there isn't enough data to fill that 00394 * number of bytes, then the process/thread will block until it is 00395 * available or EOF is reached. If a char was put back into the 00396 * stream via ungetc, it will be the first character returned. 00397 * 00398 * @remark It is possible for both bytes to be read and an error to be 00399 * returned. And if *bytes_read is less than nbytes, an accompanying 00400 * error is _always_ returned. 00401 * 00402 * @remark APR_EINTR is never returned. 00403 */ 00404 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, 00405 apr_size_t nbytes, 00406 apr_size_t *bytes_read); 00407 00408 /** 00409 * Write data to the specified file, ensuring that all of the data is 00410 * written before returning. 00411 * @param thefile The file descriptor to write to. 00412 * @param buf The buffer which contains the data. 00413 * @param nbytes The number of bytes to write. 00414 * @param bytes_written If non-NULL, set to the number of bytes written. 00415 * 00416 * @remark apr_file_write will write up to the specified number of 00417 * bytes, but never more. If the OS cannot write that many bytes, the 00418 * process/thread will block until they can be written. Exceptional 00419 * error such as "out of space" or "pipe closed" will terminate with 00420 * an error. 00421 * 00422 * @remark It is possible for both bytes to be written and an error to 00423 * be returned. And if *bytes_written is less than nbytes, an 00424 * accompanying error is _always_ returned. 00425 * 00426 * @remark APR_EINTR is never returned. 00427 */ 00428 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 00429 const void *buf, 00430 apr_size_t nbytes, 00431 apr_size_t *bytes_written); 00432 00433 00434 /** 00435 * Write data from iovec array to the specified file, ensuring that all of the 00436 * data is written before returning. 00437 * @param thefile The file descriptor to write to. 00438 * @param vec The array from which to get the data to write to the file. 00439 * @param nvec The number of elements in the struct iovec array. This must 00440 * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function 00441 * will fail with APR_EINVAL. 00442 * @param nbytes The number of bytes written. 00443 * 00444 * @remark apr_file_writev_full is available even if the underlying 00445 * operating system doesn't provide writev(). 00446 */ 00447 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile, 00448 const struct iovec *vec, 00449 apr_size_t nvec, 00450 apr_size_t *nbytes); 00451 /** 00452 * Write a character into the specified file. 00453 * @param ch The character to write. 00454 * @param thefile The file descriptor to write to 00455 */ 00456 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile); 00457 00458 /** 00459 * Read a character from the specified file. 00460 * @param ch The character to read into 00461 * @param thefile The file descriptor to read from 00462 */ 00463 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile); 00464 00465 /** 00466 * Put a character back onto a specified stream. 00467 * @param ch The character to write. 00468 * @param thefile The file descriptor to write to 00469 */ 00470 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile); 00471 00472 /** 00473 * Read a string from the specified file. 00474 * @param str The buffer to store the string in. 00475 * @param len The length of the string 00476 * @param thefile The file descriptor to read from 00477 * @remark The buffer will be NUL-terminated if any characters are stored. 00478 */ 00479 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 00480 apr_file_t *thefile); 00481 00482 /** 00483 * Write the string into the specified file. 00484 * @param str The string to write. 00485 * @param thefile The file descriptor to write to 00486 */ 00487 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile); 00488 00489 /** 00490 * Flush the file's buffer. 00491 * @param thefile The file descriptor to flush 00492 */ 00493 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile); 00494 00495 /** 00496 * Duplicate the specified file descriptor. 00497 * @param new_file The structure to duplicate into. 00498 * @param old_file The file to duplicate. 00499 * @param p The pool to use for the new file. 00500 * @remark *new_file must point to a valid apr_file_t, or point to NULL. 00501 */ 00502 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file, 00503 apr_file_t *old_file, 00504 apr_pool_t *p); 00505 00506 /** 00507 * Duplicate the specified file descriptor and close the original 00508 * @param new_file The old file that is to be closed and reused 00509 * @param old_file The file to duplicate 00510 * @param p The pool to use for the new file 00511 * 00512 * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL. 00513 */ 00514 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file, 00515 apr_file_t *old_file, 00516 apr_pool_t *p); 00517 00518 /** 00519 * Move the specified file descriptor to a new pool 00520 * @param new_file Pointer in which to return the new apr_file_t 00521 * @param old_file The file to move 00522 * @param p The pool to which the descriptor is to be moved 00523 * @remark Unlike apr_file_dup2(), this function doesn't do an 00524 * OS dup() operation on the underlying descriptor; it just 00525 * moves the descriptor's apr_file_t wrapper to a new pool. 00526 * @remark The new pool need not be an ancestor of old_file's pool. 00527 * @remark After calling this function, old_file may not be used 00528 */ 00529 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file, 00530 apr_file_t *old_file, 00531 apr_pool_t *p); 00532 00533 /** 00534 * Move the read/write file offset to a specified byte within a file. 00535 * @param thefile The file descriptor 00536 * @param where How to move the pointer, one of: 00537 * <PRE> 00538 * APR_SET -- set the offset to offset 00539 * APR_CUR -- add the offset to the current position 00540 * APR_END -- add the offset to the current file size 00541 * </PRE> 00542 * @param offset The offset to move the pointer to. 00543 * @remark The third argument is modified to be the offset the pointer 00544 was actually moved to. 00545 */ 00546 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00547 apr_seek_where_t where, 00548 apr_off_t *offset); 00549 00550 /** 00551 * Create an anonymous pipe. 00552 * @param in The file descriptor to use as input to the pipe. 00553 * @param out The file descriptor to use as output from the pipe. 00554 * @param pool The pool to operate on. 00555 */ 00556 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00557 apr_file_t **out, 00558 apr_pool_t *pool); 00559 00560 /** 00561 * Create a named pipe. 00562 * @param filename The filename of the named pipe 00563 * @param perm The permissions for the newly created pipe. 00564 * @param pool The pool to operate on. 00565 */ 00566 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 00567 apr_fileperms_t perm, 00568 apr_pool_t *pool); 00569 00570 /** 00571 * Get the timeout value for a pipe or manipulate the blocking state. 00572 * @param thepipe The pipe we are getting a timeout for. 00573 * @param timeout The current timeout value in microseconds. 00574 */ 00575 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 00576 apr_interval_time_t *timeout); 00577 00578 /** 00579 * Set the timeout value for a pipe or manipulate the blocking state. 00580 * @param thepipe The pipe we are setting a timeout on. 00581 * @param timeout The timeout value in microseconds. Values < 0 mean wait 00582 * forever, 0 means do not wait at all. 00583 */ 00584 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 00585 apr_interval_time_t timeout); 00586 00587 /** file (un)locking functions. */ 00588 00589 /** 00590 * Establish a lock on the specified, open file. The lock may be advisory 00591 * or mandatory, at the discretion of the platform. The lock applies to 00592 * the file as a whole, rather than a specific range. Locks are established 00593 * on a per-thread/process basis; a second lock by the same thread will not 00594 * block. 00595 * @param thefile The file to lock. 00596 * @param type The type of lock to establish on the file. 00597 */ 00598 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type); 00599 00600 /** 00601 * Remove any outstanding locks on the file. 00602 * @param thefile The file to unlock. 00603 */ 00604 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile); 00605 00606 /**accessor and general file_io functions. */ 00607 00608 /** 00609 * return the file name of the current file. 00610 * @param new_path The path of the file. 00611 * @param thefile The currently open file. 00612 */ 00613 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 00614 apr_file_t *thefile); 00615 00616 /** 00617 * Return the data associated with the current file. 00618 * @param data The user data associated with the file. 00619 * @param key The key to use for retreiving data associated with this file. 00620 * @param file The currently open file. 00621 */ 00622 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 00623 apr_file_t *file); 00624 00625 /** 00626 * Set the data associated with the current file. 00627 * @param file The currently open file. 00628 * @param data The user data to associate with the file. 00629 * @param key The key to use for assocaiteing data with the file. 00630 * @param cleanup The cleanup routine to use when the file is destroyed. 00631 */ 00632 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data, 00633 const char *key, 00634 apr_status_t (*cleanup)(void *)); 00635 00636 /** 00637 * Write a string to a file using a printf format. 00638 * @param fptr The file to write to. 00639 * @param format The format string 00640 * @param ... The values to substitute in the format string 00641 * @return The number of bytes written 00642 */ 00643 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, 00644 const char *format, ...) 00645 __attribute__((format(printf,2,3))); 00646 00647 /** 00648 * set the specified file's permission bits. 00649 * @param fname The file (name) to apply the permissions to. 00650 * @param perms The permission bits to apply to the file. 00651 * 00652 * @warning Some platforms may not be able to apply all of the 00653 * available permission bits; APR_INCOMPLETE will be returned if some 00654 * permissions are specified which could not be set. 00655 * 00656 * @warning Platforms which do not implement this feature will return 00657 * APR_ENOTIMPL. 00658 */ 00659 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, 00660 apr_fileperms_t perms); 00661 00662 /** 00663 * Set attributes of the specified file. 00664 * @param fname The full path to the file (using / on all systems) 00665 * @param attributes Or'd combination of 00666 * <PRE> 00667 * APR_FILE_ATTR_READONLY - make the file readonly 00668 * APR_FILE_ATTR_EXECUTABLE - make the file executable 00669 * APR_FILE_ATTR_HIDDEN - make the file hidden 00670 * </PRE> 00671 * @param attr_mask Mask of valid bits in attributes. 00672 * @param pool the pool to use. 00673 * @remark This function should be used in preference to explict manipulation 00674 * of the file permissions, because the operations to provide these 00675 * attributes are platform specific and may involve more than simply 00676 * setting permission bits. 00677 * @warning Platforms which do not implement this feature will return 00678 * APR_ENOTIMPL. 00679 */ 00680 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname, 00681 apr_fileattrs_t attributes, 00682 apr_fileattrs_t attr_mask, 00683 apr_pool_t *pool); 00684 00685 /** 00686 * Set the mtime of the specified file. 00687 * @param fname The full path to the file (using / on all systems) 00688 * @param mtime The mtime to apply to the file. 00689 * @param pool The pool to use. 00690 * @warning Platforms which do not implement this feature will return 00691 * APR_ENOTIMPL. 00692 */ 00693 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname, 00694 apr_time_t mtime, 00695 apr_pool_t *pool); 00696 00697 /** 00698 * Create a new directory on the file system. 00699 * @param path the path for the directory to be created. (use / on all systems) 00700 * @param perm Permissions for the new direcoty. 00701 * @param pool the pool to use. 00702 */ 00703 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 00704 apr_pool_t *pool); 00705 00706 /** Creates a new directory on the file system, but behaves like 00707 * 'mkdir -p'. Creates intermediate directories as required. No error 00708 * will be reported if PATH already exists. 00709 * @param path the path for the directory to be created. (use / on all systems) 00710 * @param perm Permissions for the new direcoty. 00711 * @param pool the pool to use. 00712 */ 00713 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path, 00714 apr_fileperms_t perm, 00715 apr_pool_t *pool); 00716 00717 /** 00718 * Remove directory from the file system. 00719 * @param path the path for the directory to be removed. (use / on all systems) 00720 * @param pool the pool to use. 00721 */ 00722 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool); 00723 00724 /** 00725 * get the specified file's stats. 00726 * @param finfo Where to store the information about the file. 00727 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 00728 * @param thefile The file to get information about. 00729 */ 00730 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 00731 apr_int32_t wanted, 00732 apr_file_t *thefile); 00733 00734 00735 /** 00736 * Truncate the file's length to the specified offset 00737 * @param fp The file to truncate 00738 * @param offset The offset to truncate to. 00739 */ 00740 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset); 00741 00742 /** 00743 * Retrieve the flags that were passed into apr_file_open() 00744 * when the file was opened. 00745 * @return apr_int32_t the flags 00746 */ 00747 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f); 00748 00749 /** 00750 * Get the pool used by the file. 00751 */ 00752 APR_POOL_DECLARE_ACCESSOR(file); 00753 00754 /** 00755 * Set a file to be inherited by child processes. 00756 * 00757 */ 00758 APR_DECLARE_INHERIT_SET(file); 00759 00760 /** 00761 * Unset a file from being inherited by child processes. 00762 */ 00763 APR_DECLARE_INHERIT_UNSET(file); 00764 00765 /** 00766 * Open a temporary file 00767 * @param fp The apr file to use as a temporary file. 00768 * @param templ The template to use when creating a temp file. 00769 * @param flags The flags to open the file with. If this is zero, 00770 * the file is opened with 00771 * APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE 00772 * @param p The pool to allocate the file out of. 00773 * @remark 00774 * This function generates a unique temporary file name from template. 00775 * The last six characters of template must be XXXXXX and these are replaced 00776 * with a string that makes the filename unique. Since it will be modified, 00777 * template must not be a string constant, but should be declared as a character 00778 * array. 00779 * 00780 */ 00781 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ, 00782 apr_int32_t flags, apr_pool_t *p); 00783 00784 00785 /** 00786 * Find an existing directory suitable as a temporary storage location. 00787 * @param temp_dir The temp directory. 00788 * @param p The pool to use for any necessary allocations. 00789 * @remark 00790 * This function uses an algorithm to search for a directory that an 00791 * an application can use for temporary storage. Once such a 00792 * directory is found, that location is cached by the library. Thus, 00793 * callers only pay the cost of this algorithm once if that one time 00794 * is successful. 00795 * 00796 */ 00797 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir, 00798 apr_pool_t *p); 00799 00800 /** @} */ 00801 00802 #ifdef __cplusplus 00803 } 00804 #endif 00805 00806 #endif /* ! APR_FILE_IO_H */