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