[unix-history] / lib / libc / db / hash / README

#	@(#)README	8.1 (Berkeley) 6/4/93

This package implements a superset of the hsearch and dbm/ndbm libraries.

Test Programs:
	All test programs which need key/data pairs expect them entered
	with key and data on separate lines

	tcreat3.c	
		Takes 
			bucketsize (bsize), 
			fill factor (ffactor), and
			initial number of elements (nelem).  
		Creates a hash table named hashtest containing the 
		keys/data pairs entered from standard in.
	thash4.c
		Takes
			bucketsize (bsize), 
			fill factor (ffactor), 
			initial number of elements (nelem)
			bytes of cache (ncached), and
			file from which to read data  (fname)
		Creates a table from the key/data pairs on standard in and
		then does a read of each key/data in fname
	tdel.c
		Takes
			bucketsize (bsize), and
			fill factor (ffactor).
			file from which to read data (fname)
		Reads each key/data pair from fname and deletes the
		key from the hash table hashtest
	tseq.c
		Reads the key/data pairs in the file hashtest and writes them
		to standard out.
	tread2.c
		Takes
			butes of cache (ncached).
		Reads key/data pairs from standard in and looks them up
		in the file hashtest.
	tverify.c
		Reads key/data pairs from standard in, looks them up
		in the file hashtest, and verifies that the data is
		correct.

NOTES:

The file search.h is provided for using the hsearch compatible interface
on BSD systems.  On System V derived systems, search.h should appear in 
/usr/include.

The man page ../man/db.3 explains the interface to the hashing system.
The file hash.ps is a postscript copy of a paper explaining
the history, implementation, and performance of the hash package.

"bugs" or idiosyncracies

If you have a lot of overflows, it is possible to run out of overflow
pages.  Currently, this will cause a message to be printed on stderr.
Eventually, this will be indicated by a return error code.

If you are using the ndbm interface and exit without flushing or closing the
file, you may lose updates since the package buffers all writes.  Also,
the db interface only creates a single database file.  To avoid overwriting
the user's original file, the suffix ".db" is appended to the file name
passed to dbm_open.  Additionally, if your code "knows" about the historic
.dir and .pag files, it will break.  

There is a fundamental difference between this package and the old hsearch.
Hsearch requires the user to maintain the keys and data in the application's
allocated memory while hash takes care of all storage management.  The down
side is that the byte strings passed in the ENTRY structure must be null
terminated (both the keys and the data).
Commit	Line	Data
78ed81a3	1	# @(#)README 8.1 (Berkeley) 6/4/93
15637ed4 RG	2
	3	This package implements a superset of the hsearch and dbm/ndbm libraries.
	4
15637ed4 RG	5	Test 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
	45	NOTES:
	46
15637ed4 RG	47	The file search.h is provided for using the hsearch compatible interface
	48	on BSD systems. On System V derived systems, search.h should appear in
	49	/usr/include.
	50
78ed81a3	51	The man page ../man/db.3 explains the interface to the hashing system.
15637ed4 RG	52	The file hash.ps is a postscript copy of a paper explaining
	53	the history, implementation, and performance of the hash package.
	54
	55	"bugs" or idiosyncracies
	56
	57	If you have a lot of overflows, it is possible to run out of overflow
	58	pages. Currently, this will cause a message to be printed on stderr.
	59	Eventually, this will be indicated by a return error code.
	60
	61	If you are using the ndbm interface and exit without flushing or closing the
	62	file, you may lose updates since the package buffers all writes. Also,
	63	the db interface only creates a single database file. To avoid overwriting
	64	the user's original file, the suffix ".db" is appended to the file name
	65	passed to dbm_open. Additionally, if your code "knows" about the historic
	66	.dir and .pag files, it will break.
	67
	68	There is a fundamental difference between this package and the old hsearch.
	69	Hsearch requires the user to maintain the keys and data in the application's
	70	allocated memory while hash takes care of all storage management. The down
	71	side is that the byte strings passed in the ENTRY structure must be null
	72	terminated (both the keys and the data).