| 1 | .\" Copyright (c) 1985 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement |
| 3 | .\" specifies the terms and conditions for redistribution. |
| 4 | .\" |
| 5 | .\" @(#)ndbm.3 6.1 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH NDBM 3X "" |
| 8 | .UC 6 |
| 9 | .SH NAME |
| 10 | dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- data base subroutines |
| 11 | .SH SYNOPSIS |
| 12 | .nf |
| 13 | .PP |
| 14 | .ft B |
| 15 | #include <ndbm.h> |
| 16 | .PP |
| 17 | .ft B |
| 18 | typedef struct { |
| 19 | char *dptr; |
| 20 | int dsize; |
| 21 | } datum; |
| 22 | .PP |
| 23 | .ft B |
| 24 | DBM *dbm_open(file, flags, mode) |
| 25 | char *file; |
| 26 | int flags, mode; |
| 27 | .PP |
| 28 | .ft B |
| 29 | dbm_close(db) |
| 30 | DBM *db; |
| 31 | .PP |
| 32 | .ft B |
| 33 | datum dbm_fetch(db, key) |
| 34 | DBM *db; |
| 35 | struct key; |
| 36 | datum key; |
| 37 | .PP |
| 38 | .ft B |
| 39 | dbm_store(db, key, content, flags) |
| 40 | DBM *db; |
| 41 | datum key, content; |
| 42 | int flags; |
| 43 | .PP |
| 44 | .ft B |
| 45 | dbm_delete(db, key) |
| 46 | DBM *db; |
| 47 | datum key; |
| 48 | .PP |
| 49 | .ft B |
| 50 | datum dbm_firstkey(db) |
| 51 | DBM *db; |
| 52 | .PP |
| 53 | .ft B |
| 54 | datum dbm_nextkey(db) |
| 55 | DBM *db; |
| 56 | .PP |
| 57 | .ft B |
| 58 | datum dbm_error(db) |
| 59 | DBM *db; |
| 60 | .PP |
| 61 | .ft B |
| 62 | datum dbm_clearerr(db) |
| 63 | DBM *db; |
| 64 | .SH DESCRIPTION |
| 65 | These functions maintain key/content pairs in a data base. |
| 66 | The functions will handle very large (a billion blocks) |
| 67 | databases and will access a keyed item in one or two file system accesses. |
| 68 | .PP |
| 69 | .IR Key s |
| 70 | and |
| 71 | .IR content s |
| 72 | are described by the |
| 73 | .I datum |
| 74 | typedef. A |
| 75 | .I datum |
| 76 | specifies a string of |
| 77 | .I dsize |
| 78 | bytes pointed to by |
| 79 | .I dptr. |
| 80 | Arbitrary binary data, as well as normal ASCII strings, are allowed. |
| 81 | The data base is stored in two files. |
| 82 | One file is a directory containing a bit map and has `.dir' as its suffix. |
| 83 | The second file contains all data and has `.pag' as its suffix. |
| 84 | .PP |
| 85 | Before a database can be accessed, it must be opened by |
| 86 | .IR dbm_open . |
| 87 | This will open and/or create the files |
| 88 | .IB file .dir |
| 89 | and |
| 90 | .IB file .pag |
| 91 | depending on the flags parameter (see |
| 92 | .IR open (2)). |
| 93 | .PP |
| 94 | Once open, the data stored under a key is accessed by |
| 95 | .I dbm_fetch |
| 96 | and data is placed under a key by |
| 97 | .IR dbm_store . |
| 98 | The |
| 99 | .I flags |
| 100 | field can be either |
| 101 | .B DBM_INSERT |
| 102 | or |
| 103 | .B DBM_REPLACE. |
| 104 | .B DBM_INSERT |
| 105 | will only insert new entries into the database and will not |
| 106 | change an existing entry with the same key. |
| 107 | .B DBM_REPLACE |
| 108 | will replace an existing entry if it has the same key. |
| 109 | A key (and its associated contents) is deleted by |
| 110 | .IR dbm_delete . |
| 111 | A linear pass through all keys in a database may be made, |
| 112 | in an (apparently) random order, by use of |
| 113 | .I dbm_firstkey |
| 114 | and |
| 115 | .IR dbm_nextkey . |
| 116 | .I Dbm_firstkey |
| 117 | will return the first key in the database. |
| 118 | .I Dbm_nextkey |
| 119 | will return the next key in the database. |
| 120 | This code will traverse the data base: |
| 121 | .IP |
| 122 | .B for |
| 123 | (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) |
| 124 | .PP |
| 125 | .I Dbm_error |
| 126 | returns non-zero when an error has occured reading or writing the database. |
| 127 | .I Dbm_clearerr |
| 128 | Resets the error condition on the named database. |
| 129 | .SH DIAGNOSTICS |
| 130 | All functions that return an |
| 131 | .I int |
| 132 | indicate errors with negative values. A zero return indicates ok. |
| 133 | Routines that return a |
| 134 | .I datum |
| 135 | indicate errors with a null (0) |
| 136 | .I dptr. |
| 137 | .SH BUGS |
| 138 | The `.pag' file will contain holes so that its apparent size is about |
| 139 | four times its actual content. Older UNIX systems may create real |
| 140 | file blocks for these holes when touched. These files cannot be copied |
| 141 | by normal means (cp, cat, tp, tar, ar) without filling in the holes. |
| 142 | .PP |
| 143 | .I Dptr |
| 144 | pointers returned by these subroutines point into static storage |
| 145 | that is changed by subsequent calls. |
| 146 | .PP |
| 147 | The sum of the sizes of a key/content pair must not exceed |
| 148 | the internal block size (currently 4096 bytes). |
| 149 | Moreover all key/content pairs that hash together must fit on a single block. |
| 150 | .I Dbm_store |
| 151 | will return an error in the event that a disk block fills with inseparable data. |
| 152 | .PP |
| 153 | .I Dbm_delete |
| 154 | does not physically reclaim file space, |
| 155 | although it does make it available for reuse. |
| 156 | .PP |
| 157 | The order of keys presented by |
| 158 | .I dbm_firstkey |
| 159 | and |
| 160 | .I dbm_nextkey |
| 161 | depends on a hashing function, not on anything interesting. |