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