home *** CD-ROM | disk | FTP | other *** search
/ PC Press 1997 July / Sezamfile97_1.iso / msdos / c / cbase11.a03 / CBASE11.ZIP / MAN / BTREE.MAN < prev    next >
Text File  |  1993-01-01  |  9KB  |  285 lines
  1. NAME
  2.      btsetcur - set btree cursor
  3.  
  4. SYNOPSIS
  5.      #include <btree.h>
  6.  
  7.      int btsetcur(btp, btposp)
  8.      btree_t *btp;
  9.      const btpos_t *btposp;
  10.  
  11. DESCRIPTION
  12.      The btsetcur function sets the current cursor position for btree
  13.      btp to the value in btposp.  btposp should point to a cursor
  14.      value saved previously with btgetcur.  If btposp is the NULL
  15.      pointer, the cursor is set to null.  It is important to remember
  16.      that a btree position is not valid after an insertion, deletion,
  17.      or unlock.
  18.  
  19.      btsetcur will fail if one or more of the following is true:
  20.  
  21.      [EINVAL]       btp is not a valid btree pointer.
  22.      [BTELOCK]      btp is not locked.
  23.      [BTENKEY]      btposp points to an invalid cursor value.
  24.      [BTENOPEN]     btp is not open.
  25.  
  26. SEE ALSO
  27.      btgetcur.
  28.  
  29. DIAGNOSTICS
  30.      Upon successful completion, a value of 0 is returned.  Otherwise,
  31.      a value of -1 is returned, and errno set to indicate the error.
  32.  
  33. NAME
  34.      btsetvbuf - assign buffering to a btree
  35.  
  36. SYNOPSIS
  37.      #include <btree.h>
  38.  
  39.      int btsetvbuf(btp, buf, bufcnt)
  40.      btree_t *btp;
  41.      void *buf;
  42.      size_t bufcnt;
  43.  
  44. DESCRIPTION
  45.      The btsetvbuf function is used to assign buffering to a btree.
  46.      bufcnt specifies the number of btree nodes to be buffered.  If
  47.      bufcnt has a value of zero, the btree will be completely
  48.      unbuffered.  If buf is not the NULL pointer, the storage area it
  49.      points to will be used instead of one automatically allocated for
  50.      buffering.
  51.  
  52.      The size of the storage area needed can be obtained using the
  53.      BTBUFSIZE() macro:
  54.  
  55.           char buf[BTBUFSIZE(M, KEYSIZE, BUFCNT)];
  56.           btsetvbuf(btp, buf, BUFCNT);
  57.  
  58.      where M is the degree of the btree, KEYSIZE is the size of the
  59.      keys int the btree, and BUFCNT is the number of nodes to buffer.
  60.  
  61.      Any previously buffered data is flushed before installing the new
  62.      buffer area, so btsetvbuf may be called more than once.  This
  63.      allows the buffer size to be varied with the file size.
  64.  
  65.      btsetvbuf will fail if one or more of the following is true:
  66.  
  67.      [EINVAL]       btp is not a valid btree.
  68.      [ENOMEM]       Not enough memory is available for the calling
  69.                     process to allocate.
  70.      [BTENOPEN]     btp is not open.
  71.  
  72. SEE ALSO
  73.      btsetbuf, btsync.
  74.  
  75. DIAGNOSTICS
  76.      Upon successful completion, a value of 0 is returned.  Otherwise,
  77.      a value of -1 is returned, and errno set to indicate the error.
  78.  
  79. NAME
  80.      btsync - btree synchronize
  81.  
  82. SYNOPSIS
  83.      #include <btree.h>
  84.  
  85.      int btsync(btp);
  86.      btree_t *btp;
  87.  
  88. DESCRIPTION
  89.      The btsync function causes any buffered data for the named btree
  90.      to be written to the file.  The btree remains open and the buffer
  91.      contents remain intact.
  92.  
  93.      btsync will fail if one or more of the following is true:
  94.  
  95.      [EINVAL]       btp is not a valid btree pointer.
  96.      [BTENOPEN]     btp is not open.
  97.  
  98. SEE ALSO
  99.      btclose, btlock, btsetbuf, btsetvbuf.
  100.  
  101. DIAGNOSTICS
  102.      Upon successful completion, a value of 0 is returned.  Otherwise,
  103.      a value of -1 is returned, and errno set to indicate the error.
  104.  
  105. NAME
  106.      btnext - next btree key
  107.  
  108. SYNOPSIS
  109.      #include <btree.h>
  110.  
  111.      int btnext(btp)
  112.      btree_t *btp;
  113.  
  114. DESCRIPTION
  115.      The btnext function advances the cursor of btree btp to the next
  116.      key.  If cursor is currently null, it will be advanced to the
  117.      first key.  If the cursor is currently on the last key, it will
  118.      advance to null.  If the tree is empty, the cursor will remain on
  119.      null.
  120.  
  121.      btnext will fail if one or more of the following is true:
  122.  
  123.      [EINVAL]       btp is not a valid btree pointer.
  124.      [BTELOCK]      btp is not locked.
  125.      [BTENOPEN]     btp is not open.
  126.  
  127. SEE ALSO
  128.      btcursor, btfirst, btlast, btprev.
  129.  
  130. DIAGNOSTICS
  131.      Upon successful completion, a value of 0 is returned.  Otherwise,
  132.      a value of -1 is returned, and errno set to indicate the error.
  133.  
  134. NAME
  135.      btopen - open a btree
  136.  
  137. SYNOPSIS
  138.      btree_t *btopen(filename, type, fldc, fldv)
  139.      const char *filename;
  140.      const char *type;
  141.      int fldc;
  142.      const btfield_t fldv[];
  143.  
  144. DESCRIPTION
  145.      The btopen function opens the file named by filename as a btree.
  146.      A pointer to the btree_t control structure associated with the
  147.      file is returned.
  148.  
  149.      type is a character string having one of the following values:
  150.  
  151.           "r"            open for reading
  152.           "r+"           open for update (reading and writing)
  153.  
  154.      See btcreate for explanation of the field count fldc and the
  155.      field definition list fldv.
  156.  
  157.      btopen will fail if one or more of the following is true:
  158.  
  159.      [EINVAL]       filename is the NULL pointer.
  160.      [EINVAL]       type is not "r" or "r+".
  161.      [EINVAL]       fldc is less than 1.
  162.      [EINVAL]       fldv is the NULL pointer.
  163.      [EINVAL]       fldv contains an invalid field definition.
  164.      [ENOENT]       The named btree file does not exist.
  165.      [BTEMFILE]     Too many open btrees.  The maximum is defined as
  166.                     BTOPEN_MAX in <btree.h>.
  167.  
  168. SEE ALSO
  169.      btclose, btcreate.
  170.  
  171. DIAGNOSTICS
  172.      On failure btopen returns a NULL pointer, and errno is set to
  173.      indicate the error.
  174.  
  175. NOTES
  176.      The same field count and field definition list with which the
  177.      btree was created must be used each time the btree is opened.
  178.      Otherwise the results are undefined.
  179.  
  180. NAME
  181.      btprev - previous btree key
  182.  
  183. SYNOPSIS
  184.      #include <btree.h>
  185.  
  186.      int btprev(btp)
  187.      btree_t *btp;
  188.  
  189. DESCRIPTION
  190.      The btprev function retreats the cursor of btree btp to the
  191.      previous key.  If cursor is currently null, it will be moved to
  192.      the last key.  If the cursor is currently on the last key, it
  193.      will move to null.  If the tree is empty, the cursor will remain
  194.      on null.
  195.  
  196.      btprev will fail if one or more of the following is true:
  197.  
  198.      [EINVAL]       btp is not a valid btree pointer.
  199.      [BTELOCK]      btp is not locked.
  200.      [BTENOPEN]     btp is not open.
  201.  
  202. SEE ALSO
  203.      btcursor, btfirst, btlast, btnext.
  204.  
  205. DIAGNOSTICS
  206.      Upon successful completion, a value of 0 is returned.  Otherwise,
  207.      a value of -1 is returned, and errno set to indicate the error.
  208.  
  209. NAME
  210.      btsearch - search a btree
  211.  
  212. SYNOPSIS
  213.      #include <btree.h>
  214.  
  215.      int btsearch(btp, buf)
  216.      btree_t *btp;
  217.      const void *buf;
  218.  
  219. DESCRIPTION
  220.      The btsearch function searches the btree btp for the key pointed
  221.      to by buf.  If it is found, the cursor is set to the location of
  222.      the key and 1 is returned.  If it is not found, the cursor is set
  223.      to the next higher key and 0 is returned.
  224.  
  225.      btsearch will fail if one or more of the following is true:
  226.  
  227.      [EINVAL]       btp is not a valid btree pointer.
  228.      [EINVAL]       buf is the NULL pointer.
  229.      [BTELOCK]      btp is not read locked.
  230.  
  231. SEE ALSO
  232.      btdelcur, btdelete, btinsert.
  233.  
  234. DIAGNOSTICS
  235.      Upon successful completion, a value of 1 is returned if the key
  236.      was found or a value of 0 if it was not found.  On failure, a
  237.      value of -1 is returned, and errno set to indicate the error.
  238.  
  239. NAME
  240.      btsetbuf - assign buffering to a btree
  241.  
  242. SYNOPSIS
  243.      #include <btree.h>
  244.  
  245.      int btsetbuf(btp, buf)
  246.      btree_t *btp;
  247.      void *buf;
  248.  
  249. DESCRIPTION
  250.      The btsetbuf function causes the storage area pointed to by buf
  251.      to be used by the btree associated with btree pointer btp instead
  252.      of an automatically allocated buffer area.  If buf is the NULL
  253.      pointer, btp will be completely unbuffered.
  254.  
  255.      The size of the storage area needed can be obtained using the
  256.      BTBUFSIZE() macro:
  257.  
  258.           char buf[BTBUFSIZE(M, KEYSIZE, BTBUFCNT)];
  259.           btsetbuf(btp, buf);
  260.  
  261.      where M is the degree of the btree, KEYSIZE is the size of the
  262.      keys int the btree, and BTBUFCNT is the default number of nodes
  263.      buffered when a btree is opened.  BTBUFCNT is defined in
  264.      <btree.h>.  If the number of nodes buffered has been changed using
  265.      btsetvbuf, then that number should be used in place of BTBUFCNT.
  266.  
  267.      btsetbuf may be called at any time after opening the btree,
  268.      before and after it is read or written; the buffers are flushed
  269.      before installing the new buffer area.
  270.  
  271.      btsetbuf will fail if one or more of the following is true:
  272.  
  273.      [EINVAL]       btp is not a valid btree pointer.
  274.      [BTENBUF]      buf is not the NULL pointer and btp
  275.                     is not buffered.
  276.      [BTENOPEN]     btp is not open.
  277.  
  278. SEE ALSO
  279.      btsetvbuf, btsync.
  280.  
  281. DIAGNOSTICS
  282.      Upon successful completion, a value of 0 is returned.  Otherwise,
  283.      a value of -1 is returned, and errno set to indicate the error.
  284.  
  285.