Annotation of parser3/src/lib/sdbm/pa-include/pa_file_io.h, revision 1.3
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 */
1.3 ! moko 138:
1.1 moko 139: /** @} */
140:
141: /**
142: * Open the specified file.
143: * @param new_file The opened file descriptor.
144: * @param fname The full path to the file (using / on all systems)
145: * @param flag Or'ed value of:
146: * <PRE>
147: * PA_READ open for reading
148: * PA_WRITE open for writing
149: * PA_CREATE create the file if not there
150: * PA_APPEND file ptr is set to end prior to all writes
151: * PA_TRUNCATE set length to zero if file exists
152: * PA_BINARY not a text file (This flag is ignored on
153: * UNIX because it has no meaning)
154: * PA_BUFFERED buffer the data. Default is non-buffered
155: * PA_EXCL return error if PA_CREATE and file exists
156: * PA_DELONCLOSE delete the file after closing.
157: * PA_XTHREAD Platform dependent tag to open the file
158: * for use across multiple threads
159: * PA_SHARELOCK Platform dependent support for higher
160: * level locked read/write access to support
161: * writes across process/machines
162: * PA_FILE_NOCLEANUP Do not register a cleanup with the pool
163: * passed in on the <EM>cont</EM> argument (see below).
164: * The pa_os_file_t handle in pa_file_t will not
165: & be closed when the pool is destroyed.
166: * </PRE>
167: * @param perm Access permissions for file.
168: * @param cont The pool to use.
169: * @ingroup pa_file_open
170: * @remark If perm is PA_OS_DEFAULT and the file is being created, appropriate
171: * default permissions will be used. *arg1 must point to a valid file_t,
172: * or NULL (in which case it will be allocated)
173: */
174: pa_status_t pa_file_open(pa_file_t **new_file, const char *fname,
175: pa_int32_t flag, pa_fileperms_t perm,
176: pa_pool_t *cont);
177:
178: /**
179: * Close the specified file.
180: * @param file The file descriptor to close.
181: */
182: pa_status_t pa_file_close(pa_file_t *file);
183:
184:
185: /** file (un)locking functions. */
186:
187: /**
188: * Establish a lock on the specified, open file. The lock may be advisory
189: * or mandatory, at the discretion of the platform. The lock applies to
190: * the file as a whole, rather than a specific range. Locks are established
191: * on a per-thread/process basis; a second lock by the same thread will not
192: * block.
193: * @param thefile The file to lock.
194: * @param type The type of lock to establish on the file.
195: */
196: pa_status_t pa_file_lock(pa_file_t *thefile, int type);
197:
198: /**
199: * Remove any outstanding locks on the file.
200: * @param thefile The file to unlock.
201: */
202: pa_status_t pa_file_unlock(pa_file_t *thefile);
203:
204:
205: /**
206: * get the specified file's stats.
207: * @param finfo Where to store the information about the file.
208: * @param wanted The desired pa_finfo_t fields, as a bit flag of PA_FINFO_ values
209: * @param thefile The file to get information about.
210: */
211: pa_status_t pa_file_info_get(pa_finfo_t *finfo,
212: pa_int32_t wanted,
213: pa_file_t *thefile);
214:
215: /**
216: * Move the read/write file offset to a specified byte within a file.
217: * @param thefile The file descriptor
218: * @param where How to move the pointer, one of:
219: * <PRE>
220: * PA_SET -- set the offset to offset
221: * PA_CUR -- add the offset to the current position
222: * PA_END -- add the offset to the current file size
223: * </PRE>
224: * @param offset The offset to move the pointer to.
225: * @remark The third argument is modified to be the offset the pointer
226: was actually moved to.
227: */
228: pa_status_t pa_file_seek(pa_file_t *thefile,
229: pa_seek_where_t where,
230: pa_off_t *offset);
231:
232:
233: /**
234: * Read data from the specified file, ensuring that the buffer is filled
235: * before returning.
236: * @param thefile The file descriptor to read from.
237: * @param buf The buffer to store the data to.
238: * @param nbytes The number of bytes to read.
239: * @param bytes_read If non-NULL, this will contain the number of bytes read.
240: * @remark pa_file_read will read up to the specified number of bytes, but never
241: * more. If there isn't enough data to fill that number of bytes,
242: * then the process/thread will block until it is available or EOF
243: * is reached. If a char was put back into the stream via ungetc,
244: * it will be the first character returned.
245: *
246: * It is possible for both bytes to be read and an error to be
247: * returned. And if *bytes_read is less than nbytes, an
248: * accompanying error is _always_ returned.
249: *
250: * PA_EINTR is never returned.
251: */
252: pa_status_t pa_file_read_full(pa_file_t *thefile, void *buf,
253: pa_size_t nbytes,
254: pa_size_t *bytes_read);
255:
256: /**
257: * Write data to the specified file, ensuring that all of the data is
258: * written before returning.
259: * @param thefile The file descriptor to write to.
260: * @param buf The buffer which contains the data.
261: * @param nbytes The number of bytes to write.
262: * @param bytes_written If non-NULL, this will contain the number of bytes written.
263: * @remark pa_file_write will write up to the specified number of bytes, but never
264: * more. If the OS cannot write that many bytes, the process/thread
265: * will block until they can be written. Exceptional error such as
266: * "out of space" or "pipe closed" will terminate with an error.
267: *
268: * It is possible for both bytes to be written and an error to be
269: * returned. And if *bytes_written is less than nbytes, an
270: * accompanying error is _always_ returned.
271: *
272: * PA_EINTR is never returned.
273: */
274: pa_status_t pa_file_write_full(pa_file_t *thefile, const void *buf,
275: pa_size_t nbytes,
276: pa_size_t *bytes_written);
277:
278: #ifdef __cplusplus
279: }
280: #endif
281: /** @} */
282: #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