Apache Portable Runtime
Loading...
Searching...
No Matches
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
37extern "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 */
187typedef apr_uint32_t apr_fileattrs_t;
188
189/** Type to pass as whence argument to apr_file_seek. */
191
192/**
193 * Structure for referencing files.
194 */
195typedef 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 */
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 */
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 */
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 */
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 */
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 */
841APR_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
1019APR_DECLARE(apr_status_t) apr_file_rotating_check(apr_file_t *thefile);
1020APR_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:536
#define APR_DECLARE(type)
Definition apr.h:523
#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