Annotation of parser3/src/lib/sdbm/pa-include/pa_sdbm.h, revision 1.3
1.2 moko 1: /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
2: * applicable.
1.1 moko 3: *
1.2 moko 4: * Licensed under the Apache License, Version 2.0 (the "License");
5: * you may not use this file except in compliance with the License.
6: * 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: /*
18: * sdbm - ndbm work-alike hashed database library
19: * based on Per-Ake Larson's Dynamic Hashing algorithms. BIT 18 (1978).
20: * author: oz@nexus.yorku.ca
21: * status: ex-public domain
22: */
23:
24: #ifndef PA_SDBM_H
25: #define PA_SDBM_H
26:
27: #include "pa_apr.h"
28: #include "pa_errno.h"
29: #include "pa_file_io.h" /* for pa_fileperms_t */
30:
31: #ifdef __cplusplus
32: extern "C" {
33: #endif
34:
35:
36: /**
37: * @file pa_sdbm.h
38: * @brief apr-util SDBM library
39: */
40: /**
41: * @defgroup PA_Util_DBM_SDBM SDBM library
42: * @ingroup PA_Util_DBM
43: * @{
44: */
45:
46: /**
47: * Structure for referencing an sdbm
48: */
49: typedef struct pa_sdbm_t pa_sdbm_t;
50:
51: /**
52: * Structure for referencing the datum record within an sdbm
53: */
54: typedef struct {
55: /** pointer to the data stored/retrieved */
56: char *dptr;
57: /** size of data */
58: int dsize;
59: } pa_sdbm_datum_t;
60:
61: /* The extensions used for the database files */
62: #define PA_SDBM_DIRFEXT ".dir"
63: #define PA_SDBM_PAGFEXT ".pag"
64:
65: /* flags to sdbm_store */
66: #define PA_SDBM_INSERT 0
67: #define PA_SDBM_REPLACE 1
68: #define PA_SDBM_INSERTDUP 2
69:
70: /**
71: * Open an sdbm database by file name
72: * @param db The newly opened database
73: * @param name The sdbm file to open
74: * @param mode The flag values (PA_READ and PA_BINARY flags are implicit)
75: * <PRE>
76: * PA_WRITE open for read-write access
77: * PA_CREATE create the sdbm if it does not exist
78: * PA_TRUNCATE empty the contents of the sdbm
79: * PA_EXCL fail for PA_CREATE if the file exists
80: * PA_SHARELOCK support locking across process/machines
81: * </PRE>
82: * @param perm Permissions to apply to if created
83: * @param pool The pool to use when creating the sdbm
84: * @remark The sdbm name is not a true file name, as sdbm appends suffixes
85: * for seperate data and index files.
86: */
87: pa_status_t pa_sdbm_open(pa_sdbm_t **db, const char *name,
88: pa_int32_t mode,
89: pa_fileperms_t perms, pa_pool_t *p);
90:
91: /**
92: * Close an sdbm file previously opened by pa_sdbm_open
93: * @param db The database to close
94: */
95: pa_status_t pa_sdbm_close(pa_sdbm_t *db);
96:
97: /**
98: * Lock an sdbm database for concurency of multiple operations
99: * @param db The database to lock
100: * @param type The lock type
101: * <PRE>
102: * PA_FLOCK_SHARED
103: * PA_FLOCK_EXCLUSIVE
104: * </PRE>
105: * @remark Calls to pa_sdbm_lock may be nested. All pa_sdbm functions
106: * perform implicit locking. Since an PA_FLOCK_SHARED lock cannot be
107: * portably promoted to an PA_FLOCK_EXCLUSIVE lock, pa_sdbm_store and
108: * pa_sdbm_delete calls will fail if an PA_FLOCK_SHARED lock is held.
109: * The pa_sdbm_lock call requires the database to be opened with the
110: * PA_SHARELOCK mode value.
111: */
112: pa_status_t pa_sdbm_lock(pa_sdbm_t *db, int type);
113:
114: /**
115: * Release an sdbm lock previously aquired by pa_sdbm_lock
116: * @param db The database to unlock
117: */
118: pa_status_t pa_sdbm_unlock(pa_sdbm_t *db);
119:
120: /**
121: * Fetch an sdbm record value by key
122: * @param db The database
123: * @param value The value datum retrieved for this record
124: * @param key The key datum to find this record
125: */
126: pa_status_t pa_sdbm_fetch(pa_sdbm_t *db,
127: pa_sdbm_datum_t *value,
128: pa_sdbm_datum_t key);
129:
130: /**
131: * Store an sdbm record value by key
132: * @param db The database
133: * @param key The key datum to store this record by
134: * @param value The value datum to store in this record
135: * @param opt The method used to store the record
136: * <PRE>
137: * PA_SDBM_INSERT return an error if the record exists
138: * PA_SDBM_REPLACE overwrite any existing record for key
139: * </PRE>
140: */
141: pa_status_t pa_sdbm_store(pa_sdbm_t *db, pa_sdbm_datum_t key,
142: pa_sdbm_datum_t value, int opt);
143:
144: /**
145: * Delete an sdbm record value by key
146: * @param db The database
147: * @param key The key datum of the record to delete
148: * @remark It is not an error to delete a non-existent record.
149: */
150: pa_status_t pa_sdbm_delete(pa_sdbm_t *db,
151: const pa_sdbm_datum_t key);
152:
153: /**
154: * Retrieve the first record key from a dbm
155: * @param dbm The database
156: * @param key The key datum of the first record
157: * @remark The keys returned are not ordered. To traverse the list of keys
158: * for an sdbm opened with PA_SHARELOCK, the caller must use pa_sdbm_lock
159: * prior to retrieving the first record, and hold the lock until after the
160: * last call to pa_sdbm_nextkey.
161: */
162: pa_status_t pa_sdbm_firstkey(pa_sdbm_t *db, pa_sdbm_datum_t *key);
163:
164: /**
165: * Retrieve the next record key from an sdbm
166: * @param db The database
167: * @param key The key datum of the next record
168: */
169: pa_status_t pa_sdbm_nextkey(pa_sdbm_t *db, pa_sdbm_datum_t *key);
170:
171: /**
172: * Returns true if the sdbm database opened for read-only access
173: * @param db The database to test
174: */
175: int pa_sdbm_rdonly(pa_sdbm_t *db);
176: /** @} */
177:
178: #ifdef __cplusplus
179: }
180: #endif
181:
182: #endif /* PA_SDBM_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pa_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 / pa-include