mirror of
https://github.com/MariaDB/server.git
synced 2025-01-22 14:54:20 +01:00
Work on DB->put man page. Addresses #52.
git-svn-id: file:///svn/tokudb@1171 c7de825b-a66e-492c-adef-691d508d4ae1
This commit is contained in:
Bradley C. Kuszmaul
parent
8390854489
commit
d99cd30548
3 changed files with 103 additions and 72 deletions
|
|
@ -1,4 +1,4 @@
|
|||
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))
|
||||
|
|
|
|||
|
|
@ -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>}
|
||||
|
|
|
|||
|
|
@ -1,74 +1,105 @@
|
|||
.\" 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
|
||||
The key to be inserted.
|
||||
.IP \fIdata
|
||||
The data to be inserted.
|
||||
.IP \fIflags
|
||||
Must be zero.
|
||||
@section @code{DB->put}
|
||||
@setfilename tokudb
|
||||
@settitle DB->put
|
||||
|
||||
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
|
||||
The system discovered deadlock cycle involving this and other transactions.
|
||||
This operation was killed.
|
||||
.IP \fBDB_LOCK_NOTGRANTED
|
||||
In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
|
||||
.IP \fBENOENT
|
||||
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.
|
||||
@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.)
|
||||
|
||||
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.
|
||||
@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 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
|
||||
|
||||
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.
|
||||
|
||||
If @var{flags} is zero, returns @code{BEINVAL}.
|
||||
@c man end
|
||||
|
||||
@include everyman.texi
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue