@page
@section @code{DB->put}
@setfilename tokudb
@settitle DB->put

@c man title db_put tokudb
@unnumberedsubsec Synopsis
@c man begin SYNOPSIS
@code{#include <db.h>}

@code{int DB->put(DB *}@var{db}@code{, DB_TXN *}@var{txnid}@code{, DBT*}@var{key}@code{, DBT*}@var{data}@code{, u_int32_t }@var{flags}@code{);}
@c man end

@unnumberedsubsec Description
@c man begin DESCRIPTION
@code{DB->put} stores a key/data pair into a database, replacing any
previously existing key if duplicates are not enabled, or adding a
duplicate if sorted duplicates are enabled.  (TokuDB does not support
unsorted duplicates, hence the new key-data pair is inserted at the
correct sorted location.)

Key items are limited to 16KB in size.
Data items are limited to 256KB in size (for now.) 
@c man end

@unnumberedsubsec Parameters
@c man begin PARAMETERS
@table @var
@item db
The @code{DB} handle for the database.
@item txnid
Either @code{NULL} or a @code{TXNID}.
@item key
The key to be inserted.
@item data
The data to be inserted.
@item flags
Must be zero or must be one of the following flags.  However, @code{flags} must be nonzero for sorted duplicates.
@table @code
@item 0
For non-dup databases, insert the new key/data pair, overwriting any pair with a matching key.
Zero is not allowed databases with duplicates (returns @code{EINVAL}).

@item DB_YESOVERWRITE

Insert the new key/data pair, overwriting any matching pair.  If the
database supports sorted duplicates, then the matching key/data pair
(if any) is overwritten.  If the database does not support duplicates,
then the pair with a matching key (if any) is overwritten.  (TokuDB
supports only sorted duplicates, not unsorted duplicates.)

@item DB_NOOVERWRITE
Insert the new key/data pair only if the no key/data pair with a
matching key already exists in the database.

The @code{DB->put} function returns @code{DB_KEYEXIST} if
@code{DB_NOOVERWRITE} is set and the key already exists in the
database.

@item DB_NODUPDATA
Insert the new key/data pair only if it is not already present in the database.

@code{DB_NODUPDATA} may only be specifed when operating on databases that provide sorted duplicates.

The @code{DB->put} function returns @code{DB_KEYEXIST} if @code{DB_NODUPDATA} is set and the key/data pair is already present in the database.

Using @code{DB_NODUPDATA} can dramatically slow down deletions, since
it the implementation must perform a @code{DB->get} to determine
whether the pair already exists.
@end table


Rationale: Using @code{0} for flags does not give the results that
many users expect.  The Berkeley DB documentation says that someday
they will support duplicate duplicates, and that if you want the
current behavior you should use @code{DB_NOOVERWRITE}.  On the other
hand, the current behavior is very expensive, since it requires that
the implementation perform a @code{DB->get()}.

Further confounding issues that for Berkeley@tie{}DB has the following
behavior: For sorted duplicates, inserting the same pair twice returns
@code{DB_KEYEXIST}.  For no-duplicates or unsorted duplicates,
inserting the same pair twice overwrites the pair returning @code{0}.

We wanted a mode in which matching data is overwritten, however
``matching'' is defined.  Thus for non-duplicates, a matching pair is
one with the same key.  For sorted duplicates, a matching pair is one
with the same key and data.

For high performance, use @code{DB_YESOVERWRITE}.
@end table

@c man end
@unnumberedsubsec Return Value
@c man begin RETURNVALUE

Returns zero on success.  The following non-zero errors can be returned:
@table @code
@item DB_DEADLOCK
The system discovered deadlock cycle involving this and other transactions.
This operation was killed.
@item DB_LOCK_NOTGRANTED
In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
@item ENOENT
The file or directory does not exist.
@item EINVAL
You passed invalid parameters to this operation.

In particular, if you pass 0 to a database configured for duplicates,
then @code{DB->put()} returns @code{EINVAL}.

@end table
@c man end

@include everyman.texi