11573Srgrimes# @(#)README 8.1 (Berkeley) 6/4/93 2190498Sdelphij# $FreeBSD: releng/10.2/lib/libc/db/hash/README 190498 2009-03-28 07:31:02Z delphij $ 31573Srgrimes 41573SrgrimesThis package implements a superset of the hsearch and dbm/ndbm libraries. 51573Srgrimes 61573SrgrimesTest Programs: 71573Srgrimes All test programs which need key/data pairs expect them entered 81573Srgrimes with key and data on separate lines 91573Srgrimes 101573Srgrimes tcreat3.c 111573Srgrimes Takes 121573Srgrimes bucketsize (bsize), 131573Srgrimes fill factor (ffactor), and 141573Srgrimes initial number of elements (nelem). 151573Srgrimes Creates a hash table named hashtest containing the 161573Srgrimes keys/data pairs entered from standard in. 171573Srgrimes thash4.c 181573Srgrimes Takes 191573Srgrimes bucketsize (bsize), 201573Srgrimes fill factor (ffactor), 211573Srgrimes initial number of elements (nelem) 221573Srgrimes bytes of cache (ncached), and 231573Srgrimes file from which to read data (fname) 241573Srgrimes Creates a table from the key/data pairs on standard in and 251573Srgrimes then does a read of each key/data in fname 261573Srgrimes tdel.c 271573Srgrimes Takes 281573Srgrimes bucketsize (bsize), and 291573Srgrimes fill factor (ffactor). 301573Srgrimes file from which to read data (fname) 311573Srgrimes Reads each key/data pair from fname and deletes the 321573Srgrimes key from the hash table hashtest 331573Srgrimes tseq.c 341573Srgrimes Reads the key/data pairs in the file hashtest and writes them 351573Srgrimes to standard out. 361573Srgrimes tread2.c 371573Srgrimes Takes 381573Srgrimes butes of cache (ncached). 391573Srgrimes Reads key/data pairs from standard in and looks them up 401573Srgrimes in the file hashtest. 411573Srgrimes tverify.c 421573Srgrimes Reads key/data pairs from standard in, looks them up 431573Srgrimes in the file hashtest, and verifies that the data is 441573Srgrimes correct. 451573Srgrimes 461573SrgrimesNOTES: 471573Srgrimes 481573SrgrimesThe man page ../man/db.3 explains the interface to the hashing system. 491573SrgrimesThe file hash.ps is a postscript copy of a paper explaining 501573Srgrimesthe history, implementation, and performance of the hash package. 511573Srgrimes 521573Srgrimes"bugs" or idiosyncracies 531573Srgrimes 541573SrgrimesIf you have a lot of overflows, it is possible to run out of overflow 551573Srgrimespages. Currently, this will cause a message to be printed on stderr. 561573SrgrimesEventually, this will be indicated by a return error code. 571573Srgrimes 581573SrgrimesIf you are using the ndbm interface and exit without flushing or closing the 591573Srgrimesfile, you may lose updates since the package buffers all writes. Also, 601573Srgrimesthe db interface only creates a single database file. To avoid overwriting 611573Srgrimesthe user's original file, the suffix ".db" is appended to the file name 621573Srgrimespassed to dbm_open. Additionally, if your code "knows" about the historic 631573Srgrimes.dir and .pag files, it will break. 641573Srgrimes 651573SrgrimesThere is a fundamental difference between this package and the old hsearch. 661573SrgrimesHsearch requires the user to maintain the keys and data in the application's 671573Srgrimesallocated memory while hash takes care of all storage management. The down 681573Srgrimesside is that the byte strings passed in the ENTRY structure must be null 691573Srgrimesterminated (both the keys and the data). 70