xref: /freebsd/lib/libc/db/hash/README (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1#	@(#)README	8.1 (Berkeley) 6/4/93
2
3This package implements a superset of the hsearch and dbm/ndbm libraries.
4
5Test Programs:
6	All test programs which need key/data pairs expect them entered
7	with key and data on separate lines
8
9	tcreat3.c
10		Takes
11			bucketsize (bsize),
12			fill factor (ffactor), and
13			initial number of elements (nelem).
14		Creates a hash table named hashtest containing the
15		keys/data pairs entered from standard in.
16	thash4.c
17		Takes
18			bucketsize (bsize),
19			fill factor (ffactor),
20			initial number of elements (nelem)
21			bytes of cache (ncached), and
22			file from which to read data  (fname)
23		Creates a table from the key/data pairs on standard in and
24		then does a read of each key/data in fname
25	tdel.c
26		Takes
27			bucketsize (bsize), and
28			fill factor (ffactor).
29			file from which to read data (fname)
30		Reads each key/data pair from fname and deletes the
31		key from the hash table hashtest
32	tseq.c
33		Reads the key/data pairs in the file hashtest and writes them
34		to standard out.
35	tread2.c
36		Takes
37			butes of cache (ncached).
38		Reads key/data pairs from standard in and looks them up
39		in the file hashtest.
40	tverify.c
41		Reads key/data pairs from standard in, looks them up
42		in the file hashtest, and verifies that the data is
43		correct.
44
45NOTES:
46
47The file search.h is provided for using the hsearch compatible interface
48on BSD systems.  On System V derived systems, search.h should appear in
49/usr/include.
50
51The man page ../man/db.3 explains the interface to the hashing system.
52The file hash.ps is a postscript copy of a paper explaining
53the history, implementation, and performance of the hash package.
54
55"bugs" or idiosyncracies
56
57If you have a lot of overflows, it is possible to run out of overflow
58pages.  Currently, this will cause a message to be printed on stderr.
59Eventually, this will be indicated by a return error code.
60
61If you are using the ndbm interface and exit without flushing or closing the
62file, you may lose updates since the package buffers all writes.  Also,
63the db interface only creates a single database file.  To avoid overwriting
64the user's original file, the suffix ".db" is appended to the file name
65passed to dbm_open.  Additionally, if your code "knows" about the historic
66.dir and .pag files, it will break.
67
68There is a fundamental difference between this package and the old hsearch.
69Hsearch requires the user to maintain the keys and data in the application's
70allocated memory while hash takes care of all storage management.  The down
71side is that the byte strings passed in the ENTRY structure must be null
72terminated (both the keys and the data).
73