1.\" $NetBSD: cdbw.3,v 1.6 2013/07/20 21:39:56 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 June 3, 2012 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 archive_entry.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[16]" 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.Fn descr 116parameter provides a human readable description of the database content. 117The 118.Fn seedgen 119parameter can be used to override the default PRNG. 120The bitwise layout of the output depends on the chosen seed. 121The function should return a different value for each invocation. 122The 123.Fn cdbw_stable_seeder 124can be used to create reproducible output. 125It may be slower than the default. 126.Sh SEE ALSO 127.Xr cdbr 3 , 128.Xr cdb 5 129.Sh HISTORY 130Support for the 131.Nm cdb 132format first appeared in 133.Nx 6.0 . 134.Sh AUTHORS 135The 136.Nm cdbr 137and 138.Nm cdbw 139functions have been written by 140.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org . 141