Annotation of parser3/src/lib/sdbm/apr-include/apr_file_io.h, revision 1.4
1.2 paf 1: /* ====================================================================
2: * The Apache Software License, Version 1.1
3: *
4: * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
5: * reserved.
6: *
7: * Redistribution and use in source and binary forms, with or without
8: * modification, are permitted provided that the following conditions
9: * are met:
10: *
11: * 1. Redistributions of source code must retain the above copyright
12: * notice, this list of conditions and the following disclaimer.
13: *
14: * 2. Redistributions in binary form must reproduce the above copyright
15: * notice, this list of conditions and the following disclaimer in
16: * the documentation and/or other materials provided with the
17: * distribution.
18: *
19: * 3. The end-user documentation included with the redistribution,
20: * if any, must include the following acknowledgment:
21: * "This product includes software developed by the
22: * Apache Software Foundation (http://www.apache.org/)."
23: * Alternately, this acknowledgment may appear in the software itself,
24: * if and wherever such third-party acknowledgments normally appear.
25: *
26: * 4. The names "Apache" and "Apache Software Foundation" must
27: * not be used to endorse or promote products derived from this
28: * software without prior written permission. For written
29: * permission, please contact apache@apache.org.
30: *
31: * 5. Products derived from this software may not be called "Apache",
32: * nor may "Apache" appear in their name, without prior written
33: * permission of the Apache Software Foundation.
34: *
35: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46: * SUCH DAMAGE.
47: * ====================================================================
48: *
49: * This software consists of voluntary contributions made by many
50: * individuals on behalf of the Apache Software Foundation. For more
51: * information on the Apache Software Foundation, please see
52: * <http://www.apache.org/>.
53: */
54:
55: #ifndef APR_FILE_IO_H
56: #define APR_FILE_IO_H
57: /**
58: * @file apr_file_io.h
59: * @brief APR File I/O Handling
60: */
61: /**
62: * @defgroup APR_File_IO_Handle I/O Handling Functions
63: * @ingroup APR_File_Handle
64: * @{
65: */
66:
67: #include <stdio.h>
68:
69: #include "apr_errno.h"
70: #include "apr_pools.h"
71: #include "apr_file_info.h"
72:
73: #ifdef __cplusplus
74: extern "C" {
75: #endif /* __cplusplus */
76:
77: /**
78: * @defgroup apr_file_open File Open Flags/Routines
79: * @{
80: */
81:
82: #define APR_READ 1 /**< Open the file for reading */
83: #define APR_WRITE 2 /**< Open the file for writing */
84: #define APR_CREATE 4 /**< Create the file if not there */
85: #define APR_APPEND 8 /**< Append to the end of the file */
86: #define APR_TRUNCATE 16 /**< Open the file and truncate to 0 length */
87: #define APR_BINARY 32 /**< Open the file in binary mode */
88: #define APR_EXCL 64 /**< Open should fail if APR_CREATE and file
89: exists. */
90: #define APR_BUFFERED 128 /**< Open the file for buffered I/O */
91: #define APR_DELONCLOSE 256 /**< Delete the file after close */
92: #define APR_XTHREAD 512 /**< Platform dependent tag to open the file
93: for use across multiple threads */
94: #define APR_SHARELOCK 1024 /**< Platform dependent support for higher
95: level locked read/write access to support
96: writes across process/machines */
97: #define APR_FILE_NOCLEANUP 2048 /**< Do not register a cleanup when the file
98: is opened */
99:
100: /** @} */
101:
102: /**
103: * @defgroup APR_file_seek_flags File Seek Flags
104: * @{
105: */
106:
107: /* flags for apr_file_seek */
108: #define APR_SET SEEK_SET
109: #define APR_CUR SEEK_CUR
110: #define APR_END SEEK_END
111: /** @} */
112:
113: /** should be same as whence type in lseek, POSIX defines this as int */
114: typedef int apr_seek_where_t;
115:
116: /**
117: * Structure for referencing files.
118: * @defvar apr_file_t
119: */
120: typedef struct apr_file_t apr_file_t;
121:
122: /* File lock types/flags */
123: /**
124: * @defgroup APR_file_lock_types File Lock Types
125: * @{
126: */
127:
128: #define APR_FLOCK_SHARED 1 /**< Shared lock. More than one process
129: or thread can hold a shared lock
130: at any given time. Essentially,
131: this is a "read lock", preventing
132: writers from establishing an
133: exclusive lock. */
134: #define APR_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process
135: may hold an exclusive lock at any
136: given time. This is analogous to
137: a "write lock". */
138:
139: #define APR_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
140: #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
141: file lock */
142: /** @} */
143:
144: /**
145: * Open the specified file.
146: * @param new_file The opened file descriptor.
147: * @param fname The full path to the file (using / on all systems)
148: * @param flag Or'ed value of:
149: * <PRE>
150: * APR_READ open for reading
151: * APR_WRITE open for writing
152: * APR_CREATE create the file if not there
153: * APR_APPEND file ptr is set to end prior to all writes
154: * APR_TRUNCATE set length to zero if file exists
155: * APR_BINARY not a text file (This flag is ignored on
156: * UNIX because it has no meaning)
157: * APR_BUFFERED buffer the data. Default is non-buffered
158: * APR_EXCL return error if APR_CREATE and file exists
159: * APR_DELONCLOSE delete the file after closing.
160: * APR_XTHREAD Platform dependent tag to open the file
161: * for use across multiple threads
162: * APR_SHARELOCK Platform dependent support for higher
163: * level locked read/write access to support
164: * writes across process/machines
165: * APR_FILE_NOCLEANUP Do not register a cleanup with the pool
166: * passed in on the <EM>cont</EM> argument (see below).
167: * The apr_os_file_t handle in apr_file_t will not
168: & be closed when the pool is destroyed.
169: * </PRE>
170: * @param perm Access permissions for file.
171: * @param cont The pool to use.
172: * @ingroup apr_file_open
173: * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate
174: * default permissions will be used. *arg1 must point to a valid file_t,
175: * or NULL (in which case it will be allocated)
176: */
177: APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **new_file, const char *fname,
178: apr_int32_t flag, apr_fileperms_t perm,
179: apr_pool_t *cont);
180:
181: /**
182: * Close the specified file.
183: * @param file The file descriptor to close.
184: */
185: APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
186:
187:
188: /** file (un)locking functions. */
189:
190: /**
191: * Establish a lock on the specified, open file. The lock may be advisory
192: * or mandatory, at the discretion of the platform. The lock applies to
193: * the file as a whole, rather than a specific range. Locks are established
194: * on a per-thread/process basis; a second lock by the same thread will not
195: * block.
196: * @param thefile The file to lock.
197: * @param type The type of lock to establish on the file.
198: */
199: APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
200:
201: /**
202: * Remove any outstanding locks on the file.
203: * @param thefile The file to unlock.
204: */
205: APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
206:
207:
208: /**
209: * get the specified file's stats.
210: * @param finfo Where to store the information about the file.
211: * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
212: * @param thefile The file to get information about.
213: */
214: APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo,
215: apr_int32_t wanted,
216: apr_file_t *thefile);
217:
218: /**
219: * Move the read/write file offset to a specified byte within a file.
220: * @param thefile The file descriptor
221: * @param where How to move the pointer, one of:
222: * <PRE>
223: * APR_SET -- set the offset to offset
224: * APR_CUR -- add the offset to the current position
225: * APR_END -- add the offset to the current file size
226: * </PRE>
227: * @param offset The offset to move the pointer to.
228: * @remark The third argument is modified to be the offset the pointer
229: was actually moved to.
230: */
231: APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
232: apr_seek_where_t where,
233: apr_off_t *offset);
234:
235:
236: /**
237: * Read data from the specified file, ensuring that the buffer is filled
238: * before returning.
239: * @param thefile The file descriptor to read from.
240: * @param buf The buffer to store the data to.
241: * @param nbytes The number of bytes to read.
242: * @param bytes_read If non-NULL, this will contain the number of bytes read.
243: * @remark apr_file_read will read up to the specified number of bytes, but never
244: * more. If there isn't enough data to fill that number of bytes,
245: * then the process/thread will block until it is available or EOF
246: * is reached. If a char was put back into the stream via ungetc,
247: * it will be the first character returned.
248: *
249: * It is possible for both bytes to be read and an error to be
250: * returned. And if *bytes_read is less than nbytes, an
251: * accompanying error is _always_ returned.
252: *
253: * APR_EINTR is never returned.
254: */
255: APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
256: apr_size_t nbytes,
257: apr_size_t *bytes_read);
258:
259: /**
260: * Write data to the specified file, ensuring that all of the data is
261: * written before returning.
262: * @param thefile The file descriptor to write to.
263: * @param buf The buffer which contains the data.
264: * @param nbytes The number of bytes to write.
265: * @param bytes_written If non-NULL, this will contain the number of bytes written.
266: * @remark apr_file_write will write up to the specified number of bytes, but never
267: * more. If the OS cannot write that many bytes, the process/thread
268: * will block until they can be written. Exceptional error such as
269: * "out of space" or "pipe closed" will terminate with an error.
270: *
271: * It is possible for both bytes to be written and an error to be
272: * returned. And if *bytes_written is less than nbytes, an
273: * accompanying error is _always_ returned.
274: *
275: * APR_EINTR is never returned.
276: */
277: APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf,
278: apr_size_t nbytes,
279: apr_size_t *bytes_written);
280:
281: #ifdef __cplusplus
282: }
283: #endif
284: /** @} */
285: #endif /* ! APR_FILE_IO_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_file_io.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / parser3 / src / lib / sdbm / apr-include