lib/libc/cdb/cdbr.3

   1 .\"     $NetBSD: cdbr.3,v 1.4 2013/12/05 21:17:23 joerg 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 December 5, 2013
  32 .Dt CDBR 3
  33 .Os
  34 .Sh NAME
  35 .Nm cdbr
  36 .Nm cdbr_open ,
  37 .Nm cdbr_open_mem ,
  38 .Nm cdbr_entries ,
  39 .Nm cdbr_get ,
  40 .Nm cdbr_find ,
  41 .Nm cdbr_close ,
  42 .Nm cdbr_write
  43 .Nd constant database access methods
  44 .Sh SYNOPSIS
  45 .Ft "struct cdbr *"
  46 .Fn cdbr_open "const char *path" "int flags"
  47 .Ft "struct cdbr *"
  48 .Fo cdbr_open_mem
  49 .Fa "void *base"
  50 .Fa "size_t size"
  51 .Fa "void (*unmap)(void *, void *, size_t)"
  52 .Fa "void *cookie"
  53 .Fc
  54 .Ft uint32_t
  55 .Fn cdbr_entries "struct cdbr *cdbr"
  56 .Ft int
  57 .Fn cdbr_get "struct cdbr *cdbr" "uint32_t index" "const void **data" "size_t *datalen"
  58 .Ft int
  59 .Fo cdbr_find
  60 .Fa "struct cdbr *cdbr"
  61 .Fa "const void *key"
  62 .Fa "size_t keylen"
  63 .Fa "const void **data"
  64 .Fa "size_t *datalen"
  65 .Fc
  66 .Ft void
  67 .Fn cdbr_close "struct cdbr *cdbr"
  68 .Sh DESCRIPTION
  69 The
  70 .Nm
  71 library provides a space efficient (key,value) database based
  72 on perfect hashing.
  73 .Pp
  74 A cdb database is opened for reading by calling
  75 .Fn cdbr_open .
  76 The only supported value for
  77 .Va flags
  78 is
  79 .Dv CDBR_DEFAULT .
  80 The function returns a handle to pass to the other functions.
  81 The database is closed by invoking
  82 .Fn cdbr_close .
  83 All resources associated with the handle are freed and the memory
  84 returned by
  85 .Fn cdbr_get
  86 and
  87 .Fn cdbr_find
  88 is invalidated.
  89 .Fn cdbr_open_mem
  90 works like
  91 .Fn cdbr_open ,
  92 but takes a memory reference to the content of the database file.
  93 If
  94 .Va unmap
  95 is not
  96 .Dv NULL ,
  97 it is called by
  98 .Fn cdbr_close
  99 with
 100 .Va cookie ,
 101 .Va base
 102 and
 103 .Va size
 104 as arguments.
 105 It is not called by
 106 .Fn cdbr_open_mem
 107 on error.
 108 .Pp
 109 The number of records in the database can be obtained by calling
 110 .Fn cdbr_entries .
 111 Records can be obtained by record number using
 112 .Fn cdbr_get
 113 or by key using
 114 .Fn cdbr_find .
 115 Both functions return 0 on success and update
 116 .Va data
 117 and
 118 .Va datalen
 119 accordingly.
 120 The location
 121 .Va *data
 122 remains valid until
 123 .Fn cdbr_close
 124 is called.
 125 It is the responsibility of the caller of
 126 .Fn cdbr_find
 127 to ensure that the key matches the returned data.
 128 The function returns the only possible match, but the database doesn't store
 129 the keys to minimize overhead.
 130 .Sh SEE ALSO
 131 .Xr nbperf 1 ,
 132 .Xr cdbw 3 ,
 133 .Xr db 3 ,
 134 .Xr cdb 5
 135 .Sh HISTORY
 136 Support for the
 137 .Nm cdb
 138 format first appeared in
 139 .Nx 6.0 .
 140 .Sh AUTHORS
 141 The
 142 .Nm cdbr
 143 and
 144 .Nm cdbw
 145 functions have been written by
 146 .An Joerg Sonnenberger Aq Mt joerg@NetBSD.org .