Home | History | Annotate | Line # | Download | only in hash
README revision 1.1 
      1 #	@(#)README	5.3 (Berkeley) 2/22/91
      2 
      3 This package implements a superset of the hsearch and dbm/ndbm libraries.
      4 
      5 Contents:
      6 
      7 Hashing Package:
      8 	dynahash.c
      9 	page.c
     10 	buf.c
     11 	big.c
     12 	hfunc.c
     13 	log2.c
     14 
     15 	hash.h
     16 	page.h
     17 	db.h
     18 
     19 Backward Compatibility Routines:
     20 	ndbm.c
     21 	ndbm.h
     22 	hsearch.c
     23 	search.h
     24 
     25 Misc:
     26 	byte_order.c
     27 
     28 Compatibility routines:
     29 	mkstemp.c
     30 
     31 	ansi.h
     32 	bsd.h
     33 	cdefs.h
     34 	endian.h
     35 	posix.h
     36 	unistd.h
     37 
     38 DIFFS:
     39 	These are diffs since the date of the file (i.e. a file labeled
     40 	DIFFS.2.12 are the diffs since the 2.12 version on arpa).  The
     41 	date of the DIFF file indicates when those diffs were installed.
     42 
     43 Test Programs:
     44 	All test programs which need key/data pairs expect them entered
     45 	with key and data on separate lines
     46 
     47 	tcreat3.c	
     48 		Takes 
     49 			bucketsize (bsize), 
     50 			fill factor (ffactor), and
     51 			initial number of elements (nelem).  
     52 		Creates a hash table named hashtest containing the 
     53 		keys/data pairs entered from standard in.
     54 	thash4.c
     55 		Takes
     56 			bucketsize (bsize), 
     57 			fill factor (ffactor), 
     58 			initial number of elements (nelem)
     59 			bytes of cache (ncached), and
     60 			file from which to read data  (fname)
     61 		Creates a table from the key/data pairs on standard in and
     62 		then does a read of each key/data in fname
     63 	tdel.c
     64 		Takes
     65 			bucketsize (bsize), and
     66 			fill factor (ffactor).
     67 			file from which to read data (fname)
     68 		Reads each key/data pair from fname and deletes the
     69 		key from the hash table hashtest
     70 	tseq.c
     71 		Reads the key/data pairs in the file hashtest and writes them
     72 		to standard out.
     73 	tread2.c
     74 		Takes
     75 			butes of cache (ncached).
     76 		Reads key/data pairs from standard in and looks them up
     77 		in the file hashtest.
     78 	tverify.c
     79 		Reads key/data pairs from standard in, looks them up
     80 		in the file hashtest, and verifies that the data is
     81 		correct.
     82 
     83 NOTES:
     84 
     85 If you are not running a 4.3BSD-Reno or later system, you may need to use
     86 some of the compatibility files provided.  The files are as follows:
     87 
     88 	mkstemp.c	Mkstemp/mktemp library routine.
     89 
     90 	ansi.h		Map bcopy and friends to memcpy and friends.
     91 	bsd.h		Map various new BSD things to old things.
     92 	cdefs.h		Handle the function prototypes in other include files.
     93 	endian.h	Handle byte ordering.  Be sure to set BYTE_ORDER in
     94 			endian.h appropriately for your machine.  If you don't
     95 			know what "endian" your machine is, compile
     96 			byte_order.c and run it.  It should tell you.
     97 	posix.h		Map various POSIX 1003.1 things to old-style things.
     98 	unistd.h	POSIX 1003.1 definitions.
     99 
    100 If you are not running on the current BSD release (4.3BSD-Reno+), you will
    101 need to include bsd.h in hash.h.  Depending on what system you are running
    102 on, you will need to add the other compatibility h files in hash.h.
    103 
    104 The file search.h is provided for using the hsearch compatible interface
    105 on BSD systems.  On System V derived systems, search.h should appear in 
    106 /usr/include.
    107 
    108 The man page db.3 explains the interface to the hashing system.
    109 The file hash.ps is a postscript copy of a paper explaining
    110 the history, implementation, and performance of the hash package.
    111 
    112 "bugs" or idiosyncracies
    113 
    114 If you have a lot of overflows, it is possible to run out of overflow
    115 pages.  Currently, this will cause a message to be printed on stderr.
    116 Eventually, this will be indicated by a return error code.
    117 
    118 If you are using the ndbm interface and exit without flushing or closing the
    119 file, you may lose updates since the package buffers all writes.  Also,
    120 the db interface only creates a single database file.  To avoid overwriting
    121 the user's original file, the suffix ".db" is appended to the file name
    122 passed to dbm_open.  Additionally, if your code "knows" about the historic
    123 .dir and .pag files, it will break.  
    124 
    125 There is a fundamental difference between this package and the old hsearch.
    126 Hsearch requires the user to maintain the keys and data in the application's
    127 allocated memory while hash takes care of all storage management.  The down
    128 side is that the byte strings passed in the ENTRY structure must be null
    129 terminated (both the keys and the data).
    130