aboutsummaryrefslogtreecommitdiff
path: root/src/gdbm.h.in
blob: 6f601b182ef624d40a2bb9872723c88197200fe0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
/* gdbm.h  -  The include file for dbm users.  -*- c -*- */

/*  This file is part of GDBM, the GNU data base manager, by Philip A. Nelson.
    Copyright (C) 1990-2023 Free Software Foundation, Inc.

    GDBM is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    GDBM is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with GDBM. If not, see <http://www.gnu.org/licenses/>.  

    You may contact the author by:
       e-mail:  phil@cs.wwu.edu
      us-mail:  Philip A. Nelson
                Computer Science Department
                Western Washington University
                Bellingham, WA 98226
       
*************************************************************************/

/* Protection for multiple includes. */
#ifndef _GDBM_H_
# define _GDBM_H_

# include <stdio.h>
# include <sys/types.h>

/* GDBM C++ support */
# if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
# endif

/* Parameters to gdbm_open for READERS, WRITERS, and WRITERS who
   can create the database. */
# define GDBM_READER	0	/* A reader. */
# define GDBM_WRITER	1	/* A writer. */
# define GDBM_WRCREAT	2	/* A writer.  Create the db if needed. */
# define GDBM_NEWDB	3	/* A writer.  Always create a new db. */
# define GDBM_OPENMASK	7	/* Mask for the above. */

# define GDBM_FAST	0x0010	/* Write fast! => No fsyncs.  OBSOLETE. */
# define GDBM_SYNC	0x0020	/* Sync operations to the disk. */
# define GDBM_NOLOCK	0x0040	/* Don't do file locking operations. */
# define GDBM_NOMMAP	0x0080	/* Don't use mmap(). */
# define GDBM_CLOEXEC   0x0100  /* Close the underlying fd on exec(3) */
# define GDBM_BSEXACT   0x0200  /* Don't adjust block_size. Bail out with
				   GDBM_BLOCK_SIZE_ERROR error if unable to
				   set it. */  
# define GDBM_CLOERROR  0x0400  /* Only for gdbm_fd_open: close fd on error. */
# define GDBM_XVERIFY   0x0800  /* Additional consistency checks. */
# define GDBM_PREREAD   0x1000  /* Enable pre-fault reading of mmapped regions. */
# define GDBM_NUMSYNC   0x2000  /* Enable the numsync extension */

  
/* Parameters to gdbm_store for simple insertion or replacement in the
   case that the key is already in the database. */
# define GDBM_INSERT	0	/* Never replace old data with new. */
# define GDBM_REPLACE	1	/* Always replace old data with new. */

/* Parameters to gdbm_setopt, specifying the type of operation to perform. */
# define GDBM_SETCACHESIZE    1  /* Set the cache size. */
# define GDBM_FASTMODE	      2	 /* Toggle fast mode.  OBSOLETE. */
# define GDBM_SETSYNCMODE     3  /* Turn on or off sync operations. */
# define GDBM_SETCENTFREE     4  /* Keep all free blocks in the header. */
# define GDBM_SETCOALESCEBLKS 5  /* Attempt to coalesce free blocks. */
# define GDBM_SETMAXMAPSIZE   6  /* Set maximum mapped memory size */
# define GDBM_SETMMAP         7  /* Toggle mmap mode */

/* Compatibility defines: */
# define GDBM_CACHESIZE	     GDBM_SETCACHESIZE
# define GDBM_SYNCMODE	     GDBM_SETSYNCMODE
# define GDBM_CENTFREE       GDBM_SETCENTFREE
# define GDBM_COALESCEBLKS   GDBM_SETCOALESCEBLKS

# define GDBM_GETFLAGS        8  /* Get gdbm_open flags */
# define GDBM_GETMMAP         9  /* Get mmap status */
# define GDBM_GETCACHESIZE    10 /* Get current cache side */
# define GDBM_GETSYNCMODE     11 /* Get synch mode */
# define GDBM_GETCENTFREE     12 /* Get "centfree" status */
# define GDBM_GETCOALESCEBLKS 13 /* Get free block coalesce status */
# define GDBM_GETMAXMAPSIZE   14 /* Get maximum mapped memory size */
# define GDBM_GETDBNAME       15 /* Return database file name */
# define GDBM_GETBLOCKSIZE    16 /* Return block size */
# define GDBM_GETDBFORMAT     17 /* Return the database format */
# define GDBM_GETDIRDEPTH     18 /* Directory depth: number of initial (most
				    significant) bits in hash interpreted as
				    index to the directory. */
# define GDBM_GETBUCKETSIZE   19 /* Get number of elements per bucket */
# define GDBM_GETCACHEAUTO    20 /* Get the value of cache auto-adjustment */
# define GDBM_SETCACHEAUTO    21 /* Set the value of cache auto-adjustment */
    
# define GDBM_CACHE_AUTO      0

typedef @GDBM_COUNT_T@ gdbm_count_t;

/* The data and key structure. */
typedef struct
{
  char *dptr;
  int   dsize;
} datum;

/* A pointer to the GDBM file. */
typedef struct gdbm_file_info *GDBM_FILE;

/* External variable, the gdbm build release string. */
extern const char *gdbm_version;	

# define GDBM_VERSION_MAJOR @GDBM_VERSION_MAJOR@
# define GDBM_VERSION_MINOR @GDBM_VERSION_MINOR@
# define GDBM_VERSION_PATCH @GDBM_VERSION_PATCH@

extern int const gdbm_version_number[3];

/* GDBM external functions. */

extern GDBM_FILE gdbm_fd_open (int fd, const char *file_name, int block_size,
			       int flags, void (*fatal_func) (const char *));
extern GDBM_FILE gdbm_open (const char *, int, int, int,
			    void (*)(const char *));
extern int gdbm_close (GDBM_FILE);
extern int gdbm_store (GDBM_FILE, datum, datum, int);
extern datum gdbm_fetch (GDBM_FILE, datum);
extern int gdbm_delete (GDBM_FILE, datum);
extern datum gdbm_firstkey (GDBM_FILE);
extern datum gdbm_nextkey (GDBM_FILE, datum);
extern int gdbm_reorganize (GDBM_FILE);
  
extern int gdbm_sync (GDBM_FILE);
extern int gdbm_failure_atomic (GDBM_FILE, const char *, const char *);

extern int gdbm_convert (GDBM_FILE dbf, int flag);
  
enum gdbm_latest_snapshot_status
  {
    GDBM_SNAPSHOT_OK,        /* Selected the right snapshot. */
    GDBM_SNAPSHOT_BAD,       /* Neither snapshot is readable. */
    GDBM_SNAPSHOT_ERR,       /* Error selecting snapshot. Inspect errno. */
    GDBM_SNAPSHOT_SAME,      /* Snapshot numsync and dates are the same. */
    GDBM_SNAPSHOT_SUSPICIOUS /* Selected snapshot is unreliable: numsyncs
				differ by more than 1. */
  };
extern int gdbm_latest_snapshot (const char *, const char *, const char **);
extern int gdbm_exists (GDBM_FILE, datum);
extern int gdbm_setopt (GDBM_FILE, int, void *, int);
extern int gdbm_fdesc (GDBM_FILE);
  
extern int gdbm_export (GDBM_FILE, const char *, int, int);
extern int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
  
extern int gdbm_import (GDBM_FILE, const char *, int);
extern int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);

extern int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
extern int gdbm_bucket_count (GDBM_FILE dbf, size_t *pcount);

extern int gdbm_avail_verify (GDBM_FILE dbf);

typedef struct gdbm_recovery_s
{
  /* Input members.
     These are initialized before call to gdbm_recover.  The flags argument
     specifies which of them are initialized. */
  void (*errfun) (void *data, char const *fmt, ...);
  void *data;

  size_t max_failed_keys;
  size_t max_failed_buckets;
  size_t max_failures;

  /* Output members.
     The gdbm_recover function fills these before returning. */
  size_t recovered_keys;
  size_t recovered_buckets;
  size_t failed_keys;
  size_t failed_buckets;
  size_t duplicate_keys;
  char *backup_name;
} gdbm_recovery;

#define GDBM_RCVR_DEFAULT              0x00  /* Default settings */
#define GDBM_RCVR_ERRFUN               0x01  /* errfun is initialized */
#define GDBM_RCVR_MAX_FAILED_KEYS      0x02  /* max_failed_keys is initialized */
#define GDBM_RCVR_MAX_FAILED_BUCKETS   0x04  /* max_failed_buckets is initialized */
#define GDBM_RCVR_MAX_FAILURES         0x08  /* max_failures is initialized */
#define GDBM_RCVR_BACKUP               0x10  /* Keep backup copy of the
						original database on success */
#define GDBM_RCVR_FORCE                0x20  /* Force recovery by skipping the
						check pass */
					       
extern int gdbm_recover (GDBM_FILE dbf, gdbm_recovery *rcvr, int flags);
  
  
#define GDBM_DUMP_FMT_BINARY 0
#define GDBM_DUMP_FMT_ASCII  1

#define GDBM_META_MASK_MODE    0x01
#define GDBM_META_MASK_OWNER   0x02
  
extern int gdbm_dump (GDBM_FILE, const char *, int fmt, int open_flags,
		      int mode);
extern int gdbm_dump_to_file (GDBM_FILE, FILE *, int fmt);

extern int gdbm_load (GDBM_FILE *, const char *, int replace,
		      int meta_flags,
		      unsigned long *line);
extern int gdbm_load_from_file (GDBM_FILE *, FILE *, int replace,
				int meta_flags,
				unsigned long *line);

extern int gdbm_copy_meta (GDBM_FILE dst, GDBM_FILE src);

enum
  {
    GDBM_NO_ERROR		 = 0,
    GDBM_MALLOC_ERROR	         = 1,
    GDBM_BLOCK_SIZE_ERROR	 = 2,
    GDBM_FILE_OPEN_ERROR	 = 3,
    GDBM_FILE_WRITE_ERROR	 = 4,
    GDBM_FILE_SEEK_ERROR	 = 5,
    GDBM_FILE_READ_ERROR	 = 6,
    GDBM_BAD_MAGIC_NUMBER	 = 7,
    GDBM_EMPTY_DATABASE	         = 8,
    GDBM_CANT_BE_READER	         = 9,
    GDBM_CANT_BE_WRITER	         = 10, 
    GDBM_READER_CANT_DELETE	 = 11,
    GDBM_READER_CANT_STORE	 = 12,
    GDBM_READER_CANT_REORGANIZE	 = 13,
    GDBM_UNKNOWN_ERROR	         = 14,
    GDBM_ITEM_NOT_FOUND	         = 15,
    GDBM_REORGANIZE_FAILED	 = 16,
    GDBM_CANNOT_REPLACE	         = 17,
    GDBM_MALFORMED_DATA	         = 18,
    GDBM_ILLEGAL_DATA            = GDBM_MALFORMED_DATA,
    GDBM_OPT_ALREADY_SET	 = 19,
    GDBM_OPT_BADVAL           	 = 20,
    GDBM_OPT_ILLEGAL           	 = GDBM_OPT_BADVAL,
    GDBM_BYTE_SWAPPED	         = 21,
    GDBM_BAD_FILE_OFFSET	 = 22,
    GDBM_BAD_OPEN_FLAGS	         = 23,
    GDBM_FILE_STAT_ERROR         = 24,
    GDBM_FILE_EOF                = 25,
    GDBM_NO_DBNAME               = 26,
    GDBM_ERR_FILE_OWNER          = 27,
    GDBM_ERR_FILE_MODE           = 28,
    GDBM_NEED_RECOVERY           = 29,
    GDBM_BACKUP_FAILED           = 30,
    GDBM_DIR_OVERFLOW            = 31,
    GDBM_BAD_BUCKET              = 32,
    GDBM_BAD_HEADER              = 33,
    GDBM_BAD_AVAIL               = 34,
    GDBM_BAD_HASH_TABLE          = 35,
    GDBM_BAD_DIR_ENTRY           = 36,
    GDBM_FILE_CLOSE_ERROR        = 37, 
    GDBM_FILE_SYNC_ERROR         = 38,
    GDBM_FILE_TRUNCATE_ERROR     = 39,
    GDBM_BUCKET_CACHE_CORRUPTED  = 40,
    GDBM_BAD_HASH_ENTRY          = 41,
    GDBM_ERR_SNAPSHOT_CLONE      = 42,
    GDBM_ERR_REALPATH            = 43,
    GDBM_ERR_USAGE               = 44
  };
  
# define _GDBM_MIN_ERRNO	0
# define _GDBM_MAX_ERRNO	GDBM_ERR_USAGE

/* This one was never used and will be removed in the future */
# define GDBM_UNKNOWN_UPDATE GDBM_UNKNOWN_ERROR
  
typedef int gdbm_error;
extern int *gdbm_errno_location (void);
#define gdbm_errno (*gdbm_errno_location ())
extern const char * const gdbm_errlist[];
extern int const gdbm_syserr[];
  
extern gdbm_error gdbm_last_errno (GDBM_FILE dbf);
extern int gdbm_last_syserr (GDBM_FILE dbf);
extern void gdbm_set_errno (GDBM_FILE dbf, gdbm_error ec, int fatal);
extern void gdbm_clear_error (GDBM_FILE dbf);
extern int gdbm_needs_recovery (GDBM_FILE dbf);
extern int gdbm_check_syserr (gdbm_error n);

/* extra prototypes */

extern const char *gdbm_strerror (gdbm_error);
extern const char *gdbm_db_strerror (GDBM_FILE dbf);
  
extern int gdbm_version_cmp (int const a[], int const b[]);

#if @GDBM_DEBUG_ENABLE@
# define GDBM_DEBUG_ENABLE 1

typedef void (*gdbm_debug_printer_t) (char const *, ...);
extern gdbm_debug_printer_t gdbm_debug_printer;
extern int gdbm_debug_flags;

# define GDBM_DEBUG_ERR    0x00000001
# define GDBM_DEBUG_OPEN   0x00000002
# define GDBM_DEBUG_READ   0x00000004
# define GDBM_DEBUG_STORE  0x00000008
# define GDBM_DEBUG_LOOKUP 0x00000010
  
# define GDBM_DEBUG_ALL    0xffffffff

extern int gdbm_debug_token (char const *tok);
extern void gdbm_debug_parse_state (int (*f) (void *, int, char const *),
				    void *d);
  
extern void gdbm_debug_datum (datum dat, char const *pfx);
#endif

/* Cache statistics */  
struct gdbm_cache_stat
{
  off_t adr;
  size_t hits;
};

void gdbm_get_cache_stats (GDBM_FILE dbf,
			   size_t *access_count,
			   size_t *cache_hits,
			   size_t *cache_count,
			   struct gdbm_cache_stat *bstat,
			   size_t nstat);
  
# if defined(__cplusplus) || defined(c_plusplus)
}
# endif

#endif

Return to:

Send suggestions and report system problems to the System administrator.