1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_FILE_IO_H 18251875Speter#define APR_FILE_IO_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_file_io.h 22251875Speter * @brief APR File I/O Handling 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_pools.h" 27251875Speter#include "apr_time.h" 28251875Speter#include "apr_errno.h" 29251875Speter#include "apr_file_info.h" 30251875Speter#include "apr_inherit.h" 31251875Speter 32251875Speter#define APR_WANT_STDIO /**< for SEEK_* */ 33251875Speter#define APR_WANT_IOVEC /**< for apr_file_writev */ 34251875Speter#include "apr_want.h" 35251875Speter 36251875Speter#ifdef __cplusplus 37251875Speterextern "C" { 38251875Speter#endif /* __cplusplus */ 39251875Speter 40251875Speter/** 41251875Speter * @defgroup apr_file_io File I/O Handling Functions 42251875Speter * @ingroup APR 43251875Speter * @{ 44251875Speter */ 45251875Speter 46251875Speter/** 47251875Speter * @defgroup apr_file_open_flags File Open Flags/Routines 48251875Speter * @{ 49251875Speter */ 50251875Speter 51251875Speter/* Note to implementors: Values in the range 0x00100000--0x80000000 52251875Speter are reserved for platform-specific values. */ 53251875Speter 54251875Speter#define APR_FOPEN_READ 0x00001 /**< Open the file for reading */ 55251875Speter#define APR_FOPEN_WRITE 0x00002 /**< Open the file for writing */ 56251875Speter#define APR_FOPEN_CREATE 0x00004 /**< Create the file if not there */ 57251875Speter#define APR_FOPEN_APPEND 0x00008 /**< Append to the end of the file */ 58251875Speter#define APR_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate 59251875Speter to 0 length */ 60266735Speter#define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode 61266735Speter (This flag is ignored on UNIX 62266735Speter because it has no meaning)*/ 63266735Speter#define APR_FOPEN_EXCL 0x00040 /**< Open should fail if #APR_FOPEN_CREATE 64251875Speter and file exists. */ 65251875Speter#define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */ 66251875Speter#define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */ 67251875Speter#define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open 68251875Speter the file for use across multiple 69251875Speter threads */ 70251875Speter#define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for 71251875Speter higher level locked read/write 72251875Speter access to support writes across 73251875Speter process/machines */ 74251875Speter#define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup 75266735Speter when the file is opened. The 76266735Speter apr_os_file_t handle in apr_file_t 77266735Speter will not be closed when the pool 78266735Speter is destroyed. */ 79251875Speter#define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this 80251875Speter file should support 81251875Speter apr_socket_sendfile operation */ 82251875Speter#define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable 83251875Speter * large file support, see WARNING below 84251875Speter */ 85251875Speter#define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable 86251875Speter * sparse file support, see WARNING below 87251875Speter */ 88266735Speter#define APR_FOPEN_NONBLOCK 0x40000 /**< Platform dependent flag to enable 89266735Speter * non blocking file io */ 90251875Speter 91266735Speter 92251875Speter/* backcompat */ 93251875Speter#define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */ 94251875Speter#define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */ 95251875Speter#define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */ 96251875Speter#define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */ 97251875Speter#define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */ 98251875Speter#define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */ 99251875Speter#define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */ 100251875Speter#define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */ 101251875Speter#define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */ 102251875Speter#define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */ 103251875Speter#define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */ 104251875Speter#define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */ 105251875Speter#define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */ 106251875Speter#define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */ 107251875Speter 108266735Speter/** @def APR_FOPEN_LARGEFILE 109266735Speter * @warning APR_FOPEN_LARGEFILE flag only has effect on some 110251875Speter * platforms where sizeof(apr_off_t) == 4. Where implemented, it 111251875Speter * allows opening and writing to a file which exceeds the size which 112251875Speter * can be represented by apr_off_t (2 gigabytes). When a file's size 113251875Speter * does exceed 2Gb, apr_file_info_get() will fail with an error on the 114251875Speter * descriptor, likewise apr_stat()/apr_lstat() will fail on the 115266735Speter * filename. apr_dir_read() will fail with #APR_INCOMPLETE on a 116251875Speter * directory entry for a large file depending on the particular 117251875Speter * APR_FINFO_* flags. Generally, it is not recommended to use this 118251875Speter * flag. 119251875Speter * 120266735Speter * @def APR_FOPEN_SPARSE 121251875Speter * @warning APR_FOPEN_SPARSE may, depending on platform, convert a 122251875Speter * normal file to a sparse file. Some applications may be unable 123251875Speter * to decipher a sparse file, so it's critical that the sparse file 124251875Speter * flag should only be used for files accessed only by APR or other 125251875Speter * applications known to be able to decipher them. APR does not 126251875Speter * guarantee that it will compress the file into sparse segments 127251875Speter * if it was previously created and written without the sparse flag. 128251875Speter * On platforms which do not understand, or on file systems which 129251875Speter * cannot handle sparse files, the flag is ignored by apr_file_open(). 130266735Speter * 131266735Speter * @def APR_FOPEN_NONBLOCK 132266735Speter * @warning APR_FOPEN_NONBLOCK is not implemented on all platforms. 133266735Speter * Callers should be prepared for it to fail with #APR_ENOTIMPL. 134251875Speter */ 135251875Speter 136251875Speter/** @} */ 137251875Speter 138251875Speter/** 139251875Speter * @defgroup apr_file_seek_flags File Seek Flags 140251875Speter * @{ 141251875Speter */ 142251875Speter 143251875Speter/* flags for apr_file_seek */ 144251875Speter/** Set the file position */ 145251875Speter#define APR_SET SEEK_SET 146251875Speter/** Current */ 147251875Speter#define APR_CUR SEEK_CUR 148251875Speter/** Go to end of file */ 149251875Speter#define APR_END SEEK_END 150251875Speter/** @} */ 151251875Speter 152251875Speter/** 153251875Speter * @defgroup apr_file_attrs_set_flags File Attribute Flags 154251875Speter * @{ 155251875Speter */ 156251875Speter 157251875Speter/* flags for apr_file_attrs_set */ 158251875Speter#define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */ 159251875Speter#define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */ 160251875Speter#define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */ 161251875Speter/** @} */ 162251875Speter 163251875Speter/** 164251875Speter * @defgroup apr_file_writev{_full} max iovec size 165251875Speter * @{ 166251875Speter */ 167251875Speter#if defined(DOXYGEN) 168251875Speter#define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum 169251875Speter size of an iovec array */ 170251875Speter#elif defined(IOV_MAX) 171251875Speter#define APR_MAX_IOVEC_SIZE IOV_MAX 172251875Speter#elif defined(MAX_IOVEC) 173251875Speter#define APR_MAX_IOVEC_SIZE MAX_IOVEC 174251875Speter#else 175251875Speter#define APR_MAX_IOVEC_SIZE 1024 176251875Speter#endif 177251875Speter/** @} */ 178251875Speter 179251875Speter/** File attributes */ 180251875Spetertypedef apr_uint32_t apr_fileattrs_t; 181251875Speter 182251875Speter/** Type to pass as whence argument to apr_file_seek. */ 183251875Spetertypedef int apr_seek_where_t; 184251875Speter 185251875Speter/** 186251875Speter * Structure for referencing files. 187251875Speter */ 188251875Spetertypedef struct apr_file_t apr_file_t; 189251875Speter 190251875Speter/* File lock types/flags */ 191251875Speter/** 192251875Speter * @defgroup apr_file_lock_types File Lock Types 193251875Speter * @{ 194251875Speter */ 195251875Speter 196251875Speter#define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process 197251875Speter or thread can hold a shared lock 198251875Speter at any given time. Essentially, 199251875Speter this is a "read lock", preventing 200251875Speter writers from establishing an 201251875Speter exclusive lock. */ 202251875Speter#define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process 203251875Speter may hold an exclusive lock at any 204251875Speter given time. This is analogous to 205251875Speter a "write lock". */ 206251875Speter 207251875Speter#define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */ 208251875Speter#define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the 209251875Speter file lock */ 210251875Speter/** @} */ 211251875Speter 212251875Speter/** 213251875Speter * Open the specified file. 214251875Speter * @param newf The opened file descriptor. 215251875Speter * @param fname The full path to the file (using / on all systems) 216251875Speter * @param flag Or'ed value of: 217266735Speter * @li #APR_FOPEN_READ open for reading 218266735Speter * @li #APR_FOPEN_WRITE open for writing 219266735Speter * @li #APR_FOPEN_CREATE create the file if not there 220266735Speter * @li #APR_FOPEN_APPEND file ptr is set to end prior to all writes 221266735Speter * @li #APR_FOPEN_TRUNCATE set length to zero if file exists 222266735Speter * @li #APR_FOPEN_BINARY not a text file 223266735Speter * @li #APR_FOPEN_BUFFERED buffer the data. Default is non-buffered 224266735Speter * @li #APR_FOPEN_EXCL return error if #APR_FOPEN_CREATE and file exists 225266735Speter * @li #APR_FOPEN_DELONCLOSE delete the file after closing 226266735Speter * @li #APR_FOPEN_XTHREAD Platform dependent tag to open the file 227251875Speter * for use across multiple threads 228266735Speter * @li #APR_FOPEN_SHARELOCK Platform dependent support for higher 229251875Speter * level locked read/write access to support 230251875Speter * writes across process/machines 231266735Speter * @li #APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool 232266735Speter * passed in on the @a pool argument (see below) 233266735Speter * @li #APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics 234251875Speter * for sendfile operations. Advisory only, 235266735Speter * apr_socket_sendfile does not check this flag 236266735Speter * @li #APR_FOPEN_LARGEFILE Platform dependent flag to enable large file 237266735Speter * support, see WARNING below 238266735Speter * @li #APR_FOPEN_SPARSE Platform dependent flag to enable sparse file 239266735Speter * support, see WARNING below 240266735Speter * @li #APR_FOPEN_NONBLOCK Platform dependent flag to enable 241266735Speter * non blocking file io 242251875Speter * @param perm Access permissions for file. 243251875Speter * @param pool The pool to use. 244266735Speter * @remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created, 245251875Speter * appropriate default permissions will be used. 246251875Speter * @remark By default, the returned file descriptor will not be 247251875Speter * inherited by child processes created by apr_proc_create(). This 248251875Speter * can be changed using apr_file_inherit_set(). 249251875Speter */ 250251875SpeterAPR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname, 251251875Speter apr_int32_t flag, apr_fileperms_t perm, 252251875Speter apr_pool_t *pool); 253251875Speter 254251875Speter/** 255251875Speter * Close the specified file. 256251875Speter * @param file The file descriptor to close. 257251875Speter */ 258251875SpeterAPR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file); 259251875Speter 260251875Speter/** 261251875Speter * Delete the specified file. 262251875Speter * @param path The full path to the file (using / on all systems) 263251875Speter * @param pool The pool to use. 264251875Speter * @remark If the file is open, it won't be removed until all 265251875Speter * instances are closed. 266251875Speter */ 267251875SpeterAPR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool); 268251875Speter 269251875Speter/** 270251875Speter * Rename the specified file. 271251875Speter * @param from_path The full path to the original file (using / on all systems) 272251875Speter * @param to_path The full path to the new file (using / on all systems) 273251875Speter * @param pool The pool to use. 274251875Speter * @warning If a file exists at the new location, then it will be 275251875Speter * overwritten. Moving files or directories across devices may not be 276251875Speter * possible. 277251875Speter */ 278251875SpeterAPR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 279251875Speter const char *to_path, 280251875Speter apr_pool_t *pool); 281251875Speter 282251875Speter/** 283251875Speter * Create a hard link to the specified file. 284251875Speter * @param from_path The full path to the original file (using / on all systems) 285251875Speter * @param to_path The full path to the new file (using / on all systems) 286251875Speter * @remark Both files must reside on the same device. 287251875Speter */ 288251875SpeterAPR_DECLARE(apr_status_t) apr_file_link(const char *from_path, 289251875Speter const char *to_path); 290251875Speter 291251875Speter/** 292251875Speter * Copy the specified file to another file. 293251875Speter * @param from_path The full path to the original file (using / on all systems) 294251875Speter * @param to_path The full path to the new file (using / on all systems) 295251875Speter * @param perms Access permissions for the new file if it is created. 296251875Speter * In place of the usual or'd combination of file permissions, the 297266735Speter * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source 298251875Speter * file's permissions are copied. 299251875Speter * @param pool The pool to use. 300251875Speter * @remark The new file does not need to exist, it will be created if required. 301251875Speter * @warning If the new file already exists, its contents will be overwritten. 302251875Speter */ 303251875SpeterAPR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 304251875Speter const char *to_path, 305251875Speter apr_fileperms_t perms, 306251875Speter apr_pool_t *pool); 307251875Speter 308251875Speter/** 309251875Speter * Append the specified file to another file. 310251875Speter * @param from_path The full path to the source file (use / on all systems) 311251875Speter * @param to_path The full path to the destination file (use / on all systems) 312251875Speter * @param perms Access permissions for the destination file if it is created. 313251875Speter * In place of the usual or'd combination of file permissions, the 314266735Speter * value #APR_FPROT_FILE_SOURCE_PERMS may be given, in which case the source 315251875Speter * file's permissions are copied. 316251875Speter * @param pool The pool to use. 317251875Speter * @remark The new file does not need to exist, it will be created if required. 318362181Sdim * @remark Note that advanced filesystem permissions such as ACLs are not 319362181Sdim * duplicated by this API. The target permissions (including duplicating the 320362181Sdim * source file permissions) are assigned only when the target file does not yet 321362181Sdim * exist. 322251875Speter */ 323251875SpeterAPR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 324251875Speter const char *to_path, 325251875Speter apr_fileperms_t perms, 326251875Speter apr_pool_t *pool); 327251875Speter 328251875Speter/** 329251875Speter * Are we at the end of the file 330251875Speter * @param fptr The apr file we are testing. 331266735Speter * @remark Returns #APR_EOF if we are at the end of file, #APR_SUCCESS otherwise. 332251875Speter */ 333251875SpeterAPR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); 334251875Speter 335251875Speter/** 336251875Speter * Open standard error as an apr file pointer. 337251875Speter * @param thefile The apr file to use as stderr. 338251875Speter * @param pool The pool to allocate the file out of. 339251875Speter * 340251875Speter * @remark The only reason that the apr_file_open_std* functions exist 341251875Speter * is that you may not always have a stderr/out/in on Windows. This 342251875Speter * is generally a problem with newer versions of Windows and services. 343251875Speter * 344251875Speter * @remark The other problem is that the C library functions generally work 345251875Speter * differently on Windows and Unix. So, by using apr_file_open_std* 346251875Speter * functions, you can get a handle to an APR struct that works with 347251875Speter * the APR functions which are supposed to work identically on all 348251875Speter * platforms. 349251875Speter */ 350251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, 351251875Speter apr_pool_t *pool); 352251875Speter 353251875Speter/** 354251875Speter * open standard output as an apr file pointer. 355251875Speter * @param thefile The apr file to use as stdout. 356251875Speter * @param pool The pool to allocate the file out of. 357251875Speter * 358266735Speter * @remark See remarks for apr_file_open_stderr(). 359251875Speter */ 360251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, 361251875Speter apr_pool_t *pool); 362251875Speter 363251875Speter/** 364251875Speter * open standard input as an apr file pointer. 365251875Speter * @param thefile The apr file to use as stdin. 366251875Speter * @param pool The pool to allocate the file out of. 367251875Speter * 368266735Speter * @remark See remarks for apr_file_open_stderr(). 369251875Speter */ 370251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, 371251875Speter apr_pool_t *pool); 372251875Speter 373251875Speter/** 374251875Speter * open standard error as an apr file pointer, with flags. 375251875Speter * @param thefile The apr file to use as stderr. 376266735Speter * @param flags The flags to open the file with. Only the 377266735Speter * @li #APR_FOPEN_EXCL 378266735Speter * @li #APR_FOPEN_BUFFERED 379266735Speter * @li #APR_FOPEN_XTHREAD 380266735Speter * @li #APR_FOPEN_SHARELOCK 381266735Speter * @li #APR_FOPEN_SENDFILE_ENABLED 382266735Speter * @li #APR_FOPEN_LARGEFILE 383266735Speter * 384266735Speter * flags should be used. The #APR_FOPEN_WRITE flag will 385266735Speter * be set unconditionally. 386251875Speter * @param pool The pool to allocate the file out of. 387251875Speter * 388266735Speter * @remark See remarks for apr_file_open_stderr(). 389251875Speter */ 390251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_flags_stderr(apr_file_t **thefile, 391251875Speter apr_int32_t flags, 392251875Speter apr_pool_t *pool); 393251875Speter 394251875Speter/** 395251875Speter * open standard output as an apr file pointer, with flags. 396251875Speter * @param thefile The apr file to use as stdout. 397266735Speter * @param flags The flags to open the file with. Only the 398266735Speter * @li #APR_FOPEN_EXCL 399266735Speter * @li #APR_FOPEN_BUFFERED 400266735Speter * @li #APR_FOPEN_XTHREAD 401266735Speter * @li #APR_FOPEN_SHARELOCK 402266735Speter * @li #APR_FOPEN_SENDFILE_ENABLED 403266735Speter * @li #APR_FOPEN_LARGEFILE 404266735Speter * 405266735Speter * flags should be used. The #APR_FOPEN_WRITE flag will 406266735Speter * be set unconditionally. 407251875Speter * @param pool The pool to allocate the file out of. 408251875Speter * 409266735Speter * @remark See remarks for apr_file_open_stderr(). 410251875Speter */ 411251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_flags_stdout(apr_file_t **thefile, 412251875Speter apr_int32_t flags, 413251875Speter apr_pool_t *pool); 414251875Speter 415251875Speter/** 416251875Speter * open standard input as an apr file pointer, with flags. 417251875Speter * @param thefile The apr file to use as stdin. 418266735Speter * @param flags The flags to open the file with. Only the 419266735Speter * @li #APR_FOPEN_EXCL 420266735Speter * @li #APR_FOPEN_BUFFERED 421266735Speter * @li #APR_FOPEN_XTHREAD 422266735Speter * @li #APR_FOPEN_SHARELOCK 423266735Speter * @li #APR_FOPEN_SENDFILE_ENABLED 424266735Speter * @li #APR_FOPEN_LARGEFILE 425266735Speter * 426266735Speter * flags should be used. The #APR_FOPEN_WRITE flag will 427266735Speter * be set unconditionally. 428251875Speter * @param pool The pool to allocate the file out of. 429251875Speter * 430266735Speter * @remark See remarks for apr_file_open_stderr(). 431251875Speter */ 432251875SpeterAPR_DECLARE(apr_status_t) apr_file_open_flags_stdin(apr_file_t **thefile, 433251875Speter apr_int32_t flags, 434251875Speter apr_pool_t *pool); 435251875Speter 436251875Speter/** 437251875Speter * Read data from the specified file. 438251875Speter * @param thefile The file descriptor to read from. 439251875Speter * @param buf The buffer to store the data to. 440251875Speter * @param nbytes On entry, the number of bytes to read; on exit, the number 441251875Speter * of bytes read. 442251875Speter * 443266735Speter * @remark apr_file_read() will read up to the specified number of 444251875Speter * bytes, but never more. If there isn't enough data to fill that 445251875Speter * number of bytes, all of the available data is read. The third 446251875Speter * argument is modified to reflect the number of bytes read. If a 447251875Speter * char was put back into the stream via ungetc, it will be the first 448251875Speter * character returned. 449251875Speter * 450266735Speter * @remark It is not possible for both bytes to be read and an #APR_EOF 451266735Speter * or other error to be returned. #APR_EINTR is never returned. 452251875Speter */ 453251875SpeterAPR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, 454251875Speter apr_size_t *nbytes); 455251875Speter 456251875Speter/** 457251875Speter * Write data to the specified file. 458251875Speter * @param thefile The file descriptor to write to. 459251875Speter * @param buf The buffer which contains the data. 460251875Speter * @param nbytes On entry, the number of bytes to write; on exit, the number 461251875Speter * of bytes written. 462251875Speter * 463266735Speter * @remark apr_file_write() will write up to the specified number of 464251875Speter * bytes, but never more. If the OS cannot write that many bytes, it 465251875Speter * will write as many as it can. The third argument is modified to 466251875Speter * reflect the * number of bytes written. 467251875Speter * 468251875Speter * @remark It is possible for both bytes to be written and an error to 469266735Speter * be returned. #APR_EINTR is never returned. 470251875Speter */ 471251875SpeterAPR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, 472251875Speter apr_size_t *nbytes); 473251875Speter 474251875Speter/** 475251875Speter * Write data from iovec array to the specified file. 476251875Speter * @param thefile The file descriptor to write to. 477251875Speter * @param vec The array from which to get the data to write to the file. 478251875Speter * @param nvec The number of elements in the struct iovec array. This must 479266735Speter * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function 480266735Speter * will fail with #APR_EINVAL. 481251875Speter * @param nbytes The number of bytes written. 482251875Speter * 483251875Speter * @remark It is possible for both bytes to be written and an error to 484266735Speter * be returned. #APR_EINTR is never returned. 485251875Speter * 486266735Speter * @remark apr_file_writev() is available even if the underlying 487251875Speter * operating system doesn't provide writev(). 488251875Speter */ 489251875SpeterAPR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, 490251875Speter const struct iovec *vec, 491251875Speter apr_size_t nvec, apr_size_t *nbytes); 492251875Speter 493251875Speter/** 494251875Speter * Read data from the specified file, ensuring that the buffer is filled 495251875Speter * before returning. 496251875Speter * @param thefile The file descriptor to read from. 497251875Speter * @param buf The buffer to store the data to. 498251875Speter * @param nbytes The number of bytes to read. 499251875Speter * @param bytes_read If non-NULL, this will contain the number of bytes read. 500251875Speter * 501266735Speter * @remark apr_file_read_full() will read up to the specified number of 502251875Speter * bytes, but never more. If there isn't enough data to fill that 503251875Speter * number of bytes, then the process/thread will block until it is 504251875Speter * available or EOF is reached. If a char was put back into the 505251875Speter * stream via ungetc, it will be the first character returned. 506251875Speter * 507251875Speter * @remark It is possible for both bytes to be read and an error to be 508251875Speter * returned. And if *bytes_read is less than nbytes, an accompanying 509251875Speter * error is _always_ returned. 510251875Speter * 511266735Speter * @remark #APR_EINTR is never returned. 512251875Speter */ 513251875SpeterAPR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, 514251875Speter apr_size_t nbytes, 515251875Speter apr_size_t *bytes_read); 516251875Speter 517251875Speter/** 518251875Speter * Write data to the specified file, ensuring that all of the data is 519251875Speter * written before returning. 520251875Speter * @param thefile The file descriptor to write to. 521251875Speter * @param buf The buffer which contains the data. 522251875Speter * @param nbytes The number of bytes to write. 523251875Speter * @param bytes_written If non-NULL, set to the number of bytes written. 524251875Speter * 525266735Speter * @remark apr_file_write_full() will write up to the specified number of 526251875Speter * bytes, but never more. If the OS cannot write that many bytes, the 527251875Speter * process/thread will block until they can be written. Exceptional 528251875Speter * error such as "out of space" or "pipe closed" will terminate with 529251875Speter * an error. 530251875Speter * 531251875Speter * @remark It is possible for both bytes to be written and an error to 532251875Speter * be returned. And if *bytes_written is less than nbytes, an 533251875Speter * accompanying error is _always_ returned. 534251875Speter * 535266735Speter * @remark #APR_EINTR is never returned. 536251875Speter */ 537251875SpeterAPR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 538251875Speter const void *buf, 539251875Speter apr_size_t nbytes, 540251875Speter apr_size_t *bytes_written); 541251875Speter 542251875Speter 543251875Speter/** 544251875Speter * Write data from iovec array to the specified file, ensuring that all of the 545251875Speter * data is written before returning. 546251875Speter * @param thefile The file descriptor to write to. 547251875Speter * @param vec The array from which to get the data to write to the file. 548251875Speter * @param nvec The number of elements in the struct iovec array. This must 549266735Speter * be smaller than #APR_MAX_IOVEC_SIZE. If it isn't, the function 550266735Speter * will fail with #APR_EINVAL. 551251875Speter * @param nbytes The number of bytes written. 552251875Speter * 553266735Speter * @remark apr_file_writev_full() is available even if the underlying 554251875Speter * operating system doesn't provide writev(). 555251875Speter */ 556251875SpeterAPR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile, 557251875Speter const struct iovec *vec, 558251875Speter apr_size_t nvec, 559251875Speter apr_size_t *nbytes); 560251875Speter/** 561251875Speter * Write a character into the specified file. 562251875Speter * @param ch The character to write. 563251875Speter * @param thefile The file descriptor to write to 564251875Speter */ 565251875SpeterAPR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile); 566251875Speter 567251875Speter/** 568251875Speter * Read a character from the specified file. 569251875Speter * @param ch The character to read into 570251875Speter * @param thefile The file descriptor to read from 571251875Speter */ 572251875SpeterAPR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile); 573251875Speter 574251875Speter/** 575251875Speter * Put a character back onto a specified stream. 576251875Speter * @param ch The character to write. 577251875Speter * @param thefile The file descriptor to write to 578251875Speter */ 579251875SpeterAPR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile); 580251875Speter 581251875Speter/** 582251875Speter * Read a line from the specified file 583251875Speter * @param str The buffer to store the string in. 584251875Speter * @param len The length of the string 585251875Speter * @param thefile The file descriptor to read from 586251875Speter * @remark The buffer will be NUL-terminated if any characters are stored. 587251875Speter * The newline at the end of the line will not be stripped. 588251875Speter */ 589251875SpeterAPR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 590251875Speter apr_file_t *thefile); 591251875Speter 592251875Speter/** 593251875Speter * Write the string into the specified file. 594251875Speter * @param str The string to write. 595251875Speter * @param thefile The file descriptor to write to 596251875Speter */ 597251875SpeterAPR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile); 598251875Speter 599251875Speter/** 600251875Speter * Flush the file's buffer. 601251875Speter * @param thefile The file descriptor to flush 602251875Speter */ 603251875SpeterAPR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile); 604251875Speter 605251875Speter/** 606251875Speter * Transfer all file modified data and metadata to disk. 607251875Speter * @param thefile The file descriptor to sync 608251875Speter */ 609251875SpeterAPR_DECLARE(apr_status_t) apr_file_sync(apr_file_t *thefile); 610251875Speter 611251875Speter/** 612251875Speter * Transfer all file modified data to disk. 613251875Speter * @param thefile The file descriptor to sync 614251875Speter */ 615251875SpeterAPR_DECLARE(apr_status_t) apr_file_datasync(apr_file_t *thefile); 616251875Speter 617251875Speter/** 618251875Speter * Duplicate the specified file descriptor. 619251875Speter * @param new_file The structure to duplicate into. 620251875Speter * @param old_file The file to duplicate. 621251875Speter * @param p The pool to use for the new file. 622251875Speter * @remark *new_file must point to a valid apr_file_t, or point to NULL. 623251875Speter */ 624251875SpeterAPR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file, 625251875Speter apr_file_t *old_file, 626251875Speter apr_pool_t *p); 627251875Speter 628251875Speter/** 629251875Speter * Duplicate the specified file descriptor and close the original 630251875Speter * @param new_file The old file that is to be closed and reused 631251875Speter * @param old_file The file to duplicate 632251875Speter * @param p The pool to use for the new file 633251875Speter * 634251875Speter * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL. 635251875Speter */ 636251875SpeterAPR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file, 637251875Speter apr_file_t *old_file, 638251875Speter apr_pool_t *p); 639251875Speter 640251875Speter/** 641251875Speter * Move the specified file descriptor to a new pool 642251875Speter * @param new_file Pointer in which to return the new apr_file_t 643251875Speter * @param old_file The file to move 644251875Speter * @param p The pool to which the descriptor is to be moved 645251875Speter * @remark Unlike apr_file_dup2(), this function doesn't do an 646251875Speter * OS dup() operation on the underlying descriptor; it just 647251875Speter * moves the descriptor's apr_file_t wrapper to a new pool. 648251875Speter * @remark The new pool need not be an ancestor of old_file's pool. 649251875Speter * @remark After calling this function, old_file may not be used 650251875Speter */ 651251875SpeterAPR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file, 652251875Speter apr_file_t *old_file, 653251875Speter apr_pool_t *p); 654251875Speter 655251875Speter/** 656251875Speter * Give the specified apr file handle a new buffer 657251875Speter * @param thefile The file handle that is to be modified 658251875Speter * @param buffer The buffer 659251875Speter * @param bufsize The size of the buffer 660251875Speter * @remark It is possible to add a buffer to previously unbuffered 661266735Speter * file handles, the #APR_FOPEN_BUFFERED flag will be added to 662251875Speter * the file handle's flags. Likewise, with buffer=NULL and 663251875Speter * bufsize=0 arguments it is possible to make a previously 664251875Speter * buffered file handle unbuffered. 665251875Speter */ 666251875SpeterAPR_DECLARE(apr_status_t) apr_file_buffer_set(apr_file_t *thefile, 667251875Speter char * buffer, 668251875Speter apr_size_t bufsize); 669251875Speter 670251875Speter/** 671251875Speter * Get the size of any buffer for the specified apr file handle 672251875Speter * @param thefile The file handle 673251875Speter */ 674251875SpeterAPR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile); 675251875Speter 676251875Speter/** 677251875Speter * Move the read/write file offset to a specified byte within a file. 678251875Speter * @param thefile The file descriptor 679251875Speter * @param where How to move the pointer, one of: 680266735Speter * @li #APR_SET -- set the offset to offset 681266735Speter * @li #APR_CUR -- add the offset to the current position 682266735Speter * @li #APR_END -- add the offset to the current file size 683251875Speter * @param offset The offset to move the pointer to. 684251875Speter * @remark The third argument is modified to be the offset the pointer 685251875Speter was actually moved to. 686251875Speter */ 687251875SpeterAPR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 688251875Speter apr_seek_where_t where, 689251875Speter apr_off_t *offset); 690251875Speter 691251875Speter/** 692251875Speter * Create an anonymous pipe. 693251875Speter * @param in The newly created pipe's file for reading. 694251875Speter * @param out The newly created pipe's file for writing. 695251875Speter * @param pool The pool to operate on. 696251875Speter * @remark By default, the returned file descriptors will be inherited 697251875Speter * by child processes created using apr_proc_create(). This can be 698251875Speter * changed using apr_file_inherit_unset(). 699251875Speter * @bug Some platforms cannot toggle between blocking and nonblocking, 700251875Speter * and when passing a pipe as a standard handle to an application which 701251875Speter * does not expect it, a non-blocking stream will fluxor the client app. 702362181Sdim * @deprecated @see apr_file_pipe_create_pools() 703251875Speter */ 704251875SpeterAPR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 705251875Speter apr_file_t **out, 706251875Speter apr_pool_t *pool); 707251875Speter 708251875Speter/** 709251875Speter * Create an anonymous pipe which portably supports async timeout options. 710251875Speter * @param in The newly created pipe's file for reading. 711251875Speter * @param out The newly created pipe's file for writing. 712251875Speter * @param blocking one of these values defined in apr_thread_proc.h; 713266735Speter * @li #APR_FULL_BLOCK 714266735Speter * @li #APR_READ_BLOCK 715266735Speter * @li #APR_WRITE_BLOCK 716266735Speter * @li #APR_FULL_NONBLOCK 717251875Speter * @param pool The pool to operate on. 718251875Speter * @remark By default, the returned file descriptors will be inherited 719251875Speter * by child processes created using apr_proc_create(). This can be 720251875Speter * changed using apr_file_inherit_unset(). 721251875Speter * @remark Some platforms cannot toggle between blocking and nonblocking, 722251875Speter * and when passing a pipe as a standard handle to an application which 723251875Speter * does not expect it, a non-blocking stream will fluxor the client app. 724266735Speter * Use this function rather than apr_file_pipe_create() to create pipes 725251875Speter * where one or both ends require non-blocking semantics. 726362181Sdim * @deprecated @see apr_file_pipe_create_pools() 727251875Speter */ 728251875SpeterAPR_DECLARE(apr_status_t) apr_file_pipe_create_ex(apr_file_t **in, 729251875Speter apr_file_t **out, 730251875Speter apr_int32_t blocking, 731251875Speter apr_pool_t *pool); 732251875Speter 733251875Speter/** 734362181Sdim * Create an anonymous pipe which portably supports async timeout options, 735362181Sdim * placing each side of the pipe in a different pool. 736362181Sdim * @param in The newly created pipe's file for reading. 737362181Sdim * @param out The newly created pipe's file for writing. 738362181Sdim * @param blocking one of these values defined in apr_thread_proc.h; 739362181Sdim * @li #APR_FULL_BLOCK 740362181Sdim * @li #APR_READ_BLOCK 741362181Sdim * @li #APR_WRITE_BLOCK 742362181Sdim * @li #APR_FULL_NONBLOCK 743362181Sdim * @param pool_in The pool for the reading pipe. 744362181Sdim * @param pool_out The pool for the writing pipe. 745362181Sdim * @remark By default, the returned file descriptors will be inherited 746362181Sdim * by child processes created using apr_proc_create(). This can be 747362181Sdim * changed using apr_file_inherit_unset(). 748362181Sdim * @remark Some platforms cannot toggle between blocking and nonblocking, 749362181Sdim * and when passing a pipe as a standard handle to an application which 750362181Sdim * does not expect it, a non-blocking stream will fluxor the client app. 751362181Sdim * Use this function rather than apr_file_pipe_create() to create pipes 752362181Sdim * where one or both ends require non-blocking semantics. 753362181Sdim */ 754362181SdimAPR_DECLARE(apr_status_t) apr_file_pipe_create_pools(apr_file_t **in, 755362181Sdim apr_file_t **out, 756362181Sdim apr_int32_t blocking, 757362181Sdim apr_pool_t *pool_in, 758362181Sdim apr_pool_t *pool_out); 759362181Sdim 760362181Sdim/** 761251875Speter * Create a named pipe. 762251875Speter * @param filename The filename of the named pipe 763251875Speter * @param perm The permissions for the newly created pipe. 764251875Speter * @param pool The pool to operate on. 765251875Speter */ 766251875SpeterAPR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 767251875Speter apr_fileperms_t perm, 768251875Speter apr_pool_t *pool); 769251875Speter 770251875Speter/** 771251875Speter * Get the timeout value for a pipe or manipulate the blocking state. 772251875Speter * @param thepipe The pipe we are getting a timeout for. 773251875Speter * @param timeout The current timeout value in microseconds. 774251875Speter */ 775251875SpeterAPR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 776251875Speter apr_interval_time_t *timeout); 777251875Speter 778251875Speter/** 779251875Speter * Set the timeout value for a pipe or manipulate the blocking state. 780251875Speter * @param thepipe The pipe we are setting a timeout on. 781251875Speter * @param timeout The timeout value in microseconds. Values < 0 mean wait 782251875Speter * forever, 0 means do not wait at all. 783251875Speter */ 784251875SpeterAPR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 785251875Speter apr_interval_time_t timeout); 786251875Speter 787251875Speter/** file (un)locking functions. */ 788251875Speter 789251875Speter/** 790251875Speter * Establish a lock on the specified, open file. The lock may be advisory 791251875Speter * or mandatory, at the discretion of the platform. The lock applies to 792251875Speter * the file as a whole, rather than a specific range. Locks are established 793251875Speter * on a per-thread/process basis; a second lock by the same thread will not 794251875Speter * block. 795251875Speter * @param thefile The file to lock. 796251875Speter * @param type The type of lock to establish on the file. 797251875Speter */ 798251875SpeterAPR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type); 799251875Speter 800251875Speter/** 801251875Speter * Remove any outstanding locks on the file. 802251875Speter * @param thefile The file to unlock. 803251875Speter */ 804251875SpeterAPR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile); 805251875Speter 806251875Speter/**accessor and general file_io functions. */ 807251875Speter 808251875Speter/** 809251875Speter * return the file name of the current file. 810251875Speter * @param new_path The path of the file. 811251875Speter * @param thefile The currently open file. 812251875Speter */ 813251875SpeterAPR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 814251875Speter apr_file_t *thefile); 815251875Speter 816251875Speter/** 817251875Speter * Return the data associated with the current file. 818251875Speter * @param data The user data associated with the file. 819251875Speter * @param key The key to use for retrieving data associated with this file. 820251875Speter * @param file The currently open file. 821251875Speter */ 822251875SpeterAPR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 823251875Speter apr_file_t *file); 824251875Speter 825251875Speter/** 826251875Speter * Set the data associated with the current file. 827251875Speter * @param file The currently open file. 828251875Speter * @param data The user data to associate with the file. 829251875Speter * @param key The key to use for associating data with the file. 830251875Speter * @param cleanup The cleanup routine to use when the file is destroyed. 831251875Speter */ 832251875SpeterAPR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data, 833251875Speter const char *key, 834251875Speter apr_status_t (*cleanup)(void *)); 835251875Speter 836251875Speter/** 837251875Speter * Write a string to a file using a printf format. 838251875Speter * @param fptr The file to write to. 839251875Speter * @param format The format string 840251875Speter * @param ... The values to substitute in the format string 841251875Speter * @return The number of bytes written 842251875Speter */ 843251875SpeterAPR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, 844251875Speter const char *format, ...) 845251875Speter __attribute__((format(printf,2,3))); 846251875Speter 847251875Speter/** 848251875Speter * set the specified file's permission bits. 849251875Speter * @param fname The file (name) to apply the permissions to. 850251875Speter * @param perms The permission bits to apply to the file. 851251875Speter * 852251875Speter * @warning Some platforms may not be able to apply all of the 853266735Speter * available permission bits; #APR_INCOMPLETE will be returned if some 854251875Speter * permissions are specified which could not be set. 855251875Speter * 856251875Speter * @warning Platforms which do not implement this feature will return 857266735Speter * #APR_ENOTIMPL. 858251875Speter */ 859251875SpeterAPR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, 860251875Speter apr_fileperms_t perms); 861251875Speter 862251875Speter/** 863251875Speter * Set attributes of the specified file. 864251875Speter * @param fname The full path to the file (using / on all systems) 865251875Speter * @param attributes Or'd combination of 866266735Speter * @li #APR_FILE_ATTR_READONLY - make the file readonly 867266735Speter * @li #APR_FILE_ATTR_EXECUTABLE - make the file executable 868266735Speter * @li #APR_FILE_ATTR_HIDDEN - make the file hidden 869251875Speter * @param attr_mask Mask of valid bits in attributes. 870251875Speter * @param pool the pool to use. 871251875Speter * @remark This function should be used in preference to explicit manipulation 872251875Speter * of the file permissions, because the operations to provide these 873251875Speter * attributes are platform specific and may involve more than simply 874251875Speter * setting permission bits. 875251875Speter * @warning Platforms which do not implement this feature will return 876266735Speter * #APR_ENOTIMPL. 877251875Speter */ 878251875SpeterAPR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname, 879251875Speter apr_fileattrs_t attributes, 880251875Speter apr_fileattrs_t attr_mask, 881251875Speter apr_pool_t *pool); 882251875Speter 883251875Speter/** 884251875Speter * Set the mtime of the specified file. 885251875Speter * @param fname The full path to the file (using / on all systems) 886251875Speter * @param mtime The mtime to apply to the file. 887251875Speter * @param pool The pool to use. 888251875Speter * @warning Platforms which do not implement this feature will return 889266735Speter * #APR_ENOTIMPL. 890251875Speter */ 891251875SpeterAPR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname, 892251875Speter apr_time_t mtime, 893251875Speter apr_pool_t *pool); 894251875Speter 895251875Speter/** 896251875Speter * Create a new directory on the file system. 897251875Speter * @param path the path for the directory to be created. (use / on all systems) 898251875Speter * @param perm Permissions for the new directory. 899251875Speter * @param pool the pool to use. 900251875Speter */ 901251875SpeterAPR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 902251875Speter apr_pool_t *pool); 903251875Speter 904251875Speter/** Creates a new directory on the file system, but behaves like 905251875Speter * 'mkdir -p'. Creates intermediate directories as required. No error 906251875Speter * will be reported if PATH already exists. 907251875Speter * @param path the path for the directory to be created. (use / on all systems) 908251875Speter * @param perm Permissions for the new directory. 909251875Speter * @param pool the pool to use. 910251875Speter */ 911251875SpeterAPR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path, 912251875Speter apr_fileperms_t perm, 913251875Speter apr_pool_t *pool); 914251875Speter 915251875Speter/** 916251875Speter * Remove directory from the file system. 917251875Speter * @param path the path for the directory to be removed. (use / on all systems) 918251875Speter * @param pool the pool to use. 919251875Speter * @remark Removing a directory which is in-use (e.g., the current working 920251875Speter * directory, or during apr_dir_read, or with an open file) is not portable. 921251875Speter */ 922251875SpeterAPR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool); 923251875Speter 924251875Speter/** 925251875Speter * get the specified file's stats. 926251875Speter * @param finfo Where to store the information about the file. 927266735Speter * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values 928251875Speter * @param thefile The file to get information about. 929251875Speter */ 930251875SpeterAPR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 931251875Speter apr_int32_t wanted, 932251875Speter apr_file_t *thefile); 933251875Speter 934251875Speter 935251875Speter/** 936251875Speter * Truncate the file's length to the specified offset 937251875Speter * @param fp The file to truncate 938251875Speter * @param offset The offset to truncate to. 939251875Speter * @remark The read/write file offset is repositioned to offset. 940251875Speter */ 941251875SpeterAPR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset); 942251875Speter 943251875Speter/** 944251875Speter * Retrieve the flags that were passed into apr_file_open() 945251875Speter * when the file was opened. 946251875Speter * @return apr_int32_t the flags 947251875Speter */ 948251875SpeterAPR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f); 949251875Speter 950251875Speter/** 951251875Speter * Get the pool used by the file. 952251875Speter */ 953251875SpeterAPR_POOL_DECLARE_ACCESSOR(file); 954251875Speter 955251875Speter/** 956251875Speter * Set a file to be inherited by child processes. 957251875Speter * 958251875Speter */ 959251875SpeterAPR_DECLARE_INHERIT_SET(file); 960251875Speter 961251875Speter/** 962251875Speter * Unset a file from being inherited by child processes. 963251875Speter */ 964251875SpeterAPR_DECLARE_INHERIT_UNSET(file); 965251875Speter 966251875Speter/** 967251875Speter * Open a temporary file 968251875Speter * @param fp The apr file to use as a temporary file. 969251875Speter * @param templ The template to use when creating a temp file. 970251875Speter * @param flags The flags to open the file with. If this is zero, 971251875Speter * the file is opened with 972266735Speter * #APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE | 973266735Speter * #APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE 974251875Speter * @param p The pool to allocate the file out of. 975251875Speter * @remark 976251875Speter * This function generates a unique temporary file name from template. 977251875Speter * The last six characters of template must be XXXXXX and these are replaced 978251875Speter * with a string that makes the filename unique. Since it will be modified, 979251875Speter * template must not be a string constant, but should be declared as a character 980251875Speter * array. 981251875Speter * 982251875Speter */ 983251875SpeterAPR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ, 984251875Speter apr_int32_t flags, apr_pool_t *p); 985251875Speter 986251875Speter 987251875Speter/** 988251875Speter * Find an existing directory suitable as a temporary storage location. 989251875Speter * @param temp_dir The temp directory. 990251875Speter * @param p The pool to use for any necessary allocations. 991251875Speter * @remark 992251875Speter * This function uses an algorithm to search for a directory that an 993251875Speter * an application can use for temporary storage. 994251875Speter * 995251875Speter */ 996251875SpeterAPR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir, 997251875Speter apr_pool_t *p); 998251875Speter 999251875Speter/** @} */ 1000251875Speter 1001251875Speter#ifdef __cplusplus 1002251875Speter} 1003251875Speter#endif 1004251875Speter 1005251875Speter#endif /* ! APR_FILE_IO_H */ 1006