1.\" $NetBSD: cdbw.3,v 1.9 2023/08/08 10:34:08 riastradh 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 February 6, 2014 32.Dt CDBW 3 33.Os 34.Sh NAME 35.Nm cdbw_open , 36.Nm cdbw_put , 37.Nm cdbw_put_data , 38.Nm cdbw_put_key , 39.Nm cdbw_stable_seeder , 40.Nm cdbw_output , 41.Nm cdbw_close 42.Nd create constant databases 43.Sh SYNOPSIS 44.In cdbw.h 45.Ft "struct cdbw *" 46.Fn cdbw_open "void" 47.Ft int 48.Fo cdbw_put 49.Fa "struct cdbw *cdbw" 50.Fa "const void *key" 51.Fa "size_t keylen" 52.Fa "const void *data" 53.Fa "size_t datalen" 54.Fc 55.Ft int 56.Fo cdbw_put_data 57.Fa "struct cdbw *cdbw" 58.Fa "const void *data" 59.Fa "size_t datalen" 60.Fa "uint32_t *index" 61.Fc 62.Ft int 63.Fo cdbw_put_key 64.Fa "struct cdbw *cdbw" 65.Fa "const void *key" 66.Fa "size_t keylen" 67.Fa "uint32_t index" 68.Fc 69.Ft uint32_t 70.Fo cdbw_stable_seeder 71.Fa "void" 72.Fc 73.Ft int 74.Fo cdbw_output 75.Fa "struct cdbw *cdbw" 76.Fa "int output" 77.Fa "const char *descr" 78.Fa "uint32_t (*seedgen)(void)" 79.Fc 80.Ft void 81.Fn cdbw_close "struct cdbw *cdbw" 82.Sh DESCRIPTION 83The 84.Nm cdbw 85functions are used to create a constant databases for use with 86.Xr cdbr 3 . 87Details about the file format, including overhead and limitations, 88can be found in 89.Xr cdb 5 . 90.Pp 91.Fn cdbw_open 92prepares a new 93.Nm cdb 94writer. 95The function returns a handle to pass to the other functions. 96.Pp 97.Fn cdbw_close 98frees all resources associated with the handle. 99.Pp 100.Fn cdbw_put 101adds the given (key,value) pair after checking for a duplicate key. 102.Fn cdbw_put_data 103adds the given value to the writer without adding a key reference. 104The returned index can be used in subsequent calls to 105.Fn cdbw_put_key 106to add one or more keys pointing to this value. 107.Fn cdbw_put_key 108checks for duplicate keys and valid index arguments. 109On success it adds the given key. 110.Pp 111.Fn cdbw_output 112computes the database file and writes it to the given descriptor. 113The function returns an error if the file cannot be written correctly. 114The 115.Fa descr 116parameter, a string of up to 16 bytes, provides a human readable 117description of the database content. 118The 119.Fa seedgen 120parameter can be used to override the default PRNG. 121The bitwise layout of the output depends on the chosen seed. 122The function should return a different value for each invocation. 123The 124.Fn cdbw_stable_seeder 125can be used to create reproducible output. 126It may be slower than the default. 127.Sh SEE ALSO 128.Xr cdbr 3 , 129.Xr cdb 5 130.Sh HISTORY 131Support for the 132.Nm cdb 133format first appeared in 134.Nx 6.0 . 135.Sh AUTHORS 136The 137.Nm cdbr 138and 139.Nm cdbw 140functions have been written by 141.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org . 142