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