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