1SNOBOL4NDBM(3) CSNOBOL4 Manual SNOBOL4NDBM(3)
2
6 snobol4ndbm - SNOBOL4 NDBM interface
7
9 -INCLUDE 'ndbm.sno'
10 dbhandle = DBM_OPEN(file,flags,mode)
11 DBM_CLOSE(dbhandle)
12 DBM_STORE(dbhandle,key,datum,flags)
13 datum = DBM_FETCH(dbhandle,key)
14 DBM_DELETE(dbhandle,key)
15 key = DBM_FIRSTKEY(dbhandle)
16 key = DBM_NEXTKEY(dbhandle)
17 DBM_ERROR(dbhandle)
18 DBM_CLEARERR(dbhandle)
19
21 "NDBM" (for New Data Base Management) is an industry standard fast
22 hashed storage API first created in 4.3BSD, and included in the Unix 98
23 (SUSv2) standard. The original DBM API appeared in AT&T Research Unix
24 Version 7, and only allowed access to a single file at a time.
25 There are many different implementations of this API, including:
27 • The original BSD 4.3 ndbm Based on AT&T dbm. Found in
29 commercial Un*x offerings.
30 • Berkeley DB v1 compatibility interface. Supplied with 4.4BSD
32 based systems: (Free|Open|Net)BSD, MacOS X.
33 • GNU DBM (GDBM) Found in Linux distributions (may require a DBM
35 compatibility package to be installed).
36 • SDBM, Ozan Yigit's Public Domain implementation of NDBM.
38 Supplied with this distribution, and used as a last resort on
39 Un*x systems (and by default on non Un*x systems).
40 DBM_OPEN(filename,flags,mode)
42 takes a filename (STRING), flags (either "R" for read-only, "W" for
43 write access, or "CW" to create and write a new file), and a "mode"
44 string, which defaults to "0666" (octal) and returns a database
45 handle which can be passed to the remaining functions.
46 DBM_CLOSE
48 closes the database file. DBM_CLOSE MUST be called to ensure that
49 all your data is written.
50 DBM_STORE
52 takes a database handle, key and datum strings, and a flag (either
53 DBM_INSERT to insert a new pair, or fail if the key already exists,
54 or DBM_REPLACE to insert or replace existing data). The key and
55 datum strings may contain an arbitrary series of characters.
56 DBM_FETCH
58 returns the stored datum (if any) for the supplied key, or fails.
59 DBM_DELETE
61 deletes the stored datum (if any) for the supplied key, or fails.
62 DBM_FIRSTKEY
64 and subsequent calls to DBM_NEXTKEY allow you to traverse all
65 stored keys. The keys will be returned in arbitrary order, and the
66 routines will fail at the end of the traversal.
67 DBM_ERROR
69 is a predicate which succeeds if the database handle is valid and
70 an I/O error has occurred on the file.
71 DBM_CLEARERR
73 is a predicate which succeeds if if the database handle is valid,
74 and has the side effect of clearing the I/O error flag.
75
77 NDBM, GDBM, and SDBM create two files: filename.dir and filename.pag.
78 Berkeley DB creates a single filename.db file.
79
81 snobol4sqlite3dbm(3), ndbm(3), dbopen(3), gdbm(3).
82
84 Philip L. Budne
85
87 Not safe for concurrent read and write. The snobol4sqlite3dbm(3)
88 interface achieves this portably using snobol4sqlite3(3).
89 Some implementations (classic NDBM and SDBM) place limits on the total
91 size of key plus datum (typically slightly less than 1KB).
92 NOTE: Some implementations (classic NDBM and SDBM) create sparse files
94 which appear (to "ls -l") to be larger than they are (see "ls -s").
95 Copying such files may cause the non-allocated blocks to be "filled"
96 with zeroed disk blocks, and then the files really will be large!
97 Only GDBM provides locking to eliminate the possibility of file
99 corruption, or reading of incomplete data.
100 GDBM locking sometimes fails on NFS mounted partitions but does not
102 provide a way to disable locking.
103 DBM databases accessed concurrently by multiple processes are
105 traditionally (re)created from text files and used for fast disk-based
106 read-only table lookups. Programs which need to update the file
107 generate a new temporary copy using a different name, and then rename
108 the new file(s), so that the next reader gets the new copies (existing
109 readers continue to see old data).
110CSNOBOL4B 2.3.1 March 31, 2022 SNOBOL4NDBM(3)