.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.\" Copyright (c) 2007 Tokutek.  All Rights Reserved.
.TH db_create 3 "November 2007" Tokutek "TokuDB Programmer's Manual"
.SH NAME
db_create
.SH SYNOPSIS
.LP
\fB #include <db.h>
.br
.sp
.HP 13
.BI "int db_create(DB **" dbp ", DB_ENV *" env ", u_int32_t " flags ");"
.SH DESCRIPTION
\fBdb_create\fR creates a DB handle, allocating memory and initializing its contents.
.LP
After creating the handle, you open a database using \fB*\fIdbp\fB->open()\fR.

To free the memory associated with the handle call \fB*\fIdbp\fB->close()\fR
(or \fBremove\fR or \fBrename\fR or \fBverify\fR when those are ready.)

The handle contains a field called \fBapp_private\fR which is declared
as type \fBvoid*\fR.  This field is provided for the use of the
application and is not further used by TokuDB.  One typical use of
\fBapp_private\fR is to pass information about the database to a
user-defined sort-order function.

.SH PARAMETERS
.IP \fIdbp
A pointer to a \fBDB\fR variable.  The \fBdb_create\fR function does something like \fB*\fIdbp\fB=malloc(...)\fR.

.IP \fIenv
If \fIenv\fB==NULL\fR then the database is not part of an environment
(hence it has not transactions, locking, or recovery.)

Otherwise the database is created within the specified environment,
and inherits the properties of that environment.  (For example if
logging for recovery is enabled by the environment, then the database
will have logging too.)

.IP \fIflags
The \fIflags\fR parameter must be set to 0.

.SH RETURN VALUE
.LP
Returns zero on success.  The following non-zero errors can be returned:
.IP \fBEINVAL
You passed invalid parameters to this operation.  In many cases
\fBEINVAL\fR
is not a very helpful error code, indicating only that you did something wrong.

.SH CONFORMING TO
The TokuDB embedded database provides a subset of the functionality of
the Berkeley DB.  Programs that work with TokuDB probably work with
with most versions of Berkeley DB with only recompilation or
relinking.  The database files are incompatible, however, so to
convert from one library to the other you would need to dump the
database with one library's tool and load it with the other's.
.SH RESTRICTIONS
.LP
Restrictions: At most a few thousand databases per file.
.SH AUTHOR
Tokutek, Inc.
.SH COPYRIGHT
Copyright (c) 2007 Tokutek.  All Rights Reserved.