Annotation of parser3/src/lib/sdbm/pa-include/pa_file_io.h, revision 1.2
1.1 moko 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 PA_FILE_IO_H
56: #define PA_FILE_IO_H
57: /**
58: * @file pa_file_io.h
59: * @brief APR File I/O Handling
60: */
61: /**
62: * @defgroup PA_File_IO_Handle I/O Handling Functions
63: * @ingroup PA_File_Handle
64: * @{
65: */
66:
67: #include "pa_apr.h"
68: #include "pa_errno.h"
69: #include "pa_file_info.h"
70:
71: #ifdef __cplusplus
72: extern "C" {
73: #endif /* __cplusplus */
74:
75: /**
76: * @defgroup pa_file_open File Open Flags/Routines
77: * @{
78: */
79:
80: #define PA_READ 1 /**< Open the file for reading */
81: #define PA_WRITE 2 /**< Open the file for writing */
82: #define PA_CREATE 4 /**< Create the file if not there */
83: #define PA_APPEND 8 /**< Append to the end of the file */
84: #define PA_TRUNCATE 16 /**< Open the file and truncate to 0 length */
85: #define PA_BINARY 32 /**< Open the file in binary mode */
86: #define PA_EXCL 64 /**< Open should fail if PA_CREATE and file
87: exists. */
88: #define PA_BUFFERED 128 /**< Open the file for buffered I/O */
89: #define PA_DELONCLOSE 256 /**< Delete the file after close */
90: #define PA_XTHREAD 512 /**< Platform dependent tag to open the file
91: for use across multiple threads */
92: #define PA_SHARELOCK 1024 /**< Platform dependent support for higher
93: level locked read/write access to support
94: writes across process/machines */
95: #define PA_FILE_NOCLEANUP 2048 /**< Do not register a cleanup when the file
96: is opened */
97:
98: /** @} */
99:
100: /**
101: * @defgroup PA_file_seek_flags File Seek Flags
102: * @{
103: */
104:
105: /* flags for pa_file_seek */
106: #define PA_SET SEEK_SET
107: #define PA_CUR SEEK_CUR
108: #define PA_END SEEK_END
109: /** @} */
110:
111: /** should be same as whence type in lseek, POSIX defines this as int */
112: typedef int pa_seek_where_t;
113:
114: /**
115: * Structure for referencing files.
116: * @defvar pa_file_t
117: */
118: typedef struct pa_file_t pa_file_t;
119:
120: /* File lock types/flags */
121: /**
122: * @defgroup PA_file_lock_types File Lock Types
123: * @{
124: */
125:
126: #define PA_FLOCK_SHARED 1 /**< Shared lock. More than one process
127: or thread can hold a shared lock
128: at any given time. Essentially,
129: this is a "read lock", preventing
130: writers from establishing an
131: exclusive lock. */
132: #define PA_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process
133: may hold an exclusive lock at any
134: given time. This is analogous to
135: a "write lock". */
136:
137: #define PA_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
138: #define PA_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the
139: file lock */
140: /** @} */
141:
142: /**
143: * Open the specified file.
144: * @param new_file The opened file descriptor.
145: * @param fname The full path to the file (using / on all systems)
146: * @param flag Or'ed value of:
147: * <PRE>
148: * PA_READ open for reading
149: * PA_WRITE open for writing
150: * PA_CREATE create the file if not there
151: * PA_APPEND file ptr is set to end prior to all writes
152: * PA_TRUNCATE set length to zero if file exists
153: * PA_BINARY not a text file (This flag is ignored on
154: * UNIX because it has no meaning)
155: * PA_BUFFERED buffer the data. Default is non-buffered
156: * PA_EXCL return error if PA_CREATE and file exists
157: * PA_DELONCLOSE delete the file after closing.
158: * PA_XTHREAD Platform dependent tag to open the file
159: * for use across multiple threads
160: * PA_SHARELOCK Platform dependent support for higher
161: * level locked read/write access to support
162: * writes across process/machines
163: * PA_FILE_NOCLEANUP Do not register a cleanup with the pool
164: * passed in on the <EM>cont</EM> argument (see below).
165: * The pa_os_file_t handle in pa_file_t will not
166: & be closed when the pool is destroyed.
167: * </PRE>
168: * @param perm Access permissions for file.
169: * @param cont The pool to use.
170: * @ingroup pa_file_open
171: * @remark If perm is PA_OS_DEFAULT and the file is being created, appropriate
172: * default permissions will be used. *arg1 must point to a valid file_t,
173: * or NULL (in which case it will be allocated)
174: */
175: pa_status_t pa_file_open(pa_file_t **new_file, const char *fname,
176: pa_int32_t flag, pa_fileperms_t perm,
177: pa_pool_t *cont);
178:
179: /**
180: * Close the specified file.
181: * @param file The file descriptor to close.
182: */
183: pa_status_t pa_file_close(pa_file_t *file);
184:
185:
186: /** file (un)locking functions. */
187:
188: /**
189: * Establish a lock on the specified, open file. The lock may be advisory
190: * or mandatory, at the discretion of the platform. The lock applies to
191: * the file as a whole, rather than a specific range. Locks are established
192: * on a per-thread/process basis; a second lock by the same thread will not
193: * block.
194: * @param thefile The file to lock.
195: * @param type The type of lock to establish on the file.
196: */
197: pa_status_t pa_file_lock(pa_file_t *thefile, int type);
198:
199: /**
200: * Remove any outstanding locks on the file.
201: * @param thefile The file to unlock.
202: */
203: pa_status_t pa_file_unlock(pa_file_t *thefile);
204:
205:
206: /**
207: * get the specified file's stats.
208: * @param finfo Where to store the information about the file.
209: * @param wanted The desired pa_finfo_t fields, as a bit flag of PA_FINFO_ values
210: * @param thefile The file to get information about.
211: */
212: pa_status_t pa_file_info_get(pa_finfo_t *finfo,
213: pa_int32_t wanted,
214: pa_file_t *thefile);
215:
216: /**
217: * Move the read/write file offset to a specified byte within a file.
218: * @param thefile The file descriptor
219: * @param where How to move the pointer, one of:
220: * <PRE>
221: * PA_SET -- set the offset to offset
222: * PA_CUR -- add the offset to the current position
223: * PA_END -- add the offset to the current file size
224: * </PRE>
225: * @param offset The offset to move the pointer to.
226: * @remark The third argument is modified to be the offset the pointer
227: was actually moved to.
228: */
229: pa_status_t pa_file_seek(pa_file_t *thefile,
230: pa_seek_where_t where,
231: pa_off_t *offset);
232:
233:
234: /**
235: * Read data from the specified file, ensuring that the buffer is filled
236: * before returning.
237: * @param thefile The file descriptor to read from.
238: * @param buf The buffer to store the data to.
239: * @param nbytes The number of bytes to read.
240: * @param bytes_read If non-NULL, this will contain the number of bytes read.
241: * @remark pa_file_read will read up to the specified number of bytes, but never
242: * more. If there isn't enough data to fill that number of bytes,
243: * then the process/thread will block until it is available or EOF
244: * is reached. If a char was put back into the stream via ungetc,
245: * it will be the first character returned.
246: *
247: * It is possible for both bytes to be read and an error to be
248: * returned. And if *bytes_read is less than nbytes, an
249: * accompanying error is _always_ returned.
250: *
251: * PA_EINTR is never returned.
252: */
253: pa_status_t pa_file_read_full(pa_file_t *thefile, void *buf,
254: pa_size_t nbytes,
255: pa_size_t *bytes_read);
256:
257: /**
258: * Write data to the specified file, ensuring that all of the data is
259: * written before returning.
260: * @param thefile The file descriptor to write to.
261: * @param buf The buffer which contains the data.
262: * @param nbytes The number of bytes to write.
263: * @param bytes_written If non-NULL, this will contain the number of bytes written.
264: * @remark pa_file_write will write up to the specified number of bytes, but never
265: * more. If the OS cannot write that many bytes, the process/thread
266: * will block until they can be written. Exceptional error such as
267: * "out of space" or "pipe closed" will terminate with an error.
268: *
269: * It is possible for both bytes to be written and an error to be
270: * returned. And if *bytes_written is less than nbytes, an
271: * accompanying error is _always_ returned.
272: *
273: * PA_EINTR is never returned.
274: */
275: pa_status_t pa_file_write_full(pa_file_t *thefile, const void *buf,
276: pa_size_t nbytes,
277: pa_size_t *bytes_written);
278:
279: #ifdef __cplusplus
280: }
281: #endif
282: /** @} */
283: #endif /* ! PA_FILE_IO_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pa_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 / pa-include