1LMDB(3am) GNU Awk Extension Modules LMDB(3am)
2
6 lmdb - implement the OpenLDAP LMDB (Lightning Memory-Mapped Database) C
7 API available at http://lmdb.tech
8
10 @load "lmdb"
11 Global Variables:
13 MDB_SUCCESS: 0, as defined in <lmdb.h>
14 MDB_ERRNO: return status from the last mdb function call.
15 MDB_KEY, MDB_DATA: subscripts for use with mdb_cursor_get
16 MDB: an array defining all the MDB_* constants in <lmdb.h> with the
17 "MDB_" prefix removed. For example, MDB["FIRST"] contains the value of
18 MDB_FIRST. The various flags arguments can be constructed by using the
19 gawk "or" function to combine flag bits defined in this array.
20 handle = mdb_env_create()
22 Almost all of the mdb_* functions in <lmdb.h> are implemented, as of
24 version 0.9.18.
25 To achieve optimal performance, please use cursors whenever possible.
27 Under the hood, the mdb library always uses cursors.
28
31 The lmdb extension implements the mdb C API. Please refer to the
32 <lmdb.h> header file for documentation, or view it on the web at
33 http://www.lmdb.tech/doc. This document will explain only the pecu‐
34 liarities of the gawk implementation. Aside from the mdb_strerror()
35 function, every function in this library should set the MDB_ERRNO vari‐
36 able before returning. So you can always check whether (MDB_ERRNO =
37 MDB_SUCCESS) to see if the last call succeeded. The library will also
38 set the standard gawk ERRNO variable if an error occurs.
39 string mdb_strerror(<int errno>)
42 This function takes an integer argument and returns the result
43 from calling the mdb_strerror() library function. The gawk
44 library defines an additional extension-specific error code that
45 is also supported by this function. If the argument is not an
46 integer, it will return an empty string.
47 string mdb_env_create()
50 Call mdb_env_create() and return a string handle to use for ref‐
51 erencing this environment. On error, an empty string is
52 returned, and MDB_ERRNO will contain the return code from
53 mdb_env_create()
54 int mdb_env_open(<env handle>, <path>, <u_int flags>, <u_int mode>)
57 Returns the status, which can also be found in MDB_ERRNO. You
58 can use the gawk "or" function to construct the flags. For exam‐
59 ple, the 3rd argument might be or(MDB["NOSUBDIR"],
60 MDB["NOSYNC"], MDB["NOLOCK"]).
61 int mdb_env_close(<env handle>)
64 Call mdb_env_close() and return status, which can also be found
65 in MDB_ERRNO Although the C function has no return value, this
66 function can return an error if the handle argument is invalid.
67 If the result is MDB_SUCCESS, the handle is released and may no
68 longer be used.
69 int mdb_env_sync(<env handle>, <int force>)
72 Returns the status, which can also be found in MDB_ERRNO
73 int mdb_env_copy(<env handle>, <path string>)
76 Returns the status, which can also be found in MDB_ERRNO
77 int mdb_env_copy2(<env handle>, <path string>, <u_int flags>)
80 Returns the status, which can also be found in MDB_ERRNO
81 int mdb_env_get_flags(<env handle>)
84 On error, returns 0, else the flags value. Please compare
85 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
86 int mdb_env_get_maxkeysize(<env handle>)
89 On error, returns 0, else the maxkeysize value. Please compare
90 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
91 int mdb_env_get_maxreaders(<env handle>)
94 On error, returns 0, else the maxreaders value. Please compare
95 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
96 string mdb_env_get_path(<env handle>)
99 On error, returns "", else the path value. Please compare
100 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
101 int mdb_env_set_flags(<env handle>, <u_int flags>, <int onoff>)
104 Returns the status, which can also be found in MDB_ERRNO
105 int mdb_env_set_mapsize(<env handle>, <u_int mapsize>)
108 Returns the status, which can also be found in MDB_ERRNO
109 int mdb_env_set_maxdbs(<env handle>, <u_int dbs>)
112 Returns the status, which can also be found in MDB_ERRNO
113 int mdb_env_set_maxreaders(<env handle>, <u_int readers>)
116 Returns the status, which can also be found in MDB_ERRNO
117 string mdb_txn_begin(<env handle>, <parent txn handle or empty string>,
120 <u_int flags>)
121 Call mdb_txn_begin() and return a string handle to use for ref‐
122 erencing this transaction. On error, an empty string is
123 returned, and MDB_ERRNO will contain an error code.
124 int mdb_txn_id(<txn handle>)
127 On error, returns 0, else the txn id. Please compare MDB_ERRNO
128 to MDB_SUCCESS to see whether the call succeeded.
129 int mdb_txn_commit(<txn handle>)
132 Returns the status, which can also be found in MDB_ERRNO. If
133 the result is MDB_SUCCESS, the handle is released and may no
134 longer be used.
135 int mdb_txn_abort(<txn handle>)
138 Returns the status, which can also be found in MDB_ERRNO. If
139 the result is MDB_SUCCESS, the handle is released and may no
140 longer be used.
141 int mdb_txn_reset(<txn handle>)
144 Returns the status, which can also be found in MDB_ERRNO
145 int mdb_txn_renew(<txn handle>)
148 Returns the status, which can also be found in MDB_ERRNO
149 string mdb_dbi_open(<txn handle>, <database name or empty string>,
152 <u_int flags>)
153 Call mdb_dbi_open() and return a string handle to use for refer‐
154 encing this transaction. On error, an empty string is returned,
155 and MDB_ERRNO will contain an error code.
156 int mdb_dbi_close(<env handle>, <dbi handle>)
159 Returns the status, which can also be found in MDB_ERRNO. If
160 the result is MDB_SUCCESS, the handle is released and may no
161 longer be used.
162 int mdb_dbi_flags(<txn handle>, <dbi handle>)
165 On error, returns 0, else the flags value. Please compare
166 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
167 int mdb_drop(<txn handle>, <dbi handle>, <del: 0 or 1>)
170 Returns the status, which can also be found in MDB_ERRNO. If
171 the call succeeds and <del> is 1, the dbi handle is released and
172 may no longer be used.
173 string mdb_get(<txn handle>, <dbi handle>, <key>)
176 On error, returns "", else the data string returned by the func‐
177 tion. You must check MDB_ERRNO to see whether the call suc‐
178 ceeded, since an empty string could be a valid data value.
179 Please note that starting with version 2 of the API available in
181 gawk 4.2, the result will be flagged as user input data eligible
182 for the strnum attribute. So if the value appears to be numeric,
183 gawk will treat it as a number in comparisons. This feature was
184 not available prior to version 2 of the gawk API.
185 int mdb_put(<txn handle>, <dbi handle>, <key>, <data>, <u_int flags>)
188 Returns the status, which can also be found in MDB_ERRNO.
189 int mdb_del(<txn handle>, <dbi handle>, <key>[, <data>])
192 Returns the status, which can also be found in MDB_ERRNO. If
193 the 4th argument is not present, a NULL pointer is passed as the
194 4th argument to the underlying function. Please be careful:
195 passing an empty "" string as the 4th argument is not the same
196 as omitting the 4th argument!
197 string mdb_cursor_open(<txn handle>, <dbi handle>)
200 Call mdb_cursor_open() and return a string handle to use for
201 referencing this transaction. On error, an empty string is
202 returned, and MDB_ERRNO will contain an error code.
203 int mdb_cursor_close(<cursor handle>)
206 Returns the status, which can also be found in MDB_ERRNO.
207 int mdb_cursor_renew(<cursor handle>)
210 Returns the status, which can also be found in MDB_ERRNO.
211 int mdb_cursor_get(<cursor handle>, <key/data array>, <u_int cursor
214 op>)
215 Returns the status, which can also be found in MDB_ERRNO. The
216 2nd argument is an array. If the MDB_KEY element is populated,
217 its value is passed as the 2nd argument to the underlying func‐
218 tion. In its absence, an empty "" string is passed. Similarly,
219 the contents of the MDB_DATA element are used to construct the
220 3rd argument to the underlying function. On exit, if the func‐
221 tion call succeeds, these same array elements will be populated
222 with the data returned.
223 Please note that starting with version 2 of the API available in
225 gawk 4.2, the returned array elements will be flagged as user
226 input data eligible for the strnum attribute. So if the key or
227 data appears to be numeric, gawk will treat it as a number in
228 comparisons. This feature was not available prior to version 2
229 of the gawk API.
230 int mdb_cursor_put(<cursor handle>, <key>, <data>, <u_int flags>)
233 Returns the status, which can also be found in MDB_ERRNO.
234 int mdb_cursor_del(<cursor handle>, <u_int flags>)
237 Returns the status, which can also be found in MDB_ERRNO.
238 int mdb_cursor_count(<cursor handle>)
241 On error, returns 0, else the function result. Please compare
242 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
243 int mdb_reader_check(<env handle>)
246 On error, returns 0, else the dead value from the function.
247 Please compare MDB_ERRNO to MDB_SUCCESS to see whether the call
248 succeeded.
249 int mdb_cmp(<txn handle>, <dbi handle>, <string a>, <string b>)
252 On error, returns 0, else the result of the underlying function.
253 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
254 int mdb_dcmp(<txn handle>, <dbi handle>, <string a>, <string b>)
257 On error, returns 0, else the result of the underlying function.
258 MDB_ERRNO to MDB_SUCCESS to see whether the call succeeded.
259 int mdb_env_stat(<env handle>, <array>)
262 Returns the status, which can also be found in MDB_ERRNO. If
263 the call succeeds, the array is cleared and populated with the
264 elements of the MDB_stat structure stripped of the "ms_" prefix.
265 int mdb_stat(<txn handle>, <dbi handle>, <array>)
268 Returns the status, which can also be found in MDB_ERRNO. If
269 the call succeeds, the array is cleared and populated with the
270 elements of the MDB_stat structure stripped of the "ms_" prefix.
271 int mdb_env_info(<env handle>, <array>)
274 Returns the status, which can also be found in MDB_ERRNO. If
275 the call succeeds, the array is cleared and populated with the
276 elements of the MDB_envinfo structure stripped of the "me_" pre‐
277 fix.
278 string mdb_txn_env(<txn handle>)
281 On error, an empty "" string is returned, else the env handle
282 associated with this txn.
283 string mdb_cursor_txn(<cursor handle>)
286 On error, an empty "" string is returned, else the txn handle
287 associated with this cursor.
288 string mdb_cursor_dbi(<cursor handle>)
291 On error, an empty "" string is returned, else the dbi handle
292 associated with this cursor.
293 string mdb_version([<version array>])
296 Call mdb_version() and return the version string. If the
297 optional array argument is supplied, it will be cleared, and the
298 major, minor, and patch subscripts will be populated with the
299 associated version numbers.
300 Not implemented: mdb_env_copyfd, mdb_env_copyfd2, mdb_env_get_fd,
303 mdb_env_get_userctx, mdb_env_set_assert, mdb_env_set_userctx,
304 mdb_reader_list, mdb_set_compare, mdb_set_dupsort, mdb_set_relctx,
305 mdb_set_relfunc.
306 Of these, mdb_set_compare and mdb_set_dupsort seem most impor‐
307 tant. To implement these, we need a way for the extension to
308 call into a gawk function. I do not think that is currently
309 possible.
310
313 Please refer to dict.awk and dict_cursor.awk located in the test direc‐
314 tory.
315
317 /usr/include/lmdb.h, http://www.lmdb.tech/doc
318
320 Andrew Schorr
321
323 Copyright © 2016, Free Software Foundation, Inc.
324 Permission is granted to make and distribute verbatim copies of this
326 manual page provided the copyright notice and this permission notice
327 are preserved on all copies.
328 Permission is granted to copy and distribute modified versions of this
330 manual page under the conditions for verbatim copying, provided that
331 the entire resulting derived work is distributed under the terms of a
332 permission notice identical to this one.
333 Permission is granted to copy and distribute translations of this man‐
335 ual page into another language, under the above conditions for modified
336 versions, except that this permission notice may be stated in a trans‐
337 lation approved by the Foundation.
338Free Software Foundation May 02 2016 LMDB(3am)