source/include/gdbm.h

0001 /* gdbm.h  -  The include file for dbm users.  -*- c -*- */
0002
0003 /*  This file is part of GDBM, the GNU data base manager, by Philip A. Nelson.
0004     Copyright (C) 1990-2022 Free Software Foundation, Inc.
0005
0006     GDBM is free software; you can redistribute it and/or modify
0007     it under the terms of the GNU General Public License as published by
0008     the Free Software Foundation; either version 2, or (at your option)
0009     any later version.
0010
0011     GDBM is distributed in the hope that it will be useful,
0012     but WITHOUT ANY WARRANTY; without even the implied warranty of
0013     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0014     GNU General Public License for more details.
0015
0016     You should have received a copy of the GNU General Public License
0017     along with GDBM. If not, see <http://www.gnu.org/licenses/>.
0018
0019     You may contact the author by:
0020        e-mail:  phil@cs.wwu.edu
0021       us-mail:  Philip A. Nelson
0022                 Computer Science Department
0023                 Western Washington University
0024                 Bellingham, WA 98226
0025
0026 *************************************************************************/
0027
0028 /* Protection for multiple includes. */
0029 #ifndef _GDBM_H_
0030 # define _GDBM_H_
0031
0032 # include <stdio.h>
0033 # include <sys/types.h>
0034
0035 /* GDBM C++ support */
0036 # if defined(__cplusplus) || defined(c_plusplus)
0037 extern "C" {
0038 # endif
0039
0040 /* Parameters to gdbm_open for READERS, WRITERS, and WRITERS who
0041    can create the database. */
0042 # define GDBM_READER    0   /* A reader. */
0043 # define GDBM_WRITER    1   /* A writer. */
0044 # define GDBM_WRCREAT   2   /* A writer.  Create the db if needed. */
0045 # define GDBM_NEWDB 3   /* A writer.  Always create a new db. */
0046 # define GDBM_OPENMASK  7   /* Mask for the above. */
0047
0048 # define GDBM_FAST  0x0010  /* Write fast! => No fsyncs.  OBSOLETE. */
0049 # define GDBM_SYNC  0x0020  /* Sync operations to the disk. */
0050 # define GDBM_NOLOCK    0x0040  /* Don't do file locking operations. */
0051 # define GDBM_NOMMAP    0x0080  /* Don't use mmap(). */
0052 # define GDBM_CLOEXEC   0x0100  /* Close the underlying fd on exec(3) */
0053 # define GDBM_BSEXACT   0x0200  /* Don't adjust block_size. Bail out with
0054                    GDBM_BLOCK_SIZE_ERROR error if unable to
0055                    set it. */
0056 # define GDBM_CLOERROR  0x0400  /* Only for gdbm_fd_open: close fd on error. */
0057 # define GDBM_XVERIFY   0x0800  /* Additional consistency checks. */
0058 # define GDBM_PREREAD   0x1000  /* Enable pre-fault reading of mmapped regions. */
0059 # define GDBM_NUMSYNC   0x2000  /* Enable the numsync extension */
0060
0061
0062 /* Parameters to gdbm_store for simple insertion or replacement in the
0063    case that the key is already in the database. */
0064 # define GDBM_INSERT    0   /* Never replace old data with new. */
0065 # define GDBM_REPLACE   1   /* Always replace old data with new. */
0066
0067 /* Parameters to gdbm_setopt, specifying the type of operation to perform. */
0068 # define GDBM_SETCACHESIZE    1  /* Set the cache size. */
0069 # define GDBM_FASTMODE        2  /* Toggle fast mode.  OBSOLETE. */
0070 # define GDBM_SETSYNCMODE     3  /* Turn on or off sync operations. */
0071 # define GDBM_SETCENTFREE     4  /* Keep all free blocks in the header. */
0072 # define GDBM_SETCOALESCEBLKS 5  /* Attempt to coalesce free blocks. */
0073 # define GDBM_SETMAXMAPSIZE   6  /* Set maximum mapped memory size */
0074 # define GDBM_SETMMAP         7  /* Toggle mmap mode */
0075
0076 /* Compatibility defines: */
0077 # define GDBM_CACHESIZE      GDBM_SETCACHESIZE
0078 # define GDBM_SYNCMODE       GDBM_SETSYNCMODE
0079 # define GDBM_CENTFREE       GDBM_SETCENTFREE
0080 # define GDBM_COALESCEBLKS   GDBM_SETCOALESCEBLKS
0081
0082 # define GDBM_GETFLAGS        8  /* Get gdbm_open flags */
0083 # define GDBM_GETMMAP         9  /* Get mmap status */
0084 # define GDBM_GETCACHESIZE    10 /* Get current cache side */
0085 # define GDBM_GETSYNCMODE     11 /* Get synch mode */
0086 # define GDBM_GETCENTFREE     12 /* Get "centfree" status */
0087 # define GDBM_GETCOALESCEBLKS 13 /* Get free block coalesce status */
0088 # define GDBM_GETMAXMAPSIZE   14 /* Get maximum mapped memory size */
0089 # define GDBM_GETDBNAME       15 /* Return database file name */
0090 # define GDBM_GETBLOCKSIZE    16 /* Return block size */
0091 # define GDBM_GETDBFORMAT     17 /* Return the database format */
0092 # define GDBM_GETDIRDEPTH     18 /* Directory depth: number of initial (most
0093                     significant) bits in hash interpreted as
0094                     index to the directory. */
0095 # define GDBM_GETBUCKETSIZE   19 /* Get number of elements per bucket */
0096 # define GDBM_GETCACHEAUTO    20 /* Get the value of cache auto-adjustment */
0097 # define GDBM_SETCACHEAUTO    21 /* Set the value of cache auto-adjustment */
0098
0099 # define GDBM_CACHE_AUTO      0
0100
0101 typedef unsigned long long int gdbm_count_t;
0102
0103 /* The data and key structure. */
0104 typedef struct
0105 {
0106   char *dptr;
0107   int   dsize;
0108 } datum;
0109
0110 /* A pointer to the GDBM file. */
0111 typedef struct gdbm_file_info *GDBM_FILE;
0112
0113 /* External variable, the gdbm build release string. */
0114 extern const char *gdbm_version;
0115
0116 # define GDBM_VERSION_MAJOR 1
0117 # define GDBM_VERSION_MINOR 23
0118 # define GDBM_VERSION_PATCH 0
0119
0120 extern int const gdbm_version_number[3];
0121
0122 /* GDBM external functions. */
0123
0124 extern GDBM_FILE gdbm_fd_open (int fd, const char *file_name, int block_size,
0125                    int flags, void (*fatal_func) (const char *));
0126 extern GDBM_FILE gdbm_open (const char *, int, int, int,
0127                 void (*)(const char *));
0128 extern int gdbm_close (GDBM_FILE);
0129 extern int gdbm_store (GDBM_FILE, datum, datum, int);
0130 extern datum gdbm_fetch (GDBM_FILE, datum);
0131 extern int gdbm_delete (GDBM_FILE, datum);
0132 extern datum gdbm_firstkey (GDBM_FILE);
0133 extern datum gdbm_nextkey (GDBM_FILE, datum);
0134 extern int gdbm_reorganize (GDBM_FILE);
0135
0136 extern int gdbm_sync (GDBM_FILE);
0137 extern int gdbm_failure_atomic (GDBM_FILE, const char *, const char *);
0138
0139 extern int gdbm_convert (GDBM_FILE dbf, int flag);
0140
0141 enum gdbm_latest_snapshot_status
0142   {
0143     GDBM_SNAPSHOT_OK,        /* Selected the right snapshot. */
0144     GDBM_SNAPSHOT_BAD,       /* Neither snapshot is readable. */
0145     GDBM_SNAPSHOT_ERR,       /* Error selecting snapshot. Inspect errno. */
0146     GDBM_SNAPSHOT_SAME,      /* Snapshot numsync and dates are the same. */
0147     GDBM_SNAPSHOT_SUSPICIOUS /* Selected snapshot is unreliable: numsyncs
0148                 differ by more than 1. */
0149   };
0150 extern int gdbm_latest_snapshot (const char *, const char *, const char **);
0151 extern int gdbm_exists (GDBM_FILE, datum);
0152 extern int gdbm_setopt (GDBM_FILE, int, void *, int);
0153 extern int gdbm_fdesc (GDBM_FILE);
0154
0155 extern int gdbm_export (GDBM_FILE, const char *, int, int);
0156 extern int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
0157
0158 extern int gdbm_import (GDBM_FILE, const char *, int);
0159 extern int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
0160
0161 extern int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
0162 extern int gdbm_bucket_count (GDBM_FILE dbf, size_t *pcount);
0163
0164 extern int gdbm_avail_verify (GDBM_FILE dbf);
0165
0166 typedef struct gdbm_recovery_s
0167 {
0168   /* Input members.
0169      These are initialized before call to gdbm_recover.  The flags argument
0170      specifies which of them are initialized. */
0171   void (*errfun) (void *data, char const *fmt, ...);
0172   void *data;
0173
0174   size_t max_failed_keys;
0175   size_t max_failed_buckets;
0176   size_t max_failures;
0177
0178   /* Output members.
0179      The gdbm_recover function fills these before returning. */
0180   size_t recovered_keys;
0181   size_t recovered_buckets;
0182   size_t failed_keys;
0183   size_t failed_buckets;
0184   size_t duplicate_keys;
0185   char *backup_name;
0186 } gdbm_recovery;
0187
0188 #define GDBM_RCVR_DEFAULT              0x00  /* Default settings */
0189 #define GDBM_RCVR_ERRFUN               0x01  /* errfun is initialized */
0190 #define GDBM_RCVR_MAX_FAILED_KEYS      0x02  /* max_failed_keys is initialized */
0191 #define GDBM_RCVR_MAX_FAILED_BUCKETS   0x04  /* max_failed_buckets is initialized */
0192 #define GDBM_RCVR_MAX_FAILURES         0x08  /* max_failures is initialized */
0193 #define GDBM_RCVR_BACKUP               0x10  /* Keep backup copy of the
0194                         original database on success */
0195 #define GDBM_RCVR_FORCE                0x20  /* Force recovery by skipping the
0196                         check pass */
0197
0198 extern int gdbm_recover (GDBM_FILE dbf, gdbm_recovery *rcvr, int flags);
0199
0200
0201 #define GDBM_DUMP_FMT_BINARY 0
0202 #define GDBM_DUMP_FMT_ASCII  1
0203
0204 #define GDBM_META_MASK_MODE    0x01
0205 #define GDBM_META_MASK_OWNER   0x02
0206
0207 extern int gdbm_dump (GDBM_FILE, const char *, int fmt, int open_flags,
0208               int mode);
0209 extern int gdbm_dump_to_file (GDBM_FILE, FILE *, int fmt);
0210
0211 extern int gdbm_load (GDBM_FILE *, const char *, int replace,
0212               int meta_flags,
0213               unsigned long *line);
0214 extern int gdbm_load_from_file (GDBM_FILE *, FILE *, int replace,
0215                 int meta_flags,
0216                 unsigned long *line);
0217
0218 extern int gdbm_copy_meta (GDBM_FILE dst, GDBM_FILE src);
0219
0220 enum
0221   {
0222     GDBM_NO_ERROR        = 0,
0223     GDBM_MALLOC_ERROR            = 1,
0224     GDBM_BLOCK_SIZE_ERROR    = 2,
0225     GDBM_FILE_OPEN_ERROR     = 3,
0226     GDBM_FILE_WRITE_ERROR    = 4,
0227     GDBM_FILE_SEEK_ERROR     = 5,
0228     GDBM_FILE_READ_ERROR     = 6,
0229     GDBM_BAD_MAGIC_NUMBER    = 7,
0230     GDBM_EMPTY_DATABASE          = 8,
0231     GDBM_CANT_BE_READER          = 9,
0232     GDBM_CANT_BE_WRITER          = 10,
0233     GDBM_READER_CANT_DELETE  = 11,
0234     GDBM_READER_CANT_STORE   = 12,
0235     GDBM_READER_CANT_REORGANIZE  = 13,
0236     GDBM_UNKNOWN_ERROR           = 14,
0237     GDBM_ITEM_NOT_FOUND          = 15,
0238     GDBM_REORGANIZE_FAILED   = 16,
0239     GDBM_CANNOT_REPLACE          = 17,
0240     GDBM_MALFORMED_DATA          = 18,
0241     GDBM_ILLEGAL_DATA            = GDBM_MALFORMED_DATA,
0242     GDBM_OPT_ALREADY_SET     = 19,
0243     GDBM_OPT_BADVAL              = 20,
0244     GDBM_OPT_ILLEGAL             = GDBM_OPT_BADVAL,
0245     GDBM_BYTE_SWAPPED            = 21,
0246     GDBM_BAD_FILE_OFFSET     = 22,
0247     GDBM_BAD_OPEN_FLAGS          = 23,
0248     GDBM_FILE_STAT_ERROR         = 24,
0249     GDBM_FILE_EOF                = 25,
0250     GDBM_NO_DBNAME               = 26,
0251     GDBM_ERR_FILE_OWNER          = 27,
0252     GDBM_ERR_FILE_MODE           = 28,
0253     GDBM_NEED_RECOVERY           = 29,
0254     GDBM_BACKUP_FAILED           = 30,
0255     GDBM_DIR_OVERFLOW            = 31,
0256     GDBM_BAD_BUCKET              = 32,
0257     GDBM_BAD_HEADER              = 33,
0258     GDBM_BAD_AVAIL               = 34,
0259     GDBM_BAD_HASH_TABLE          = 35,
0260     GDBM_BAD_DIR_ENTRY           = 36,
0261     GDBM_FILE_CLOSE_ERROR        = 37,
0262     GDBM_FILE_SYNC_ERROR         = 38,
0263     GDBM_FILE_TRUNCATE_ERROR     = 39,
0264     GDBM_BUCKET_CACHE_CORRUPTED  = 40,
0265     GDBM_BAD_HASH_ENTRY          = 41,
0266     GDBM_ERR_SNAPSHOT_CLONE      = 42,
0267     GDBM_ERR_REALPATH            = 43,
0268     GDBM_ERR_USAGE               = 44
0269   };
0270
0271 # define _GDBM_MIN_ERRNO    0
0272 # define _GDBM_MAX_ERRNO    GDBM_ERR_USAGE
0273
0274 /* This one was never used and will be removed in the future */
0275 # define GDBM_UNKNOWN_UPDATE GDBM_UNKNOWN_ERROR
0276
0277 typedef int gdbm_error;
0278 extern int *gdbm_errno_location (void);
0279 #define gdbm_errno (*gdbm_errno_location ())
0280 extern const char * const gdbm_errlist[];
0281 extern int const gdbm_syserr[];
0282
0283 extern gdbm_error gdbm_last_errno (GDBM_FILE dbf);
0284 extern int gdbm_last_syserr (GDBM_FILE dbf);
0285 extern void gdbm_set_errno (GDBM_FILE dbf, gdbm_error ec, int fatal);
0286 extern void gdbm_clear_error (GDBM_FILE dbf);
0287 extern int gdbm_needs_recovery (GDBM_FILE dbf);
0288 extern int gdbm_check_syserr (gdbm_error n);
0289
0290 /* extra prototypes */
0291
0292 extern const char *gdbm_strerror (gdbm_error);
0293 extern const char *gdbm_db_strerror (GDBM_FILE dbf);
0294
0295 extern int gdbm_version_cmp (int const a[], int const b[]);
0296
0297 #if 0
0298 # define GDBM_DEBUG_ENABLE 1
0299
0300 typedef void (*gdbm_debug_printer_t) (char const *, ...);
0301 extern gdbm_debug_printer_t gdbm_debug_printer;
0302 extern int gdbm_debug_flags;
0303
0304 # define GDBM_DEBUG_ERR    0x00000001
0305 # define GDBM_DEBUG_OPEN   0x00000002
0306 # define GDBM_DEBUG_READ   0x00000004
0307 # define GDBM_DEBUG_STORE  0x00000008
0308 # define GDBM_DEBUG_LOOKUP 0x00000010
0309
0310 # define GDBM_DEBUG_ALL    0xffffffff
0311
0312 extern int gdbm_debug_token (char const *tok);
0313 extern void gdbm_debug_parse_state (int (*f) (void *, int, char const *),
0314                     void *d);
0315
0316 extern void gdbm_debug_datum (datum dat, char const *pfx);
0317 #endif
0318
0319 /* Cache statistics */
0320 struct gdbm_cache_stat
0321 {
0322   off_t adr;
0323   size_t hits;
0324 };
0325
0326 void gdbm_get_cache_stats (GDBM_FILE dbf,
0327                size_t *access_count,
0328                size_t *cache_hits,
0329                size_t *cache_count,
0330                struct gdbm_cache_stat *bstat,
0331                size_t nstat);
0332
0333 # if defined(__cplusplus) || defined(c_plusplus)
0334 }
0335 # endif
0336
0337 #endif