Work on DB->put man page. Addresses #52.

git-svn-id: file:///svn/tokudb@1171 c7de825b-a66e-492c-adef-691d508d4ae1

man/texi/Makefile

-MANPAGES = tdb_create tdb_del
+MANPAGES = tdb_create tdb_del tdb_put
 MANPAGES_TEXI = $(patsubst %,%.texi,$(MANPAGES))
 MANPAGES_POD = $(patsubst %,%.pod,$(MANPAGES))
 MANPAGES_3   = $(patsubst %,%.3,$(MANPAGES))

man/texi/tdb_del.texi

@@ -2,7 +2,7 @@
 @setfilename tokudb
 @settitle DB->del
 
-@c man title db_create tokudb
+@c man title db_del tokudb
 @unnumberedsubsec Synopsis
 @c man begin SYNOPSIS
 @code{#include <db.h>}

man/texi/tdb_put.texi

-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.\" Copyright (c) 2007 Tokutek.  All Rights Reserved.
-.TH DB->put 3 "November 2007" Tokutek "TokuDB Programmer's Manual"
-.SH NAME
-DB->open
-.SH SYNOPSIS
-.LP
-\fB #include <db.h>
-.br
-.sp
-.HP 12
-.BI "int DB->put(DB *" db ,
-.br
-.BI "DB_TXN *" txnid ,
-.br
-.BI "DBT *" key ,
-.br
-.BI "DBT *" data ,
-.br
-.BI "u_int32_t " flags );
-.br
-.SH DESCRIPTION
-.B 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
-duplicates are enabled.  TokuDB does not support unsorted duplicates
-(it supports no-duplicates and sorted duplicates), hence the new
-key-data pair is inserted at the correct sorted location.
-.SH PARAMETERS
-.IP \fIdb
-The \fBDB\fR handle for the database\fR.
-.IP \fItxnid
-Either \fBNULL\fR or a \fBTXNID\fR.
-.IP \fIkey
+@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.
-.IP \fIdata
+@item data
 The data to be inserted.
-.IP \fIflags
-Must be zero.
+@item flags
+Must not be zero, but instead must be one of the following flagsd:.  
+@table @code
+@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.
+@end table
+
+@c man end
+@unnumberedsubsec Return Value
+@c man begin RETURNVALUE
 
-Note: TokuDB does supports neither \fBDB_NODUPDATA\fR nor \fBDB_NOOVERRITE\fR.
-.SH RETURN VALUE
-.LP
 Returns zero on success.  The following non-zero errors can be returned:
-.IP \fBDB_DEADLOCK
+@table @code
+@item DB_DEADLOCK
 The system discovered deadlock cycle involving this and other transactions.
 This operation was killed.
-.IP \fBDB_LOCK_NOTGRANTED
+@item DB_LOCK_NOTGRANTED
 In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
-.IP \fBENOENT
+@item ENOENT
 The file or directory does not exist.
-.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.
-
-If \fIflags\fR is non-zero, returns \fBEINVAL\fR.
-.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
-Key items are limited to 16KB in size.
-Data items are limited to 256KB in size (for now.) 
-.SH AUTHOR
-Tokutek, Inc.
-.SH COPYRIGHT
-Copyright (c) 2007 Tokutek.  All Rights Reserved.
+@item EINVAL
+You passed invalid parameters to this operation.  
+
+If @var{flags} is zero, returns @code{BEINVAL}.
+@c man end
+
+@include everyman.texi
+