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