![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ndbm.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to ndbm.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 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.8 (Berkeley) 1/2/90
6: .\"
7: .TH NDBM 3 "January 2, 1990"
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: void dbm_close(db)
30: DBM *db;
31: .PP
32: .ft B
33: datum dbm_fetch(db, key)
34: DBM *db;
35: datum key;
36: .PP
37: .ft B
38: int dbm_store(db, key, content, flags)
39: DBM *db;
40: datum key, content;
41: int flags;
42: .PP
43: .ft B
44: int dbm_delete(db, key)
45: DBM *db;
46: datum key;
47: .PP
48: .ft B
49: datum dbm_firstkey(db)
50: DBM *db;
51: .PP
52: .ft B
53: datum dbm_nextkey(db)
54: DBM *db;
55: .PP
56: .ft B
57: int dbm_error(db)
58: DBM *db;
59: .PP
60: .ft B
61: int dbm_clearerr(db)
62: DBM *db;
63: .SH DESCRIPTION
64: These functions maintain key/content pairs in a data base.
65: The functions will handle very large (a billion blocks)
66: databases and will access a keyed item in one or two file system accesses.
67: This package replaces the earlier
68: .IR dbm (3x)
69: library, which managed only a single database.
70: .PP
71: .IR Key s
72: and
73: .IR content s
74: are described by the
75: .I datum
76: typedef. A
77: .I datum
78: specifies a string of
79: .I dsize
80: bytes pointed to by
81: .I dptr.
82: Arbitrary binary data, as well as normal ASCII strings, are allowed.
83: The data base is stored in two files.
84: One file is a directory containing a bit map and has `.dir' as its suffix.
85: The second file contains all data and has `.pag' as its suffix.
86: .PP
87: Before a database can be accessed, it must be opened by
88: .IR dbm_open .
89: This will open and/or create the files
90: .IB file .dir
91: and
92: .IB file .pag
93: depending on the flags parameter (see
94: .IR open (2)).
95: .PP
96: Once open, the data stored under a key is accessed by
97: .I dbm_fetch
98: and data is placed under a key by
99: .IR dbm_store .
100: The
101: .I flags
102: field can be either
103: .B DBM_INSERT
104: or
105: .B DBM_REPLACE.
106: .B DBM_INSERT
107: will only insert new entries into the database and will not
108: change an existing entry with the same key.
109: .B DBM_REPLACE
110: will replace an existing entry if it has the same key.
111: A key (and its associated contents) is deleted by
112: .IR dbm_delete .
113: A linear pass through all keys in a database may be made,
114: in an (apparently) random order, by use of
115: .I dbm_firstkey
116: and
117: .IR dbm_nextkey .
118: .I Dbm_firstkey
119: will return the first key in the database.
120: .I Dbm_nextkey
121: will return the next key in the database.
122: This code will traverse the data base:
123: .IP
124: .B for
125: (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
126: .PP
127: .I Dbm_error
128: returns non-zero when an error has occurred reading or writing the database.
129: .I Dbm_clearerr
130: resets the error condition on the named database.
131: .SH DIAGNOSTICS
132: All functions that return an
133: .I int
134: indicate errors with negative values. A zero return indicates ok.
135: Routines that return a
136: .I datum
137: indicate errors with a null (0)
138: .I dptr.
139: If
140: .IR dbm_store
141: called with a
142: .I flags
143: value of
144: .B DBM_INSERT
145: finds an existing entry with the same key
146: it returns 1.
147: .SH BUGS
148: The `.pag' file will contain holes so that its apparent size is about
149: four times its actual content. Older UNIX systems may create real
150: file blocks for these holes when touched. These files cannot be copied
151: by normal means (cp, cat, tp, tar, ar) without filling in the holes.
152: .PP
153: .I Dptr
154: pointers returned by these subroutines point into static storage that is
155: changed by subsequent calls. This storage is not necessarily aligned;
156: stored ``longs'', for example, should be copied to a properly aligned
157: block of memory before being accessed.
158: .PP
159: The sum of the sizes of a key/content pair must not exceed
160: the internal block size (currently 1024 bytes).
161: Moreover all key/content pairs that hash together must fit on a single block.
162: .I Dbm_store
163: will return an error in the event that a disk block fills with inseparable data.
164: .PP
165: .I Dbm_delete
166: does not physically reclaim file space,
167: although it does make it available for reuse.
168: .PP
169: The order of keys presented by
170: .I dbm_firstkey
171: and
172: .I dbm_nextkey
173: depends on a hashing function, not on anything interesting.
174: .SH SEE ALSO
175: dbm(3X)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.