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