gdbm (1.23)
1 /* gdbm.h - The include file for dbm users. -*- c -*- */
2
3 /* This file is part of GDBM, the GNU data base manager, by Philip A. Nelson.
4 Copyright (C) 1990-2022 Free Software Foundation, Inc.
5
6 GDBM is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10
11 GDBM is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GDBM. If not, see <http://www.gnu.org/licenses/>.
18
19 You may contact the author by:
20 e-mail: phil@cs.wwu.edu
21 us-mail: Philip A. Nelson
22 Computer Science Department
23 Western Washington University
24 Bellingham, WA 98226
25
26 *************************************************************************/
27
28 /* Protection for multiple includes. */
29 #ifndef _GDBM_H_
30 # define _GDBM_H_
31
32 # include <stdio.h>
33 # include <sys/types.h>
34
35 /* GDBM C++ support */
36 # if defined(__cplusplus) || defined(c_plusplus)
37 extern "C" {
38 # endif
39
40 /* Parameters to gdbm_open for READERS, WRITERS, and WRITERS who
41 can create the database. */
42 # define GDBM_READER 0 /* A reader. */
43 # define GDBM_WRITER 1 /* A writer. */
44 # define GDBM_WRCREAT 2 /* A writer. Create the db if needed. */
45 # define GDBM_NEWDB 3 /* A writer. Always create a new db. */
46 # define GDBM_OPENMASK 7 /* Mask for the above. */
47
48 # define GDBM_FAST 0x0010 /* Write fast! => No fsyncs. OBSOLETE. */
49 # define GDBM_SYNC 0x0020 /* Sync operations to the disk. */
50 # define GDBM_NOLOCK 0x0040 /* Don't do file locking operations. */
51 # define GDBM_NOMMAP 0x0080 /* Don't use mmap(). */
52 # define GDBM_CLOEXEC 0x0100 /* Close the underlying fd on exec(3) */
53 # define GDBM_BSEXACT 0x0200 /* Don't adjust block_size. Bail out with
54 GDBM_BLOCK_SIZE_ERROR error if unable to
55 set it. */
56 # define GDBM_CLOERROR 0x0400 /* Only for gdbm_fd_open: close fd on error. */
57 # define GDBM_XVERIFY 0x0800 /* Additional consistency checks. */
58 # define GDBM_PREREAD 0x1000 /* Enable pre-fault reading of mmapped regions. */
59 # define GDBM_NUMSYNC 0x2000 /* Enable the numsync extension */
60
61
62 /* Parameters to gdbm_store for simple insertion or replacement in the
63 case that the key is already in the database. */
64 # define GDBM_INSERT 0 /* Never replace old data with new. */
65 # define GDBM_REPLACE 1 /* Always replace old data with new. */
66
67 /* Parameters to gdbm_setopt, specifying the type of operation to perform. */
68 # define GDBM_SETCACHESIZE 1 /* Set the cache size. */
69 # define GDBM_FASTMODE 2 /* Toggle fast mode. OBSOLETE. */
70 # define GDBM_SETSYNCMODE 3 /* Turn on or off sync operations. */
71 # define GDBM_SETCENTFREE 4 /* Keep all free blocks in the header. */
72 # define GDBM_SETCOALESCEBLKS 5 /* Attempt to coalesce free blocks. */
73 # define GDBM_SETMAXMAPSIZE 6 /* Set maximum mapped memory size */
74 # define GDBM_SETMMAP 7 /* Toggle mmap mode */
75
76 /* Compatibility defines: */
77 # define GDBM_CACHESIZE GDBM_SETCACHESIZE
78 # define GDBM_SYNCMODE GDBM_SETSYNCMODE
79 # define GDBM_CENTFREE GDBM_SETCENTFREE
80 # define GDBM_COALESCEBLKS GDBM_SETCOALESCEBLKS
81
82 # define GDBM_GETFLAGS 8 /* Get gdbm_open flags */
83 # define GDBM_GETMMAP 9 /* Get mmap status */
84 # define GDBM_GETCACHESIZE 10 /* Get current cache side */
85 # define GDBM_GETSYNCMODE 11 /* Get synch mode */
86 # define GDBM_GETCENTFREE 12 /* Get "centfree" status */
87 # define GDBM_GETCOALESCEBLKS 13 /* Get free block coalesce status */
88 # define GDBM_GETMAXMAPSIZE 14 /* Get maximum mapped memory size */
89 # define GDBM_GETDBNAME 15 /* Return database file name */
90 # define GDBM_GETBLOCKSIZE 16 /* Return block size */
91 # define GDBM_GETDBFORMAT 17 /* Return the database format */
92 # define GDBM_GETDIRDEPTH 18 /* Directory depth: number of initial (most
93 significant) bits in hash interpreted as
94 index to the directory. */
95 # define GDBM_GETBUCKETSIZE 19 /* Get number of elements per bucket */
96 # define GDBM_GETCACHEAUTO 20 /* Get the value of cache auto-adjustment */
97 # define GDBM_SETCACHEAUTO 21 /* Set the value of cache auto-adjustment */
98
99 # define GDBM_CACHE_AUTO 0
100
101 typedef unsigned long long int gdbm_count_t;
102
103 /* The data and key structure. */
104 typedef struct
105 {
106 char *dptr;
107 int dsize;
108 } datum;
109
110 /* A pointer to the GDBM file. */
111 typedef struct gdbm_file_info *GDBM_FILE;
112
113 /* External variable, the gdbm build release string. */
114 extern const char *gdbm_version;
115
116 # define GDBM_VERSION_MAJOR 1
117 # define GDBM_VERSION_MINOR 23
118 # define GDBM_VERSION_PATCH 0
119
120 extern int const gdbm_version_number[3];
121
122 /* GDBM external functions. */
123
124 extern GDBM_FILE gdbm_fd_open (int fd, const char *file_name, int block_size,
125 int flags, void (*fatal_func) (const char *));
126 extern GDBM_FILE gdbm_open (const char *, int, int, int,
127 void (*)(const char *));
128 extern int gdbm_close (GDBM_FILE);
129 extern int gdbm_store (GDBM_FILE, datum, datum, int);
130 extern datum gdbm_fetch (GDBM_FILE, datum);
131 extern int gdbm_delete (GDBM_FILE, datum);
132 extern datum gdbm_firstkey (GDBM_FILE);
133 extern datum gdbm_nextkey (GDBM_FILE, datum);
134 extern int gdbm_reorganize (GDBM_FILE);
135
136 extern int gdbm_sync (GDBM_FILE);
137 extern int gdbm_failure_atomic (GDBM_FILE, const char *, const char *);
138
139 extern int gdbm_convert (GDBM_FILE dbf, int flag);
140
141 enum gdbm_latest_snapshot_status
142 {
143 GDBM_SNAPSHOT_OK, /* Selected the right snapshot. */
144 GDBM_SNAPSHOT_BAD, /* Neither snapshot is readable. */
145 GDBM_SNAPSHOT_ERR, /* Error selecting snapshot. Inspect errno. */
146 GDBM_SNAPSHOT_SAME, /* Snapshot numsync and dates are the same. */
147 GDBM_SNAPSHOT_SUSPICIOUS /* Selected snapshot is unreliable: numsyncs
148 differ by more than 1. */
149 };
150 extern int gdbm_latest_snapshot (const char *, const char *, const char **);
151 extern int gdbm_exists (GDBM_FILE, datum);
152 extern int gdbm_setopt (GDBM_FILE, int, void *, int);
153 extern int gdbm_fdesc (GDBM_FILE);
154
155 extern int gdbm_export (GDBM_FILE, const char *, int, int);
156 extern int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
157
158 extern int gdbm_import (GDBM_FILE, const char *, int);
159 extern int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
160
161 extern int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
162 extern int gdbm_bucket_count (GDBM_FILE dbf, size_t *pcount);
163
164 extern int gdbm_avail_verify (GDBM_FILE dbf);
165
166 typedef struct gdbm_recovery_s
167 {
168 /* Input members.
169 These are initialized before call to gdbm_recover. The flags argument
170 specifies which of them are initialized. */
171 void (*errfun) (void *data, char const *fmt, ...);
172 void *data;
173
174 size_t max_failed_keys;
175 size_t max_failed_buckets;
176 size_t max_failures;
177
178 /* Output members.
179 The gdbm_recover function fills these before returning. */
180 size_t recovered_keys;
181 size_t recovered_buckets;
182 size_t failed_keys;
183 size_t failed_buckets;
184 size_t duplicate_keys;
185 char *backup_name;
186 } gdbm_recovery;
187
188 #define GDBM_RCVR_DEFAULT 0x00 /* Default settings */
189 #define GDBM_RCVR_ERRFUN 0x01 /* errfun is initialized */
190 #define GDBM_RCVR_MAX_FAILED_KEYS 0x02 /* max_failed_keys is initialized */
191 #define GDBM_RCVR_MAX_FAILED_BUCKETS 0x04 /* max_failed_buckets is initialized */
192 #define GDBM_RCVR_MAX_FAILURES 0x08 /* max_failures is initialized */
193 #define GDBM_RCVR_BACKUP 0x10 /* Keep backup copy of the
194 original database on success */
195 #define GDBM_RCVR_FORCE 0x20 /* Force recovery by skipping the
196 check pass */
197
198 extern int gdbm_recover (GDBM_FILE dbf, gdbm_recovery *rcvr, int flags);
199
200
201 #define GDBM_DUMP_FMT_BINARY 0
202 #define GDBM_DUMP_FMT_ASCII 1
203
204 #define GDBM_META_MASK_MODE 0x01
205 #define GDBM_META_MASK_OWNER 0x02
206
207 extern int gdbm_dump (GDBM_FILE, const char *, int fmt, int open_flags,
208 int mode);
209 extern int gdbm_dump_to_file (GDBM_FILE, FILE *, int fmt);
210
211 extern int gdbm_load (GDBM_FILE *, const char *, int replace,
212 int meta_flags,
213 unsigned long *line);
214 extern int gdbm_load_from_file (GDBM_FILE *, FILE *, int replace,
215 int meta_flags,
216 unsigned long *line);
217
218 extern int gdbm_copy_meta (GDBM_FILE dst, GDBM_FILE src);
219
220 enum
221 {
222 GDBM_NO_ERROR = 0,
223 GDBM_MALLOC_ERROR = 1,
224 GDBM_BLOCK_SIZE_ERROR = 2,
225 GDBM_FILE_OPEN_ERROR = 3,
226 GDBM_FILE_WRITE_ERROR = 4,
227 GDBM_FILE_SEEK_ERROR = 5,
228 GDBM_FILE_READ_ERROR = 6,
229 GDBM_BAD_MAGIC_NUMBER = 7,
230 GDBM_EMPTY_DATABASE = 8,
231 GDBM_CANT_BE_READER = 9,
232 GDBM_CANT_BE_WRITER = 10,
233 GDBM_READER_CANT_DELETE = 11,
234 GDBM_READER_CANT_STORE = 12,
235 GDBM_READER_CANT_REORGANIZE = 13,
236 GDBM_UNKNOWN_ERROR = 14,
237 GDBM_ITEM_NOT_FOUND = 15,
238 GDBM_REORGANIZE_FAILED = 16,
239 GDBM_CANNOT_REPLACE = 17,
240 GDBM_MALFORMED_DATA = 18,
241 GDBM_ILLEGAL_DATA = GDBM_MALFORMED_DATA,
242 GDBM_OPT_ALREADY_SET = 19,
243 GDBM_OPT_BADVAL = 20,
244 GDBM_OPT_ILLEGAL = GDBM_OPT_BADVAL,
245 GDBM_BYTE_SWAPPED = 21,
246 GDBM_BAD_FILE_OFFSET = 22,
247 GDBM_BAD_OPEN_FLAGS = 23,
248 GDBM_FILE_STAT_ERROR = 24,
249 GDBM_FILE_EOF = 25,
250 GDBM_NO_DBNAME = 26,
251 GDBM_ERR_FILE_OWNER = 27,
252 GDBM_ERR_FILE_MODE = 28,
253 GDBM_NEED_RECOVERY = 29,
254 GDBM_BACKUP_FAILED = 30,
255 GDBM_DIR_OVERFLOW = 31,
256 GDBM_BAD_BUCKET = 32,
257 GDBM_BAD_HEADER = 33,
258 GDBM_BAD_AVAIL = 34,
259 GDBM_BAD_HASH_TABLE = 35,
260 GDBM_BAD_DIR_ENTRY = 36,
261 GDBM_FILE_CLOSE_ERROR = 37,
262 GDBM_FILE_SYNC_ERROR = 38,
263 GDBM_FILE_TRUNCATE_ERROR = 39,
264 GDBM_BUCKET_CACHE_CORRUPTED = 40,
265 GDBM_BAD_HASH_ENTRY = 41,
266 GDBM_ERR_SNAPSHOT_CLONE = 42,
267 GDBM_ERR_REALPATH = 43,
268 GDBM_ERR_USAGE = 44
269 };
270
271 # define _GDBM_MIN_ERRNO 0
272 # define _GDBM_MAX_ERRNO GDBM_ERR_USAGE
273
274 /* This one was never used and will be removed in the future */
275 # define GDBM_UNKNOWN_UPDATE GDBM_UNKNOWN_ERROR
276
277 typedef int gdbm_error;
278 extern int *gdbm_errno_location (void);
279 #define gdbm_errno (*gdbm_errno_location ())
280 extern const char * const gdbm_errlist[];
281 extern int const gdbm_syserr[];
282
283 extern gdbm_error gdbm_last_errno (GDBM_FILE dbf);
284 extern int gdbm_last_syserr (GDBM_FILE dbf);
285 extern void gdbm_set_errno (GDBM_FILE dbf, gdbm_error ec, int fatal);
286 extern void gdbm_clear_error (GDBM_FILE dbf);
287 extern int gdbm_needs_recovery (GDBM_FILE dbf);
288 extern int gdbm_check_syserr (gdbm_error n);
289
290 /* extra prototypes */
291
292 extern const char *gdbm_strerror (gdbm_error);
293 extern const char *gdbm_db_strerror (GDBM_FILE dbf);
294
295 extern int gdbm_version_cmp (int const a[], int const b[]);
296
297 #if 0
298 # define GDBM_DEBUG_ENABLE 1
299
300 typedef void (*gdbm_debug_printer_t) (char const *, ...);
301 extern gdbm_debug_printer_t gdbm_debug_printer;
302 extern int gdbm_debug_flags;
303
304 # define GDBM_DEBUG_ERR 0x00000001
305 # define GDBM_DEBUG_OPEN 0x00000002
306 # define GDBM_DEBUG_READ 0x00000004
307 # define GDBM_DEBUG_STORE 0x00000008
308 # define GDBM_DEBUG_LOOKUP 0x00000010
309
310 # define GDBM_DEBUG_ALL 0xffffffff
311
312 extern int gdbm_debug_token (char const *tok);
313 extern void gdbm_debug_parse_state (int (*f) (void *, int, char const *),
314 void *d);
315
316 extern void gdbm_debug_datum (datum dat, char const *pfx);
317 #endif
318
319 /* Cache statistics */
320 struct gdbm_cache_stat
321 {
322 off_t adr;
323 size_t hits;
324 };
325
326 void gdbm_get_cache_stats (GDBM_FILE dbf,
327 size_t *access_count,
328 size_t *cache_hits,
329 size_t *cache_count,
330 struct gdbm_cache_stat *bstat,
331 size_t nstat);
332
333 # if defined(__cplusplus) || defined(c_plusplus)
334 }
335 # endif
336
337 #endif
Browse
Usage
Versions