Annotation of parser3/src/lib/sdbm/pa-include/pa_sdbm.h, revision 1.2
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_DELONCLOSE delete the sdbm when closed
81: * PA_SHARELOCK support locking across process/machines
82: * </PRE>
83: * @param perm Permissions to apply to if created
84: * @param pool The pool to use when creating the sdbm
85: * @remark The sdbm name is not a true file name, as sdbm appends suffixes
86: * for seperate data and index files.
87: */
88: pa_status_t pa_sdbm_open(pa_sdbm_t **db, const char *name,
89: pa_int32_t mode,
90: pa_fileperms_t perms, pa_pool_t *p);
91:
92: /**
93: * Close an sdbm file previously opened by pa_sdbm_open
94: * @param db The database to close
95: */
96: pa_status_t pa_sdbm_close(pa_sdbm_t *db);
97:
98: /**
99: * Lock an sdbm database for concurency of multiple operations
100: * @param db The database to lock
101: * @param type The lock type
102: * <PRE>
103: * PA_FLOCK_SHARED
104: * PA_FLOCK_EXCLUSIVE
105: * </PRE>
106: * @remark Calls to pa_sdbm_lock may be nested. All pa_sdbm functions
107: * perform implicit locking. Since an PA_FLOCK_SHARED lock cannot be
108: * portably promoted to an PA_FLOCK_EXCLUSIVE lock, pa_sdbm_store and
109: * pa_sdbm_delete calls will fail if an PA_FLOCK_SHARED lock is held.
110: * The pa_sdbm_lock call requires the database to be opened with the
111: * PA_SHARELOCK mode value.
112: */
113: pa_status_t pa_sdbm_lock(pa_sdbm_t *db, int type);
114:
115: /**
116: * Release an sdbm lock previously aquired by pa_sdbm_lock
117: * @param db The database to unlock
118: */
119: pa_status_t pa_sdbm_unlock(pa_sdbm_t *db);
120:
121: /**
122: * Fetch an sdbm record value by key
123: * @param db The database
124: * @param value The value datum retrieved for this record
125: * @param key The key datum to find this record
126: */
127: pa_status_t pa_sdbm_fetch(pa_sdbm_t *db,
128: pa_sdbm_datum_t *value,
129: pa_sdbm_datum_t key);
130:
131: /**
132: * Store an sdbm record value by key
133: * @param db The database
134: * @param key The key datum to store this record by
135: * @param value The value datum to store in this record
136: * @param opt The method used to store the record
137: * <PRE>
138: * PA_SDBM_INSERT return an error if the record exists
139: * PA_SDBM_REPLACE overwrite any existing record for key
140: * </PRE>
141: */
142: pa_status_t pa_sdbm_store(pa_sdbm_t *db, pa_sdbm_datum_t key,
143: pa_sdbm_datum_t value, int opt);
144:
145: /**
146: * Delete an sdbm record value by key
147: * @param db The database
148: * @param key The key datum of the record to delete
149: * @remark It is not an error to delete a non-existent record.
150: */
151: pa_status_t pa_sdbm_delete(pa_sdbm_t *db,
152: const pa_sdbm_datum_t key);
153:
154: /**
155: * Retrieve the first record key from a dbm
156: * @param dbm The database
157: * @param key The key datum of the first record
158: * @remark The keys returned are not ordered. To traverse the list of keys
159: * for an sdbm opened with PA_SHARELOCK, the caller must use pa_sdbm_lock
160: * prior to retrieving the first record, and hold the lock until after the
161: * last call to pa_sdbm_nextkey.
162: */
163: pa_status_t pa_sdbm_firstkey(pa_sdbm_t *db, pa_sdbm_datum_t *key);
164:
165: /**
166: * Retrieve the next record key from an sdbm
167: * @param db The database
168: * @param key The key datum of the next record
169: */
170: pa_status_t pa_sdbm_nextkey(pa_sdbm_t *db, pa_sdbm_datum_t *key);
171:
172: /**
173: * Returns true if the sdbm database opened for read-only access
174: * @param db The database to test
175: */
176: int pa_sdbm_rdonly(pa_sdbm_t *db);
177: /** @} */
178:
179: #ifdef __cplusplus
180: }
181: #endif
182:
183: #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