.TH DBM 2.SH NAMEDbm: Dbf, init \- data base with hashed indexing.SH SYNOPSIS.EXinclude "dbm.m"; dbm := load Dbm Dbm->PATH;Datum, Dbf: import dbm; Datum:  type array of byte; Dbf: adt {    create: fn(file: string, perm: int): ref Dbf;    open:   fn(file: string, flags: int): ref Dbf;     fetch:  fn(db: self ref Dbf, key: Datum): Datum;    delete: fn(db: self ref Dbf, key: Datum): int;    store:  fn(db: self ref Dbf, key: Datum, data: Datum,                  replace: int): int;     firstkey: fn(db: self ref Dbf): Datum;    nextkey:  fn(db: self ref Dbf, key: Datum): Datum;     flush:    fn(db: self ref Dbf);    isrdonly: fn(db: self ref Dbf): int;}; init:   fn();.EE.SH DESCRIPTION.B Dbmmaintainskey/content pairs in a data base.The functions will handle very large(a billion blocks)databases and will access a keyed itemin one or two filesystem accesses..PP.IR Key sand.IR content sare both represented by arrays of bytes(with the synonym.BR Datum ),allowingarbitrary binary values..PPThe data base is stored in two files.One file is a directory containing a bit mapand has.L .diras its suffix.The second file contains all data and has.L .pagas its suffix.An application can access several databases at once, but must avoidconcurrent operations on any one database (eg, by using a monitor process to control access)..PP.B Initmust be called before any other operation of the module..PPA database is created by.IR Dbf.create ,which accepts a file permission parameter.IR perm ,as described for.B Sys->create(see.IR sys-open (2));it creates the two files.IB file .dirand.IB file .pag .If successful, it returns a.B Dbfreference describing the database, whichis open for reading and writing.(It will truncate an existing database.)It returns nil if it cannot create the database for some reason,and sets the error string..PP.B Dbf.openaccepts a.I modeparameter as described in.IR sys-open (2),and opens the existing database in.IB file .dirand.IB file .pag .If successful, it returns a.B Dbfreference describing the database,which is open either for reading and writing (ie,.BR Sys->ORDWR ),or only for reading.RB ( Sys->OREAD )as determined by.IR mode .It returns nil if the database cannot be opened successfully, and sets the error string..PPThe remaining operations apply to an existing.B Dbfreference.IR db :.TP.IB db .fetch( key )Return the data stored under a.IR key ;nil is returned if the key is not in the database..TP.IB db .store( key,\ data,\ replace )Store.I dataunder the given.IR key .If.I replaceis non-zero,.B storewill simply replace the existing value by the new one if the key is alreadyin the database;if.I replaceis zero.B storewill return 0 if the new item was inserted, but1 if the key already appears in the database,and the new value will not be stored..TP.IB db .delete( key ).I Keyand its associated valueis removed from the database..TP.IB db .firstkey()Return the first key in the database;return nil if the database is empty..TP.IB db .nextkey( key )Return the key following the given.IR key ,or nil if there is none..TP.IB db .flush()Discard any data cached from the file.The cache is write-through, so it is not necessary to flush the filebefore the application exits..TP.IB db .isrdonly()Return true if.I dbwas opened only for reading and writes are not allowed..SH EXAMPLE.PPA linear pass through all keys in a databasemay be made,in an (apparently) random order,by use of.B Dbf.firstkeyand.BR Dbf.nextkey .This code will traverse the data base:.IP.EXfor(key := db.firstkey(); key != nil; key = db.nextkey(key)){	d := db.fetch(key);}.EE.PPThe order of keys presented by.B Dbf.firstkeyand.B Dbf.nextkeydepends on a hashing function, not on anythinginteresting..SH SOURCE.B /appl/lib/dbm.b.SH DIAGNOSTICSAll functions that return an.I intindicate errors with negative values.A zero return indicates success.Routines that return pointers, including values of.BR Datum ,return nil values on error..B Dbf.createand.B Dbf.openreturn nil on failure to access the database,setting the error string to a more detailed diagnostic..SH BUGSOn some systems (notably Plan 9 but also some Unix systems),the.B .pagfile might contain holes where no data block has ever been written sothat its apparent size is aboutfour times its actual content.These files cannot be copiedby normal means (cp, cat)without filling in the holes..PPExcept for.B firstkeyand.BR nextkey ,.B Datumvalues returnedby these functionspoint to storagethat is changed by subsequent calls..PPThe sum of the sizes of akey/content pair must not exceedthe internal block size(currently 512 bytes).Moreover all key/content pairs that hashtogether must fit on a single block..B Dbf.storewill return an error in the event thata block fills with inseparable data.