home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / man / cat3 / db.0 < prev    next >
Text File  |  1993-12-07  |  17KB  |  331 lines
  1. btree_open, hash_open, recno_open - database access methods
  2. ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  3. ##iinncclluuddee <<ddbb..hh>>
  4.  
  5. DDBB **
  6. bbttrreeee__ooppeenn((ccoonnsstt cchhaarr **ffiillee,, iinntt ffllaaggss,, iinntt mmooddee,,
  7.      ccoonnsstt BBTTRREEEEIINNFFOO ** ooppeenniinnffoo));;
  8.  
  9. DDBB **
  10. hhaasshh__ooppeenn((ccoonnsstt cchhaarr **ffiillee,, iinntt ffllaaggss,, iinntt mmooddee,,
  11.      ccoonnsstt HHAASSHHIINNFFOO ** ooppeenniinnffoo));;
  12.  
  13. DDBB **
  14. rreeccnnoo__ooppeenn((ccoonnsstt cchhaarr **ffiillee,, iinntt ffllaaggss,, iinntt mmooddee,,
  15.      ccoonnsstt RREECCNNOOIINNFFOO ** ooppeenniinnffoo));;
  16. and  are  access  method  interfaces  to database files in btree,
  17. hashed, and flat­file formats, respectively.  The btree format is
  18. a  representation  of  a  sorted,  balanced  tree structure.  The
  19. hashed format is an  extensible,  dynamic  hashing  scheme.   The
  20. flat­file  format  is  a  UNIX file with fixed or variable length
  21. lines.  These formats are described in more detail below.  Access
  22. to all file types is based on key/data pairs.  Each routine opens
  23. for reading and/or writing.  Databases never intended to be  pre­
  24. served  on  disk  may be created by setting the file parameter to
  25. NULL.  The and are as specified to the routine, however, only the
  26. O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC and O_WRONLY flags are
  27. meaningful.  The argument is a pointer to an access  method  spe­
  28. cific  structure  described  below.   The  open routines return a
  29. pointer to a DB structure on success and NULL on error.   The  DB
  30. structure contains at least the following fields:
  31.  
  32. typedef struct {
  33. int (*close)(const DB *db);
  34. int (*sync)(const DB *db);
  35. int (*del)(const DB *db, const DBT *key, u_int flags);
  36. int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
  37. int (*put)(const DB *db, const DBT *key, const DBT *data,
  38.      u_int flags);
  39. int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
  40. int type;
  41. void *openinfo;
  42. } DB;
  43. The  elements of this structure consist of a pointer to an access
  44. method specific structure and a set  of  routines  which  perform
  45. various  functions.   All  of  these routines take a pointer to a
  46. structure as returned by one of the open routines,  one  or  more
  47. pointers  to  key/data structures, and, optionally, a flag value.
  48. openinfo A pointer to an internal structure specific to  the  ac­
  49. cess  method.  type The type of the underlying access method; ei­
  50. ther DB_BTREE, DB_HASH or DB_RECNO.  close A pointer to a routine
  51. to  flush  any cached information to disk, free any allocated re­
  52. sources, and close the database file.  Since key/data  pairs  may
  53. be cached in memory, failing to close the file with a routine may
  54. result in inconsistent or lost information.  routines  return  ­1
  55. on  error  (setting and 0 on success.  del A pointer to a routine
  56. to remove key/data pairs from the database.  routines  return  ­1
  57. on error (setting 0 on success, and 1 if the specified was not in
  58. the file.  get A pointer to a routine which is the interface  for
  59. keyed retrieval from the database.  The address and length of the
  60. data associated with the specified are returned in the  structure
  61. referenced  by routines return ­1 on error (setting 0 on success,
  62. and 1 if the was not in the file.  put A pointer to a routine  to
  63. store  key/data pairs in the database.  The parameter must be set
  64. to one of the following values: R_IAFTER Append the data  immedi­
  65. ately  after the data referenced by creating a new key/data pair.
  66. (This implies that the access method is able to create new  keys,
  67. i.e.  the  keys  are ordered and independent, for example, record
  68. numbers.  Applicable only to the access method.)   R_IBEFORE  In­
  69. sert  the data immediately before the data referenced by creating
  70. a new key/data pair.  (This implies that  the  access  method  is
  71. able  to  create new keys, i.e. the keys are ordered and indepen­
  72. dent, for example, record numbers.  Applicable only to the access
  73. method.)   R_NOOVERWRITE  Enter the new key/data pair only if the
  74. key does not previously exist.  R_PUT Enter the new key/data pair
  75. and  replace  any previously existing key.  routines return ­1 on
  76. error (setting 0 on success, and 1 if the R_NOOVERWRITE  was  set
  77. and  the key already exists in the file.  seq A pointer to a rou­
  78. tine which is the interface for  sequential  retrieval  from  the
  79. database.   The address and length of the key are returned in the
  80. structure referenced by and the address and length  of  the  data
  81. are  returned  in the structure referenced by Sequential key/data
  82. pair retrieval may begin at any time, and  the  position  of  the
  83. ``cursor''  is not affected by calls to the or routines.  Modifi­
  84. cations to the database during a sequential scan will be reflect­
  85. ed  in the scan, i.e. records inserted behind the cursor will not
  86. be returned while records inserted in front of the cursor will be
  87. returned.   The  flag  value  must be set to one of the following
  88. values: R_CURSOR The data associated with the  specified  key  is
  89. returned.   This  differs  from  the routines in that it sets the
  90. ``cursor'' to the location of the key  as  well.   (This  implies
  91. that  the  access  method  has  a  implicit  order which does not
  92. change.  Applicable only to the and access methods.)  R_FIRST The
  93. first key/data pair of the database is returned.  R_LAST The last
  94. key/data pair of the database is returned.   (This  implies  that
  95. the  access  method  has  a implicit order which does not change.
  96. Applicable only to the and access methods.)  R_NEXT Retrieve  the
  97. key/data  pair  immediately after the key/data pair most recently
  98. retrieved using the routine.  The cursor is moved to the returned
  99. key/data pair.  If is set to R_NEXT the first time the routine is
  100. called, the first key/data pair  of  the  database  is  returned.
  101. R_PREV Retrieve the key/data pair immediately before the key/data
  102. pair most recently retrieved using the routine.   The  cursor  is
  103. moved  to  the  returned  key/data pair.  If is set to R_PREV the
  104. first time the routine is called, the last key/data pair  of  the
  105. database is returned.  (This implies that the access method has a
  106. implicit order which does not change.  Applicable only to the and
  107. access  methods.)  routines return ­1 on error (setting 0 on suc­
  108. cess, 1 if there are no more key/data pairs  available.   If  the
  109. access  method is being used, and if the database file is a char­
  110. acter special file and no complete key/data pairs  are  currently
  111. available, the routines return 2.  sync A pointer to a routine to
  112. flush any cached information to disk.  If the database is in mem­
  113. ory  only,  the  routine  has  no effect and will always succeed.
  114. routines return ­1 on error (setting and 0 on success.  Access to
  115. all  file  types  is based on key/data pairs.  Both keys and data
  116. are represented by the following data structure: typedef struct {
  117. void *data;
  118. size_t size; } DBT; The elements of the DBT structure are defined
  119. as follows: data A pointer to a byte string.  size The length  of
  120. the  byte string.  Key/data strings must fit into available memo­
  121. ry.  One of the access methods is a  btree:  a  sorted,  balanced
  122. tree structure with associated key/data pairs.  The access method
  123. specific data structure provided to is as follows: typedef struct
  124. { u_long flags;
  125. u_int psize;
  126. u_int cachesize;
  127. int (*compare)(const void *, const void *);
  128. int  lorder;  } BTREEINFO; The elements of this structure are de­
  129. fined as follows: flags The flag value is specified by any of the
  130. following  values:  R_DUP On insertion, if the key to be inserted
  131. already exists, permit insertion anyway.  This flag  permits  du­
  132. plicate keys in the tree.  By default, duplicates are not permit­
  133. ted, and attempts to insert them will fail.  Note, the  order  of
  134. retrieval  of  key/data  pairs  with duplicate keys is undefined.
  135. cachesize A suggested maximum  size,  in  bytes,  of  the  memory
  136. cache.   Setting this value to zero specifies that an appropriate
  137. amount of memory should be