Apache Portable Runtime
|
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 (This flag is ignored on UNIX 00062 because it has no meaning)*/ 00063 #define APR_FOPEN_EXCL 0x00040 /**< Open should fail if #APR_FOPEN_CREATE 00064 and file exists. */ 00065 #define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */ 00066 #define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */ 00067 #define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open 00068 the file for use across multiple 00069 threads */ 00070 #define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for 00071 higher level locked read/write 00072 access to support writes across 00073 process/machines */ 00074 #define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup 00075 when the file is opened. The 00076 apr_os_file_t handle in apr_file_t 00077 will not be closed when the pool 00078 is destroyed. */ 00079 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this 00080 file should support 00081 apr_socket_sendfile operation */ 00082 #define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable 00083 * large file support, see WARNING below 00084 */ 00085 #define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable 00086 * sparse file support, see WARNING below 00087 */ 00088 #define APR_FOPEN_NONBLOCK 0x40000 /**< Platform dependent flag to enable 00089 * non blocking file io */ 00090 00091 00092 /* backcompat */ 00093 #define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */ 00094 #define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */ 00095 #define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */ 00096 #define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */ 00097 #define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */ 00098 #define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */ 00099 #define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */ 00100 #define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */ 00101 #define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */ 00102 #define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */ 00103 #define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */ 00104 #define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */ 00105 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */ 00106 #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */ 00107 00108 /** @def APR_FOPEN_LARGEFILE 00109 * @warning APR_FOPEN_LARGEFILE flag only has effect on some 00110 * platforms where sizeof(apr_off_t) == 4. Where implemented, it 00111 * allows opening and writing to a file which exceeds the size which 00112 * can be represented by apr_off_t (2 gigabytes). When a file's size 00113 * does exceed 2Gb, apr_file_info_get() will fail with an error on the 00114 * descriptor, likewise apr_stat()/apr_lstat() will fail on the 00115 * filename. apr_dir_read() will fail with #APR_INCOMPLETE on a 00116 * directory entry for a large file depending on the particular 00117 * APR_FINFO_* flags. Generally, it is not recommended to use this 00118 * flag. 00119 * 00120 * @def APR_FOPEN_SPARSE 00121 * @warning APR_FOPEN_SPARSE may, depending on platform, convert a 00122 * normal file to a sparse file. Some applications may be unable 00123 * to decipher a sparse file, so it's critical that the sparse file 00124 * flag should only be used for files accessed only by APR or other 00125 * applications known to be able to decipher them. APR does not 00126 * guarantee that it will compress the file into sparse segments 00127 * if it was previously created and written without the sparse flag. 00128 * On platforms which do not understand, or on file systems which 00129 * cannot handle sparse files, the flag is ignored by apr_file_open(). 00130 * 00131 * @def APR_FOPEN_NONBLOCK 00132 * @warning APR_FOPEN_NONBLOCK is not implemented on all platforms. 00133 * Callers should be prepared for it to fail with #APR_ENOTIMPL. 00134 */ 00135 00136 /** @} */ 00137 00138 /** 00139 * @defgroup apr_file_seek_flags File Seek Flags 00140 * @{ 00141 */ 00142 00143 /* flags for apr_file_seek */ 00144 /** Set the file position */ 00145 #define APR_SET SEEK_SET 00146 /** Current */ 00147 #define APR_CUR SEEK_CUR 00148 /** Go to end of file */ 00149 #define APR_END SEEK_END 00150 /** @} */ 00151 00152 /** 00153 * @defgroup apr_file_attrs_set_flags File Attribute Flags 00154 * @{ 00155 */ 00156 00157 /* flags for apr_file_attrs_set */ 00158 #define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */ 00159 #define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */ 00160 #define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */ 00161 /** @} */ 00162 00163 /** 00164 * @defgroup apr_file_writev{_full} max iovec size 00165 * @{ 00166 */ 00167 #if defined(DOXYGEN) 00168 #define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum 00169 size of an iovec array */ 00170 #elif defined(IOV_MAX) 00171 #define APR_MAX_IOVEC_SIZE IOV_MAX 00172 #elif defined(MAX_IOVEC) 00173 #define APR_MAX_IOVEC_SIZE MAX_IOVEC 00174 #else 00175 #define APR_MAX_IOVEC_SIZE 1024 00176 #endif 00177 /** @} */ 00178 00179 /** File attributes */ 00180 typedef apr_uint32_t apr_fileattrs_t; 00181 00182 /** Type to pass as whence argument to apr_file_seek. */ 00183 typedef int apr_seek_where_t; 00184 00185 /** 00186 * Structure for referencing files. 00187 */ 00188 typedef struct apr_file_t apr_file_t; 00189 00190 /* File lock types/flags */ 00191 /** 00192 * @defgroup apr_file_lock_types File Lock Types 00193 * @{ 00194 */ 00195 00196 #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process 00197 or thread can hold a shared lock 00198 at any given time. Essentially, 00199 this is a "read lock", preventing 00200 writers from establishing an 00201 exclusive lock. */ 00202 #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process 00203 may hold an exclusive lock at any 00204 given time. This is analogous to 00205 a "write lock". */ 00206 00207 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */ 00208 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the 00209 file lock */ 00210 /** @} */ 00211 00212 /** 00213 * Open the specified file. 00214 * @param newf The opened file descriptor. 00215 * @param fname The full path to the file (using / on all systems) 00216 * @param flag Or'ed value of: 00217 * @li #APR_FOPEN_READ open for reading 00218 * @li #APR_FOPEN_WRITE open for writing 00219 * @li #APR_FOPEN_CREATE create the file if not there 00220 * @li #APR_FOPEN_APPEND file ptr is set to end prior to all writes 00221 * @li #APR_FOPEN_TRUNCATE set length to zero if file exists 00222 * @li #APR_FOPEN_BINARY not a text file 00223 * @li #APR_FOPEN_BUFFERED buffer the data. Default is non-buffered 00224 * @li #APR_FOPEN_EXCL return error if #APR_FOPEN_CREATE and file exists 00225 * @li #APR_FOPEN_DELONCLOSE delete the file after closing 00226 * @li #APR_FOPEN_XTHREAD Platform dependent tag to open the file 00227 * for use across multiple threads 00228 * @li #APR_FOPEN_SHARELOCK Platform dependent support for higher 00229 * level locked read/write access to support 00230 * writes across process/machines 00231 * @li #APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool 00232 * passed in on the @a pool argument (see below) 00233 * @li #APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics 00234 * for sendfile operations. Advisory only, 00235 * apr_socket_sendfile does not check this flag 00236 * @li #APR_FOPEN_LARGEFILE Platform dependent flag to enable large file 00237 * support, see WARNING below 00238 * @li #APR_FOPEN_SPARSE Platform dependent flag to enable sparse file 00239 * support, see WARNING below 00240 * @li #APR_FOPEN_NONBLOCK Platform dependent flag to enable 00241 * non blocking file io 00242 * @param perm Access permissions for file. 00243 * @param pool The pool to use. 00244 * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created, 00245 * appropriate default permissions will be used. 00246 * @remark By default, the returned file descriptor will not be 00247 * inherited by child processes created by apr_proc_create(). This 00248 * can be changed using apr_file_inherit_set(). 00249 */ 00250 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname, 00251 apr_int32_t flag, apr_fileperms_t perm, 00252 apr_pool_t *pool); 00253 00254 /** 00255 * Close the specified file. 00256 * @param file The file descriptor to close. 00257 */ 00258 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file); 00259 00260 /** 00261 * Delete the specified file. 00262 * @param path The full path to the file (using / on all systems) 00263 * @param pool The pool to use. 00264 * @remark If the file is open, it won't be removed until all 00265 * instances are closed. 00266 */ 00267 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool); 00268 00269 /** 00270 * Rename the specified file. 00271 * @param from_path The full path to the original file (using / on all systems) 00272 * @param to_path The full path to the new file (using / on all systems) 00273 * @param pool The pool to use. 00274 * @warning If a file exists at the new location, then it will be 00275 * overwritten. Moving files or directories across devices may not be 00276 * possible. 00277 */ 00278 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 00279 const char *to_path, 00280 apr_pool_t *pool); 00281 00282 /** 00283 * Create a hard link to the specified file. 00284 * @param from_path The full path to the original file (using / on all systems) 00285 * @param to_path The full path to the new file (using / on all systems) 00286 * @remark Both files must reside on the same device. 00287 */ 00288 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path, 00289 const char *to_path); 00290 00291 /** 00292 * Copy the specified file to another file. 00293 * @param from_path The full path to the original file (using / on all systems) 00294 * @param to_path The full path to the new file (using / on all systems) 00295 * @param perms Access permissions for the new file if it is created. 00296 * In place of the usual or'd combination of file permissions, the 00297 * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source 00298 * file's permissions are copied. 00299 * @param pool The pool to use. 00300 * @remark The new file does not need to exist, it will be created if required. 00301 * @warning If the new file already exists, its contents will be overwritten. 00302 */ 00303 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 00304 const char *to_path, 00305 apr_fileperms_t perms, 00306 apr_pool_t *pool); 00307 00308 /** 00309 * Append the specified file to another file. 00310 * @param from_path The full path to the source file (use / on all systems) 00311 * @param to_path The full path to the destination file (use / on all systems) 00312 * @param perms Access permissions for the destination file if it is created. 00313 * In place of the usual or'd combination of file permissions, the 00314 * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source 00315 * file's permissions are copied. 00316 * @param pool The pool to use. 00317 * @remark The new file does not need to exist, it will be created if required. 00318 * @remark Note that advanced filesystem permissions such as ACLs are not 00319 * duplicated by this API. The target permissions (including duplicating the 00320 * source file permissions) are assigned only when the target file does not yet 00321 * exist. 00322 */ 00323 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 00324 const char *to_path, 00325 apr_fileperms_t perms, 00326 apr_pool_t *pool); 00327 00328 /** 00329 * Are we at the end of the file 00330 * @param fptr The apr file we are testing. 00331 * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise. 00332 */ 00333 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); 00334 00335 /** 00336 * Open standard error as an apr file pointer. 00337 * @param thefile The apr file to use as stderr. 00338 * @param pool The pool to allocate the file out of. 00339 * 00340 * @remark The only reason that the apr_file_open_std* functions exist 00341 * is that you may not always have a stderr/out/in on Windows. This 00342 * is generally a problem with newer versions of Windows and services. 00343 * 00344 * @remark The other problem is that the C library functions generally work 00345 * differently on Windows and Unix. So, by using apr_file_open_std* 00346 * functions, you can get a handle to an APR struct that works with 00347 * the APR functions which are supposed to work identically on all 00348 * platforms. 00349 */ 00350 APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, 00351 apr_pool_t *pool); 00352 00353 /** 00354 * open standard output as an apr file pointer. 00355 * @param thefile The apr file to use as stdout. 00356 * @param pool The pool to allocate the file out of. 00357 * 00358 * @remark See remarks for apr_file_open_stderr(). 00359 */ 00360 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, 00361 apr_pool_t *pool); 00362 00363 /** 00364 * open standard input as an apr file pointer. 00365 * @param thefile The apr file to use as stdin. 00366 * @param pool The pool to allocate the file out of. 00367 * 00368 * @remark See remarks for apr_file_open_stderr(). 00369 */ 00370 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, 00371 apr_pool_t *pool); 00372 00373 /** 00374 * open standard error as an apr file pointer, with flags. 00375 * @param thefile The apr file to use as stderr. 00376 * @param flags The flags to open the file with. Only the 00377 * @li #APR_FOPEN_EXCL 00378 * @li #APR_FOPEN_BUFFERED 00379 * @li #APR_FOPEN_XTHREAD 00380 * @li #APR_FOPEN_SHARELOCK 00381 * @li #APR_FOPEN_SENDFILE_ENABLED 00382 * @li #APR_FOPEN_LARGEFILE 00383 * 00384 * flags should be used. The #APR_FOPEN_WRITE flag will 00385 * be set unconditionally. 00386 * @param pool The pool to allocate the file out of. 00387 * 00388 * @remark See remarks for apr_file_open_stderr(). 00389 */ 00390 APR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile, 00391 apr_int32_t flags, 00392 apr_pool_t *pool); 00393 00394 /** 00395 * open standard output as an apr file pointer, with flags. 00396 * @param thefile The apr file to use as stdout. 00397 * @param flags The flags to open the file with. Only the 00398 * @li #APR_FOPEN_EXCL 00399 * @li #APR_FOPEN_BUFFERED 00400 * @li #APR_FOPEN_XTHREAD 00401 * @li #APR_FOPEN_SHARELOCK 00402 * @li #APR_FOPEN_SENDFILE_ENABLED 00403 * @li #APR_FOPEN_LARGEFILE 00404 * 00405 * flags should be used. The #APR_FOPEN_WRITE flag will 00406 * be set unconditionally. 00407 * @param pool The pool to allocate the file out of. 00408 * 00409 * @remark See remarks for apr_file_open_stderr(). 00410 */ 00411 APR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile, 00412 apr_int32_t flags, 00413 apr_pool_t *pool); 00414 00415 /** 00416 * open standard input as an apr file pointer, with flags. 00417 * @param thefile The apr file to use as stdin. 00418 * @param flags The flags to open the file with. Only the 00419 * @li #APR_FOPEN_EXCL 00420 * @li #APR_FOPEN_BUFFERED 00421 * @li #APR_FOPEN_XTHREAD 00422 * @li #APR_FOPEN_SHARELOCK 00423 * @li #APR_FOPEN_SENDFILE_ENABLED 00424 * @li #APR_FOPEN_LARGEFILE 00425 * 00426 * flags should be used. The #APR_FOPEN_WRITE flag will 00427 * be set unconditionally. 00428 * @param pool The pool to allocate the file out of. 00429 * 00430 * @remark See remarks for apr_file_open_stderr(). 00431 */ 00432 APR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile, 00433 apr_int32_t flags, 00434 apr_pool_t *pool); 00435 00436 /** 00437 * Read data from the specified file. 00438 * @param thefile The file descriptor to read from. 00439 * @param buf The buffer to store the data to. 00440 * @param nbytes On entry, the number of bytes to read; on exit, the number 00441 * of bytes read. 00442 * 00443 * @remark apr_file_read() will read up to the specified number of 00444 * bytes, but never more. If there isn't enough data to fill that 00445 * number of bytes, all of the available data is read. The third 00446 * argument is modified to reflect the number of bytes read. If a 00447 * char was put back into the stream via ungetc, it will be the first 00448 * character returned. 00449 * 00450 * @remark It is not possible for both bytes to be read and an #APR_EOF 00451 * or other error to be returned. #APR_EINTR is never returned. 00452 */ 00453 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, 00454 apr_size_t *nbytes); 00455 00456 /** 00457 * Write data to the specified file. 00458 * @param thefile The file descriptor to write to. 00459 * @param buf The buffer which contains the data. 00460 * @param nbytes On entry, the number of bytes to write; on exit, the number 00461 * of bytes written. 00462 * 00463 * @remark apr_file_write() will write up to the specified number of 00464 * bytes, but never more. If the OS cannot write that many bytes, it 00465 * will write as many as it can. The third argument is modified to 00466 * reflect the * number of bytes written. 00467 * 00468 * @remark It is possible for both bytes to be written and an error to 00469 * be returned. #APR_EINTR is never returned. 00470 */ 00471 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, 00472 apr_size_t *nbytes); 00473 00474 /** 00475 * Write data from iovec array to the specified file. 00476 * @param thefile The file descriptor to write to. 00477 * @param vec The array from which to get the data to write to the file. 00478 * @param nvec The number of elements in the struct iovec array. This must 00479 * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function 00480 * will fail with #APR_EINVAL. 00481 * @param nbytes The number of bytes written. 00482 * 00483 * @remark It is possible for both bytes to be written and an error to 00484 * be returned. #APR_EINTR is never returned. 00485 * 00486 * @remark apr_file_writev() is available even if the underlying 00487 * operating system doesn't provide writev(). 00488 */ 00489 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, 00490 const struct iovec *vec, 00491 apr_size_t nvec, apr_size_t *nbytes); 00492 00493 /** 00494 * Read data from the specified file, ensuring that the buffer is filled 00495 * before returning. 00496 * @param thefile The file descriptor to read from. 00497 * @param buf The buffer to store the data to. 00498 * @param nbytes The number of bytes to read. 00499 * @param bytes_read If non-NULL, this will contain the number of bytes read. 00500 * 00501 * @remark apr_file_read_full() will read up to the specified number of 00502 * bytes, but never more. If there isn't enough data to fill that 00503 * number of bytes, then the process/thread will block until it is 00504 * available or EOF is reached. If a char was put back into the 00505 * stream via ungetc, it will be the first character returned. 00506 * 00507 * @remark It is possible for both bytes to be read and an error to be 00508 * returned. And if *bytes_read is less than nbytes, an accompanying 00509 * error is _always_ returned. 00510 * 00511 * @remark #APR_EINTR is never returned. 00512 */ 00513 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, 00514 apr_size_t nbytes, 00515 apr_size_t *bytes_read); 00516 00517 /** 00518 * Write data to the specified file, ensuring that all of the data is 00519 * written before returning. 00520 * @param thefile The file descriptor to write to. 00521 * @param buf The buffer which contains the data. 00522 * @param nbytes The number of bytes to write. 00523 * @param bytes_written If non-NULL, set to the number of bytes written. 00524 * 00525 * @remark apr_file_write_full() will write up to the specified number of 00526 * bytes, but never more. If the OS cannot write that many bytes, the 00527 * process/thread will block until they can be written. Exceptional 00528 * error such as "out of space" or "pipe closed" will terminate with 00529 * an error. 00530 * 00531 * @remark It is possible for both bytes to be written and an error to 00532 * be returned. And if *bytes_written is less than nbytes, an 00533 * accompanying error is _always_ returned. 00534 * 00535 * @remark #APR_EINTR is never returned. 00536 */ 00537 APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 00538 const void *buf, 00539 apr_size_t nbytes, 00540 apr_size_t *bytes_written); 00541 00542 00543 /** 00544 * Write data from iovec array to the specified file, ensuring that all of the 00545 * data is written before returning. 00546 * @param thefile The file descriptor to write to. 00547 * @param vec The array from which to get the data to write to the file. 00548 * @param nvec The number of elements in the struct iovec array. This must 00549 * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function 00550 * will fail with #APR_EINVAL. 00551 * @param nbytes The number of bytes written. 00552 * 00553 * @remark apr_file_writev_full() is available even if the underlying 00554 * operating system doesn't provide writev(). 00555 */ 00556 APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile, 00557 const struct iovec *vec, 00558 apr_size_t nvec, 00559 apr_size_t *nbytes); 00560 /** 00561 * Write a character into the specified file. 00562 * @param ch The character to write. 00563 * @param thefile The file descriptor to write to 00564 */ 00565 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile); 00566 00567 /** 00568 * Read a character from the specified file. 00569 * @param ch The character to read into 00570 * @param thefile The file descriptor to read from 00571 */ 00572 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile); 00573 00574 /** 00575 * Put a character back onto a specified stream. 00576 * @param ch The character to write. 00577 * @param thefile The file descriptor to write to 00578 */ 00579 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile); 00580 00581 /** 00582 * Read a line from the specified file 00583 * @param str The buffer to store the string in. 00584 * @param len The length of the string 00585 * @param thefile The file descriptor to read from 00586 * @remark The buffer will be NUL-terminated if any characters are stored. 00587 * The newline at the end of the line will not be stripped. 00588 */ 00589 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 00590 apr_file_t *thefile); 00591 00592 /** 00593 * Write the string into the specified file. 00594 * @param str The string to write. 00595 * @param thefile The file descriptor to write to 00596 */ 00597 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile); 00598 00599 /** 00600 * Flush the file's buffer. 00601 * @param thefile The file descriptor to flush 00602 */ 00603 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile); 00604 00605 /** 00606 * Transfer all file modified data and metadata to disk. 00607 * @param thefile The file descriptor to sync 00608 */ 00609 APR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile); 00610 00611 /** 00612 * Transfer all file modified data to disk. 00613 * @param thefile The file descriptor to sync 00614 */ 00615 APR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile); 00616 00617 /** 00618 * Duplicate the specified file descriptor. 00619 * @param new_file The structure to duplicate into. 00620 * @param old_file The file to duplicate. 00621 * @param p The pool to use for the new file. 00622 * @remark *new_file must point to a valid apr_file_t, or point to NULL. 00623 */ 00624 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file, 00625 apr_file_t *old_file, 00626 apr_pool_t *p); 00627 00628 /** 00629 * Duplicate the specified file descriptor and close the original 00630 * @param new_file The old file that is to be closed and reused 00631 * @param old_file The file to duplicate 00632 * @param p The pool to use for the new file 00633 * 00634 * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL. 00635 */ 00636 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file, 00637 apr_file_t *old_file, 00638 apr_pool_t *p); 00639 00640 /** 00641 * Move the specified file descriptor to a new pool 00642 * @param new_file Pointer in which to return the new apr_file_t 00643 * @param old_file The file to move 00644 * @param p The pool to which the descriptor is to be moved 00645 * @remark Unlike apr_file_dup2(), this function doesn't do an 00646 * OS dup() operation on the underlying descriptor; it just 00647 * moves the descriptor's apr_file_t wrapper to a new pool. 00648 * @remark The new pool need not be an ancestor of old_file's pool. 00649 * @remark After calling this function, old_file may not be used 00650 */ 00651 APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file, 00652 apr_file_t *old_file, 00653 apr_pool_t *p); 00654 00655 /** 00656 * Give the specified apr file handle a new buffer 00657 * @param thefile The file handle that is to be modified 00658 * @param buffer The buffer 00659 * @param bufsize The size of the buffer 00660 * @remark It is possible to add a buffer to previously unbuffered 00661 * file handles, the #APR_FOPEN_BUFFERED flag will be added to 00662 * the file handle's flags. Likewise, with buffer=NULL and 00663 * bufsize=0 arguments it is possible to make a previously 00664 * buffered file handle unbuffered. 00665 */ 00666 APR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 00667 char * buffer, 00668 apr_size_t bufsize); 00669 00670 /** 00671 * Get the size of any buffer for the specified apr file handle 00672 * @param thefile The file handle 00673 */ 00674 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 00675 00676 /** 00677 * Move the read/write file offset to a specified byte within a file. 00678 * @param thefile The file descriptor 00679 * @param where How to move the pointer, one of: 00680 * @li #APR_SET -- set the offset to offset 00681 * @li #APR_CUR -- add the offset to the current position 00682 * @li #APR_END -- add the offset to the current file size 00683 * @param offset The offset to move the pointer to. 00684 * @remark The third argument is modified to be the offset the pointer 00685 was actually moved to. 00686 */ 00687 APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 00688 apr_seek_where_t where, 00689 apr_off_t *offset); 00690 00691 /** 00692 * Create an anonymous pipe. 00693 * @param in The newly created pipe's file for reading. 00694 * @param out The newly created pipe's file for writing. 00695 * @param pool The pool to operate on. 00696 * @remark By default, the returned file descriptors will be inherited 00697 * by child processes created using apr_proc_create(). This can be 00698 * changed using apr_file_inherit_unset(). 00699 * @bug Some platforms cannot toggle between blocking and nonblocking, 00700 * and when passing a pipe as a standard handle to an application which 00701 * does not expect it, a non-blocking stream will fluxor the client app. 00702 * @deprecated @see apr_file_pipe_create_pools() 00703 */ 00704 APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 00705 apr_file_t **out, 00706 apr_pool_t *pool); 00707 00708 /** 00709 * Create an anonymous pipe which portably supports async timeout options. 00710 * @param in The newly created pipe's file for reading. 00711 * @param out The newly created pipe's file for writing. 00712 * @param blocking one of these values defined in apr_thread_proc.h; 00713 * @li #APR_FULL_BLOCK 00714 * @li #APR_READ_BLOCK 00715 * @li #APR_WRITE_BLOCK 00716 * @li #APR_FULL_NONBLOCK 00717 * @param pool The pool to operate on. 00718 * @remark By default, the returned file descriptors will be inherited 00719 * by child processes created using apr_proc_create(). This can be 00720 * changed using apr_file_inherit_unset(). 00721 * @remark Some platforms cannot toggle between blocking and nonblocking, 00722 * and when passing a pipe as a standard handle to an application which 00723 * does not expect it, a non-blocking stream will fluxor the client app. 00724 * Use this function rather than apr_file_pipe_create() to create pipes 00725 * where one or both ends require non-blocking semantics. 00726 * @deprecated @see apr_file_pipe_create_pools() 00727 */ 00728 APR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in, 00729 apr_file_t **out, 00730 apr_int32_t blocking, 00731 apr_pool_t *pool); 00732 00733 /** 00734 * Create an anonymous pipe which portably supports async timeout options, 00735 * placing each side of the pipe in a different pool. 00736 * @param in The newly created pipe's file for reading. 00737 * @param out The newly created pipe's file for writing. 00738 * @param blocking one of these values defined in apr_thread_proc.h; 00739 * @li #APR_FULL_BLOCK 00740 * @li #APR_READ_BLOCK 00741 * @li #APR_WRITE_BLOCK 00742 * @li #APR_FULL_NONBLOCK 00743 * @param pool_in The pool for the reading pipe. 00744 * @param pool_out The pool for the writing pipe. 00745 * @remark By default, the returned file descriptors will be inherited 00746 * by child processes created using apr_proc_create(). This can be 00747 * changed using apr_file_inherit_unset(). 00748 * @remark Some platforms cannot toggle between blocking and nonblocking, 00749 * and when passing a pipe as a standard handle to an application which 00750 * does not expect it, a non-blocking stream will fluxor the client app. 00751 * Use this function rather than apr_file_pipe_create() to create pipes 00752 * where one or both ends require non-blocking semantics. 00753 */ 00754 APR_DECLARE(apr_status_t) apr_file_pipe_create_pools(apr_file_t **in, 00755 apr_file_t **out, 00756 apr_int32_t blocking, 00757 apr_pool_t *pool_in, 00758 apr_pool_t *pool_out); 00759 00760 /** 00761 * Create a named pipe. 00762 * @param filename The filename of the named pipe 00763 * @param perm The permissions for the newly created pipe. 00764 * @param pool The pool to operate on. 00765 */ 00766 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 00767 apr_fileperms_t perm, 00768 apr_pool_t *pool); 00769 00770 /** 00771 * Get the timeout value for a pipe or manipulate the blocking state. 00772 * @param thepipe The pipe we are getting a timeout for. 00773 * @param timeout The current timeout value in microseconds. 00774 */ 00775 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 00776 apr_interval_time_t *timeout); 00777 00778 /** 00779 * Set the timeout value for a pipe or manipulate the blocking state. 00780 * @param thepipe The pipe we are setting a timeout on. 00781 * @param timeout The timeout value in microseconds. Values < 0 mean wait 00782 * forever, 0 means do not wait at all. 00783 */ 00784 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 00785 apr_interval_time_t timeout); 00786 00787 /** file (un)locking functions. */ 00788 00789 /** 00790 * Establish a lock on the specified, open file. The lock may be advisory 00791 * or mandatory, at the discretion of the platform. The lock applies to 00792 * the file as a whole, rather than a specific range. Locks are established 00793 * on a per-thread/process basis; a second lock by the same thread will not 00794 * block. 00795 * @param thefile The file to lock. 00796 * @param type The type of lock to establish on the file. 00797 */ 00798 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type); 00799 00800 /** 00801 * Remove any outstanding locks on the file. 00802 * @param thefile The file to unlock. 00803 */ 00804 APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile); 00805 00806 /**accessor and general file_io functions. */ 00807 00808 /** 00809 * return the file name of the current file. 00810 * @param new_path The path of the file. 00811 * @param thefile The currently open file. 00812 */ 00813 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 00814 apr_file_t *thefile); 00815 00816 /** 00817 * Return the data associated with the current file. 00818 * @param data The user data associated with the file. 00819 * @param key The key to use for retrieving data associated with this file. 00820 * @param file The currently open file. 00821 */ 00822 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 00823 apr_file_t *file); 00824 00825 /** 00826 * Set the data associated with the current file. 00827 * @param file The currently open file. 00828 * @param data The user data to associate with the file. 00829 * @param key The key to use for associating data with the file. 00830 * @param cleanup The cleanup routine to use when the file is destroyed. 00831 */ 00832 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data, 00833 const char *key, 00834 apr_status_t (*cleanup)(void *)); 00835 00836 /** 00837 * Write a string to a file using a printf format. 00838 * @param fptr The file to write to. 00839 * @param format The format string 00840 * @param ... The values to substitute in the format string 00841 * @return The number of bytes written 00842 */ 00843 APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, 00844 const char *format, ...) 00845 __attribute__((format(printf,2,3))); 00846 00847 /** 00848 * set the specified file's permission bits. 00849 * @param fname The file (name) to apply the permissions to. 00850 * @param perms The permission bits to apply to the file. 00851 * 00852 * @warning Some platforms may not be able to apply all of the 00853 * available permission bits; #APR_INCOMPLETE will be returned if some 00854 * permissions are specified which could not be set. 00855 * 00856 * @warning Platforms which do not implement this feature will return 00857 * #APR_ENOTIMPL. 00858 */ 00859 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, 00860 apr_fileperms_t perms); 00861 00862 /** 00863 * Set attributes of the specified file. 00864 * @param fname The full path to the file (using / on all systems) 00865 * @param attributes Or'd combination of 00866 * @li #APR_FILE_ATTR_READONLY - make the file readonly 00867 * @li #APR_FILE_ATTR_EXECUTABLE - make the file executable 00868 * @li #APR_FILE_ATTR_HIDDEN - make the file hidden 00869 * @param attr_mask Mask of valid bits in attributes. 00870 * @param pool the pool to use. 00871 * @remark This function should be used in preference to explicit manipulation 00872 * of the file permissions, because the operations to provide these 00873 * attributes are platform specific and may involve more than simply 00874 * setting permission bits. 00875 * @warning Platforms which do not implement this feature will return 00876 * #APR_ENOTIMPL. 00877 */ 00878 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname, 00879 apr_fileattrs_t attributes, 00880 apr_fileattrs_t attr_mask, 00881 apr_pool_t *pool); 00882 00883 /** 00884 * Set the mtime of the specified file. 00885 * @param fname The full path to the file (using / on all systems) 00886 * @param mtime The mtime to apply to the file. 00887 * @param pool The pool to use. 00888 * @warning Platforms which do not implement this feature will return 00889 * #APR_ENOTIMPL. 00890 */ 00891 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname, 00892 apr_time_t mtime, 00893 apr_pool_t *pool); 00894 00895 /** 00896 * Create a new directory on the file system. 00897 * @param path the path for the directory to be created. (use / on all systems) 00898 * @param perm Permissions for the new directory. 00899 * @param pool the pool to use. 00900 */ 00901 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 00902 apr_pool_t *pool); 00903 00904 /** Creates a new directory on the file system, but behaves like 00905 * 'mkdir -p'. Creates intermediate directories as required. No error 00906 * will be reported if PATH already exists. 00907 * @param path the path for the directory to be created. (use / on all systems) 00908 * @param perm Permissions for the new directory. 00909 * @param pool the pool to use. 00910 */ 00911 APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path, 00912 apr_fileperms_t perm, 00913 apr_pool_t *pool); 00914 00915 /** 00916 * Remove directory from the file system. 00917 * @param path the path for the directory to be removed. (use / on all systems) 00918 * @param pool the pool to use. 00919 * @remark Removing a directory which is in-use (e.g., the current working 00920 * directory, or during apr_dir_read, or with an open file) is not portable. 00921 */ 00922 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool); 00923 00924 /** 00925 * get the specified file's stats. 00926 * @param finfo Where to store the information about the file. 00927 * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values 00928 * @param thefile The file to get information about. 00929 */ 00930 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 00931 apr_int32_t wanted, 00932 apr_file_t *thefile); 00933 00934 00935 /** 00936 * Truncate the file's length to the specified offset 00937 * @param fp The file to truncate 00938 * @param offset The offset to truncate to. 00939 * @remark The read/write file offset is repositioned to offset. 00940 */ 00941 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset); 00942 00943 /** 00944 * Retrieve the flags that were passed into apr_file_open() 00945 * when the file was opened. 00946 * @return apr_int32_t the flags 00947 */ 00948 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f); 00949 00950 /** 00951 * Get the pool used by the file. 00952 */ 00953 APR_POOL_DECLARE_ACCESSOR(file); 00954 00955 /** 00956 * Set a file to be inherited by child processes. 00957 * 00958 */ 00959 APR_DECLARE_INHERIT_SET(file); 00960 00961 /** 00962 * Unset a file from being inherited by child processes. 00963 */ 00964 APR_DECLARE_INHERIT_UNSET(file); 00965 00966 /** 00967 * Open a temporary file 00968 * @param fp The apr file to use as a temporary file. 00969 * @param templ The template to use when creating a temp file. 00970 * @param flags The flags to open the file with. If this is zero, 00971 * the file is opened with 00972 * #APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE | 00973 * #APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE 00974 * @param p The pool to allocate the file out of. 00975 * @remark 00976 * This function generates a unique temporary file name from template. 00977 * The last six characters of template must be XXXXXX and these are replaced 00978 * with a string that makes the filename unique. Since it will be modified, 00979 * template must not be a string constant, but should be declared as a character 00980 * array. 00981 * 00982 */ 00983 APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ, 00984 apr_int32_t flags, apr_pool_t *p); 00985 00986 00987 /** 00988 * Find an existing directory suitable as a temporary storage location. 00989 * @param temp_dir The temp directory. 00990 * @param p The pool to use for any necessary allocations. 00991 * @remark 00992 * This function uses an algorithm to search for a directory that an 00993 * an application can use for temporary storage. 00994 * 00995 */ 00996 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir, 00997 apr_pool_t *p); 00998 00999 /** @} */ 01000 01001 #ifdef __cplusplus 01002 } 01003 #endif 01004 01005 #endif /* ! APR_FILE_IO_H */