lib/libc/cdb/cdbr.3

   1 .\"     $NetBSD: cdbr.3,v 1.2 2010/04/25 10:32:44 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Joerg Sonnenberger.
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .Dd March 3, 2010
  32 .Dt CDBR 3
  33 .Os
  34 .Sh NAME
  35 .Nm cdbr
  36 .Nm cdbr_open ,
  37 .Nm cdbr_entries ,
  38 .Nm cdbr_get ,
  39 .Nm cdbr_find ,
  40 .Nm cdbr_close ,
  41 .Nm cdbr_write
  42 .Nd constant database access methods
  43 .Sh SYNOPSIS
  44 .Ft "struct cdbr *"
  45 .Fn cdbr_open "const char *path" "int flags"
  46 .Ft uint32_t
  47 .Fn cdbr_entries "struct cdbr *cdbr"
  48 .Ft int
  49 .Fn cdbr_get "struct cdbr *cdbr" "uint32_t index" "const void **data" "size_t *datalen"
  50 .Ft int
  51 .Fo cdbr_find
  52 .Fa "struct cdbr *cdbr"
  53 .Fa "const void *key"
  54 .Fa "size_t keylen"
  55 .Fa "const void **data"
  56 .Fa "size_t *datalen"
  57 .Fc
  58 .Ft void
  59 .Fn cdbr_close "struct cdbr *cdbr"
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 library provides a space efficient (key,value) database based
  64 on perfect hashing.
  65 .Pp
  66 A cdb database is opened for reading by calling
  67 .Fn cdbr_open .
  68 The only supported value for
  69 .Va flags
  70 is
  71 .Dv CDBR_DEFAULT .
  72 The function returns a handle to pass to the other functions.
  73 The database is closed by invoking
  74 .Fn cdbr_close .
  75 All resources associated with the handle are freed and the memory
  76 returned by
  77 .Fn cdbr_get
  78 and
  79 .Fn cdbr_find
  80 is invalidated.
  81 .Pp
  82 The number of records in the database can be obtained by calling
  83 .Fn cdbr_entries .
  84 Records can be obtained by record number using
  85 .Fn cdbr_get
  86 or by key using
  87 .Fn cdbr_find .
  88 Both functions return 0 on success and update
  89 .Va data
  90 and
  91 .Va datalen
  92 accordingly.
  93 The location
  94 .Va *data
  95 remains valid until
  96 .Fn cdbr_close
  97 is called.
  98 It is the responsibility of the caller of
  99 .Fn cdbr_find
 100 to ensure that the key matches the returned data.
 101 The function returns the only possible match, but the database doesn't store
 102 the keys to minimize overhead.
 103 .Sh SEE ALSO
 104 .Xr nbperf 1 ,
 105 .Xr cdbw 3 ,
 106 .Xr db 3 ,
 107 .Xr cdb 5
 108 .Sh HISTORY
 109 Support for the
 110 .Nm cdb
 111 format first appeared in
 112 .Nx 6.0 .
 113 .Sh AUTHORS
 114 The
 115 .Nm cdbr
 116 and
 117 .Nm cdbw
 118 functions have been written by
 119 .An Joerg Sonnenberger Aq joerg@NetBSD.org .