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