1dbm(3UCB)          SunOS/BSD Compatibility Library Functions         dbm(3UCB)
2
3
4

NAME

6       dbm,  dbminit, dbmclose, fetch, store, delete, firstkey, nextkey - data
7       base subroutines
8

SYNOPSIS

10       /usr/ucb/cc [ flag ... ] file ... -ldbm
11       #include <dbm.h>
12
13       typedef struct {
14            char *dptr;
15            int dsize;
16        }datum;
17
18       int dbminit(file)
19       char *file;
20
21
22       int dbmclose();
23
24
25       datum fetch(key)
26       datum key;
27
28
29       int store( key, dat)
30       datum key, dat;
31
32
33       int delete(key)
34       datum key;
35
36
37       datum firstkey();
38
39
40       datum nextkey(key)
41       datum key;
42
43

DESCRIPTION

45       The dbm() library has been superseded by ndbm (see ndbm(3C)).
46
47
48       These functions maintain key/content pairs in a data  base.  The  func‐
49       tions  will  handle  very  large  (a billion blocks) databases and will
50       access a keyed item in one or two file system accesses.
51
52
53       key/dat and their content are described by the datum typedef.  A  datum
54       specifies  a string of dsize bytes pointed to by dptr. Arbitrary binary
55       data, as well as normal ASCII strings, are allowed. The  data  base  is
56       stored  in  two files. One file is a directory containing a bit map and
57       has .dir as its suffix. The second file contains all data and has  .pag
58       as its suffix.
59
60
61       Before  a  database can be accessed, it must be opened by dbminit(). At
62       the time of this call, the files file.dir and file.pag must  exist.  An
63       empty database is created by creating zero-length .dir and .pag files.
64
65
66       A  database may be closed by calling dbmclose(). You must close a data‐
67       base before opening a new one.
68
69
70       Once open, the data stored under a key is accessed by fetch() and  data
71       is  placed under a key by store. A key (and its associated contents) is
72       deleted by delete(). A linear pass through all keys in a  database  may
73       be made, in an (apparently) random order, by use of firstkey() and nex‐
74       tkey(). firstkey() will return the first key in the database. With  any
75       key  nextkey() will return the next key in the database. This code will
76       traverse the data base:
77
78         for (key = firstkey; key.dptr != NULL; key = nextkey(key))
79
80

RETURN VALUES

82       All functions that return an int indicate errors with negative  values.
83       A zero return indicates no error. Routines that return a datum indicate
84       errors with a NULL (0) dptr.
85

SEE ALSO

87       ar(1), cat(1), cp(1), tar(1), ndbm(3C)
88

NOTES

90       Use of these interfaces should be restricted to only applications writ‐
91       ten  on  BSD platforms.  Use of these interfaces with any of the system
92       libraries or in multi-thread applications is unsupported.
93
94
95       The .pag file will contain holes so  that  its  apparent  size  may  be
96       larger  than  its  actual content. Older versions of the UNIX operating
97       system may create real file blocks for these holes when touched.  These
98       files  cannot be copied by normal means ( cp(1), cat(1), tar(1), ar(1))
99       without filling in the holes.
100
101
102       dptr pointers returned by these subroutines point into  static  storage
103       that is changed by subsequent calls.
104
105
106       The sum of the sizes of a key/content pair must not exceed the internal
107       block size (currently 1024 bytes). Moreover all key/content pairs  that
108       hash together must fit on a single block. store will return an error in
109       the event that a disk block fills with inseparable data.
110
111
112       delete() does not physically reclaim file space, although it does  make
113       it available for reuse.
114
115
116       The  order  of  keys presented by firstkey() and nextkey() depends on a
117       hashing function, not on anything interesting.
118
119
120       There are no interlocks and no reliable cache flushing; thus concurrent
121       updating and reading is risky.
122
123
124       The database files (file.dir and file.pag) are binary and are architec‐
125       ture-specific (for example, they  depend  on  the  architecture's  byte
126       order.)  These files are not guaranteed to be portable across architec‐
127       tures.
128
129
130
131SunOS 5.11                        30 Oct 2007                        dbm(3UCB)
Impressum