.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "LMDB_File 3pm" .TH LMDB_File 3pm "2022-10-20" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" LMDB_File \- Tie to LMDB (OpenLDAP's Lightning Memory\-Mapped Database) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Simple TIE interface, when you\*(Aqre in a rush \& use LMDB_File; \& \& $db = tie %hash, \*(AqLMDB_File\*(Aq, $path; \& \& $hash{$key} = $value; \& $value = $hash{$key}; \& each %hash; \& keys %hash; \& values %hash; \& ... \& \& \& # The full power \& use LMDB_File qw(:flags :cursor_op); \& \& $env = LMDB::Env\->new($path, { \& mapsize => 100 * 1024 * 1024 * 1024, # Plenty space, don\*(Aqt worry \& maxdbs => 20, # Some databases \& mode => 0600, \& # More options \& }); \& \& $txn = $env\->BeginTxn(); # Open a new transaction \& \& $DB = $txn\->OpenDB( { # Create a new database \& dbname => $dbname, \& flags => MDB_CREATE \& }); \& \& $DB\->put($key, $value); # Simple put \& $value = $DB\->get($key); # Simple get \& \& $DB\->put($key, $value, MDB_NOOVERWITE); # Don\*(Aqt replace existing value \& \& # Work with cursors \& $cursor => $DB\->Cursor; \& \& $cursor\->get($key, $value, MDB_FIRST); # First key/value in DB \& $cursor\->get($key, $value, MDB_NEXT); # Next key/value in DB \& $cursor\->get($key, $value, MDB_LAST); # Last key/value in DB \& $cursor\->get($key, $value, MDB_PREV); # Previous key/value in DB \& \& $DB\->set_compare( sub { lc($a) cmp lc($b) } ); # Use my own key comparison function .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fB\s-1NOTE:\s0 This document is still under construction. Expect it to be\fR \&\fBincomplete in places.\fR .PP LMDB_File is a Perl module which allows Perl programs to make use of the facilities provided by OpenLDAP's Lightning Memory-Mapped Database \*(L"\s-1LMDB\*(R".\s0 .PP \&\s-1LMDB\s0 is a Btree-based database management library modeled loosely on the BerkeleyDB \s-1API,\s0 but much simplified and extremely fast. .PP It is assumed that you have a copy of \s-1LMBD\s0's documentation at hand when reading this documentation. The interface defined here mirrors the C interface closely but with an \s-1OO\s0 approach. .PP This is implemented with a number of Perl classes. .PP A \s-1LMDB\s0's \fBenvironment\fR handler (MDB_env* in C) will be wrapped in the \&\fBLMDB::Env\fR class. .PP A \s-1LMDB\s0's \fBtransaction\fR handler (MDB_txn* in C) will be wrapped in the \&\fBLMDB::Txn\fR class. .PP A \s-1LMDB\s0's \fBcursor\fR handler (MDB_cursor* in C) will be wrapped in the \&\fBLMDB::Cursor\fR class. .PP A \s-1LMDB\s0's \fBDatabase\fR handler (MDB_dbi in C) will be exposed as a simple integer, but because in \s-1LMDB\s0 all Database operations needs both a Transaction and a Database handler, LMDB_File provides you a convenient \*(L"LMDB_File\*(R" object that encapsulates both and mimic the syntax of other *_File modules. .SH "Error reporting" .IX Header "Error reporting" In the C \s-1API,\s0 most functions return 0 on success and an error code on failure. .PP In this module, when a function fails, the package variable \fB\f(CB$die_on_err\fB\fR controls the course of action. When \fB\f(CB$die_on_err\fB\fR is set to \s-1TRUE,\s0 this causes LMDB_File to \&\f(CW\*(C`die\*(C'\fR with an error message that can be trapped by an \f(CW\*(C`eval { ... }\*(C'\fR block. .PP When \s-1FALSE,\s0 the function will return the error code, in this case you should check the return value of any function call. .PP By default \fB\f(CB$die_on_err\fB\fR is \s-1TRUE.\s0 .PP Regardless of the value of \fB\f(CB$die_on_err\fB\fR, the code of the last error can be found in the package variable \fB\f(CB$last_err\fB\fR. .SH "LMDB::Env" .IX Header "LMDB::Env" This class wraps an opened \s-1LMDB\s0 \fBenvironment\fR. .PP At construction time, the environment is created, if it does not exist, and opened. .PP When you are finished using it, in the C \s-1API\s0 you must call the \f(CW\*(C`mdb_env_close\*(C'\fR function to close it and free the memory allocated, but in Perl you simply will let that the object get out of scope. .SS "Constructor" .IX Subsection "Constructor" \&\f(CW$Env\fR = LMDB::Env\->new ( \f(CW$path\fR [, \s-1ENVOPTIONS\s0 ] ) .PP Creates a new \f(CW\*(C`LMDB::Env\*(C'\fR object and returns it. It encapsulates both \s-1LMDB\s0's \&\f(CW\*(C`mdb_env_create\*(C'\fR and \f(CW\*(C`mdb_env_open\*(C'\fR functions. .PP \&\fI\f(CI$path\fI\fR is the directory in which the database files reside. This directory must already exist and should be writable. .PP \&\fB\s-1ENVOPTIONS\s0\fR, if provided, must be a \s-1HASH\s0 Reference with any of the following options: .IP "mapsize => \s-1INT\s0" 4 .IX Item "mapsize => INT" The size of the memory map to use for this environment. .Sp The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database. The size should be a multiple of the \s-1OS\s0 page size. .Sp The default is 1048576 bytes (1 \s-1MB\s0). .IP "maxreaders => \s-1INT\s0" 4 .IX Item "maxreaders => INT" The maximum number of threads/reader slots for the environment. .Sp This defines the number of slots in the lock table that is used to track readers in the environment. .Sp The default is 126. .IP "maxdbs => \s-1INT\s0" 4 .IX Item "maxdbs => INT" The maximum number of named databases for the environment. .Sp This option is only needed if multiple databases will be used in the environment. Simpler applications that use the environment as a single unnamed database can ignore this option. .Sp The default is 0, i.e. no named databases allowed. .IP "mode => \s-1INT\s0" 4 .IX Item "mode => INT" The \s-1UNIX\s0 permissions to set on created files. This parameter is ignored on Windows. It defaults to 0600 .IP "flags => \s-1ENVFLAGS\s0" 4 .IX Item "flags => ENVFLAGS" Set special options for this environment. This option, if provided, can be specified by \s-1OR\s0'ing the following flags: .RS 4 .IP "\s-1MDB_FIXEDMAP\s0" 4 .IX Item "MDB_FIXEDMAP" Use a fixed address for the mmap region. This flag must be specified when creating the environment, and is stored persistently in the environment. If successful, the memory map will always reside at the same virtual address and pointers used to reference data items in the database will be constant across multiple invocations. This option may not always work, depending on how the operating system has allocated memory to shared libraries and other uses. The feature is highly experimental. .IP "\s-1MDB_NOSUBDIR\s0" 4 .IX Item "MDB_NOSUBDIR" By default, \s-1LMDB\s0 creates its environment in a directory whose pathname is given in \fI\f(CI$path\fI\fR, and creates its data and lock files under that directory. With this option, \fI\f(CI$path\fI\fR is used as-is for the database main data file. The database lock file is the \fI\f(CI$path\fI\fR with \*(L"\-lock\*(R" appended. .IP "\s-1MDB_RDONLY\s0" 4 .IX Item "MDB_RDONLY" Open the environment in read-only mode. No write operations will be allowed. \s-1LMDB\s0 will still modify the lock file \- except on read-only filesystems, where \s-1LMDB\s0 does not use locks. .IP "\s-1MDB_WRITEMAP\s0" 4 .IX Item "MDB_WRITEMAP" Use a writeable memory map unless \f(CW\*(C`MDB_RDONLY\*(C'\fR is set. This is faster and uses fewer mallocs, but loses protection from application bugs like wild pointer writes and other bad updates into the database. .Sp Incompatible with nested transactions (also known as sub transactions). .IP "\s-1MDB_NOMETASYNC\s0" 4 .IX Item "MDB_NOMETASYNC" Flush system buffers to disk only once per transaction, omit the metadata flush. Defer that until the system flushes files to disk, or next non\-MDB_RDONLY commit or \f(CW\*(C`$Env\->sync()\*(C'\fR. This optimization maintains database integrity, but a system crash may undo the last committed transaction. I.e. it preserves the \s-1ACI\s0 (atomicity, consistency, isolation) but not D (durability) database property. .Sp This flag may be changed at any time using \f(CW\*(C`$Env\->set_flags()\*(C'\fR. .IP "\s-1MDB_NOSYNC\s0" 4 .IX Item "MDB_NOSYNC" Don't flush system buffers to disk when committing a transaction. This optimization means a system crash can corrupt the database or lose the last transactions if buffers are not yet flushed to disk. The risk is governed by how often the system flushes dirty buffers to disk and how often \f(CW\*(C`$Env\->sync()\*(C'\fR is called. However, if the filesystem preserves write order and the \f(CW\*(C`MDB_WRITEMAP\*(C'\fR flag is not used, transactions exhibit \s-1ACI\s0 (atomicity, consistency, isolation) properties and only lose D (durability). I.e. database integrity is maintained, but a system crash may undo the final transactions. Note that \f(CW\*(C`MDB_NOSYNC | MDB_WRITEMAP\*(C'\fR leaves the system with no hint for when to write transactions to disk, unless \f(CW\*(C`$Env\->sync()\*(C'\fR is called. \f(CW\*(C`MDB_MAPASYNC | MDB_WRITEMAP\*(C'\fR) may be preferable. .Sp This flag may be changed at any time using \f(CW\*(C`$Env\->set_flags()\*(C'\fR. .IP "\s-1MDB_MAPASYNC\s0" 4 .IX Item "MDB_MAPASYNC" When using \f(CW\*(C`MDB_WRITEMAP\*(C'\fR, use asynchronous flushes to disk. As with \f(CW\*(C`MDB_NOSYNC\*(C'\fR, a system crash can then corrupt the database or lose the last transactions. Calling \f(CW\*(C`$Env\->sync()\*(C'\fR ensures on-disk database integrity until next commit. .Sp This flag may be changed at any time using \f(CW\*(C`$Env\->set_flags()\*(C'\fR. .IP "\s-1MDB_NOTLS\s0" 4 .IX Item "MDB_NOTLS" Don't use Thread-Local Storage. Tie reader locktable slots to \&\*(L"LMDB::Txn\*(R" objects instead of to threads. I.e. \f(CW\*(C`$Txn\->reset()\*(C'\fR keeps the slot reserved for the \*(L"LMDB::Txn\*(R" object. A thread may use parallel read-only transactions. A read-only transaction may span threads if the user synchronizes its use. Applications that multiplex many user threads over individual \s-1OS\s0 threads need this option. Such an application must also serialize the write transactions in an \s-1OS\s0 thread, since \s-1LMDB\s0's write locking is unaware of the user threads. .RE .RS 4 .RE .SS "Class methods" .IX Subsection "Class methods" .ie n .IP "$Env\->copy ( $path )" 4 .el .IP "\f(CW$Env\fR\->copy ( \f(CW$path\fR )" 4 .IX Item "$Env->copy ( $path )" Copy an \s-1LMDB\s0 environment to the specified \fI\f(CI$path\fI\fR .ie n .IP "$Env\->copyfd ( \s-1HANDLE\s0 )" 4 .el .IP "\f(CW$Env\fR\->copyfd ( \s-1HANDLE\s0 )" 4 .IX Item "$Env->copyfd ( HANDLE )" Copy an \s-1LMDB\s0 environment to the specified \fB\s-1HANDLE\s0\fR. .ie n .IP "$status = $Env\->stat" 4 .el .IP "\f(CW$status\fR = \f(CW$Env\fR\->stat" 4 .IX Item "$status = $Env->stat" Returns a \s-1HASH\s0 reference with statistics for the main, unnamed, database in the environment, the \s-1HASH\s0 contains the following keys: .RS 4 .IP "\fBpsize\fR Size of a database page." 4 .IX Item "psize Size of a database page." .PD 0 .IP "\fBdepth\fR Depth (height) of the B\-Tree" 4 .IX Item "depth Depth (height) of the B-Tree" .IP "\fBbranch_pages\fR Number of internal (non-leaf) pages" 4 .IX Item "branch_pages Number of internal (non-leaf) pages" .IP "\fBoverflow_pages\fR Number of overflow pages" 4 .IX Item "overflow_pages Number of overflow pages" .IP "\fBentries\fR Number of data items" 4 .IX Item "entries Number of data items" .RE .RS 4 .RE .ie n .IP "$info = $Env\->info" 4 .el .IP "\f(CW$info\fR = \f(CW$Env\fR\->info" 4 .IX Item "$info = $Env->info" .PD Returns a \s-1HASH\s0 reference with information about the environment, \fI\f(CI$info\fI\fR, with the following keys: .RS 4 .IP "\fBmapaddr\fR Address of map, if fixed" 4 .IX Item "mapaddr Address of map, if fixed" .PD 0 .IP "\fBmapsize\fR Size of the data memory map" 4 .IX Item "mapsize Size of the data memory map" .IP "\fBlast_pgno\fR \s-1ID\s0 of the last used page" 4 .IX Item "last_pgno ID of the last used page" .IP "\fBlast_txnid\fR \s-1ID\s0 of the last committed transaction" 4 .IX Item "last_txnid ID of the last committed transaction" .IP "\fBmaxreaders\fR Max reader slots in the environment" 4 .IX Item "maxreaders Max reader slots in the environment" .IP "\fBnumreaders\fR Max reader slot used in the environment" 4 .IX Item "numreaders Max reader slot used in the environment" .RE .RS 4 .RE .ie n .IP "$Env\->sync ( \s-1BOOL\s0 )" 4 .el .IP "\f(CW$Env\fR\->sync ( \s-1BOOL\s0 )" 4 .IX Item "$Env->sync ( BOOL )" .PD Flush the data buffers to disk. .Sp Data is always written to disk when \f(CW\*(C`$Txn\->commit()\*(C'\fR is called, but the operating system may keep it buffered. \s-1LMDB\s0 always flushes the \s-1OS\s0 buffers upon commit as well, unless the environment was opened with \f(CW\*(C`MDB_NOSYNC\*(C'\fR or in part \f(CW\*(C`MDB_NOMETASYNC\*(C'\fR. .Sp If \fI\s-1BOOL\s0\fR is \s-1TRUE\s0 force a synchronous flush. Otherwise if the environment has the \f(CW\*(C`MDB_NOSYNC\*(C'\fR flag set the flushes will be omitted, and with \f(CW\*(C`MDB_MAPASYNC\*(C'\fR they will be asynchronous. .ie n .IP "$Env\->set_flags ( \s-1BITMASK, BOOL\s0 )" 4 .el .IP "\f(CW$Env\fR\->set_flags ( \s-1BITMASK, BOOL\s0 )" 4 .IX Item "$Env->set_flags ( BITMASK, BOOL )" As noted above, some environment flags can be changed at any time. .Sp \&\fI\s-1BITMASK\s0\fR is the flags to change, bitwise \s-1OR\s0'ed together. \&\fI\s-1BOOL\s0\fR \s-1TRUE\s0 set the flags, \s-1FALSE\s0 clears them. .ie n .IP "$Env\->get_flags ( $flags )" 4 .el .IP "\f(CW$Env\fR\->get_flags ( \f(CW$flags\fR )" 4 .IX Item "$Env->get_flags ( $flags )" Returns in \fI\f(CI$flags\fI\fR the environment flags. .ie n .IP "$Env\->get_path ( $path )" 4 .el .IP "\f(CW$Env\fR\->get_path ( \f(CW$path\fR )" 4 .IX Item "$Env->get_path ( $path )" Returns in \fI\f(CI$path\fI\fR the path that was used in \f(CW\*(C`LMDB::Env\->new(...)\*(C'\fR .ie n .IP "$Env\->get_maxreaders ( $readers )" 4 .el .IP "\f(CW$Env\fR\->get_maxreaders ( \f(CW$readers\fR )" 4 .IX Item "$Env->get_maxreaders ( $readers )" Returns in \fI\f(CI$readers\fI\fR the maximum number of threads/reader slots for the environment .ie n .IP "$mks = $Env\->get_maxkeysize" 4 .el .IP "\f(CW$mks\fR = \f(CW$Env\fR\->get_maxkeysize" 4 .IX Item "$mks = $Env->get_maxkeysize" Returns the maximum size of a key for the environment. .ie n .IP "$Txn = $Env\->BeginTxn ( [ $tflags ] )" 4 .el .IP "\f(CW$Txn\fR = \f(CW$Env\fR\->BeginTxn ( [ \f(CW$tflags\fR ] )" 4 .IX Item "$Txn = $Env->BeginTxn ( [ $tflags ] )" Returns a new Transaction. A simple wrapper over the constructor of \&\*(L"LMDB::Txn\*(R". .Sp If provided, \f(CW$tflags\fR will be passed to the constructor, if not provided, this wrapper will propagate the environment's flag \f(CW\*(C`MDB_RDONLY\*(C'\fR, if set, to the transaction constructor. .SH "LMDB::Txn" .IX Header "LMDB::Txn" In \s-1LMDB\s0 every operation (read or write) on a Database needs to be inside a \&\fBtransaction\fR. This class wraps an \s-1LMDB\s0 transaction. .PP You must terminate the transaction by either the \f(CW\*(C`abort\*(C'\fR or \f(CW\*(C`commit\*(C'\fR methods. After a transaction is terminated, you should not call any other method on it, except \f(CW\*(C`env\*(C'\fR. .PP If you let an object of this class get out of scope, by default the transaction will be aborted. .SS "Constructor" .IX Subsection "Constructor" .Vb 1 \& $Txn = LMDB::Txn\->new ( $Env [, $tflags ] ) .Ve .PP Create a new \fBtransaction\fR for use in the \fBenvironment\fR. .SS "Class methods" .IX Subsection "Class methods" .ie n .IP "$Txn\->abort" 4 .el .IP "\f(CW$Txn\fR\->abort" 4 .IX Item "$Txn->abort" Abort the transaction, terminating the transaction. .ie n .IP "$Txn\->commit" 4 .el .IP "\f(CW$Txn\fR\->commit" 4 .IX Item "$Txn->commit" Commit the transaction, terminating the transaction. .ie n .IP "$Txn\->reset" 4 .el .IP "\f(CW$Txn\fR\->reset" 4 .IX Item "$Txn->reset" Reset a read-only transaction. .Sp Abort the transaction like \f(CW\*(C`$Txn\->abort()\*(C'\fR, but keep the transaction handle in the inactive state so \f(CW\*(C`$Txn\->renew()\*(C'\fR may reactivate the handle. .Sp This saves allocation overhead if the process will start a new read-only transaction soon, and also saves locking overhead if \s-1MDB_NOTLS\s0 is in use. .Sp The reader table lock is released, but the table slot stays tied to its thread or Transaction. Use \f(CW\*(C`$Txn\->abort()\*(C'\fR to discard a reseted handle, and to free its lock table slot if \s-1MDB_NOTLS\s0 is in use. .ie n .IP "$Txn\->renew" 4 .el .IP "\f(CW$Txn\fR\->renew" 4 .IX Item "$Txn->renew" Renew a read-only transaction. .Sp This acquires a new reader lock for a transaction handle that had been inactivated by \f(CW\*(C`$Txn\->reset()\*(C'\fR. It must be called before an inactive (reseted) transaction may be used again. .Sp In this Perl implementation if you call \f(CW\*(C`$Txn\->renew()\*(C'\fR in an active Transaction the method internally calls \f(CW\*(C`$Txn\->reset()\*(C'\fR for you. .ie n .IP "$Env = $Txn\->env" 4 .el .IP "\f(CW$Env\fR = \f(CW$Txn\fR\->env" 4 .IX Item "$Env = $Txn->env" Returns the environment (an LMDB::Env object) that created the transaction, if it is still alive, or \f(CW\*(C`undef\*(C'\fR if called on a terminated transaction. .ie n .IP "$SubTxn = $Txn\->SubTxn ( [ $tflags ] )" 4 .el .IP "\f(CW$SubTxn\fR = \f(CW$Txn\fR\->SubTxn ( [ \f(CW$tflags\fR ] )" 4 .IX Item "$SubTxn = $Txn->SubTxn ( [ $tflags ] )" Creates and returns a sub transaction (also known as a nested transaction). .Sp Nested transactions are useful for combining components that create and commit transactions. No modifications are permanently stored until the highest level \*(L"parent\*(R" transaction is committed. Nested transactions can be aborted without aborting the parent transaction and only the changes made in the nested transaction will be rolled-back. .Sp Aborting the parent transaction will abort and terminate all outstanding nested transactions. Committing the parent transaction will similarly commit and terminate all outstanding nested transactions. .Sp Unlike some other databases, in \s-1LMDB\s0 changes made inside nested transactions are not visible to the parent transaction until the nested transaction is committed. In other words, transactions are always isolated, even when they are nested. .ie n .IP "$Txn\->AutoCommit ( [ \s-1BOOL\s0 ] )" 4 .el .IP "\f(CW$Txn\fR\->AutoCommit ( [ \s-1BOOL\s0 ] )" 4 .IX Item "$Txn->AutoCommit ( [ BOOL ] )" When \fI\s-1BOOL\s0\fR is provided, it sets the behavior of the transaction when going out of scope: \fI\s-1BOOL\s0\fR \s-1TRUE\s0 makes arrangements for the transaction to be auto committed and \fI\s-1BOOL\s0\fR \s-1FALSE\s0 returns to the default behavior: to be aborted. .Sp If you don't provide \fI\s-1BOOL\s0\fR, you are only interested in knowing the current value of this option, which is returned in every case. .ie n .IP "$DB = $Txn\->OpenDB ( [ \s-1DBOPTIONS\s0 ] )" 4 .el .IP "\f(CW$DB\fR = \f(CW$Txn\fR\->OpenDB ( [ \s-1DBOPTIONS\s0 ] )" 4 .IX Item "$DB = $Txn->OpenDB ( [ DBOPTIONS ] )" .PD 0 .ie n .IP "$DB = $Txn\->OpenDB ( [ $dbname [, \s-1DBFLAGS\s0 ]] )" 4 .el .IP "\f(CW$DB\fR = \f(CW$Txn\fR\->OpenDB ( [ \f(CW$dbname\fR [, \s-1DBFLAGS\s0 ]] )" 4 .IX Item "$DB = $Txn->OpenDB ( [ $dbname [, DBFLAGS ]] )" .PD This method opens a Database in the environment and returns a \*(L"LMDB_File\*(R" object that encapsulates both the Transaction and the Database handler. .Sp This is a convenience shortcut for \f(CW\*(C`LMDB_File\->new( $Txn, $Txn\->open(...) )\*(C'\fR for use when you want to use the hi-level LMDB_File's \s-1OO\s0 approach. .Sp \&\fB\s-1DBOPTIONS\s0\fR, if provided, should be a \s-1HASH\s0 reference with any of the following keys: .RS 4 .ie n .IP "\fBdbname\fR => $dbname" 4 .el .IP "\fBdbname\fR => \f(CW$dbname\fR" 4 .IX Item "dbname => $dbname" .PD 0 .IP "\fBflags\fR => \s-1DBFLAGS\s0" 4 .IX Item "flags => DBFLAGS" .RE .RS 4 .PD .Sp You can also call this method using its values, \fI\f(CI$dbname\fI\fR and \fB\s-1DBFLAGS\s0\fR, documented ahead. .RE .ie n .IP "$dbi = $Txn\->open ( [ $dbname [, \s-1DBFLAGS\s0 ]] )" 4 .el .IP "\f(CW$dbi\fR = \f(CW$Txn\fR\->open ( [ \f(CW$dbname\fR [, \s-1DBFLAGS\s0 ]] )" 4 .IX Item "$dbi = $Txn->open ( [ $dbname [, DBFLAGS ]] )" This method open a Database in the environment and returns the low level Database handler, an integer. .Sp If provided \fI\f(CI$dbname\fI\fR, will be the name of a named Database in the environment, if not provided (or if \fI\f(CI$dbname\fI\fR is \f(CW\*(C`undef\*(C'\fR), the opened Database will be the unnamed (the default) one. .Sp \&\fB\s-1DBFLAGS\s0\fR, if provided, will set special options for this Database and can be specified by \s-1OR\s0'ing the following flags: .RS 4 .IP "\s-1MDB_REVERSEKEY\s0" 4 .IX Item "MDB_REVERSEKEY" Keys are strings to be compared in reverse order .IP "\s-1MDB_DUPSORT\s0" 4 .IX Item "MDB_DUPSORT" Duplicate keys may be used in the database. (Or, from another perspective, keys may have multiple data items, stored in sorted order.) By default keys must be unique and may have only a single data item. .IP "\s-1MDB_INTEGERKEY\s0" 4 .IX Item "MDB_INTEGERKEY" Keys are binary integers in native byte order. .IP "\s-1MDB_DUPFIXED\s0" 4 .IX Item "MDB_DUPFIXED" This flag may only be used in combination with #MDB_DUPSORT. This option tells the library that the data items for this database are all the same size, which allows further optimizations in storage and retrieval. When all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE cursor operations may be used to retrieve multiple items at once. .IP "\s-1MDB_INTEGERDUP\s0" 4 .IX Item "MDB_INTEGERDUP" This option specifies that duplicate data items are also integers, and should be sorted as such. .IP "\s-1MDB_REVERSEDUP\s0" 4 .IX Item "MDB_REVERSEDUP" This option specifies that duplicate data items should be compared as strings in reverse order. .IP "\s-1MDB_CREATE\s0" 4 .IX Item "MDB_CREATE" Create the named database if it doesn't exist. This option is not allowed in a read-only transaction or a read-only environment. .Sp After successfully commit the transaction that created the Database, it will remains opened in the Environment so you can reuse \fI\f(CI$dbi\fI\fR in other transactions. .RE .RS 4 .Sp If you will need to use that Database handler in more than one transaction or want to use a more traditional (in \s-1LMDB\s0's point of view) approach, this the method you should use. .Sp To operate in the opened database with the returned \fI\f(CI$dbi\fI\fR handler you can use the methods described bellow or call \f(CW\*(C`LMDB_File\->new(...)\*(C'\fR to obtain a \*(L"LMDB_File\*(R" object to operate the database in a particular transaction. .RE .ie n .IP "$Txn\->put ( $dbi, $key, $data [, \s-1WRITEFLAGS\s0 [, $length ] )" 4 .el .IP "\f(CW$Txn\fR\->put ( \f(CW$dbi\fR, \f(CW$key\fR, \f(CW$data\fR [, \s-1WRITEFLAGS\s0 [, \f(CW$length\fR ] )" 4 .IX Item "$Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] )" Store items into the database \fI\f(CI$dbi\fI\fR .Sp Provided for when your main concern is the raw speed. .Sp For details of the other arguments, please see the method of the same name in LMDB_File below. .ie n .IP "$Txn\->get ( $dbi, $key, $data )" 4 .el .IP "\f(CW$Txn\fR\->get ( \f(CW$dbi\fR, \f(CW$key\fR, \f(CW$data\fR )" 4 .IX Item "$Txn->get ( $dbi, $key, $data )" Get items from the database \fI\f(CI$dbi\fI\fR .Sp Provided for when your main concern is the raw speed. .Sp For details of the other arguments, please see the method of the same name in LMDB_File below. .ie n .IP "$Txn\->id ()" 4 .el .IP "\f(CW$Txn\fR\->id ()" 4 .IX Item "$Txn->id ()" Return the transaction's \s-1ID.\s0 This returns the identifier associated with this transaction. For a read-only transaction, this corresponds to the snapshot being read; concurrent readers will frequently have the same transaction \s-1ID.\s0 .SH "LMDB_File" .IX Header "LMDB_File" In the \s-1LMDB C API\s0 all Database operations need both an active Transaction and a Database handler. To simplify those operations and be syntax compatible with others *_File modules, this Perl \s-1API\s0 provides you a \fBLMDB_File\fR object that encapsulates both and implements some hi-level extensions. .PP LMDB_File's methods, in contrast to the LMDB::Txn's ones of the same name, perform some checks before calling the low-level C \s-1API.\s0 .SS "Constructors" .IX Subsection "Constructors" .ie n .IP "$DB = LMDB_File\->new( $Txn, $dbi )" 4 .el .IP "\f(CW$DB\fR = LMDB_File\->new( \f(CW$Txn\fR, \f(CW$dbi\fR )" 4 .IX Item "$DB = LMDB_File->new( $Txn, $dbi )" Associates a Transaction \fI\f(CI$Txn\fI\fR with a previously opened Database handler \fI\f(CI$dbi\fI\fR to use this \s-1OO API\s0 .ie n .IP "$DB = LMDB_File\->open ( $Txn [, $dbname [, \s-1DBFLAGS\s0 ] ] )" 4 .el .IP "\f(CW$DB\fR = LMDB_File\->open ( \f(CW$Txn\fR [, \f(CW$dbname\fR [, \s-1DBFLAGS\s0 ] ] )" 4 .IX Item "$DB = LMDB_File->open ( $Txn [, $dbname [, DBFLAGS ] ] )" An alternative to \f(CW\*(C`$Txn\->OpenDB(...)\*(C'\fR for open a Database and associate it with a Transaction in one call. .SS "Class methods" .IX Subsection "Class methods" .ie n .IP "$DB\->put ( $key, $data [, \s-1WRITEFLAGS\s0 [, $length ] ] )" 4 .el .IP "\f(CW$DB\fR\->put ( \f(CW$key\fR, \f(CW$data\fR [, \s-1WRITEFLAGS\s0 [, \f(CW$length\fR ] ] )" 4 .IX Item "$DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] )" Store items into a database. .Sp This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed .Sp \&\fI\f(CI$key\fI\fR is the key to store in the database and \fI\f(CI$data\fI\fR the data to store. .Sp \&\fB\s-1WRITEFLAGS\s0\fR, if provided, will set special options for this operation and can be one of following flags: .RS 4 .IP "\s-1MDB_NODUPDATA\s0" 4 .IX Item "MDB_NODUPDATA" Enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with #MDB_DUPSORT. The function will fail with \s-1MDB_KEYEXIST\s0 if the key/data pair already appears in the database. .IP "\s-1MDB_NOOVERWRITE\s0" 4 .IX Item "MDB_NOOVERWRITE" Enter the new key/data pair only if the key does not already appear in the database. .Sp The function will return \s-1MDB_KEYEXIST\s0 if the key already appears in the database, even if the database supports duplicates (#MDB_DUPSORT). The \fI\f(CI$data\fI\fR parameter will be set to the existing item. .IP "\s-1MDB_RESERVE\s0" 4 .IX Item "MDB_RESERVE" Reserve space for data of the given size in \fI\f(CI$length\fI\fR, but don't copy anything. Instead, return in \fI\f(CI$data\fI\fR a magical scalar with a pointer to the reserved space, which the caller can fill in later, but before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. .Sp In this particular case, you need to pass the extra \fI\f(CI$length\fI\fR parameter to specify how many bytes to reserve. .Sp Please read about the \f(CW\*(C`$DB\->ReadMode\*(C'\fR method caveats bellow for details that apply to the magical scalar returned in \fI\f(CI$data\fI\fR in this case. .IP "\s-1MDB_APPEND\s0" 4 .IX Item "MDB_APPEND" Append the given key/data pair to the end of the database. .Sp No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. .Sp \&\fB\s-1NOTE:\s0\fR Loading unsorted keys with this flag will cause data corruption. .IP "\s-1MDB_APPENDDUP\s0" 4 .IX Item "MDB_APPENDDUP" As above, but for sorted duplicated data. .RE .RS 4 .RE .ie n .IP "$DB\->get ( $key, $data )" 4 .el .IP "\f(CW$DB\fR\->get ( \f(CW$key\fR, \f(CW$data\fR )" 4 .IX Item "$DB->get ( $key, $data )" .PD 0 .ie n .IP "$data = $DB\->get ( $key )" 4 .el .IP "\f(CW$data\fR = \f(CW$DB\fR\->get ( \f(CW$key\fR )" 4 .IX Item "$data = $DB->get ( $key )" .PD Get items from a database. .Sp This method retrieves key/data pairs from the database. .Sp If the database supports duplicate keys (#MDB_DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of the \f(CW\*(C`LMBD::Cursor\->get()\*(C'\fR method. .Sp The two-argument form, closer to the C \s-1API,\s0 returns in the provided argument \&\fI\f(CI$data\fI\fR the value associated with \fI\f(CI$key\fI\fR in the database if it exists or reports an error if not. .Sp In the simpler, more \*(L"perlish\*(R" one-argument form, the method returns the value associated with \fI\f(CI$key\fI\fR in the database or \f(CW\*(C`undef\*(C'\fR if no such value exists. .ie n .IP "$DB\->del ( $key [, $data ] )" 4 .el .IP "\f(CW$DB\fR\->del ( \f(CW$key\fR [, \f(CW$data\fR ] )" 4 .IX Item "$DB->del ( $key [, $data ] )" Delete items from the database. .Sp This function removes key/data pairs from the database. .Sp If the database does not support sorted duplicate data items, (\s-1MDB_DUPSORT\s0) the \fI\f(CI$data\fI\fR parameter is optional and is ignored. .Sp If the database supports sorted duplicates and the \fI\f(CI$data\fI\fR parameter is \f(CW\*(C`undef\*(C'\fR or not provided, all of the duplicate data items for the \fI\f(CI$key\fI\fR will be deleted. Otherwise, if the \fI\f(CI$data\fI\fR parameter is provided only the matching data item will be deleted. .ie n .IP "$DB\->set_compare ( \s-1CODE\s0 )" 4 .el .IP "\f(CW$DB\fR\->set_compare ( \s-1CODE\s0 )" 4 .IX Item "$DB->set_compare ( CODE )" Set a custom key comparison function referenced by \fI\s-1CODE\s0\fR for a database. .Sp \&\fI\s-1CODE\s0\fR should be a subroutine reference or an anonymous subroutine, that like Perl's \*(L"sort\*(R" in perlfunc, will receive the values to compare in the global variables \f(CW$a\fR and \f(CW$b\fR. .Sp The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified in \f(CW\*(C`LMDB_File\->open()\*(C'\fR, the keys are compared lexically, with shorter keys collating before longer keys. .Sp \&\fBWarning:\fR This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used. .ie n .IP "$flags = $DB\->flags" 4 .el .IP "\f(CW$flags\fR = \f(CW$DB\fR\->flags" 4 .IX Item "$flags = $DB->flags" Retrieve the \s-1DB\s0 flags for the associated database. .ie n .IP "$status = $DB\->stat" 4 .el .IP "\f(CW$status\fR = \f(CW$DB\fR\->stat" 4 .IX Item "$status = $DB->stat" Returns a \s-1HASH\s0 reference with statistics for the associated database, the hash will contain the following keys: .RS 4 .IP "\fBpsize\fR Size of a database page." 4 .IX Item "psize Size of a database page." .PD 0 .IP "\fBdepth\fR Depth (height) of the B\-Tree" 4 .IX Item "depth Depth (height) of the B-Tree" .IP "\fBbranch_pages\fR Number of internal (non-leaf) pages" 4 .IX Item "branch_pages Number of internal (non-leaf) pages" .IP "\fBoverflow_pages\fR Number of overflow pages" 4 .IX Item "overflow_pages Number of overflow pages" .IP "\fBentries\fR Number of data items" 4 .IX Item "entries Number of data items" .RE .RS 4 .RE .ie n .IP "$DB\->drop( [ \s-1REMOVE\s0 ] )" 4 .el .IP "\f(CW$DB\fR\->drop( [ \s-1REMOVE\s0 ] )" 4 .IX Item "$DB->drop( [ REMOVE ] )" .PD If \fI\s-1REMOVE\s0\fR isn't provided or \s-1FALSE,\s0 the database is emptied. If \fI\s-1REMOVE\s0\fR is \s-1TRUE\s0 the database is closed and removed from the Environment. .ie n .IP "$DB\->Alive" 4 .el .IP "\f(CW$DB\fR\->Alive" 4 .IX Item "$DB->Alive" Returns a \s-1TRUE\s0 value if the associated transaction is still alive, i.e. not commited nor aborted yet, and \s-1FALSE\s0 otherwise. .ie n .IP "$Cursor = $DB\->Cursor" 4 .el .IP "\f(CW$Cursor\fR = \f(CW$DB\fR\->Cursor" 4 .IX Item "$Cursor = $DB->Cursor" Creates a new LMDB::Cursor object to work in the database, see \*(L"LMDB::Cursor\*(R" .ie n .IP "$txn = $DB\->Txn" 4 .el .IP "\f(CW$txn\fR = \f(CW$DB\fR\->Txn" 4 .IX Item "$txn = $DB->Txn" Returns the transaction, an \*(L"LMDB::Txn\*(R" object, associated with \fI\f(CI$DB\fI\fR. .Sp .Vb 1 \& $DB\->Txn\->commit; # Commit the current transaction. .Ve .Sp If the method \f(CW\*(C`$DB\->Alive\*(C'\fR has returned \s-1FALSE\s0 before, this method will return \&\f(CW\*(C`undef\*(C'\fR. .Sp You can use \f(CW\*(C`$DB\->Txn\*(C'\fR as an lvalue to change the associated Transaction, but remember that, if \f(CW$DB\fR is holding the last reference of the current transaction, that transaction will be terminated. .Sp .Vb 5 \& $DB\->Txn\->commit; # Commit current \& $DB\->Alive; # FALSE \& ... \& $DB\->Txn = $Env\->BeginTxn; # Start another, with same Database \& ... .Ve .ie n .IP "$dbi = $DB\->dbi" 4 .el .IP "\f(CW$dbi\fR = \f(CW$DB\fR\->dbi" 4 .IX Item "$dbi = $DB->dbi" Returns the low level Database handler associated with \fI\f(CI$DB\fI\fR .Sp You can use \f(CW\*(C`$DB\->dbi\*(C'\fR as an lvalue to switch the associated Datbase hander: .Sp .Vb 1 \& $DB\->dbi = $other_dbi; .Ve .ie n .IP "$DB\->ReadMode ( [ \s-1MODE\s0 ] )" 4 .el .IP "\f(CW$DB\fR\->ReadMode ( [ \s-1MODE\s0 ] )" 4 .IX Item "$DB->ReadMode ( [ MODE ] )" This method allows you to modify the behavior of \*(L"get\*(R" (read) operations on the database. .Sp The C documentation for the \f(CW\*(C`mdb_get\*(C'\fR function states that: .Sp .Vb 4 \& The memory pointed to by the returned values is owned by the \& database. The caller need not dispose of the memory, and may not \& modify it in any way. For values returned in a read\-only transaction \& any modification attempts will cause a SIGSEGV. .Ve .Sp So this module implements two modes of operation for its \*(L"get\*(R" methods and you can select between them with this method. .Sp When \s-1MODE\s0 is 0 (or any \s-1FALSE\s0 value) a default \*(L"safe\*(R" mode is used in which the data value found in the database is copied to the scalar returned, so you can do anything you want to that scalar without side effects. .Sp But when \s-1MODE\s0 is 1 (or, in the current implementation, any \s-1TRUE\s0 value) a sort of hack is used to avoid the memory copy and a magical scalar returned that hold only a pointer to the data value found. This is much faster and uses less memory, especially when used with large values. .Sp In a environment opened with \s-1MDB_WRITEMAP\s0 and in a transaction without the \s-1MDB_RDONLY\s0 flag, you are allowed to modify the returned scalar, and the modifications are reflected to the associated memory block and preserved in the database when the transaction is commited. Otherwise the magical scalar is marked READ-ONLY and any attempt to modify it (other than reuse it in another \f(CW\*(C`$DB\->get\*(C'\fR ), will cause perl to croak. .Sp \&\fB\s-1CAVEATS:\s0\fR In a read-only transaction the value is valid only until the end of the transaction, and in a read-write transaction the value is valid only until the next write operation (because any write operation can potentially modify the in-memory btree). In the current implementation, you are responsible for the proper timing of usage. .Sp \&\fB\s-1NOTE:\s0\fR In order to achieve the zero-copy behavior desired by setting ReadMode to \s-1TRUE,\s0 you must use the two-argument form of get (\f(CW\*(C`$DB\->get ( $key, $data )\*(C'\fR), use the new \f(CW\*(C`$DB\->Rget( $key )\*(C'\fR or use the cursor get method described below. .ie n .IP "$DB\->\s-1UTF8\s0 ( [ \s-1MODE\s0 ] )" 4 .el .IP "\f(CW$DB\fR\->\s-1UTF8\s0 ( [ \s-1MODE\s0 ] )" 4 .IX Item "$DB->UTF8 ( [ MODE ] )" Instructs LDMB_File to use the \s-1UTF\-8\s0 encoding for the associated database when \fI\s-1MODE\s0\fR is 1 or revert to raw bytes when 0. .Sp Returns the previous value. .Sp By default, all values in \s-1LMDB\s0 are simple byte buffers of certain fixed length. .Sp So if you are storing binary data in your database all works as expected: what you put is what you get. .Sp But when you need to store some arbitrary Unicode text value, remember that internally perl stores your strings in either the native eight-bit character set or in \s-1UTF\-8,\s0 and to warrant a consistent encoding in your database you should do something like: .Sp .Vb 2 \& use Encoding; \& ... \& \& $DB\->put($key, Encode::encode($my_encoding, $characters)); \& \& $characters = Encode::decode($my_encoding, $DB\->get($key)); .Ve .Sp For any value of \f(CW$my_encoding\fR, see Encode for the gory details. .Sp But if you use for interchange the \s-1UTF\-8\s0 encoding, with this method you can avoid all that typing. .Sp When \fI\s-1MODE\s0\fR is 1, all values that you put in the Database will be encoded in \s-1UTF\-8,\s0 And all get calls will expect \s-1UTF\-8\s0 data and it will be verified and decoded. In this mode, if malformed data is found, a warning will be emitted, the decode attempt aborted and the raw bytes returned. .Sp In this mode, a \f(CW\*(C`$foo\->get(...)\*(C'\fR call interacts with the bytes pragma in a special way: In the lexical scope under the effects of \f(CW\*(C`use bytes\*(C'\fR, any get call skips the decode step, returning the fetched encoded \s-1UTF\-8\s0 data as bytes, i.e. with the internal perl \s-1UTF8\s0 flag off, as expected by modules like \s-1JSON::XS.\s0 .SH "LMDB::Cursor" .IX Header "LMDB::Cursor" To construct a cursor you should call the \f(CW\*(C`Cursor\*(C'\fR method of the \f(CW\*(C`LMDB_File\*(C'\fR class: .PP .Vb 1 \& $cursor = $DB\->Cursor .Ve .SS "Class methods" .IX Subsection "Class methods" .ie n .IP "$cursor\->get($key, $data, \s-1CURSOR_OP\s0)" 4 .el .IP "\f(CW$cursor\fR\->get($key, \f(CW$data\fR, \s-1CURSOR_OP\s0)" 4 .IX Item "$cursor->get($key, $data, CURSOR_OP)" This function retrieves key/data pairs from the database. .Sp The variables \fI\f(CI$key\fI\fR and \fI\f(CI$data\fI\fR are used to return the values found. .Sp \&\fB\s-1CURSOR_OP\s0\fR determines the key/data to be retrieved and must be one of the following: .RS 4 .IP "\s-1MDB_FIRST\s0" 4 .IX Item "MDB_FIRST" Position at first key/data item. .IP "\s-1MDB_FIRST_DUP\s0" 4 .IX Item "MDB_FIRST_DUP" Position at first data item of current key. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_GET_BOTH\s0" 4 .IX Item "MDB_GET_BOTH" Position at key/data pair. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_GET_BOTH_RANGE\s0" 4 .IX Item "MDB_GET_BOTH_RANGE" Position at key, nearest data. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_GET_CURRENT\s0" 4 .IX Item "MDB_GET_CURRENT" Return key/data at current cursor position. .IP "\s-1MDB_GET_MULTIPLE\s0" 4 .IX Item "MDB_GET_MULTIPLE" Return all the duplicate data items at the current cursor position. Only for \f(CW\*(C`MDB_DUPFIXED\*(C'\fR .IP "\s-1MDB_LAST\s0" 4 .IX Item "MDB_LAST" Position at last key/data item. .IP "\s-1MDB_LAST_DUP\s0" 4 .IX Item "MDB_LAST_DUP" Position at last data item of current key. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_NEXT\s0" 4 .IX Item "MDB_NEXT" Position at next data item. .IP "\s-1MDB_NEXT_DUP\s0" 4 .IX Item "MDB_NEXT_DUP" Position at next data item of current key. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_NEXT_MULTIPLE\s0" 4 .IX Item "MDB_NEXT_MULTIPLE" Return all duplicate data items at the next cursor position. Only for \f(CW\*(C`MDB_DUPFIXED\*(C'\fR .IP "\s-1MDB_NEXT_NODUP\s0" 4 .IX Item "MDB_NEXT_NODUP" Position at first data item of next key. .IP "\s-1MDB_PREV\s0" 4 .IX Item "MDB_PREV" Position at previous data item. .IP "\s-1MDB_PREV_DUP\s0" 4 .IX Item "MDB_PREV_DUP" Position at previous data item of current key. Only for \f(CW\*(C`MDB_DUPSORT\*(C'\fR .IP "\s-1MDB_PREV_NODUP\s0" 4 .IX Item "MDB_PREV_NODUP" Position at last data item of previous key. .IP "\s-1MDB_SET\s0" 4 .IX Item "MDB_SET" Position at specified key. .IP "\s-1MDB_SET_KEY\s0" 4 .IX Item "MDB_SET_KEY" Position at specified key, return key + data. .IP "\s-1MDB_SET_RANGE\s0" 4 .IX Item "MDB_SET_RANGE" Position at first key greater than or equal to specified key. .RE .RS 4 .RE .ie n .IP "$cursor\->put($key, $data, \s-1WRITEFLAGS\s0)" 4 .el .IP "\f(CW$cursor\fR\->put($key, \f(CW$data\fR, \s-1WRITEFLAGS\s0)" 4 .IX Item "$cursor->put($key, $data, WRITEFLAGS)" This function stores key/data pairs into the database. .Sp If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item. .Sp If the function fails for any reason, the state of the cursor will undetermined. .Sp \&\fB\s-1NOTE:\s0\fR Earlier documentation incorrectly said errors would leave the state of the cursor unchanged. .ie n .IP "$cursor\->del( [ \s-1DELFLAGS\s0 ] )" 4 .el .IP "\f(CW$cursor\fR\->del( [ \s-1DELFLAGS\s0 ] )" 4 .IX Item "$cursor->del( [ DELFLAGS ] )" This function deletes the key/data pair to which the cursor refers. .Sp If the database was opened with \f(CW\*(C`MDB_DUPSORT\*(C'\fR, the optional parameter \fI\s-1DELFLAGS\s0\fR can be \f(CW\*(C`MDB_NODUPDATA\*(C'\fR to deletes all of the data items for the current key. .SH "Exportable constants" .IX Header "Exportable constants" At \f(CW\*(C`use\*(C'\fR time you can import into your namespace the following constants, grouped by their tags. .ie n .SS "Environment flags "":envflags""" .el .SS "Environment flags \f(CW:envflags\fP" .IX Subsection "Environment flags :envflags" .Vb 2 \& MDB_FIXEDMAP MDB_NOSUBDIR MDB_NOSYNC MDB_RDONLY MDB_NOMETASYNC \& MDB_WRITEMAP MDB_MAPASYNC MDB_NOTLS .Ve .ie n .SS "Data base flags "":dbflags""" .el .SS "Data base flags \f(CW:dbflags\fP" .IX Subsection "Data base flags :dbflags" .Vb 2 \& MDB_REVERSEKEY MDB_DUPSORT MDB_INTEGERKEY MDB_DUPFIXED \& MDB_INTEGERDUP MDB_REVERSEDUP MDB_CREATE .Ve .ie n .SS "Write flags "":writeflags""" .el .SS "Write flags \f(CW:writeflags\fP" .IX Subsection "Write flags :writeflags" .Vb 2 \& MDB_NOOVERWRITE MDB_NODUPDATA MDB_CURRENT MDB_RESERVE \& MDB_APPEND MDB_APPENDDUP MDB_MULTIPLE .Ve .ie n .SS "All flags "":flags""" .el .SS "All flags \f(CW:flags\fP" .IX Subsection "All flags :flags" All of \f(CW\*(C`:envflags\*(C'\fR, \f(CW\*(C`:dbflags\*(C'\fR and \f(CW\*(C`:writeflags\*(C'\fR .ie n .SS "Cursor operations "":cursor_op""" .el .SS "Cursor operations \f(CW:cursor_op\fP" .IX Subsection "Cursor operations :cursor_op" .Vb 4 \& MDB_FIRST MDB_FIRST_DUP MDB_GET_BOTH MDB_GET_BOTH_RANGE \& MDB_GET_CURRENT MDB_GET_MULTIPLE MDB_NEXT MDB_NEXT_DUP MDB_NEXT_MULTIPLE \& MDB_NEXT_NODUP MDB_PREV MDB_PREV_DUP MDB_PREV_NODUP MDB_LAST MDB_LAST_DUP \& MDB_SET MDB_SET_KEY MDB_SET_RANGE .Ve .ie n .SS "Error codes "":error""" .el .SS "Error codes \f(CW:error\fP" .IX Subsection "Error codes :error" .Vb 4 \& MDB_SUCCESS MDB_KEYEXIST MDB_NOTFOUND MDB_PAGE_NOTFOUND MDB_CORRUPTED \& MDB_PANIC MDB_VERSION_MISMATCH MDB_INVALID MDB_MAP_FULL MDB_DBS_FULL \& MDB_READERS_FULL MDB_TLS_FULL MDB_TXN_FULL MDB_CURSOR_FULL MDB_PAGE_FULL \& MDB_MAP_RESIZED MDB_INCOMPATIBLE MDB_BAD_RSLOT MDB_LAST_ERRCODE .Ve .ie n .SS "Version information "":version""" .el .SS "Version information \f(CW:version\fP" .IX Subsection "Version information :version" .Vb 2 \& MDB_VERSION_FULL MDB_VERSION_MAJOR MDB_VERSION_MINOR \& MDB_VERSION_PATCH MDB_VERSION_STRING MDB_VERSION_DATE .Ve .SH "TIE Interface" .IX Header "TIE Interface" The simplest interface to \s-1LMDB\s0 is using \*(L"tie\*(R" in perlfunc. .PP The \s-1TIE\s0 interface of LMDB_File can take several forms that depend on the data at hand. .ie n .IP "tie %hash, 'LMDB_File', $path [, $options ]" 4 .el .IP "tie \f(CW%hash\fR, 'LMDB_File', \f(CW$path\fR [, \f(CW$options\fR ]" 4 .IX Item "tie %hash, 'LMDB_File', $path [, $options ]" The most simple form. .ie n .IP "tie %hash, 'LMDB_File', $path, $flags, $mode" 4 .el .IP "tie \f(CW%hash\fR, 'LMDB_File', \f(CW$path\fR, \f(CW$flags\fR, \f(CW$mode\fR" 4 .IX Item "tie %hash, 'LMDB_File', $path, $flags, $mode" For compatibility with other \s-1DBM\s0 modules. .ie n .IP "tie %hash, 'LMDB_File', $Txn [, \s-1DBOPTIONS\s0 ]" 4 .el .IP "tie \f(CW%hash\fR, 'LMDB_File', \f(CW$Txn\fR [, \s-1DBOPTIONS\s0 ]" 4 .IX Item "tie %hash, 'LMDB_File', $Txn [, DBOPTIONS ]" When you have a Transaction object \fI\f(CI$Txn\fI\fR at hand. .ie n .IP "tie %hash, 'LMDB_File', $Env [, \s-1DBOPTIONS\s0 ]" 4 .el .IP "tie \f(CW%hash\fR, 'LMDB_File', \f(CW$Env\fR [, \s-1DBOPTIONS\s0 ]" 4 .IX Item "tie %hash, 'LMDB_File', $Env [, DBOPTIONS ]" When you have an Environment object \fI\f(CI$Env\fI\fR at hand. .ie n .IP "tie %hash, $DB" 4 .el .IP "tie \f(CW%hash\fR, \f(CW$DB\fR" 4 .IX Item "tie %hash, $DB" When you have an opened Transaction encapsulated database. .PP The first two forms will create and/or open the Environment at \fI\f(CI$path\fI\fR, create a new Transaction and open a Database in the Transaction. .PP If provided, \fI\f(CI$options\fI\fR must be a \s-1HASH\s0 reference with options for both the Environment and the database. .PP Valid keys for \fI\f(CI$option\fI\fR are any described above for \fB\s-1ENVOPTIONS\s0\fR and \fB\s-1DBOPTIONS\s0\fR. .PP In the case that you have already created a transaction or an environment, you can provide a \s-1HASH\s0 reference in \fB\s-1DBOPTIONS\s0\fR for options exclusively for the database. .PP In the forms that needs to create a Transaction, this is setted for \&\fBAutocommit\fR mode. .SH "AUTHOR" .IX Header "AUTHOR" Salvador Ortiz Garcia, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .Vb 2 \& Copyright (C) 2013\-2014 by Salvador Ortiz García \& Copyright (C) 2013\-2014 by Matías Software Group, S.A. de C.V. .Ve .PP This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0, see \s-1LICENSE\s0.