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