1251876Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251876Speter * contributor license agreements. See the NOTICE file distributed with 3251876Speter * this work for additional information regarding copyright ownership. 4251876Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251876Speter * (the "License"); you may not use this file except in compliance with 6251876Speter * the License. You may obtain a copy of the License at 7251876Speter * 8251876Speter * http://www.apache.org/licenses/LICENSE-2.0 9251876Speter * 10251876Speter * Unless required by applicable law or agreed to in writing, software 11251876Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251876Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251876Speter * See the License for the specific language governing permissions and 14251876Speter * limitations under the License. 15251876Speter */ 16251876Speter 17251876Speter/* 18251876Speter * sdbm - ndbm work-alike hashed database library 19251876Speter * based on Per-Ake Larson's Dynamic Hashing algorithms. BIT 18 (1978). 20251876Speter * author: oz@nexus.yorku.ca 21251876Speter * status: ex-public domain 22251876Speter */ 23251876Speter 24251876Speter#ifndef APR_SDBM_H 25251876Speter#define APR_SDBM_H 26251876Speter 27251876Speter#include "apu.h" 28251876Speter#include "apr_errno.h" 29251876Speter#include "apr_file_io.h" /* for apr_fileperms_t */ 30251876Speter 31251876Speter/** 32251876Speter * @file apr_sdbm.h 33251876Speter * @brief apr-util SDBM library 34251876Speter */ 35251876Speter/** 36251876Speter * @defgroup APR_Util_DBM_SDBM SDBM library 37251876Speter * @ingroup APR_Util_DBM 38251876Speter * @{ 39251876Speter */ 40251876Speter 41251876Speter/** 42251876Speter * Structure for referencing an sdbm 43251876Speter */ 44251876Spetertypedef struct apr_sdbm_t apr_sdbm_t; 45251876Speter 46251876Speter/** 47251876Speter * Structure for referencing the datum record within an sdbm 48251876Speter */ 49251876Spetertypedef struct { 50251876Speter /** pointer to the data stored/retrieved */ 51251876Speter char *dptr; 52251876Speter /** size of data */ 53251876Speter /* apr_ssize_t for release 2.0??? */ 54251876Speter int dsize; 55251876Speter} apr_sdbm_datum_t; 56251876Speter 57251876Speter/* The extensions used for the database files */ 58251876Speter/** SDBM Directory file extension */ 59251876Speter#define APR_SDBM_DIRFEXT ".dir" 60251876Speter/** SDBM page file extension */ 61251876Speter#define APR_SDBM_PAGFEXT ".pag" 62251876Speter 63251876Speter/* flags to sdbm_store */ 64251876Speter#define APR_SDBM_INSERT 0 /**< Insert */ 65251876Speter#define APR_SDBM_REPLACE 1 /**< Replace */ 66251876Speter#define APR_SDBM_INSERTDUP 2 /**< Insert with duplicates */ 67251876Speter 68251876Speter/** 69251876Speter * Open an sdbm database by file name 70251876Speter * @param db The newly opened database 71251876Speter * @param name The sdbm file to open 72251876Speter * @param mode The flag values (APR_READ and APR_BINARY flags are implicit) 73251876Speter * <PRE> 74251876Speter * APR_WRITE open for read-write access 75251876Speter * APR_CREATE create the sdbm if it does not exist 76251876Speter * APR_TRUNCATE empty the contents of the sdbm 77251876Speter * APR_EXCL fail for APR_CREATE if the file exists 78251876Speter * APR_DELONCLOSE delete the sdbm when closed 79251876Speter * APR_SHARELOCK support locking across process/machines 80251876Speter * </PRE> 81251876Speter * @param perms Permissions to apply to if created 82251876Speter * @param p The pool to use when creating the sdbm 83251876Speter * @remark The sdbm name is not a true file name, as sdbm appends suffixes 84251876Speter * for seperate data and index files. 85251876Speter */ 86251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_open(apr_sdbm_t **db, const char *name, 87251876Speter apr_int32_t mode, 88251876Speter apr_fileperms_t perms, apr_pool_t *p); 89251876Speter 90251876Speter/** 91251876Speter * Close an sdbm file previously opened by apr_sdbm_open 92251876Speter * @param db The database to close 93251876Speter */ 94251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_close(apr_sdbm_t *db); 95251876Speter 96251876Speter/** 97251876Speter * Lock an sdbm database for concurency of multiple operations 98251876Speter * @param db The database to lock 99251876Speter * @param type The lock type 100251876Speter * <PRE> 101251876Speter * APR_FLOCK_SHARED 102251876Speter * APR_FLOCK_EXCLUSIVE 103251876Speter * </PRE> 104251876Speter * @remark Calls to apr_sdbm_lock may be nested. All apr_sdbm functions 105251876Speter * perform implicit locking. Since an APR_FLOCK_SHARED lock cannot be 106251876Speter * portably promoted to an APR_FLOCK_EXCLUSIVE lock, apr_sdbm_store and 107251876Speter * apr_sdbm_delete calls will fail if an APR_FLOCK_SHARED lock is held. 108251876Speter * The apr_sdbm_lock call requires the database to be opened with the 109251876Speter * APR_SHARELOCK mode value. 110251876Speter */ 111251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_lock(apr_sdbm_t *db, int type); 112251876Speter 113251876Speter/** 114251876Speter * Release an sdbm lock previously aquired by apr_sdbm_lock 115251876Speter * @param db The database to unlock 116251876Speter */ 117251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_unlock(apr_sdbm_t *db); 118251876Speter 119251876Speter/** 120251876Speter * Fetch an sdbm record value by key 121251876Speter * @param db The database 122251876Speter * @param value The value datum retrieved for this record 123251876Speter * @param key The key datum to find this record 124251876Speter */ 125251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_fetch(apr_sdbm_t *db, 126251876Speter apr_sdbm_datum_t *value, 127251876Speter apr_sdbm_datum_t key); 128251876Speter 129251876Speter/** 130251876Speter * Store an sdbm record value by key 131251876Speter * @param db The database 132251876Speter * @param key The key datum to store this record by 133251876Speter * @param value The value datum to store in this record 134251876Speter * @param opt The method used to store the record 135251876Speter * <PRE> 136251876Speter * APR_SDBM_INSERT return an error if the record exists 137251876Speter * APR_SDBM_REPLACE overwrite any existing record for key 138251876Speter * </PRE> 139251876Speter */ 140251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_store(apr_sdbm_t *db, apr_sdbm_datum_t key, 141251876Speter apr_sdbm_datum_t value, int opt); 142251876Speter 143251876Speter/** 144251876Speter * Delete an sdbm record value by key 145251876Speter * @param db The database 146251876Speter * @param key The key datum of the record to delete 147251876Speter * @remark It is not an error to delete a non-existent record. 148251876Speter */ 149251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_delete(apr_sdbm_t *db, 150251876Speter const apr_sdbm_datum_t key); 151251876Speter 152251876Speter/** 153251876Speter * Retrieve the first record key from a dbm 154251876Speter * @param db The database 155251876Speter * @param key The key datum of the first record 156251876Speter * @remark The keys returned are not ordered. To traverse the list of keys 157251876Speter * for an sdbm opened with APR_SHARELOCK, the caller must use apr_sdbm_lock 158251876Speter * prior to retrieving the first record, and hold the lock until after the 159251876Speter * last call to apr_sdbm_nextkey. 160251876Speter */ 161251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_firstkey(apr_sdbm_t *db, apr_sdbm_datum_t *key); 162251876Speter 163251876Speter/** 164251876Speter * Retrieve the next record key from an sdbm 165251876Speter * @param db The database 166251876Speter * @param key The key datum of the next record 167251876Speter */ 168251876SpeterAPU_DECLARE(apr_status_t) apr_sdbm_nextkey(apr_sdbm_t *db, apr_sdbm_datum_t *key); 169251876Speter 170251876Speter/** 171251876Speter * Returns true if the sdbm database opened for read-only access 172251876Speter * @param db The database to test 173251876Speter */ 174251876SpeterAPU_DECLARE(int) apr_sdbm_rdonly(apr_sdbm_t *db); 175251876Speter/** @} */ 176251876Speter#endif /* APR_SDBM_H */ 177