home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rcs / sources / readme < prev    next >
Text File  |  1991-05-23  |  15KB  |  421 lines
  1. /*
  2.  * MS-DOS port (c) 1990 by Thorsten Ohl, td12@@ddagsi3.bitnet
  3.  *
  4.  * To this port, the same copying conditions apply as to the
  5.  * original release.
  6.  *
  7.  * IMPORTANT:
  8.  * These files are not identical to the original GNU release!
  9.  * You should have received this code as patch to the official
  10.  * GNU release.
  11.  *
  12.  * MORE IMPORTANT:
  13.  * This port comes with ABSOLUTELY NO WARRANTY.
  14.  */
  15.  
  16. Note: This port was done for 1.4.
  17. I have applied a part of it to 1.5 and made some minor further changes
  18.  
  19. Kai Uwe Rommel
  20. rommel@lan.informatik.tu-muenchen.dbp.de
  21. -----------
  22.  
  23.  
  24. This is release 1.5 of GNU dbm.  Better documentation will be written
  25. soon.  For now, this file briefly describes the contents of this
  26. release and how to use it.
  27.  
  28. The files are:
  29.  
  30. COPYING        - Copying information.
  31. README        - This file.
  32.  
  33. bucket.c, extern.h, falloc.c, findkey.c, gdbm.proto, gdbmclose.c,
  34. gdbmconst.h gdbmdefs.h, gdbmdelete.c, gdbmerrno.h, gdbmfetch.c,
  35. gdbmopen.c, gdbmreorg.c, gdbmseq.c, gdbmstore.c, global.c, gndbm.h,
  36. hash.c systems.h, update.c, version.c - Source for GNU dbm library.
  37.  
  38. dbm.h dbminit.c, delete.c, fetch.c, seq.c, store.c - Source for the
  39. DBM interface.
  40.  
  41. dbmclose.c, dbmdelete.c, dbmdirfno.c, dbmfetch.c, dbmopen.c, dbmpagfno.c
  42. dbmseq.c, dbmstore.c, ndbm.h - Source for the NDBM interface.
  43.  
  44. Makefile     - Makefile, will make gdbm.a  (BSD and SYSV)
  45. testgdbm.c    - A simple test program.
  46. testdbm.c    - A simple test program.
  47. testndbm.c    - A simple test program.
  48. conv2gdbm.c    - A dbm database conversion program.
  49.  
  50. CHANGES from 1.4 to 1.5:
  51.   1.  Minor bug fixes.  See the ChangeLog.
  52.   2.  Added gdbmconst.h to allow users to change the size of the
  53.       bucket cache in the systems.h file.
  54.  
  55. CHANGES from 1.0 to 1.4:
  56.   1.  Mainly bug fixes.
  57.   2.  A define for "dbmclose()" was added to dbm.h for those few
  58.       implementaions that need that call.
  59.   3.  For details, see the ChangeLog.
  60.  
  61. CHANGES from 0.9 to 1.0:
  62.   1.  Makefiles were combined into one and a few new things added to it.
  63.   2.  Several minor bugs were fixed including a cache bug.
  64.   3.  Two new calls (dbm_pagfno, dbm_dirfno) were added to the NDBM interface.
  65.   3.  A conversion program from dbm files to gdbm files was added.
  66.   4.  Reorganize was changed to allow complex file names. (dir/file form)
  67.   5.  testgdbm, testndbm, and testdbm were modified to return key and data
  68.       pairs where needed and to take an optional file name as an argument.
  69.       testgdbm had some command characters changed.
  70.   6.  The DBM and NDBM interfaces were separated.
  71.   7.  An include file for dbm users was added. (dbm.h)
  72.   8.  The include file for ndbm users was renamed ndbm.h. (It was gndbm.h.)
  73.  
  74. CHANGES from 0.8 to 0.9:
  75.   1.  The hash function changed.
  76.   2.  The file format changed.
  77.   3.  There was a complete rewrite of falloc.c.
  78.   4.  There were added compatiblity routines for ndbm.
  79.   5.  The file names for dbm compatibility routines were made to
  80.       look like dbm.
  81.   6.  Test programs changed.
  82.   7.  Support for System V.
  83.   8.  Various other small changes.
  84.   9.  The need for recovery and associated code was removed.
  85.  
  86.  
  87. GNU dbm is a set of database routines that use extendible hashing and
  88. works similar to the standard UNIX dbm routines.  The basic unit of
  89. data is the structure
  90.  
  91.   typedef struct {
  92.              char *dptr;
  93.              int   dsize;
  94.           } datum;
  95.  
  96. The following is a quick list of the routines.  After this list, a
  97. longer description of each routine will be given.  An include file
  98. will be produced that can be included by the user. The file is
  99. "gdbm.h".  The following routines are defined in terms of gdbm.h:
  100.  
  101.   GDBM_FILE gdbm_open ( name, block_size, read_write, mode, fatal_func )
  102.  
  103.   void gdbm_close ( dbf )
  104.  
  105.   int gdbm_store ( dbf, key, content, flags )
  106.  
  107.   datum gdbm_fetch ( dbf, key )
  108.  
  109.   int gdbm_delete ( dbf, key )
  110.  
  111.   datum gdbm_firstkey ( dbf )
  112.  
  113.   datum gdbm_nextkey ( dbf, key )
  114.  
  115.   int gdbm_reorganize ( dbf )
  116.  
  117.  
  118. For compatibility with the standard dbm, the following routines are
  119. defined.  There is an include file for dbm users called "dbm.h".
  120.  
  121.   int dbminit ( name )
  122.  
  123.   int store ( key, content )
  124.  
  125.   datum fetch ( key )
  126.  
  127.   int delete ( key )
  128.  
  129.   datum firstkey ()
  130.  
  131.   datum nextkey ( key )
  132.  
  133.  
  134. There are also compatibility routines for ndbm.  For ndbm compatiblity
  135. routines, you need the include file "ndbm.h".  The routines are:
  136.  
  137. DBM *dbm_open (name, flags, mode)
  138.  
  139. void dbm_close (file)
  140.  
  141. datum dbm_fetch (file, key)
  142.  
  143. int dbm_store (file, key, content, flags)
  144.  
  145. int dbm_delete (file, key)
  146.  
  147. datum dbm_firstkey (file)
  148.  
  149. datum dbm_nextkey (file)
  150.  
  151. int dbm_error (file)
  152.  
  153. int dbm_clearerr (file)
  154.  
  155. int dbm_pagfno (file)
  156.  
  157. int dbm_dirfno (file)
  158.  
  159.  
  160. Description of GNU dbm routines.
  161. --------------------------------
  162.  
  163. GNU dbm allows multiple data files.  A routine that opens a gdbm file
  164. is designated as a "reader" or a "writer".  Only one writer may open a
  165. gdbm file and many readers may open the file.  Readers and writers can
  166. not open the gdbm file at the same time. The procedure for opening a
  167. gdbm file is:
  168.  
  169. GDBM_FILE dbf;
  170.  
  171. dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
  172.  
  173. The parameters are:
  174.   char *name - the name of the file (the complete name, gdbm does
  175.       not append any characters to this name)
  176.   int block_size - the size of a single transfer from disk to memory.
  177.       This parameter is ignored unless the file is a new file.
  178.       The minimum size is 512.  If it is less than 512, dbm will
  179.       use the stat block size for the file system.
  180.   int read_write - 0 => reader, 1 => writer, 2 => writer (if the database
  181.       does not exist, create a new one, 3 => writer and create a new
  182.       database regardless if one exists.  (Defined in gdbm.h as
  183.       GDBM_READER, GDBM_WRITER, GDBM_WRCREAT, GDBM_NEWDB.)
  184.   int mode - file mode (see chmod(2) and open(2)) if the file is created.
  185.   void (*fatal_func) () - a function for dbm to call if it detects a
  186.       fatal error. The only parameter of this function is a string.
  187.       If the value of 0 is provided, gdbm will use a default function.
  188.  
  189. The return value, dbf, is the pointer needed by all other routines to
  190. access that gdbm file.  If the return is the NULL pointer, gdbm_open
  191. was not successful.  The errors can be found in "gdbm_errno" for gdbm
  192. errors and in "errno" for file system errors.  (For error codes, see
  193. gdbmerrno.h.)
  194.  
  195. In all of the following calls, the parameter "dbf" refers to the pointer
  196. returned from gdbm_open.
  197.  
  198. It is important that every file opened is also closed.  This is needed to
  199. update the reader/writer count on the file.  This is done by:
  200.  
  201.   gdbm_close(dbf);
  202.  
  203.  
  204. The database is used by 3 primary routines.  The first stores data in the
  205. database.
  206.  
  207.   ret = gdbm_store ( dbf, key, content, flag )
  208.  
  209.   The parameters are:
  210.      char *dbf - the pointer returned by gdbm_open
  211.      datum key - the key data
  212.      datum content - the data to be associated with the key
  213.      int   flag - 0 => insert only, generate an error if key exists.
  214.               1 => replace contents if key exists.  (Defined in
  215.               gdbm.h as GDBM_INSERT and GDBM_REPLACE.)
  216.  
  217.   If a reader calls store, ret gets -1.  If called with GDBM_INSERT and
  218.   key is in the database, ret gets 1.  Otherwise, ret is 0.
  219.   NOTICE: If you store data for a key that is already in the data base,
  220.   gdbm replaces the old data with the new data if called with GDBM_REPLACE.
  221.   You do not get two data items for the same key and you do not get an
  222.   error from gdbm_store.
  223.   NOTICE: The size in gdbm is not restricted like dbm or ndbm.  Your data
  224.   can be as large as your "want".
  225.   NOTICE: Both key and content must have the dptr field be a non-NULL
  226.   value.  Since a NULL dptr field is used by other routines to indicate an
  227.   error, a NULL field cannot be valid data.  If either key or content have
  228.   a null dptr field, gdbm_open will return an error.
  229.  
  230. To search for some data:
  231.  
  232.   content = gdbm_fetch ( dbf, key )
  233.  
  234.   The parameters are:
  235.      char *dbf - the pointer returned by gdbm_open
  236.      datum key - the key data
  237.  
  238.   The "datum" returned in content is a pointer to the data found.  If the
  239.   dptr is NULL, no data was found.  If dptr is not NULL, then it points
  240.   to data allocated by malloc.  gdbm does not automatically free this data.
  241.   The user must free this storage when done using it.  This eliminates the
  242.   need to copy the result to save it for later use. (You just save the
  243.   pointer.)
  244.  
  245. To remove some data from the database:
  246.  
  247.   ret = gdbm_delete ( dbf, key )
  248.  
  249.   The parameters are:
  250.      char *dbf - the pointer returned by gdbm_open
  251.      datum key - the key data
  252.  
  253.   The ret value is -1 if the item is not present or the requester is a reader.
  254.   The ret value is 0 if there was a successful delete.
  255.  
  256.  
  257. The next two routines allow for accessing all items in the database.  This
  258. access is not key sequential, but it is guaranteed to visit every key in
  259. the database once.  (The order has to do with the hash values.)
  260.  
  261.   key = gdbm_firstkey ( dbf )
  262.  
  263.   nextkey = gdbm_nextkey ( dbf, key )
  264.  
  265.   The parameters are:
  266.      char *dbf - the pointer returned by gdbm_open
  267.      datum key - the key data
  268.  
  269.   The return values are both datum.  If key.dptr or nextkey.dptr is NULL,
  270.   there is no first key or next key.  Again notice that dptr points to
  271.   data allocated by malloc and gdbm will not free it for you.
  272.  
  273. The following routine should be used very seldom.
  274.  
  275.   ret = gdbm_reorganize ( dbf )
  276.  
  277.   If you have had a lot of deletions and would like to shrink the space
  278.   used by the gdbm file, the this routine will reorganize the database.
  279.   gdbm will not shorten the length of a gdbm file except by using this
  280.   reorganization.  (Deleted file space will be reused.)
  281.  
  282.  
  283. The following two are variables that may need to be used:
  284.  
  285.   gdbm_error gdbm_errno   -   the variable that contains more information
  286.                               about gdbm errors.  ( gdbm.h has the
  287.                   definitions of the error values. )
  288.  
  289.   char * gdbm_version     -   the string containing the version information.
  290.  
  291.  
  292. There are a few more things of interest.  First, gdbm files are not
  293. "sparse".  You can copy them with the UNIX cp command and they will
  294. not expand in the copying process.  Also, there is a compatibility
  295. mode for use with programs that already use UNIX dbm.  In this
  296. compatibility mode, no gdbm file pointer is required by the user.
  297. Only one file may be opened at a time.  All users in compatibility
  298. mode are assumed to be writers.  If the gdbm file is a read only, it
  299. will fail as a writer, but will also try to open it as a reader.  All
  300. returned pointers in datum structures point to data that gdbm WILL
  301. free.  They should be treated as static pointers (as standard UNIX dbm
  302. does).  The compatibility routine names are the same as the UNIX dbm
  303. routine names.  Their definitions follow:
  304.  
  305.   int dbminit ( name )
  306.  
  307.   int store ( key, content )
  308.  
  309.   datum fetch ( key )
  310.  
  311.   int delete ( key )
  312.  
  313.   datum firstkey ()
  314.  
  315.   datum nextkey ( key )
  316.  
  317. NOTE: Some implementations have an include file "dbm.h".  That file is just
  318. a file that defines datum and the above routines.  Many original dbm
  319. sites do not have a "dbm.h" file.  One is included here for those who
  320. want it.
  321.  
  322. WARNING: standard UNIX dbm and GNU dbm do not have the same data format in the
  323. file.  You cannot access a standard UNIX dbm file with GNU dbm!  If you want
  324. to use an old database with GNU dbm, you must use the convert program.
  325.  
  326. Also, GNU dbm has compatibility routines for ndbm.  For ndbm compatiblity
  327. routines, you need the include file "ndbm.h".
  328.  
  329. WARNING: If you have ndbm and gdbm, there is a conflict in the names of the
  330. include file for the ndbm interface and the original ndbm package.  Do not
  331. blindly copy "ndbm.h" to your include directory.
  332.  
  333. The routines are:
  334.  
  335.     DBM *dbm_open (name, flags, mode)
  336.  
  337.     void dbm_close (file)
  338.  
  339.     datum dbm_fetch (file, key)
  340.  
  341.     int dbm_store (file, key, content, flags)
  342.  
  343.     int dbm_delete (file, key)
  344.  
  345.     datum dbm_firstkey (file)
  346.  
  347.     datum dbm_nextkey (file)
  348.  
  349.     int dbm_error (file)
  350.  
  351.     int dbm_clearerr (file)
  352.  
  353.     int dbm_dirfno (file)
  354.  
  355.     int dbm_pagfno (file)
  356.  
  357. Again, just like ndbm, any returned datum can be assumed to be static
  358. storage.  You do not have to free that memory, the ndbm compatibility
  359. routines will do it for you.
  360.  
  361.  
  362. Notes on making GNU dbm.
  363. ------------------------
  364.  
  365. The "Makefile" will make both "gdbm.a", the collection of gdbm routines and
  366. three simple test programs that uses the gdbm routines.  Two test programs
  367. test the dbm and the ndbm interface routines.  The third was use to help
  368. debug gdbm and contains "inside knowledge."   The first two can be linked
  369. using the original dbm and ndbm routines.  The makefile also makes the
  370. conversion program, conv2gdbm.   The make commands are:
  371.  
  372.    make gdbm.a        makes the gdbm.a archive.
  373.    make testgdbm    makes both gdbm.a and the gdbm test program.
  374.    make testdbm     makes both gdbm.a and the dbm test program with gdbm.
  375.    make testndbm    makes both gdbm.a and the ndbm test program with gdbm.
  376.    make allgdbm        makes all of the above.
  377.    make tdbm        makes the dbm test program linked with dbm, not gdbm.
  378.    make tndbm        makes the ndbm test program linked with ndbm, not gdbm.
  379.    make alldbm        makes the two previous programs.
  380.    make conv2gdbm    makes the conversion program.
  381.    make all        makes all the above.
  382.    make install        installs gdbm.a as /usr/lib/libgdbm.a and gdbm.h.
  383.  
  384.  
  385. CONV2GDBM
  386. ---------
  387.  
  388. The program conv2gdbm has been provided to help you convert from dbm
  389. databases to gdbm.  The usage is:
  390.  
  391.    conv2gdbm [-q] [-b block_size] dbm_file [gdbm_file]
  392.  
  393. The optional "block_size" is the same as in gdbm_open.  The dbm_file is
  394. the name of the dbm file without the .pag or .dir extensions.  The
  395. optional gdbm_file is the complete file name.  If not included, the
  396. gdbm file name is the same as the dbm file name without any extensions.
  397. That is "conv2gdbm dbmfile" converts the files "dbmfile.pag" and
  398. "dbmfile.dir" into a gdbm file called "dbmfile".  The -q option causes
  399. conv2gdbm to work quietly.
  400.  
  401.  
  402. System V support  (And other systems.)
  403. --------------------------------------
  404.  
  405. There is now support for System V.  This done via the systems.h file.
  406. This is the place where all system dependencies should go.  The
  407. makefile should make gdbm with a few changes.  The makefile describes
  408. the changes necessary for use with System V.  Also, read the makefile
  409. and edit it if you use gcc.  There are several places where changes
  410. are needed to use gcc.
  411.   1)  uncomment: #CC=gcc
  412.   2)  change the lines to make the test programs. (See the comments.)
  413.  
  414. If you port gdbm to another system, try to follow the change style used for
  415. System V changes.  Please send your changes to phil@cs.wwu.edu if you would
  416. like your changes included in a future release of gdbm.
  417.  
  418. Please send bug reports to bug-gnu-utils@prep.ai.mit.edu.
  419.  
  420. Thank you.
  421.