.\"-
.\" Copyright (c) 2014 Dmitry Selyutin
.\" All rights reserved.
.\"
.\" 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 AUTHOR 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 AUTHOR 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 August 18, 2014
.Dt COLLDB 3
.Os
.Sh NAME
.Nm colldb_create ,
.Nm colldb_open ,
.Nm colldb_sync ,
.Nm colldb_close ,
.Nm colldb_get ,
.Nm colldb_put
.Nd Collation database functions
.Sh LIBRARY
.Lb libcolldb
.Sh SYNOPSIS
.In colldb.h
.Ft void *
.Fn colldb_create "const char *path" "int mode"
.Ft void *
.Fn colldb_open "const char *path"
.Ft int
.Fn colldb_sync "void *colldb"
.Ft int
.Fn colldb_close "void *colldb"
.Ft int
.Fn colldb_get "void *colldb" "struct colldb_key *key" \
"struct colldb_value *value"
.Ft int
.Fn colldb_put "void *colldb" "struct colldb_key *key" \
"struct colldb_value *value"
.Sh DESCRIPTION
libcolldb provides a high-level interface for processing collation databases.
Database is a map of struct colldb_key and struct colldb_value pairs, where
each uint32_t integer is stored in network byte order.
.br
Conversion between host and network byte order is done implicitly.
.Pp
.Sh STRUCTURES
.Pp
.Bd -literal
struct colldb_weight {
	uint8_t alternate;
	uint32_t level1;
	uint32_t level2;
	uint32_t level3;
	uint32_t level4;
};
.Ed
.Pp
.Bd -literal
struct colldb_key {
	size_t count;
	uint32_t *chars;
};
.Ed
.Pp
.Bd -literal
struct colldb_value {
	size_t count;
	struct colldb_weight *weights;
};
.Ed
.Pp
.Fn colldb_create
creates a new collation database.
.Fa mode
argument is interpreted in the same way as in
.Fn open
call.
.Pp
.Fn colldb_open
opens existing collation database.
.Pp
.Fn colldb_sync
flushes any cached information to disk.
.Pp
.Fn colldb_close
flushes any cached information to disk, frees any allocated resources, and
closes the underlying file.
.Pp
.Fn colldb_get
accepts database, key and value. Key is converted to network byte order if
necessary. Fields of struct colldb_value must be already correctly initialized,
since value from database is written directly to it. Usually it is enough to
allocate
.Dv Va COLLDB_WEIGHTS_MAX
weights, set
.Va count
member of struct colldb_value to this number and set
.Va weights
member of struct colldb_value to point to allocated weights. However, in order
to support exotic databases, colldb_get() may return -1 and set errno to
.Er ERANGE
to indicate that struct colldb_value must allocate a larger weights buffer.
.Pp
.Fn colldb_put
accepts database, key and value. If necessary, it converts key and value into
the network byte order before writing.
.Sh ERRORS
.Fn colldb_create
and
.Fn colldb_open
return handle to collation database or NULL in case of failure. All other
functions behave exactly like their Berkley Database ancestors. Thus caller
must use return value and errno to determine what error happened.
.Sh SEE ALSO
.Xr colldb 1