Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apr_file_io.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef APR_FILE_IO_H
18 #define APR_FILE_IO_H
19 
20 /**
21  * @file apr_file_io.h
22  * @brief APR File I/O Handling
23  */
24 
25 #include "apr.h"
26 #include "apr_pools.h"
27 #include "apr_time.h"
28 #include "apr_errno.h"
29 #include "apr_file_info.h"
30 #include "apr_inherit.h"
31 
32 #define APR_WANT_STDIO /**< for SEEK_* */
33 #define APR_WANT_IOVEC /**< for apr_file_writev */
34 #include "apr_want.h"
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif /* __cplusplus */
39 
40 /**
41  * @defgroup apr_file_io File I/O Handling Functions
42  * @ingroup APR
43  * @{
44  */
45 
46 /**
47  * @defgroup apr_file_open_flags File Open Flags/Routines
48  * @{
49  */
50 
51 /* Note to implementors: Values in the range 0x00100000--0x80000000
52  are reserved for platform-specific values. */
53 
54 #define APR_FOPEN_READ 0x00001 /**< Open the file for reading */
55 #define APR_FOPEN_WRITE 0x00002 /**< Open the file for writing */
56 #define APR_FOPEN_CREATE 0x00004 /**< Create the file if not there */
57 #define APR_FOPEN_APPEND 0x00008 /**< Append to the end of the file */
58 #define APR_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate
59  to 0 length */
60 #define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode */
61 #define APR_FOPEN_EXCL 0x00040 /**< Open should fail if APR_CREATE
62  and file exists. */
63 #define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */
64 #define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */
65 #define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open
66  the file for use across multiple
67  threads */
68 #define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for
69  higher level locked read/write
70  access to support writes across
71  process/machines */
72 #define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup
73  when the file is opened */
74 #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
75  file should support
76  apr_socket_sendfile operation */
77 #define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable
78  * large file support, see WARNING below
79  */
80 #define APR_FOPEN_SPARSE 0x08000 /**< Platform dependent flag to enable
81  * sparse file support, see WARNING below
82  */
83 
84 /* backcompat */
85 #define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */
86 #define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */
87 #define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */
88 #define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */
89 #define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */
90 #define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */
91 #define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */
92 #define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */
93 #define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */
94 #define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */
95 #define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */
96 #define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */
97 #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */
98 #define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */
99 
100 /** @warning APR_FOPEN_LARGEFILE flag only has effect on some
101  * platforms where sizeof(apr_off_t) == 4. Where implemented, it
102  * allows opening and writing to a file which exceeds the size which
103  * can be represented by apr_off_t (2 gigabytes). When a file's size
104  * does exceed 2Gb, apr_file_info_get() will fail with an error on the
105  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
106  * filename. apr_dir_read() will fail with APR_INCOMPLETE on a
107  * directory entry for a large file depending on the particular
108  * APR_FINFO_* flags. Generally, it is not recommended to use this
109  * flag.
110  *
111  * @warning APR_FOPEN_SPARSE may, depending on platform, convert a
112  * normal file to a sparse file. Some applications may be unable
113  * to decipher a sparse file, so it's critical that the sparse file
114  * flag should only be used for files accessed only by APR or other
115  * applications known to be able to decipher them. APR does not
116  * guarantee that it will compress the file into sparse segments
117  * if it was previously created and written without the sparse flag.
118  * On platforms which do not understand, or on file systems which
119  * cannot handle sparse files, the flag is ignored by apr_file_open().
120  */
121 
122 /** @} */
123 
124 /**
125  * @defgroup apr_file_seek_flags File Seek Flags
126  * @{
127  */
128 
129 /* flags for apr_file_seek */
130 /** Set the file position */
131 #define APR_SET SEEK_SET
132 /** Current */
133 #define APR_CUR SEEK_CUR
134 /** Go to end of file */
135 #define APR_END SEEK_END
136 /** @} */
137 
138 /**
139  * @defgroup apr_file_attrs_set_flags File Attribute Flags
140  * @{
141  */
142 
143 /* flags for apr_file_attrs_set */
144 #define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */
145 #define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */
146 #define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */
147 /** @} */
148 
149 /**
150  * @defgroup apr_file_writev{_full} max iovec size
151  * @{
152  */
153 #if defined(DOXYGEN)
154 #define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum
155  size of an iovec array */
156 #elif defined(IOV_MAX)
157 #define APR_MAX_IOVEC_SIZE IOV_MAX
158 #elif defined(MAX_IOVEC)
159 #define APR_MAX_IOVEC_SIZE MAX_IOVEC
160 #else
161 #define APR_MAX_IOVEC_SIZE 1024
162 #endif
163 /** @} */
164 
165 /** File attributes */
166 typedef apr_uint32_t apr_fileattrs_t;
167 
168 /** Type to pass as whence argument to apr_file_seek. */
169 typedef int apr_seek_where_t;
170 
171 /**
172  * Structure for referencing files.
173  */
174 typedef struct apr_file_t apr_file_t;
175 
176 /* File lock types/flags */
177 /**
178  * @defgroup apr_file_lock_types File Lock Types
179  * @{
180  */
181 
182 #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process
183  or thread can hold a shared lock
184  at any given time. Essentially,
185  this is a "read lock", preventing
186  writers from establishing an
187  exclusive lock. */
188 #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process
189  may hold an exclusive lock at any
190  given time. This is analogous to
191  a "write lock". */
192 
193 #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
194 #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
195  file lock */
196 /** @} */
197 
198 /**
199  * Open the specified file.
200  * @param newf The opened file descriptor.
201  * @param fname The full path to the file (using / on all systems)
202  * @param flag Or'ed value of:
203  * <PRE>
204  * APR_READ open for reading
205  * APR_WRITE open for writing
206  * APR_CREATE create the file if not there
207  * APR_APPEND file ptr is set to end prior to all writes
208  * APR_TRUNCATE set length to zero if file exists
209  * APR_BINARY not a text file (This flag is ignored on
210  * UNIX because it has no meaning)
211  * APR_BUFFERED buffer the data. Default is non-buffered
212  * APR_EXCL return error if APR_CREATE and file exists
213  * APR_DELONCLOSE delete the file after closing.
214  * APR_XTHREAD Platform dependent tag to open the file
215  * for use across multiple threads
216  * APR_SHARELOCK Platform dependent support for higher
217  * level locked read/write access to support
218  * writes across process/machines
219  * APR_FILE_NOCLEANUP Do not register a cleanup with the pool
220  * passed in on the <EM>pool</EM> argument (see below).
221  * The apr_os_file_t handle in apr_file_t will not
222  * be closed when the pool is destroyed.
223  * APR_SENDFILE_ENABLED Open with appropriate platform semantics
224  * for sendfile operations. Advisory only,
225  * apr_socket_sendfile does not check this flag.
226  * </PRE>
227  * @param perm Access permissions for file.
228  * @param pool The pool to use.
229  * @remark If perm is APR_OS_DEFAULT and the file is being created,
230  * appropriate default permissions will be used.
231  * @remark By default, the returned file descriptor will not be
232  * inherited by child processes created by apr_proc_create(). This
233  * can be changed using apr_file_inherit_set().
234  */
235 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
236  apr_int32_t flag, apr_fileperms_t perm,
237  apr_pool_t *pool);
238 
239 /**
240  * Close the specified file.
241  * @param file The file descriptor to close.
242  */
244 
245 /**
246  * Delete the specified file.
247  * @param path The full path to the file (using / on all systems)
248  * @param pool The pool to use.
249  * @remark If the file is open, it won't be removed until all
250  * instances are closed.
251  */
252 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
253 
254 /**
255  * Rename the specified file.
256  * @param from_path The full path to the original file (using / on all systems)
257  * @param to_path The full path to the new file (using / on all systems)
258  * @param pool The pool to use.
259  * @warning If a file exists at the new location, then it will be
260  * overwritten. Moving files or directories across devices may not be
261  * possible.
262  */
263 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
264  const char *to_path,
265  apr_pool_t *pool);
266 
267 /**
268  * Create a hard link to the specified file.
269  * @param from_path The full path to the original file (using / on all systems)
270  * @param to_path The full path to the new file (using / on all systems)
271  * @remark Both files must reside on the same device.
272  */
273 APR_DECLARE(apr_status_t) apr_file_link(const char *from_path,
274  const char *to_path);
275 
276 /**
277  * Copy the specified file to another file.
278  * @param from_path The full path to the original file (using / on all systems)
279  * @param to_path The full path to the new file (using / on all systems)
280  * @param perms Access permissions for the new file if it is created.
281  * In place of the usual or'd combination of file permissions, the
282  * value APR_FILE_SOURCE_PERMS may be given, in which case the source
283  * file's permissions are copied.
284  * @param pool The pool to use.
285  * @remark The new file does not need to exist, it will be created if required.
286  * @warning If the new file already exists, its contents will be overwritten.
287  */
288 APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
289  const char *to_path,
290  apr_fileperms_t perms,
291  apr_pool_t *pool);
292 
293 /**
294  * Append the specified file to another file.
295  * @param from_path The full path to the source file (use / on all systems)
296  * @param to_path The full path to the destination file (use / on all systems)
297  * @param perms Access permissions for the destination file if it is created.
298  * In place of the usual or'd combination of file permissions, the
299  * value APR_FILE_SOURCE_PERMS may be given, in which case the source
300  * file's permissions are copied.
301  * @param pool The pool to use.
302  * @remark The new file does not need to exist, it will be created if required.
303  */
304 APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
305  const char *to_path,
306  apr_fileperms_t perms,
307  apr_pool_t *pool);
308 
309 /**
310  * Are we at the end of the file
311  * @param fptr The apr file we are testing.
312  * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
313  */
315 
316 /**
317  * Open standard error as an apr file pointer.
318  * @param thefile The apr file to use as stderr.
319  * @param pool The pool to allocate the file out of.
320  *
321  * @remark The only reason that the apr_file_open_std* functions exist
322  * is that you may not always have a stderr/out/in on Windows. This
323  * is generally a problem with newer versions of Windows and services.
324  *
325  * @remark The other problem is that the C library functions generally work
326  * differently on Windows and Unix. So, by using apr_file_open_std*
327  * functions, you can get a handle to an APR struct that works with
328  * the APR functions which are supposed to work identically on all
329  * platforms.
330  */
332  apr_pool_t *pool);
333 
334 /**
335  * open standard output as an apr file pointer.
336  * @param thefile The apr file to use as stdout.
337  * @param pool The pool to allocate the file out of.
338  *
339  * @remark See remarks for apr_file_open_stderr.
340  */
342  apr_pool_t *pool);
343 
344 /**
345  * open standard input as an apr file pointer.
346  * @param thefile The apr file to use as stdin.
347  * @param pool The pool to allocate the file out of.
348  *
349  * @remark See remarks for apr_file_open_stderr.
350  */
352  apr_pool_t *pool);
353 
354 /**
355  * open standard error as an apr file pointer, with flags.
356  * @param thefile The apr file to use as stderr.
357  * @param flags The flags to open the file with. Only the APR_EXCL,
358  * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
359  * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
360  * be used. The APR_WRITE flag will be set unconditionally.
361  * @param pool The pool to allocate the file out of.
362  *
363  * @remark See remarks for apr_file_open_stderr.
364  */
366  apr_int32_t flags,
367  apr_pool_t *pool);
368 
369 /**
370  * open standard output as an apr file pointer, with flags.
371  * @param thefile The apr file to use as stdout.
372  * @param flags The flags to open the file with. Only the APR_EXCL,
373  * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
374  * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
375  * be used. The APR_WRITE flag will be set unconditionally.
376  * @param pool The pool to allocate the file out of.
377  *
378  * @remark See remarks for apr_file_open_stderr.
379  */
381  apr_int32_t flags,
382  apr_pool_t *pool);
383 
384 /**
385  * open standard input as an apr file pointer, with flags.
386  * @param thefile The apr file to use as stdin.
387  * @param flags The flags to open the file with. Only the APR_EXCL,
388  * APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK,
389  * APR_SENDFILE_ENABLED and APR_LARGEFILE flags should
390  * be used. The APR_READ flag will be set unconditionally.
391  * @param pool The pool to allocate the file out of.
392  *
393  * @remark See remarks for apr_file_open_stderr.
394  */
396  apr_int32_t flags,
397  apr_pool_t *pool);
398 
399 /**
400  * Read data from the specified file.
401  * @param thefile The file descriptor to read from.
402  * @param buf The buffer to store the data to.
403  * @param nbytes On entry, the number of bytes to read; on exit, the number
404  * of bytes read.
405  *
406  * @remark apr_file_read will read up to the specified number of
407  * bytes, but never more. If there isn't enough data to fill that
408  * number of bytes, all of the available data is read. The third
409  * argument is modified to reflect the number of bytes read. If a
410  * char was put back into the stream via ungetc, it will be the first
411  * character returned.
412  *
413  * @remark It is not possible for both bytes to be read and an APR_EOF
414  * or other error to be returned. APR_EINTR is never returned.
415  */
416 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
417  apr_size_t *nbytes);
418 
419 /**
420  * Write data to the specified file.
421  * @param thefile The file descriptor to write to.
422  * @param buf The buffer which contains the data.
423  * @param nbytes On entry, the number of bytes to write; on exit, the number
424  * of bytes written.
425  *
426  * @remark apr_file_write will write up to the specified number of
427  * bytes, but never more. If the OS cannot write that many bytes, it
428  * will write as many as it can. The third argument is modified to
429  * reflect the * number of bytes written.
430  *
431  * @remark It is possible for both bytes to be written and an error to
432  * be returned. APR_EINTR is never returned.
433  */
434 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
435  apr_size_t *nbytes);
436 
437 /**
438  * Write data from iovec array to the specified file.
439  * @param thefile The file descriptor to write to.
440  * @param vec The array from which to get the data to write to the file.
441  * @param nvec The number of elements in the struct iovec array. This must
442  * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function
443  * will fail with APR_EINVAL.
444  * @param nbytes The number of bytes written.
445  *
446  * @remark It is possible for both bytes to be written and an error to
447  * be returned. APR_EINTR is never returned.
448  *
449  * @remark apr_file_writev is available even if the underlying
450  * operating system doesn't provide writev().
451  */
453  const struct iovec *vec,
454  apr_size_t nvec, apr_size_t *nbytes);
455 
456 /**
457  * Read data from the specified file, ensuring that the buffer is filled
458  * before returning.
459  * @param thefile The file descriptor to read from.
460  * @param buf The buffer to store the data to.
461  * @param nbytes The number of bytes to read.
462  * @param bytes_read If non-NULL, this will contain the number of bytes read.
463  *
464  * @remark apr_file_read will read up to the specified number of
465  * bytes, but never more. If there isn't enough data to fill that
466  * number of bytes, then the process/thread will block until it is
467  * available or EOF is reached. If a char was put back into the
468  * stream via ungetc, it will be the first character returned.
469  *
470  * @remark It is possible for both bytes to be read and an error to be
471  * returned. And if *bytes_read is less than nbytes, an accompanying
472  * error is _always_ returned.
473  *
474  * @remark APR_EINTR is never returned.
475  */
477  apr_size_t nbytes,
478  apr_size_t *bytes_read);
479 
480 /**
481  * Write data to the specified file, ensuring that all of the data is
482  * written before returning.
483  * @param thefile The file descriptor to write to.
484  * @param buf The buffer which contains the data.
485  * @param nbytes The number of bytes to write.
486  * @param bytes_written If non-NULL, set to the number of bytes written.
487  *
488  * @remark apr_file_write will write up to the specified number of
489  * bytes, but never more. If the OS cannot write that many bytes, the
490  * process/thread will block until they can be written. Exceptional
491  * error such as "out of space" or "pipe closed" will terminate with
492  * an error.
493  *
494  * @remark It is possible for both bytes to be written and an error to
495  * be returned. And if *bytes_written is less than nbytes, an
496  * accompanying error is _always_ returned.
497  *
498  * @remark APR_EINTR is never returned.
499  */
501  const void *buf,
502  apr_size_t nbytes,
503  apr_size_t *bytes_written);
504 
505 
506 /**
507  * Write data from iovec array to the specified file, ensuring that all of the
508  * data is written before returning.
509  * @param thefile The file descriptor to write to.
510  * @param vec The array from which to get the data to write to the file.
511  * @param nvec The number of elements in the struct iovec array. This must
512  * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function
513  * will fail with APR_EINVAL.
514  * @param nbytes The number of bytes written.
515  *
516  * @remark apr_file_writev_full is available even if the underlying
517  * operating system doesn't provide writev().
518  */
520  const struct iovec *vec,
521  apr_size_t nvec,
522  apr_size_t *nbytes);
523 /**
524  * Write a character into the specified file.
525  * @param ch The character to write.
526  * @param thefile The file descriptor to write to
527  */
529 
530 /**
531  * Read a character from the specified file.
532  * @param ch The character to read into
533  * @param thefile The file descriptor to read from
534  */
535 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
536 
537 /**
538  * Put a character back onto a specified stream.
539  * @param ch The character to write.
540  * @param thefile The file descriptor to write to
541  */
543 
544 /**
545  * Read a line from the specified file
546  * @param str The buffer to store the string in.
547  * @param len The length of the string
548  * @param thefile The file descriptor to read from
549  * @remark The buffer will be NUL-terminated if any characters are stored.
550  * The newline at the end of the line will not be stripped.
551  */
552 APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len,
553  apr_file_t *thefile);
554 
555 /**
556  * Write the string into the specified file.
557  * @param str The string to write.
558  * @param thefile The file descriptor to write to
559  */
560 APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
561 
562 /**
563  * Flush the file's buffer.
564  * @param thefile The file descriptor to flush
565  */
567 
568 /**
569  * Transfer all file modified data and metadata to disk.
570  * @param thefile The file descriptor to sync
571  */
573 
574 /**
575  * Transfer all file modified data to disk.
576  * @param thefile The file descriptor to sync
577  */
579 
580 /**
581  * Duplicate the specified file descriptor.
582  * @param new_file The structure to duplicate into.
583  * @param old_file The file to duplicate.
584  * @param p The pool to use for the new file.
585  * @remark *new_file must point to a valid apr_file_t, or point to NULL.
586  */
588  apr_file_t *old_file,
589  apr_pool_t *p);
590 
591 /**
592  * Duplicate the specified file descriptor and close the original
593  * @param new_file The old file that is to be closed and reused
594  * @param old_file The file to duplicate
595  * @param p The pool to use for the new file
596  *
597  * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
598  */
600  apr_file_t *old_file,
601  apr_pool_t *p);
602 
603 /**
604  * Move the specified file descriptor to a new pool
605  * @param new_file Pointer in which to return the new apr_file_t
606  * @param old_file The file to move
607  * @param p The pool to which the descriptor is to be moved
608  * @remark Unlike apr_file_dup2(), this function doesn't do an
609  * OS dup() operation on the underlying descriptor; it just
610  * moves the descriptor's apr_file_t wrapper to a new pool.
611  * @remark The new pool need not be an ancestor of old_file's pool.
612  * @remark After calling this function, old_file may not be used
613  */
615  apr_file_t *old_file,
616  apr_pool_t *p);
617 
618 /**
619  * Give the specified apr file handle a new buffer
620  * @param thefile The file handle that is to be modified
621  * @param buffer The buffer
622  * @param bufsize The size of the buffer
623  * @remark It is possible to add a buffer to previously unbuffered
624  * file handles, the APR_BUFFERED flag will be added to
625  * the file handle's flags. Likewise, with buffer=NULL and
626  * bufsize=0 arguments it is possible to make a previously
627  * buffered file handle unbuffered.
628  */
630  char * buffer,
631  apr_size_t bufsize);
632 
633 /**
634  * Get the size of any buffer for the specified apr file handle
635  * @param thefile The file handle
636  */
637 APR_DECLARE(apr_size_t) apr_file_buffer_size_get(apr_file_t *thefile);
638 
639 /**
640  * Move the read/write file offset to a specified byte within a file.
641  * @param thefile The file descriptor
642  * @param where How to move the pointer, one of:
643  * <PRE>
644  * APR_SET -- set the offset to offset
645  * APR_CUR -- add the offset to the current position
646  * APR_END -- add the offset to the current file size
647  * </PRE>
648  * @param offset The offset to move the pointer to.
649  * @remark The third argument is modified to be the offset the pointer
650  was actually moved to.
651  */
653  apr_seek_where_t where,
654  apr_off_t *offset);
655 
656 /**
657  * Create an anonymous pipe.
658  * @param in The newly created pipe's file for reading.
659  * @param out The newly created pipe's file for writing.
660  * @param pool The pool to operate on.
661  * @remark By default, the returned file descriptors will be inherited
662  * by child processes created using apr_proc_create(). This can be
663  * changed using apr_file_inherit_unset().
664  * @bug Some platforms cannot toggle between blocking and nonblocking,
665  * and when passing a pipe as a standard handle to an application which
666  * does not expect it, a non-blocking stream will fluxor the client app.
667  * @deprecated @see apr_file_pipe_create_ex
668  */
670  apr_file_t **out,
671  apr_pool_t *pool);
672 
673 /**
674  * Create an anonymous pipe which portably supports async timeout options.
675  * @param in The newly created pipe's file for reading.
676  * @param out The newly created pipe's file for writing.
677  * @param blocking one of these values defined in apr_thread_proc.h;
678  * @param pool The pool to operate on.
679  * <pre>
680  * APR_FULL_BLOCK
681  * APR_READ_BLOCK
682  * APR_WRITE_BLOCK
683  * APR_FULL_NONBLOCK
684  * </pre>
685  * @remark By default, the returned file descriptors will be inherited
686  * by child processes created using apr_proc_create(). This can be
687  * changed using apr_file_inherit_unset().
688  * @remark Some platforms cannot toggle between blocking and nonblocking,
689  * and when passing a pipe as a standard handle to an application which
690  * does not expect it, a non-blocking stream will fluxor the client app.
691  * Use this function rather than apr_file_pipe_create to create pipes
692  * where one or both ends require non-blocking semantics.
693  */
695  apr_file_t **out,
696  apr_int32_t blocking,
697  apr_pool_t *pool);
698 
699 /**
700  * Create a named pipe.
701  * @param filename The filename of the named pipe
702  * @param perm The permissions for the newly created pipe.
703  * @param pool The pool to operate on.
704  */
705 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
706  apr_fileperms_t perm,
707  apr_pool_t *pool);
708 
709 /**
710  * Get the timeout value for a pipe or manipulate the blocking state.
711  * @param thepipe The pipe we are getting a timeout for.
712  * @param timeout The current timeout value in microseconds.
713  */
715  apr_interval_time_t *timeout);
716 
717 /**
718  * Set the timeout value for a pipe or manipulate the blocking state.
719  * @param thepipe The pipe we are setting a timeout on.
720  * @param timeout The timeout value in microseconds. Values < 0 mean wait
721  * forever, 0 means do not wait at all.
722  */
724  apr_interval_time_t timeout);
725 
726 /** file (un)locking functions. */
727 
728 /**
729  * Establish a lock on the specified, open file. The lock may be advisory
730  * or mandatory, at the discretion of the platform. The lock applies to
731  * the file as a whole, rather than a specific range. Locks are established
732  * on a per-thread/process basis; a second lock by the same thread will not
733  * block.
734  * @param thefile The file to lock.
735  * @param type The type of lock to establish on the file.
736  */
737 APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
738 
739 /**
740  * Remove any outstanding locks on the file.
741  * @param thefile The file to unlock.
742  */
744 
745 /**accessor and general file_io functions. */
746 
747 /**
748  * return the file name of the current file.
749  * @param new_path The path of the file.
750  * @param thefile The currently open file.
751  */
752 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
753  apr_file_t *thefile);
754 
755 /**
756  * Return the data associated with the current file.
757  * @param data The user data associated with the file.
758  * @param key The key to use for retrieving data associated with this file.
759  * @param file The currently open file.
760  */
761 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
762  apr_file_t *file);
763 
764 /**
765  * Set the data associated with the current file.
766  * @param file The currently open file.
767  * @param data The user data to associate with the file.
768  * @param key The key to use for associating data with the file.
769  * @param cleanup The cleanup routine to use when the file is destroyed.
770  */
772  const char *key,
773  apr_status_t (*cleanup)(void *));
774 
775 /**
776  * Write a string to a file using a printf format.
777  * @param fptr The file to write to.
778  * @param format The format string
779  * @param ... The values to substitute in the format string
780  * @return The number of bytes written
781  */
783  const char *format, ...)
784  __attribute__((format(printf,2,3)));
785 
786 /**
787  * set the specified file's permission bits.
788  * @param fname The file (name) to apply the permissions to.
789  * @param perms The permission bits to apply to the file.
790  *
791  * @warning Some platforms may not be able to apply all of the
792  * available permission bits; APR_INCOMPLETE will be returned if some
793  * permissions are specified which could not be set.
794  *
795  * @warning Platforms which do not implement this feature will return
796  * APR_ENOTIMPL.
797  */
798 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
799  apr_fileperms_t perms);
800 
801 /**
802  * Set attributes of the specified file.
803  * @param fname The full path to the file (using / on all systems)
804  * @param attributes Or'd combination of
805  * <PRE>
806  * APR_FILE_ATTR_READONLY - make the file readonly
807  * APR_FILE_ATTR_EXECUTABLE - make the file executable
808  * APR_FILE_ATTR_HIDDEN - make the file hidden
809  * </PRE>
810  * @param attr_mask Mask of valid bits in attributes.
811  * @param pool the pool to use.
812  * @remark This function should be used in preference to explicit manipulation
813  * of the file permissions, because the operations to provide these
814  * attributes are platform specific and may involve more than simply
815  * setting permission bits.
816  * @warning Platforms which do not implement this feature will return
817  * APR_ENOTIMPL.
818  */
819 APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
820  apr_fileattrs_t attributes,
821  apr_fileattrs_t attr_mask,
822  apr_pool_t *pool);
823 
824 /**
825  * Set the mtime of the specified file.
826  * @param fname The full path to the file (using / on all systems)
827  * @param mtime The mtime to apply to the file.
828  * @param pool The pool to use.
829  * @warning Platforms which do not implement this feature will return
830  * APR_ENOTIMPL.
831  */
832 APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
833  apr_time_t mtime,
834  apr_pool_t *pool);
835 
836 /**
837  * Create a new directory on the file system.
838  * @param path the path for the directory to be created. (use / on all systems)
839  * @param perm Permissions for the new directory.
840  * @param pool the pool to use.
841  */
842 APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
843  apr_pool_t *pool);
844 
845 /** Creates a new directory on the file system, but behaves like
846  * 'mkdir -p'. Creates intermediate directories as required. No error
847  * will be reported if PATH already exists.
848  * @param path the path for the directory to be created. (use / on all systems)
849  * @param perm Permissions for the new directory.
850  * @param pool the pool to use.
851  */
853  apr_fileperms_t perm,
854  apr_pool_t *pool);
855 
856 /**
857  * Remove directory from the file system.
858  * @param path the path for the directory to be removed. (use / on all systems)
859  * @param pool the pool to use.
860  * @remark Removing a directory which is in-use (e.g., the current working
861  * directory, or during apr_dir_read, or with an open file) is not portable.
862  */
863 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
864 
865 /**
866  * get the specified file's stats.
867  * @param finfo Where to store the information about the file.
868  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
869  * @param thefile The file to get information about.
870  */
872  apr_int32_t wanted,
873  apr_file_t *thefile);
874 
875 
876 /**
877  * Truncate the file's length to the specified offset
878  * @param fp The file to truncate
879  * @param offset The offset to truncate to.
880  * @remark The read/write file offset is repositioned to offset.
881  */
882 APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
883 
884 /**
885  * Retrieve the flags that were passed into apr_file_open()
886  * when the file was opened.
887  * @return apr_int32_t the flags
888  */
889 APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
890 
891 /**
892  * Get the pool used by the file.
893  */
895 
896 /**
897  * Set a file to be inherited by child processes.
898  *
899  */
901 
902 /**
903  * Unset a file from being inherited by child processes.
904  */
906 
907 /**
908  * Open a temporary file
909  * @param fp The apr file to use as a temporary file.
910  * @param templ The template to use when creating a temp file.
911  * @param flags The flags to open the file with. If this is zero,
912  * the file is opened with
913  * APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
914  * @param p The pool to allocate the file out of.
915  * @remark
916  * This function generates a unique temporary file name from template.
917  * The last six characters of template must be XXXXXX and these are replaced
918  * with a string that makes the filename unique. Since it will be modified,
919  * template must not be a string constant, but should be declared as a character
920  * array.
921  *
922  */
924  apr_int32_t flags, apr_pool_t *p);
925 
926 
927 /**
928  * Find an existing directory suitable as a temporary storage location.
929  * @param temp_dir The temp directory.
930  * @param p The pool to use for any necessary allocations.
931  * @remark
932  * This function uses an algorithm to search for a directory that an
933  * an application can use for temporary storage.
934  *
935  */
936 APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir,
937  apr_pool_t *p);
938 
939 /** @} */
940 
941 #ifdef __cplusplus
942 }
943 #endif
944 
945 #endif /* ! APR_FILE_IO_H */