Annotation of parser3/src/lib/sdbm/pa-include/pa_file_io.h, revision 1.1
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 <stdio.h>
! 68:
! 69: #include "pa_apr.h"
! 70: #include "pa_errno.h"
! 71: #include "pa_file_info.h"
! 72:
! 73: #ifdef __cplusplus
! 74: extern "C" {
! 75: #endif /* __cplusplus */
! 76:
! 77: /**
! 78: * @defgroup pa_file_open File Open Flags/Routines
! 79: * @{
! 80: */
! 81:
! 82: #define PA_READ 1 /**< Open the file for reading */
! 83: #define PA_WRITE 2 /**< Open the file for writing */
! 84: #define PA_CREATE 4 /**< Create the file if not there */
! 85: #define PA_APPEND 8 /**< Append to the end of the file */
! 86: #define PA_TRUNCATE 16 /**< Open the file and truncate to 0 length */
! 87: #define PA_BINARY 32 /**< Open the file in binary mode */
! 88: #define PA_EXCL 64 /**< Open should fail if PA_CREATE and file
! 89: exists. */
! 90: #define PA_BUFFERED 128 /**< Open the file for buffered I/O */
! 91: #define PA_DELONCLOSE 256 /**< Delete the file after close */
! 92: #define PA_XTHREAD 512 /**< Platform dependent tag to open the file
! 93: for use across multiple threads */
! 94: #define PA_SHARELOCK 1024 /**< Platform dependent support for higher
! 95: level locked read/write access to support
! 96: writes across process/machines */
! 97: #define PA_FILE_NOCLEANUP 2048 /**< Do not register a cleanup when the file
! 98: is opened */
! 99:
! 100: /** @} */
! 101:
! 102: /**
! 103: * @defgroup PA_file_seek_flags File Seek Flags
! 104: * @{
! 105: */
! 106:
! 107: /* flags for pa_file_seek */
! 108: #define PA_SET SEEK_SET
! 109: #define PA_CUR SEEK_CUR
! 110: #define PA_END SEEK_END
! 111: /** @} */
! 112:
! 113: /** should be same as whence type in lseek, POSIX defines this as int */
! 114: typedef int pa_seek_where_t;
! 115:
! 116: /**
! 117: * Structure for referencing files.
! 118: * @defvar pa_file_t
! 119: */
! 120: typedef struct pa_file_t pa_file_t;
! 121:
! 122: /* File lock types/flags */
! 123: /**
! 124: * @defgroup PA_file_lock_types File Lock Types
! 125: * @{
! 126: */
! 127:
! 128: #define PA_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 PA_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 PA_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */
! 140: #define PA_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: * PA_READ open for reading
! 151: * PA_WRITE open for writing
! 152: * PA_CREATE create the file if not there
! 153: * PA_APPEND file ptr is set to end prior to all writes
! 154: * PA_TRUNCATE set length to zero if file exists
! 155: * PA_BINARY not a text file (This flag is ignored on
! 156: * UNIX because it has no meaning)
! 157: * PA_BUFFERED buffer the data. Default is non-buffered
! 158: * PA_EXCL return error if PA_CREATE and file exists
! 159: * PA_DELONCLOSE delete the file after closing.
! 160: * PA_XTHREAD Platform dependent tag to open the file
! 161: * for use across multiple threads
! 162: * PA_SHARELOCK Platform dependent support for higher
! 163: * level locked read/write access to support
! 164: * writes across process/machines
! 165: * PA_FILE_NOCLEANUP Do not register a cleanup with the pool
! 166: * passed in on the <EM>cont</EM> argument (see below).
! 167: * The pa_os_file_t handle in pa_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 pa_file_open
! 173: * @remark If perm is PA_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: pa_status_t pa_file_open(pa_file_t **new_file, const char *fname,
! 178: pa_int32_t flag, pa_fileperms_t perm,
! 179: pa_pool_t *cont);
! 180:
! 181: /**
! 182: * Close the specified file.
! 183: * @param file The file descriptor to close.
! 184: */
! 185: pa_status_t pa_file_close(pa_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: pa_status_t pa_file_lock(pa_file_t *thefile, int type);
! 200:
! 201: /**
! 202: * Remove any outstanding locks on the file.
! 203: * @param thefile The file to unlock.
! 204: */
! 205: pa_status_t pa_file_unlock(pa_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 pa_finfo_t fields, as a bit flag of PA_FINFO_ values
! 212: * @param thefile The file to get information about.
! 213: */
! 214: pa_status_t pa_file_info_get(pa_finfo_t *finfo,
! 215: pa_int32_t wanted,
! 216: pa_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: * PA_SET -- set the offset to offset
! 224: * PA_CUR -- add the offset to the current position
! 225: * PA_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: pa_status_t pa_file_seek(pa_file_t *thefile,
! 232: pa_seek_where_t where,
! 233: pa_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 pa_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: * PA_EINTR is never returned.
! 254: */
! 255: pa_status_t pa_file_read_full(pa_file_t *thefile, void *buf,
! 256: pa_size_t nbytes,
! 257: pa_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 pa_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: * PA_EINTR is never returned.
! 276: */
! 277: pa_status_t pa_file_write_full(pa_file_t *thefile, const void *buf,
! 278: pa_size_t nbytes,
! 279: pa_size_t *bytes_written);
! 280:
! 281: #ifdef __cplusplus
! 282: }
! 283: #endif
! 284: /** @} */
! 285: #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