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