/usr/share/doc/lmdb-doc/html/index.html is in lmdb-doc 0.9.17-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>LMDB: Lightning Memory-Mapped Database Manager (LMDB)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">LMDB
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Lightning Memory-Mapped Database Manager (LMDB) </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro_sec"></a>
Introduction</h1>
<p>LMDB is a Btree-based database management library modeled loosely on the BerkeleyDB API, but much simplified. The entire database is exposed in a memory map, and all data fetches return data directly from the mapped memory, so no malloc's or memcpy's occur during data fetches. As such, the library is extremely simple because it requires no page caching layer of its own, and it is extremely high performance and memory-efficient. It is also fully transactional with full ACID semantics, and when the memory map is read-only, the database integrity cannot be corrupted by stray pointer writes from application code.</p>
<p>The library is fully thread-aware and supports concurrent read/write access from multiple processes and threads. Data pages use a copy-on- write strategy so no active data pages are ever overwritten, which also provides resistance to corruption and eliminates the need of any special recovery procedures after a system crash. Writes are fully serialized; only one write transaction may be active at a time, which guarantees that writers can never deadlock. The database structure is multi-versioned so readers run with no locks; writers cannot block readers, and readers don't block writers.</p>
<p>Unlike other well-known database mechanisms which use either write-ahead transaction logs or append-only data writes, LMDB requires no maintenance during operation. Both write-ahead loggers and append-only databases require periodic checkpointing and/or compaction of their log or database files otherwise they grow without bound. LMDB tracks free pages within the database and re-uses them for new write operations, so the database size does not grow without bound in normal use.</p>
<p>The memory map can be used as a read-only or read-write map. It is read-only by default as this provides total immunity to corruption. Using read-write mode offers much higher write performance, but adds the possibility for stray application writes thru pointers to silently corrupt the database. Of course if your application code is known to be bug-free (...) then this is not an issue.</p>
<h1><a class="anchor" id="caveats_sec"></a>
Caveats</h1>
<p>Troubleshooting the lock file, plus semaphores on BSD systems:</p>
<ul>
<li><p class="startli">A broken lockfile can cause sync issues. Stale reader transactions left behind by an aborted program cause further writes to grow the database quickly, and stale locks can block further operation.</p>
<p class="startli">Fix: Check for stale readers periodically, using the <a class="el" href="group__mdb.html#ga366923d08bb384b3d9580a98edf5d668" title="Check for stale entries in the reader lock table. ">mdb_reader_check</a> function or the <a class="elRef" doxygen="/build/lmdb-hqxAxG/lmdb-0.9.17/libraries/liblmdb/tooltag:./man1/" href="./man1/mdb_stat.1.html">mdb_stat</a> tool. Stale writers will be cleared automatically on some systems:</p><ul>
<li>Windows - automatic</li>
<li>Linux, systems using POSIX mutexes with Robust option - automatic</li>
<li>not on BSD, systems using POSIX semaphores. Otherwise just make all programs using the database close it; the lockfile is always reset on first open of the environment.</li>
</ul>
</li>
<li><p class="startli">On BSD systems or others configured with MDB_USE_POSIX_SEM, startup can fail due to semaphores owned by another userid.</p>
<p class="startli">Fix: Open and close the database as the user which owns the semaphores (likely last user) or as root, while no other process is using the database.</p>
</li>
</ul>
<p>Restrictions/caveats (in addition to those listed for some functions):</p>
<ul>
<li>Only the database owner should normally use the database on BSD systems or when otherwise configured with MDB_USE_POSIX_SEM. Multiple users can cause startup to fail later, as noted above.</li>
<li>There is normally no pure read-only mode, since readers need write access to locks and lock file. Exceptions: On read-only filesystems or with the <a class="el" href="group__mdb__env.html#ga9b0450b1a87cb9f22e033550e49e5037">MDB_NOLOCK</a> flag described under <a class="el" href="group__mdb.html#ga32a193c6bf4d7d5c5d579e71f22e9340" title="Open an environment handle. ">mdb_env_open()</a>.</li>
<li>By default, in versions before 0.9.10, unused portions of the data file might receive garbage data from memory freed by other code. (This does not happen when using the <a class="el" href="group__mdb__env.html#ga7b81e9fd5f8fae38786d67e1a8387fa7">MDB_WRITEMAP</a> flag.) As of 0.9.10 the default behavior is to initialize such memory before writing to the data file. Since there may be a slight performance cost due to this initialization, applications may disable it using the <a class="el" href="group__mdb__env.html#gafa035a1f17ebf31376eafb7bd2cdd448">MDB_NOMEMINIT</a> flag. Applications handling sensitive data which must not be written should not use this flag. This flag is irrelevant when using <a class="el" href="group__mdb__env.html#ga7b81e9fd5f8fae38786d67e1a8387fa7">MDB_WRITEMAP</a>.</li>
<li>A thread can only use one transaction at a time, plus any child transactions. Each transaction belongs to one thread. See below. The <a class="el" href="group__mdb__env.html#ga5dca84a576d14b4bfe2deddc2dc622d3">MDB_NOTLS</a> flag changes this for read-only transactions.</li>
<li>Use an MDB_env* in the process which opened it, without fork()ing.</li>
<li>Do not have open an LMDB database twice in the same process at the same time. Not even from a plain open() call - close()ing it breaks flock() advisory locking.</li>
<li>Avoid long-lived transactions. Read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. Write transactions prevent other write transactions, since writes are serialized.</li>
<li>Avoid suspending a process with active transactions. These would then be "long-lived" as above. Also read transactions suspended when writers commit could sometimes see wrong data.</li>
</ul>
<p>...when several processes can use a database concurrently:</p>
<ul>
<li><p class="startli">Avoid aborting a process with an active transaction. The transaction becomes "long-lived" as above until a check for stale readers is performed or the lockfile is reset, since the process may not remove it from the lockfile.</p>
<p class="startli">This does not apply to write transactions if the system clears stale writers, see above.</p>
</li>
<li>If you do that anyway, do a periodic check for stale readers. Or close the environment once in a while, so the lockfile can get reset.</li>
<li>Do not use LMDB databases on remote filesystems, even between processes on the same host. This breaks flock() on some OSes, possibly memory map sync, and certainly sync between programs on different hosts.</li>
<li>Opening a database can fail if another process is opening or closing it at exactly the same time.</li>
</ul>
<dl class="section author"><dt>Author</dt><dd>Howard Chu, Symas Corporation.</dd></dl>
<dl class="section copyright"><dt>Copyright</dt><dd>Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved.</dd></dl>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted only as authorized by the OpenLDAP Public License.</p>
<p>A copy of this license is available in the file LICENSE in the top-level directory of the distribution or, alternatively, at <a href="http://www.OpenLDAP.org/license.html">http://www.OpenLDAP.org/license.html</a>.</p>
<dl class="section user"><dt>Derived From:</dt><dd>This code is derived from btree.c written by Martin Hedenfalk.</dd></dl>
<p>Copyright (c) 2009, 2010 Martin Hedenfalk <a href="#" onclick="location.href='mai'+'lto:'+'mar'+'ti'+'n@b'+'ze'+'ro.'+'se'; return false;">marti<span style="display: none;">.nosp@m.</span>n@bz<span style="display: none;">.nosp@m.</span>ero.s<span style="display: none;">.nosp@m.</span>e</a></p>
<p>Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.9.1
</small></address>
</body>
</html>
|