home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / gdbm-1.7.1-bin.lha / info / gdbm.info (.txt)
GNU Info File  |  1994-02-22  |  24KB  |  508 lines
  1. This is Info file gdbm.info, produced by Makeinfo-1.49 from the input
  2. file ./gdbm.texinfo.
  3.    This file documents the GNU dbm utility.
  4.    Copyright (C) 1989-1993 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the entire resulting derived work is distributed under the terms
  11. of a permission notice identical to this one.
  12.    Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions.
  15. File: gdbm.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
  16.    GNU `dbm' is a library of functions implementing a hashed database
  17. on a disk file.  This manual documents GNU `dbm' Version 1.7.1
  18. (`gdbm').  The software was written by Philip A. Nelson. This document
  19. was originally written by Pierre Gaumond from texts written by Phil.
  20. * Menu:
  21. Introduction:
  22. * Copying::                    Your rights.
  23. * Intro::                      Introduction to GNU dbm.
  24. * List::                       List of functions.
  25. Functions:
  26. * Open::                       Opening the database.
  27. * Close::                      Closing the database.
  28. * Store::                      Inserting and replacing records in the database.
  29. * Fetch::                      Searching records in the database.
  30. * Delete::                     Removing records from the database.
  31. * Sequential::                 Sequential access to records.
  32. * Reorganization::             Database reorganization.
  33. * Sync::                       Insure all writes to disk have competed.
  34. * Errors::                     Convert internal error codes into English.
  35. * Options::                    Setting internal options.
  36. Other topics:
  37. * Variables::                  Two useful variables.
  38. * Compatibility::              Compatibility with UNIX dbm and ndbm.
  39. * Conversion::                 Converting dbm files to gdbm format.
  40. * Bugs::                       Problems and bugs.
  41. File: gdbm.info,  Node: Copying,  Next: Intro,  Prev: Top,  Up: Top
  42. Copying Conditions.
  43. *******************
  44.    This library is "free"; this means that everyone is free to use it
  45. and free to redistribute it on a free basis.  GNU `dbm' (`gdbm') is not
  46. in the public domain; it is copyrighted and there are restrictions on
  47. its distribution, but these restrictions are designed to permit
  48. everything that a good cooperating citizen would want to do.  What is
  49. not allowed is to try to prevent others from further sharing any
  50. version of `gdbm' that they might get from you.
  51.    Specifically, we want to make sure that you have the right to give
  52. away copies `gdbm', that you receive source code or else can get it if
  53. you want it, that you can change these functions or use pieces of them
  54. in new free programs, and that you know you can do these things.
  55.    To make sure that everyone has such rights, we have to forbid you to
  56. deprive anyone else of these rights.  For example, if you distribute
  57. copies `gdbm', you must give the recipients all the rights that you
  58. have.  You must make sure that they, too, receive or can get the source
  59. code.  And you must tell them their rights.
  60.    Also, for our own protection, we must make certain that everyone
  61. finds out that there is no warranty for anything in the `gdbm'
  62. distribution. If these functions are modified by someone else and
  63. passed on, we want their recipients to know that what they have is not
  64. what we distributed, so that any problems introduced by others will not
  65. reflect on our reputation.
  66.    `gdbm' is currently distributed under the terms of the GNU General
  67. Public License, Version 2.  (*NOT* under the GNU General Library Public
  68. License.)  A copy the GNU General Public License is included with the
  69. distribution of `gdbm'.
  70. File: gdbm.info,  Node: Intro,  Next: List,  Prev: Copying,  Up: Top
  71. Introduction to GNU `dbm'.
  72. **************************
  73.    GNU `dbm' (`gdbm')is a library of database functions that use
  74. extendible hashing and works similar to the standard UNIX `dbm'
  75. functions.  These routines are provided to a programmer needing to
  76. create and manipulate a hashed database. (`gdbm' is *NOT* a complete
  77. database package for an end user.)
  78.    The basic use of `gdbm' is to store key/data pairs in a data file.
  79. Each key must be unique and each key is paired with only one data item.
  80. The keys can not be directly accessed in sorted order.  The basic unit
  81. of data in `gdbm' is the structure:
  82.        typedef struct {
  83.                   char *dptr;
  84.                   int  dsize;
  85.                } datum;
  86.    This structure allows for arbitrary sized keys and data items.
  87.    The key/data pairs are stored in a `gdbm' disk file, called a `gdbm'
  88. database.  An application must open a `gdbm' database to be able
  89. manipulate the keys and data contained in the database. `gdbm' allows
  90. an application to have multiple databases open at the same time.  When
  91. an application opens a `gdbm' database, it is designated as a `reader'
  92. or a `writer'.  A `gdbm' database opened by at most one writer at a
  93. time.  However, many readers may open the database open simultaneously.
  94.  Readers and writers can not open the `gdbm' database at the same time.
  95. File: gdbm.info,  Node: List,  Next: Open,  Prev: Intro,  Up: Top
  96. List of functions.
  97. ******************
  98.    The following is a quick list of the functions contained in the
  99. `gdbm' library. The include file `gdbm.h', that can be included by the
  100. user, contains a definition of these functions.
  101.      #include <gdbm.h>
  102.      
  103.      GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
  104.      void gdbm_close(dbf);
  105.      int gdbm_store(dbf, key, content, flag);
  106.      datum gdbm_fetch(dbf, key);
  107.      int gdbm_delete(dbf, key);
  108.      datum gdbm_firstkey(dbf);
  109.      datum gdbm_nextkey(dbf, key);
  110.      int gdbm_reorganize(dbf);
  111.      void gdbm_sync(dbf);
  112.      int gdbm_exists(dbf, key);
  113.      char *gdbm_strerror(errno);
  114.      int gdbm_setopt(dbf, option, value, size)
  115.    The `gdbm.h' include file is often in the `/gnu/include'
  116. directory. (The actual location of `gdbm.h' depends on your local
  117. installation of `gdbm'.)
  118. File: gdbm.info,  Node: Open,  Next: Close,  Prev: List,  Up: Top
  119. Opening the database.
  120. *********************
  121.    Initialize `gdbm' system. If the file has a size of zero bytes, a
  122. file initialization procedure is performed, setting up the initial
  123. structure in the file.
  124.    The procedure for opening a `gdbm' file is:
  125.      GDBM_FILE dbf;
  126.      
  127.      dbf = gdbm_open(name, block_size, flags, mode, fatal_func);
  128.    The parameters are:
  129. char *name
  130.      The name of the file (the complete name, `gdbm' does not append any
  131.      characters to this name).
  132. int block_size
  133.      It is used during initialization to determine the size of various
  134.      constructs. It is the size of a single transfer from disk to
  135.      memory. This parameter is ignored if the file has been previously
  136.      initialized. The minimum size is 512. If the value is less than
  137.      512, the file system blocksize is used, otherwise the value of
  138.      `block_size' is used.
  139. int flags
  140.      If `flags' is set to GDBM_READER, the user wants to just read the
  141.      database and any call to `gdbm_store' or `gdbm_delete' will fail.
  142.      Many readers can access the database at the same time. If `flags'
  143.      is set to GDBM_WRITER, the user wants both read and write access
  144.      to the database and requires exclusive access. If `flags' is set
  145.      to GDBM_WRCREAT, the user wants both read and write access to the
  146.      database and if the database does not exist, create a new one. If
  147.      `flags' is set to GDBM_NEWDB, the user want a new database
  148.      created, regardless of whether one existed, and wants read and
  149.      write access to the new database.  For all writers (GDBM_WRITER,
  150.      GDBM_WRCREAT and GDBM_NEWDB) the value GDBM_FAST can be added to
  151.      the `flags' field using logical or.  This option causes `gdbm' to
  152.      write the database without any disk file synchronization.  This
  153.      allows faster writes, but may produce an inconsistent database in
  154.