120 lines
3.4 KiB
Groff
120 lines
3.4 KiB
Groff
|
.\" $NetBSD: cdbr.3,v 1.2 2010/04/25 10:32:44 wiz Exp $
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
||
|
|
.\" by Joerg Sonnenberger.
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\"
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in
|
||
|
|
.\" the documentation and/or other materials provided with the
|
||
|
|
.\" distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
|
|
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
||
|
|
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
||
|
|
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
||
|
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
||
|
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
||
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
|
|
.\" SUCH DAMAGE.
|
||
|
|
.Dd March 3, 2010
|
||
|
|
.Dt CDBR 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm cdbr
|
||
|
|
.Nm cdbr_open ,
|
||
|
|
.Nm cdbr_entries ,
|
||
|
|
.Nm cdbr_get ,
|
||
|
|
.Nm cdbr_find ,
|
||
|
|
.Nm cdbr_close ,
|
||
|
|
.Nm cdbr_write
|
||
|
|
.Nd constant database access methods
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.Ft "struct cdbr *"
|
||
|
|
.Fn cdbr_open "const char *path" "int flags"
|
||
|
|
.Ft uint32_t
|
||
|
|
.Fn cdbr_entries "struct cdbr *cdbr"
|
||
|
|
.Ft int
|
||
|
|
.Fn cdbr_get "struct cdbr *cdbr" "uint32_t index" "const void **data" "size_t *datalen"
|
||
|
|
.Ft int
|
||
|
|
.Fo cdbr_find
|
||
|
|
.Fa "struct cdbr *cdbr"
|
||
|
|
.Fa "const void *key"
|
||
|
|
.Fa "size_t keylen"
|
||
|
|
.Fa "const void **data"
|
||
|
|
.Fa "size_t *datalen"
|
||
|
|
.Fc
|
||
|
|
.Ft void
|
||
|
|
.Fn cdbr_close "struct cdbr *cdbr"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
library provides a space efficient (key,value) database based
|
||
|
|
on perfect hashing.
|
||
|
|
.Pp
|
||
|
|
A cdb database is opened for reading by calling
|
||
|
|
.Fn cdbr_open .
|
||
|
|
The only supported value for
|
||
|
|
.Va flags
|
||
|
|
is
|
||
|
|
.Dv CDBR_DEFAULT .
|
||
|
|
The function returns a handle to pass to the other functions.
|
||
|
|
The database is closed by invoking
|
||
|
|
.Fn cdbr_close .
|
||
|
|
All resources associated with the handle are freed and the memory
|
||
|
|
returned by
|
||
|
|
.Fn cdbr_get
|
||
|
|
and
|
||
|
|
.Fn cdbr_find
|
||
|
|
is invalidated.
|
||
|
|
.Pp
|
||
|
|
The number of records in the database can be obtained by calling
|
||
|
|
.Fn cdbr_entries .
|
||
|
|
Records can be obtained by record number using
|
||
|
|
.Fn cdbr_get
|
||
|
|
or by key using
|
||
|
|
.Fn cdbr_find .
|
||
|
|
Both functions return 0 on success and update
|
||
|
|
.Va data
|
||
|
|
and
|
||
|
|
.Va datalen
|
||
|
|
accordingly.
|
||
|
|
The location
|
||
|
|
.Va *data
|
||
|
|
remains valid until
|
||
|
|
.Fn cdbr_close
|
||
|
|
is called.
|
||
|
|
It is the responsibility of the caller of
|
||
|
|
.Fn cdbr_find
|
||
|
|
to ensure that the key matches the returned data.
|
||
|
|
The function returns the only possible match, but the database doesn't store
|
||
|
|
the keys to minimize overhead.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr nbperf 1 ,
|
||
|
|
.Xr cdbw 3 ,
|
||
|
|
.Xr db 3 ,
|
||
|
|
.Xr cdb 5
|
||
|
|
.Sh HISTORY
|
||
|
|
Support for the
|
||
|
|
.Nm cdb
|
||
|
|
format first appeared in
|
||
|
|
.Nx 6.0 .
|
||
|
|
.Sh AUTHORS
|
||
|
|
The
|
||
|
|
.Nm cdbr
|
||
|
|
and
|
||
|
|
.Nm cdbw
|
||
|
|
functions have been written by
|
||
|
|
.An Joerg Sonnenberger Aq joerg@NetBSD.org .
|