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