Annotation of parser3/src/lib/sdbm/apr-include/apr_sdbm.h, revision 1.1
1.1 ! paf 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: /*
! 56: * sdbm - ndbm work-alike hashed database library
! 57: * based on Per-Ake Larson's Dynamic Hashing algorithms. BIT 18 (1978).
! 58: * author: oz@nexus.yorku.ca
! 59: * status: ex-public domain
! 60: */
! 61:
! 62: #ifndef APR_SDBM_H
! 63: #define APR_SDBM_H
! 64:
! 65: #include "apu.h"
! 66: #include "apr_errno.h"
! 67: #include "apr_file_io.h" /* for apr_fileperms_t */
! 68:
! 69: /**
! 70: * @file apr_sdbm.h
! 71: * @brief apr-util SDBM library
! 72: */
! 73: /**
! 74: * @defgroup APR_Util_DBM_SDBM SDBM library
! 75: * @ingroup APR_Util_DBM
! 76: * @{
! 77: */
! 78:
! 79: /**
! 80: * Structure for referencing an sdbm
! 81: */
! 82: typedef struct apr_sdbm_t apr_sdbm_t;
! 83:
! 84: /**
! 85: * Structure for referencing the datum record within an sdbm
! 86: */
! 87: typedef struct {
! 88: /** pointer to the data stored/retrieved */
! 89: char *dptr;
! 90: /** size of data */
! 91: int dsize;
! 92: } apr_sdbm_datum_t;
! 93:
! 94: /* The extensions used for the database files */
! 95: #define APR_SDBM_DIRFEXT ".dir"
! 96: #define APR_SDBM_PAGFEXT ".pag"
! 97:
! 98: /* flags to sdbm_store */
! 99: #define APR_SDBM_INSERT 0
! 100: #define APR_SDBM_REPLACE 1
! 101: #define APR_SDBM_INSERTDUP 2
! 102:
! 103: /**
! 104: * Open an sdbm database by file name
! 105: * @param db The newly opened database
! 106: * @param name The sdbm file to open
! 107: * @param mode The flag values (APR_READ and APR_BINARY flags are implicit)
! 108: * <PRE>
! 109: * APR_WRITE open for read-write access
! 110: * APR_CREATE create the sdbm if it does not exist
! 111: * APR_TRUNCATE empty the contents of the sdbm
! 112: * APR_EXCL fail for APR_CREATE if the file exists
! 113: * APR_DELONCLOSE delete the sdbm when closed
! 114: * APR_SHARELOCK support locking across process/machines
! 115: * </PRE>
! 116: * @param perm Permissions to apply to if created
! 117: * @param pool The pool to use when creating the sdbm
! 118: * @remark The sdbm name is not a true file name, as sdbm appends suffixes
! 119: * for seperate data and index files.
! 120: */
! 121: APU_DECLARE(apr_status_t) apr_sdbm_open(apr_sdbm_t **db, const char *name,
! 122: apr_int32_t mode,
! 123: apr_fileperms_t perms, apr_pool_t *p);
! 124:
! 125: /**
! 126: * Close an sdbm file previously opened by apr_sdbm_open
! 127: * @param db The database to close
! 128: */
! 129: APU_DECLARE(apr_status_t) apr_sdbm_close(apr_sdbm_t *db);
! 130:
! 131: /**
! 132: * Lock an sdbm database for concurency of multiple operations
! 133: * @param db The database to lock
! 134: * @param type The lock type
! 135: * <PRE>
! 136: * APR_FLOCK_SHARED
! 137: * APR_FLOCK_EXCLUSIVE
! 138: * </PRE>
! 139: * @remark Calls to apr_sdbm_lock may be nested. All apr_sdbm functions
! 140: * perform implicit locking. Since an APR_FLOCK_SHARED lock cannot be
! 141: * portably promoted to an APR_FLOCK_EXCLUSIVE lock, apr_sdbm_store and
! 142: * apr_sdbm_delete calls will fail if an APR_FLOCK_SHARED lock is held.
! 143: * The apr_sdbm_lock call requires the database to be opened with the
! 144: * APR_SHARELOCK mode value.
! 145: */
! 146: APU_DECLARE(apr_status_t) apr_sdbm_lock(apr_sdbm_t *db, int type);
! 147:
! 148: /**
! 149: * Release an sdbm lock previously aquired by apr_sdbm_lock
! 150: * @param db The database to unlock
! 151: */
! 152: APU_DECLARE(apr_status_t) apr_sdbm_unlock(apr_sdbm_t *db);
! 153:
! 154: /**
! 155: * Fetch an sdbm record value by key
! 156: * @param db The database
! 157: * @param value The value datum retrieved for this record
! 158: * @param key The key datum to find this record
! 159: */
! 160: APU_DECLARE(apr_status_t) apr_sdbm_fetch(apr_sdbm_t *db,
! 161: apr_sdbm_datum_t *value,
! 162: apr_sdbm_datum_t key);
! 163:
! 164: /**
! 165: * Store an sdbm record value by key
! 166: * @param db The database
! 167: * @param key The key datum to store this record by
! 168: * @param value The value datum to store in this record
! 169: * @param opt The method used to store the record
! 170: * <PRE>
! 171: * APR_SDBM_INSERT return an error if the record exists
! 172: * APR_SDBM_REPLACE overwrite any existing record for key
! 173: * </PRE>
! 174: */
! 175: APU_DECLARE(apr_status_t) apr_sdbm_store(apr_sdbm_t *db, apr_sdbm_datum_t key,
! 176: apr_sdbm_datum_t value, int opt);
! 177:
! 178: /**
! 179: * Delete an sdbm record value by key
! 180: * @param db The database
! 181: * @param key The key datum of the record to delete
! 182: * @remark It is not an error to delete a non-existent record.
! 183: */
! 184: APU_DECLARE(apr_status_t) apr_sdbm_delete(apr_sdbm_t *db,
! 185: const apr_sdbm_datum_t key);
! 186:
! 187: /**
! 188: * Retrieve the first record key from a dbm
! 189: * @param dbm The database
! 190: * @param key The key datum of the first record
! 191: * @remark The keys returned are not ordered. To traverse the list of keys
! 192: * for an sdbm opened with APR_SHARELOCK, the caller must use apr_sdbm_lock
! 193: * prior to retrieving the first record, and hold the lock until after the
! 194: * last call to apr_sdbm_nextkey.
! 195: */
! 196: APU_DECLARE(apr_status_t) apr_sdbm_firstkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
! 197:
! 198: /**
! 199: * Retrieve the next record key from an sdbm
! 200: * @param db The database
! 201: * @param key The key datum of the next record
! 202: */
! 203: APU_DECLARE(apr_status_t) apr_sdbm_nextkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
! 204:
! 205: /**
! 206: * Returns true if the sdbm database opened for read-only access
! 207: * @param db The database to test
! 208: */
! 209: APU_DECLARE(int) apr_sdbm_rdonly(apr_sdbm_t *db);
! 210: /** @} */
! 211: #endif /* APR_SDBM_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_sdbm.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / parser3 / src / lib / sdbm / apr-include