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