1
/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
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.
22
* @brief APR File I/O Handling
26
#include "apr_pools.h"
28
#include "apr_errno.h"
29
#include "apr_file_info.h"
30
#include "apr_inherit.h"
32
#define APR_WANT_STDIO /**< for SEEK_* */
33
#define APR_WANT_IOVEC /**< for apr_file_writev */
38
#endif /* __cplusplus */
41
* @defgroup apr_file_io File I/O Handling Functions
47
* @defgroup apr_file_open_flags File Open Flags/Routines
51
/* Note to implementors: Values in the range 0x00100000--0x80000000
52
are reserved for platform-specific values. */
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
60
#define APR_FOPEN_BINARY 0x00020 /**< Open the file in binary mode */
61
#define APR_FOPEN_EXCL 0x00040 /**< Open should fail if APR_CREATE
63
#define APR_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */
64
#define APR_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */
65
#define APR_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open
66
the file for use across multiple
68
#define APR_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for
69
higher level locked read/write
70
access to support writes across
72
#define APR_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup
73
when the file is opened */
74
#define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
76
apr_socket_sendfile operation */
77
#define APR_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable
78
large file support; WARNING see
81
#define APR_READ APR_FOPEN_READ /**< @deprecated @see APR_FOPEN_READ */
82
#define APR_WRITE APR_FOPEN_WRITE /**< @deprecated @see APR_FOPEN_WRITE */
83
#define APR_CREATE APR_FOPEN_CREATE /**< @deprecated @see APR_FOPEN_CREATE */
84
#define APR_APPEND APR_FOPEN_APPEND /**< @deprecated @see APR_FOPEN_APPEND */
85
#define APR_TRUNCATE APR_FOPEN_TRUNCATE /**< @deprecated @see APR_FOPEN_TRUNCATE */
86
#define APR_BINARY APR_FOPEN_BINARY /**< @deprecated @see APR_FOPEN_BINARY */
87
#define APR_EXCL APR_FOPEN_EXCL /**< @deprecated @see APR_FOPEN_EXCL */
88
#define APR_BUFFERED APR_FOPEN_BUFFERED /**< @deprecated @see APR_FOPEN_BUFFERED */
89
#define APR_DELONCLOSE APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */
90
#define APR_XTHREAD APR_FOPEN_XTHREAD /**< @deprecated @see APR_FOPEN_XTHREAD */
91
#define APR_SHARELOCK APR_FOPEN_SHARELOCK /**< @deprecated @see APR_FOPEN_SHARELOCK */
92
#define APR_FILE_NOCLEANUP APR_FOPEN_NOCLEANUP /**< @deprecated @see APR_FOPEN_NOCLEANUP */
93
#define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */
94
#define APR_LARGEFILE APR_FOPEN_LARGEFILE /**< @deprecated @see APR_FOPEN_LARGEFILE */
96
/** @warning The APR_LARGEFILE flag only has effect on some platforms
97
* where sizeof(apr_off_t) == 4. Where implemented, it allows opening
98
* and writing to a file which exceeds the size which can be
99
* represented by apr_off_t (2 gigabytes). When a file's size does
100
* exceed 2Gb, apr_file_info_get() will fail with an error on the
101
* descriptor, likewise apr_stat()/apr_lstat() will fail on the
102
* filename. apr_dir_read() will fail with APR_INCOMPLETE on a
103
* directory entry for a large file depending on the particular
104
* APR_FINFO_* flags. Generally, it is not recommended to use this
110
* @defgroup apr_file_seek_flags File Seek Flags
114
/* flags for apr_file_seek */
115
/** Set the file position */
116
#define APR_SET SEEK_SET
118
#define APR_CUR SEEK_CUR
119
/** Go to end of file */
120
#define APR_END SEEK_END
124
* @defgroup apr_file_attrs_set_flags File Attribute Flags
128
/* flags for apr_file_attrs_set */
129
#define APR_FILE_ATTR_READONLY 0x01 /**< File is read-only */
130
#define APR_FILE_ATTR_EXECUTABLE 0x02 /**< File is executable */
131
#define APR_FILE_ATTR_HIDDEN 0x04 /**< File is hidden */
135
* @defgroup apr_file_writev{_full} max iovec size
139
#define APR_MAX_IOVEC_SIZE 1024 /**< System dependent maximum
140
size of an iovec array */
141
#elif defined(IOV_MAX)
142
#define APR_MAX_IOVEC_SIZE IOV_MAX
143
#elif defined(MAX_IOVEC)
144
#define APR_MAX_IOVEC_SIZE MAX_IOVEC
146
#define APR_MAX_IOVEC_SIZE 1024
150
/** File attributes */
151
typedef apr_uint32_t apr_fileattrs_t;
153
/** Type to pass as whence argument to apr_file_seek. */
154
typedef int apr_seek_where_t;
157
* Structure for referencing files.
159
typedef struct apr_file_t apr_file_t;
161
/* File lock types/flags */
163
* @defgroup apr_file_lock_types File Lock Types
167
#define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process
168
or thread can hold a shared lock
169
at any given time. Essentially,
170
this is a "read lock", preventing
171
writers from establishing an
173
#define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process
174
may hold an exclusive lock at any
175
given time. This is analogous to
178
#define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
179
#define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
184
* Open the specified file.
185
* @param newf The opened file descriptor.
186
* @param fname The full path to the file (using / on all systems)
187
* @param flag Or'ed value of:
189
* APR_READ open for reading
190
* APR_WRITE open for writing
191
* APR_CREATE create the file if not there
192
* APR_APPEND file ptr is set to end prior to all writes
193
* APR_TRUNCATE set length to zero if file exists
194
* APR_BINARY not a text file (This flag is ignored on
195
* UNIX because it has no meaning)
196
* APR_BUFFERED buffer the data. Default is non-buffered
197
* APR_EXCL return error if APR_CREATE and file exists
198
* APR_DELONCLOSE delete the file after closing.
199
* APR_XTHREAD Platform dependent tag to open the file
200
* for use across multiple threads
201
* APR_SHARELOCK Platform dependent support for higher
202
* level locked read/write access to support
203
* writes across process/machines
204
* APR_FILE_NOCLEANUP Do not register a cleanup with the pool
205
* passed in on the <EM>pool</EM> argument (see below).
206
* The apr_os_file_t handle in apr_file_t will not
207
* be closed when the pool is destroyed.
208
* APR_SENDFILE_ENABLED Open with appropriate platform semantics
209
* for sendfile operations. Advisory only,
210
* apr_socket_sendfile does not check this flag.
212
* @param perm Access permissions for file.
213
* @param pool The pool to use.
214
* @remark If perm is APR_OS_DEFAULT and the file is being created,
215
* appropriate default permissions will be used.
217
APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
218
apr_int32_t flag, apr_fileperms_t perm,
222
* Close the specified file.
223
* @param file The file descriptor to close.
225
APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
228
* Delete the specified file.
229
* @param path The full path to the file (using / on all systems)
230
* @param pool The pool to use.
231
* @remark If the file is open, it won't be removed until all
232
* instances are closed.
234
APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
237
* Rename the specified file.
238
* @param from_path The full path to the original file (using / on all systems)
239
* @param to_path The full path to the new file (using / on all systems)
240
* @param pool The pool to use.
241
* @warning If a file exists at the new location, then it will be
242
* overwritten. Moving files or directories across devices may not be
245
APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path,
250
* Copy the specified file to another file.
251
* @param from_path The full path to the original file (using / on all systems)
252
* @param to_path The full path to the new file (using / on all systems)
253
* @param perms Access permissions for the new file if it is created.
254
* In place of the usual or'd combination of file permissions, the
255
* value APR_FILE_SOURCE_PERMS may be given, in which case the source
256
* file's permissions are copied.
257
* @param pool The pool to use.
258
* @remark The new file does not need to exist, it will be created if required.
259
* @warning If the new file already exists, its contents will be overwritten.
261
APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
263
apr_fileperms_t perms,
267
* Append the specified file to another file.
268
* @param from_path The full path to the source file (use / on all systems)
269
* @param to_path The full path to the destination file (use / on all systems)
270
* @param perms Access permissions for the destination file if it is created.
271
* In place of the usual or'd combination of file permissions, the
272
* value APR_FILE_SOURCE_PERMS may be given, in which case the source
273
* file's permissions are copied.
274
* @param pool The pool to use.
275
* @remark The new file does not need to exist, it will be created if required.
277
APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
279
apr_fileperms_t perms,
283
* Are we at the end of the file
284
* @param fptr The apr file we are testing.
285
* @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
287
APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
290
* Open standard error as an apr file pointer.
291
* @param thefile The apr file to use as stderr.
292
* @param pool The pool to allocate the file out of.
294
* @remark The only reason that the apr_file_open_std* functions exist
295
* is that you may not always have a stderr/out/in on Windows. This
296
* is generally a problem with newer versions of Windows and services.
298
* @remark The other problem is that the C library functions generally work
299
* differently on Windows and Unix. So, by using apr_file_open_std*
300
* functions, you can get a handle to an APR struct that works with
301
* the APR functions which are supposed to work identically on all
304
APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
308
* open standard output as an apr file pointer.
309
* @param thefile The apr file to use as stdout.
310
* @param pool The pool to allocate the file out of.
312
* @remark See remarks for apr_file_open_stdout.
314
APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
318
* open standard input as an apr file pointer.
319
* @param thefile The apr file to use as stdin.
320
* @param pool The pool to allocate the file out of.
322
* @remark See remarks for apr_file_open_stdout.
324
APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
328
* Read data from the specified file.
329
* @param thefile The file descriptor to read from.
330
* @param buf The buffer to store the data to.
331
* @param nbytes On entry, the number of bytes to read; on exit, the number
334
* @remark apr_file_read will read up to the specified number of
335
* bytes, but never more. If there isn't enough data to fill that
336
* number of bytes, all of the available data is read. The third
337
* argument is modified to reflect the number of bytes read. If a
338
* char was put back into the stream via ungetc, it will be the first
339
* character returned.
341
* @remark It is not possible for both bytes to be read and an APR_EOF
342
* or other error to be returned. APR_EINTR is never returned.
344
APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
348
* Write data to the specified file.
349
* @param thefile The file descriptor to write to.
350
* @param buf The buffer which contains the data.
351
* @param nbytes On entry, the number of bytes to write; on exit, the number
354
* @remark apr_file_write will write up to the specified number of
355
* bytes, but never more. If the OS cannot write that many bytes, it
356
* will write as many as it can. The third argument is modified to
357
* reflect the * number of bytes written.
359
* @remark It is possible for both bytes to be written and an error to
360
* be returned. APR_EINTR is never returned.
362
APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
366
* Write data from iovec array to the specified file.
367
* @param thefile The file descriptor to write to.
368
* @param vec The array from which to get the data to write to the file.
369
* @param nvec The number of elements in the struct iovec array. This must
370
* be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function
371
* will fail with APR_EINVAL.
372
* @param nbytes The number of bytes written.
374
* @remark It is possible for both bytes to be written and an error to
375
* be returned. APR_EINTR is never returned.
377
* @remark apr_file_writev is available even if the underlying
378
* operating system doesn't provide writev().
380
APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
381
const struct iovec *vec,
382
apr_size_t nvec, apr_size_t *nbytes);
385
* Read data from the specified file, ensuring that the buffer is filled
387
* @param thefile The file descriptor to read from.
388
* @param buf The buffer to store the data to.
389
* @param nbytes The number of bytes to read.
390
* @param bytes_read If non-NULL, this will contain the number of bytes read.
392
* @remark apr_file_read will read up to the specified number of
393
* bytes, but never more. If there isn't enough data to fill that
394
* number of bytes, then the process/thread will block until it is
395
* available or EOF is reached. If a char was put back into the
396
* stream via ungetc, it will be the first character returned.
398
* @remark It is possible for both bytes to be read and an error to be
399
* returned. And if *bytes_read is less than nbytes, an accompanying
400
* error is _always_ returned.
402
* @remark APR_EINTR is never returned.
404
APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
406
apr_size_t *bytes_read);
409
* Write data to the specified file, ensuring that all of the data is
410
* written before returning.
411
* @param thefile The file descriptor to write to.
412
* @param buf The buffer which contains the data.
413
* @param nbytes The number of bytes to write.
414
* @param bytes_written If non-NULL, set to the number of bytes written.
416
* @remark apr_file_write will write up to the specified number of
417
* bytes, but never more. If the OS cannot write that many bytes, the
418
* process/thread will block until they can be written. Exceptional
419
* error such as "out of space" or "pipe closed" will terminate with
422
* @remark It is possible for both bytes to be written and an error to
423
* be returned. And if *bytes_written is less than nbytes, an
424
* accompanying error is _always_ returned.
426
* @remark APR_EINTR is never returned.
428
APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile,
431
apr_size_t *bytes_written);
435
* Write data from iovec array to the specified file, ensuring that all of the
436
* data is written before returning.
437
* @param thefile The file descriptor to write to.
438
* @param vec The array from which to get the data to write to the file.
439
* @param nvec The number of elements in the struct iovec array. This must
440
* be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function
441
* will fail with APR_EINVAL.
442
* @param nbytes The number of bytes written.
444
* @remark apr_file_writev_full is available even if the underlying
445
* operating system doesn't provide writev().
447
APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile,
448
const struct iovec *vec,
452
* Write a character into the specified file.
453
* @param ch The character to write.
454
* @param thefile The file descriptor to write to
456
APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
459
* Read a character from the specified file.
460
* @param ch The character to read into
461
* @param thefile The file descriptor to read from
463
APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
466
* Put a character back onto a specified stream.
467
* @param ch The character to write.
468
* @param thefile The file descriptor to write to
470
APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
473
* Read a string from the specified file.
474
* @param str The buffer to store the string in.
475
* @param len The length of the string
476
* @param thefile The file descriptor to read from
477
* @remark The buffer will be NUL-terminated if any characters are stored.
479
APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len,
480
apr_file_t *thefile);
483
* Write the string into the specified file.
484
* @param str The string to write.
485
* @param thefile The file descriptor to write to
487
APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
490
* Flush the file's buffer.
491
* @param thefile The file descriptor to flush
493
APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
496
* Duplicate the specified file descriptor.
497
* @param new_file The structure to duplicate into.
498
* @param old_file The file to duplicate.
499
* @param p The pool to use for the new file.
500
* @remark *new_file must point to a valid apr_file_t, or point to NULL.
502
APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
503
apr_file_t *old_file,
507
* Duplicate the specified file descriptor and close the original
508
* @param new_file The old file that is to be closed and reused
509
* @param old_file The file to duplicate
510
* @param p The pool to use for the new file
512
* @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
514
APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
515
apr_file_t *old_file,
519
* Move the specified file descriptor to a new pool
520
* @param new_file Pointer in which to return the new apr_file_t
521
* @param old_file The file to move
522
* @param p The pool to which the descriptor is to be moved
523
* @remark Unlike apr_file_dup2(), this function doesn't do an
524
* OS dup() operation on the underlying descriptor; it just
525
* moves the descriptor's apr_file_t wrapper to a new pool.
526
* @remark The new pool need not be an ancestor of old_file's pool.
527
* @remark After calling this function, old_file may not be used
529
APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
530
apr_file_t *old_file,
534
* Move the read/write file offset to a specified byte within a file.
535
* @param thefile The file descriptor
536
* @param where How to move the pointer, one of:
538
* APR_SET -- set the offset to offset
539
* APR_CUR -- add the offset to the current position
540
* APR_END -- add the offset to the current file size
542
* @param offset The offset to move the pointer to.
543
* @remark The third argument is modified to be the offset the pointer
544
was actually moved to.
546
APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
547
apr_seek_where_t where,
551
* Create an anonymous pipe.
552
* @param in The file descriptor to use as input to the pipe.
553
* @param out The file descriptor to use as output from the pipe.
554
* @param pool The pool to operate on.
556
APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in,
561
* Create a named pipe.
562
* @param filename The filename of the named pipe
563
* @param perm The permissions for the newly created pipe.
564
* @param pool The pool to operate on.
566
APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename,
567
apr_fileperms_t perm,
571
* Get the timeout value for a pipe or manipulate the blocking state.
572
* @param thepipe The pipe we are getting a timeout for.
573
* @param timeout The current timeout value in microseconds.
575
APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
576
apr_interval_time_t *timeout);
579
* Set the timeout value for a pipe or manipulate the blocking state.
580
* @param thepipe The pipe we are setting a timeout on.
581
* @param timeout The timeout value in microseconds. Values < 0 mean wait
582
* forever, 0 means do not wait at all.
584
APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe,
585
apr_interval_time_t timeout);
587
/** file (un)locking functions. */
590
* Establish a lock on the specified, open file. The lock may be advisory
591
* or mandatory, at the discretion of the platform. The lock applies to
592
* the file as a whole, rather than a specific range. Locks are established
593
* on a per-thread/process basis; a second lock by the same thread will not
595
* @param thefile The file to lock.
596
* @param type The type of lock to establish on the file.
598
APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
601
* Remove any outstanding locks on the file.
602
* @param thefile The file to unlock.
604
APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
606
/**accessor and general file_io functions. */
609
* return the file name of the current file.
610
* @param new_path The path of the file.
611
* @param thefile The currently open file.
613
APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
614
apr_file_t *thefile);
617
* Return the data associated with the current file.
618
* @param data The user data associated with the file.
619
* @param key The key to use for retreiving data associated with this file.
620
* @param file The currently open file.
622
APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
626
* Set the data associated with the current file.
627
* @param file The currently open file.
628
* @param data The user data to associate with the file.
629
* @param key The key to use for assocaiteing data with the file.
630
* @param cleanup The cleanup routine to use when the file is destroyed.
632
APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
634
apr_status_t (*cleanup)(void *));
637
* Write a string to a file using a printf format.
638
* @param fptr The file to write to.
639
* @param format The format string
640
* @param ... The values to substitute in the format string
641
* @return The number of bytes written
643
APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr,
644
const char *format, ...)
645
__attribute__((format(printf,2,3)));
648
* set the specified file's permission bits.
649
* @param fname The file (name) to apply the permissions to.
650
* @param perms The permission bits to apply to the file.
652
* @warning Some platforms may not be able to apply all of the
653
* available permission bits; APR_INCOMPLETE will be returned if some
654
* permissions are specified which could not be set.
656
* @warning Platforms which do not implement this feature will return
659
APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
660
apr_fileperms_t perms);
663
* Set attributes of the specified file.
664
* @param fname The full path to the file (using / on all systems)
665
* @param attributes Or'd combination of
667
* APR_FILE_ATTR_READONLY - make the file readonly
668
* APR_FILE_ATTR_EXECUTABLE - make the file executable
669
* APR_FILE_ATTR_HIDDEN - make the file hidden
671
* @param attr_mask Mask of valid bits in attributes.
672
* @param pool the pool to use.
673
* @remark This function should be used in preference to explict manipulation
674
* of the file permissions, because the operations to provide these
675
* attributes are platform specific and may involve more than simply
676
* setting permission bits.
677
* @warning Platforms which do not implement this feature will return
680
APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
681
apr_fileattrs_t attributes,
682
apr_fileattrs_t attr_mask,
686
* Set the mtime of the specified file.
687
* @param fname The full path to the file (using / on all systems)
688
* @param mtime The mtime to apply to the file.
689
* @param pool The pool to use.
690
* @warning Platforms which do not implement this feature will return
693
APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
698
* Create a new directory on the file system.
699
* @param path the path for the directory to be created. (use / on all systems)
700
* @param perm Permissions for the new direcoty.
701
* @param pool the pool to use.
703
APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
706
/** Creates a new directory on the file system, but behaves like
707
* 'mkdir -p'. Creates intermediate directories as required. No error
708
* will be reported if PATH already exists.
709
* @param path the path for the directory to be created. (use / on all systems)
710
* @param perm Permissions for the new direcoty.
711
* @param pool the pool to use.
713
APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
714
apr_fileperms_t perm,
718
* Remove directory from the file system.
719
* @param path the path for the directory to be removed. (use / on all systems)
720
* @param pool the pool to use.
722
APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
725
* get the specified file's stats.
726
* @param finfo Where to store the information about the file.
727
* @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
728
* @param thefile The file to get information about.
730
APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
732
apr_file_t *thefile);
736
* Truncate the file's length to the specified offset
737
* @param fp The file to truncate
738
* @param offset The offset to truncate to.
740
APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
743
* Retrieve the flags that were passed into apr_file_open()
744
* when the file was opened.
745
* @return apr_int32_t the flags
747
APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
750
* Get the pool used by the file.
752
APR_POOL_DECLARE_ACCESSOR(file);
755
* Set a file to be inherited by child processes.
758
APR_DECLARE_INHERIT_SET(file);
761
* Unset a file from being inherited by child processes.
763
APR_DECLARE_INHERIT_UNSET(file);
766
* Open a temporary file
767
* @param fp The apr file to use as a temporary file.
768
* @param templ The template to use when creating a temp file.
769
* @param flags The flags to open the file with. If this is zero,
770
* the file is opened with
771
* APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
772
* @param p The pool to allocate the file out of.
774
* This function generates a unique temporary file name from template.
775
* The last six characters of template must be XXXXXX and these are replaced
776
* with a string that makes the filename unique. Since it will be modified,
777
* template must not be a string constant, but should be declared as a character
781
APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
782
apr_int32_t flags, apr_pool_t *p);
786
* Find an existing directory suitable as a temporary storage location.
787
* @param temp_dir The temp directory.
788
* @param p The pool to use for any necessary allocations.
790
* This function uses an algorithm to search for a directory that an
791
* an application can use for temporary storage. Once such a
792
* directory is found, that location is cached by the library. Thus,
793
* callers only pay the cost of this algorithm once if that one time
797
APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir,
806
#endif /* ! APR_FILE_IO_H */