1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2014-06-03 01:29+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man3/btree.3:36
26 #: build/C/man3/btree.3:36 build/C/man3/hash.3:36 build/C/man3/recno.3:36
32 #: build/C/man3/btree.3:36 build/C/man3/dbopen.3:36 build/C/man3/hash.3:36 build/C/man3/mpool.3:36 build/C/man3/recno.3:36
34 msgid "Linux Programmer's Manual"
38 #: build/C/man3/btree.3:38 build/C/man3/dbopen.3:38 build/C/man3/hash.3:38 build/C/man3/mpool.3:38 build/C/man3/recno.3:38
44 #: build/C/man3/btree.3:40
45 msgid "btree - btree database access method"
49 #: build/C/man3/btree.3:40 build/C/man3/dbopen.3:40 build/C/man3/hash.3:40 build/C/man3/mpool.3:40 build/C/man3/recno.3:40
55 #: build/C/man3/btree.3:45 build/C/man3/hash.3:45 build/C/man3/recno.3:45
58 "B<#include E<lt>sys/types.hE<gt>\n"
59 "#include E<lt>db.hE<gt>>\n"
63 #: build/C/man3/btree.3:47 build/C/man3/dbopen.3:51 build/C/man3/hash.3:47 build/C/man3/mpool.3:62 build/C/man3/recno.3:47
69 #: build/C/man3/btree.3:54 build/C/man3/dbopen.3:58 build/C/man3/hash.3:54 build/C/man3/mpool.3:69 build/C/man3/recno.3:54
71 "I<Note well>: This page documents interfaces provided in glibc up until "
72 "version 2.1. Since version 2.2, glibc no longer provides these interfaces. "
73 "Probably, you are looking for the APIs provided by the I<libdb> library "
78 #: build/C/man3/btree.3:62
80 "The routine B<dbopen>(3) is the library interface to database files. One "
81 "of the supported file formats is btree files. The general description of "
82 "the database access methods is in B<dbopen>(3), this manual page describes "
83 "only the btree-specific information."
87 #: build/C/man3/btree.3:65
89 "The btree data structure is a sorted, balanced tree structure storing "
90 "associated key/data pairs."
94 #: build/C/man3/btree.3:71
96 "The btree access-method-specific data structure provided to B<dbopen>(3) is "
97 "defined in the I<E<lt>db.hE<gt>> include file as follows:"
101 #: build/C/man3/btree.3:84
105 " unsigned long flags;\n"
106 " unsigned int cachesize;\n"
109 " unsigned int psize;\n"
110 " int (*compare)(const DBT *key1, const DBT *key2);\n"
111 " size_t (*prefix)(const DBT *key1, const DBT *key2);\n"
117 #: build/C/man3/btree.3:88 build/C/man3/hash.3:85
118 msgid "The elements of this structure are as follows:"
122 #: build/C/man3/btree.3:88 build/C/man3/recno.3:93
128 #: build/C/man3/btree.3:91 build/C/man3/recno.3:97
129 msgid "The flag value is specified by ORing any of the following values:"
133 #: build/C/man3/btree.3:92
139 #: build/C/man3/btree.3:111
141 "Permit duplicate keys in the tree, that is, permit insertion if the key to "
142 "be inserted already exists in the tree. The default behavior, as described "
143 "in B<dbopen>(3), is to overwrite a matching key when inserting a new key or "
144 "to fail if the B<R_NOOVERWRITE> flag is specified. The B<R_DUP> flag is "
145 "overridden by the B<R_NOOVERWRITE> flag, and if the B<R_NOOVERWRITE> flag is "
146 "specified, attempts to insert duplicate keys into the tree will fail."
150 #: build/C/man3/btree.3:121
152 "If the database contains duplicate keys, the order of retrieval of key/data "
153 "pairs is undefined if the I<get> routine is used, however, I<seq> routine "
154 "calls with the B<R_CURSOR> flag set will always return the logical \"first\" "
155 "of any group of duplicate keys."
159 #: build/C/man3/btree.3:122 build/C/man3/hash.3:102 build/C/man3/recno.3:129
165 #: build/C/man3/btree.3:137
167 "A suggested maximum size (in bytes) of the memory cache. This value is "
168 "I<only> advisory, and the access method will allocate more memory rather "
169 "than fail. Since every search examines the root page of the tree, caching "
170 "the most recently used pages substantially improves access time. In "
171 "addition, physical writes are delayed as long as possible, so a moderate "
172 "cache can reduce the number of I/O operations significantly. Obviously, "
173 "using a cache increases (but only increases) the likelihood of corruption or "
174 "lost data if the system crashes while a tree is being modified. If "
175 "I<cachesize> is 0 (no size is specified), a default cache is used."
179 #: build/C/man3/btree.3:137
181 msgid "I<maxkeypage>"
184 #. The maximum number of keys which will be stored on any single page.
185 #. Because of the way the btree data structure works,
187 #. must always be greater than or equal to 2.
190 #. is 0 (no maximum number of keys is specified), the page fill factor is
191 #. made as large as possible (which is almost invariably what is wanted).
193 #: build/C/man3/btree.3:149
195 "The maximum number of keys which will be stored on any single page. Not "
196 "currently implemented."
200 #: build/C/man3/btree.3:149
202 msgid "I<minkeypage>"
206 #: build/C/man3/btree.3:159
208 "The minimum number of keys which will be stored on any single page. This "
209 "value is used to determine which keys will be stored on overflow pages, that "
210 "is, if a key or data item is longer than the pagesize divided by the "
211 "minkeypage value, it will be stored on overflow pages instead of in the page "
212 "itself. If I<minkeypage> is 0 (no minimum number of keys is specified), a "
213 "value of 2 is used."
217 #: build/C/man3/btree.3:159 build/C/man3/recno.3:138
223 #: build/C/man3/btree.3:167
225 "Page size is the size (in bytes) of the pages used for nodes in the tree. "
226 "The minimum page size is 512 bytes and the maximum page size is 64K. If "
227 "I<psize> is 0 (no page size is specified), a page size is chosen based on "
228 "the underlying filesystem I/O block size."
232 #: build/C/man3/btree.3:167
238 #: build/C/man3/btree.3:179
240 "Compare is the key comparison function. It must return an integer less "
241 "than, equal to, or greater than zero if the first key argument is considered "
242 "to be respectively less than, equal to, or greater than the second key "
243 "argument. The same comparison function must be used on a given tree every "
244 "time it is opened. If I<compare> is NULL (no comparison function is "
245 "specified), the keys are compared lexically, with shorter keys considered "
246 "less than longer keys."
250 #: build/C/man3/btree.3:179
256 #: build/C/man3/btree.3:198
258 "Prefix is the prefix comparison function. If specified, this routine must "
259 "return the number of bytes of the second key argument which are necessary to "
260 "determine that it is greater than the first key argument. If the keys are "
261 "equal, the key length should be returned. Note, the usefulness of this "
262 "routine is very data-dependent, but, in some data sets can produce "
263 "significantly reduced tree sizes and search times. If I<prefix> is NULL (no "
264 "prefix function is specified), I<and> no comparison function is specified, a "
265 "default lexical comparison routine is used. If I<prefix> is NULL and a "
266 "comparison routine is specified, no prefix comparison is done."
270 #: build/C/man3/btree.3:198 build/C/man3/hash.3:117 build/C/man3/recno.3:150
276 #: build/C/man3/btree.3:206 build/C/man3/recno.3:158
278 "The byte order for integers in the stored database metadata. The number "
279 "should represent the order as an integer; for example, big endian order "
280 "would be the number 4,321. If I<lorder> is 0 (no order is specified), the "
281 "current host order is used."
285 #: build/C/man3/btree.3:217
287 "If the file already exists (and the B<O_TRUNC> flag is not specified), the "
288 "values specified for the arguments I<flags>, I<lorder> and I<psize> are "
289 "ignored in favor of the values used when the tree was created."
293 #: build/C/man3/btree.3:219
294 msgid "Forward sequential scans of a tree are from the least key to the greatest."
298 #: build/C/man3/btree.3:225
300 "Space freed up by deleting key/data pairs from the tree is never reclaimed, "
301 "although it is normally made available for reuse. This means that the btree "
302 "storage structure is grow-only. The only solutions are to avoid excessive "
303 "deletions, or to create a fresh tree periodically from a scan of an existing "
308 #: build/C/man3/btree.3:231
310 "Searches, insertions, and deletions in a btree will all complete in O lg "
311 "base N where base is the average fill factor. Often, inserting ordered data "
312 "into btrees results in a low fill factor. This implementation has been "
313 "modified to make ordered insertion the best case, resulting in a much better "
314 "than normal page fill factor."
318 #: build/C/man3/btree.3:231 build/C/man3/dbopen.3:481 build/C/man3/hash.3:151 build/C/man3/mpool.3:185 build/C/man3/recno.3:210
324 #: build/C/man3/btree.3:238
326 "The I<btree> access method routines may fail and set I<errno> for any of the "
327 "errors specified for the library routine B<dbopen>(3)."
331 #: build/C/man3/btree.3:238 build/C/man3/dbopen.3:543 build/C/man3/hash.3:158 build/C/man3/recno.3:222
337 #: build/C/man3/btree.3:240 build/C/man3/recno.3:224
338 msgid "Only big and little endian byte order is supported."
342 #: build/C/man3/btree.3:240 build/C/man3/dbopen.3:554 build/C/man3/hash.3:160 build/C/man3/mpool.3:230 build/C/man3/recno.3:224
348 #: build/C/man3/btree.3:245
349 msgid "B<dbopen>(3), B<hash>(3), B<mpool>(3), B<recno>(3)"
353 #: build/C/man3/btree.3:248
355 "I<The Ubiquitous B-tree>, Douglas Comer, ACM Comput. Surv. 11, 2 (June "
360 #: build/C/man3/btree.3:252
362 "I<Prefix B-trees>, Bayer and Unterauer, ACM Transactions on Database "
363 "Systems, Vol. 2, 1 (March 1977), 11-26."
367 #: build/C/man3/btree.3:255
369 "I<The Art of Computer Programming Vol. 3: Sorting and Searching>, "
370 "D.E. Knuth, 1968, pp 471-480."
374 #: build/C/man3/btree.3:255 build/C/man3/dbopen.3:562 build/C/man3/hash.3:171 build/C/man3/mpool.3:235 build/C/man3/recno.3:233
380 #: build/C/man3/btree.3:263 build/C/man3/dbopen.3:570 build/C/man3/hash.3:179 build/C/man3/mpool.3:243 build/C/man3/recno.3:241
382 "This page is part of release 3.67 of the Linux I<man-pages> project. A "
383 "description of the project, information about reporting bugs, and the latest "
384 "version of this page, can be found at "
385 "\\%http://www.kernel.org/doc/man-pages/."
389 #: build/C/man3/dbopen.3:36
395 #: build/C/man3/dbopen.3:36
401 #: build/C/man3/dbopen.3:40
402 msgid "dbopen - database access methods"
406 #: build/C/man3/dbopen.3:46
409 "B<#include E<lt>sys/types.hE<gt>>\n"
410 "B<#include E<lt>limits.hE<gt>>\n"
411 "B<#include E<lt>db.hE<gt>>\n"
412 "B<#include E<lt>fcntl.hE<gt>>\n"
416 #: build/C/man3/dbopen.3:50
419 "B<DB *dbopen(const char *>I<file>B<, int >I<flags>B<, int >I<mode>B<, DBTYPE "
421 "B< const void *>I<openinfo>B<);>\n"
425 #: build/C/man3/dbopen.3:72
427 "B<dbopen>() is the library interface to database files. The supported file "
428 "formats are btree, hashed and UNIX file oriented. The btree format is a "
429 "representation of a sorted, balanced tree structure. The hashed format is "
430 "an extensible, dynamic hashing scheme. The flat-file format is a byte "
431 "stream file with fixed or variable length records. The formats and "
432 "file-format-specific information are described in detail in their respective "
433 "manual pages B<btree>(3), B<hash>(3) and B<recno>(3)."
437 #: build/C/man3/dbopen.3:81
439 "B<dbopen>() opens I<file> for reading and/or writing. Files never intended "
440 "to be preserved on disk may be created by setting the I<file> argument to "
444 #. Three additional options may be specified by ORing
450 #. Do the necessary locking in the database to support concurrent access.
451 #. If concurrent access isn't needed or the database is read-only this
452 #. flag should not be set, as it tends to have an associated performance
456 #. Place the underlying memory pool used by the database in shared
458 #. Necessary for concurrent access.
461 #. Support transactions in the database.
462 #. The DB_LOCK and DB_SHMEM flags must be set as well.
464 #: build/C/man3/dbopen.3:121
466 "The I<flags> and I<mode> arguments are as specified to the B<open>(2) "
467 "routine, however, only the B<O_CREAT>, B<O_EXCL>, B<O_EXLOCK>, "
468 "B<O_NONBLOCK>, B<O_RDONLY>, B<O_RDWR>, B<O_SHLOCK>, and B<O_TRUNC> flags are "
469 "meaningful. (Note, opening a database file B<O_WRONLY> is not possible.)"
473 #: build/C/man3/dbopen.3:134
475 "The I<type> argument is of type I<DBTYPE> (as defined in the "
476 "I<E<lt>db.hE<gt>> include file) and may be set to B<DB_BTREE>, B<DB_HASH>, "
481 #: build/C/man3/dbopen.3:143
483 "The I<openinfo> argument is a pointer to an access-method-specific structure "
484 "described in the access method's manual page. If I<openinfo> is NULL, each "
485 "access method will use defaults appropriate for the system and the access "
490 #: build/C/man3/dbopen.3:154
492 "B<dbopen>() returns a pointer to a I<DB> structure on success and NULL on "
493 "error. The I<DB> structure is defined in the I<E<lt>db.hE<gt>> include "
494 "file, and contains at least the following fields:"
498 #: build/C/man3/dbopen.3:170
503 " int (*close)(const DB *db);\n"
504 " int (*del)(const DB *db, const DBT *key, unsigned int flags);\n"
505 " int (*fd)(const DB *db);\n"
506 " int (*get)(const DB *db, DBT *key, DBT *data,\n"
507 " unsigned int flags);\n"
508 " int (*put)(const DB *db, DBT *key, const DBT *data,\n"
509 " unsigned int flags);\n"
510 " int (*sync)(const DB *db, unsigned int flags);\n"
511 " int (*seq)(const DB *db, DBT *key, DBT *data,\n"
512 " unsigned int flags);\n"
517 #: build/C/man3/dbopen.3:178
519 "These elements describe a database type and a set of functions performing "
520 "various actions. These functions take a pointer to a structure as returned "
521 "by B<dbopen>(), and sometimes one or more pointers to key/data structures "
526 #: build/C/man3/dbopen.3:178
532 #: build/C/man3/dbopen.3:181
533 msgid "The type of the underlying access method (and file format)."
537 #: build/C/man3/dbopen.3:181
543 #: build/C/man3/dbopen.3:195
545 "A pointer to a routine to flush any cached information to disk, free any "
546 "allocated resources, and close the underlying file(s). Since key/data pairs "
547 "may be cached in memory, failing to sync the file with a I<close> or I<sync> "
548 "function may result in inconsistent or lost information. I<close> routines "
549 "return -1 on error (setting I<errno>) and 0 on success."
553 #: build/C/man3/dbopen.3:195
559 #: build/C/man3/dbopen.3:198
560 msgid "A pointer to a routine to remove key/data pairs from the database."
564 #: build/C/man3/dbopen.3:202
565 msgid "The argument I<flag> may be set to the following value:"
569 #: build/C/man3/dbopen.3:203 build/C/man3/dbopen.3:259 build/C/man3/dbopen.3:359
575 #: build/C/man3/dbopen.3:207
577 "Delete the record referenced by the cursor. The cursor must have previously "
582 #: build/C/man3/dbopen.3:215
584 "I<delete> routines return -1 on error (setting I<errno>), 0 on success, and "
585 "1 if the specified I<key> was not in the file."
589 #: build/C/man3/dbopen.3:215
595 #: build/C/man3/dbopen.3:237
597 "A pointer to a routine which returns a file descriptor representative of the "
598 "underlying database. A file descriptor referencing the same file will be "
599 "returned to all processes which call B<dbopen>() with the same I<file> "
600 "name. This file descriptor may be safely used as an argument to the "
601 "B<fcntl>(2) and B<flock>(2) locking functions. The file descriptor is not "
602 "necessarily associated with any of the underlying files used by the access "
603 "method. No file descriptor is available for in memory databases. I<fd> "
604 "routines return -1 on error (setting I<errno>), and the file descriptor on "
609 #: build/C/man3/dbopen.3:237
615 #: build/C/man3/dbopen.3:251
617 "A pointer to a routine which is the interface for keyed retrieval from the "
618 "database. The address and length of the data associated with the specified "
619 "I<key> are returned in the structure referenced by I<data>. I<get> routines "
620 "return -1 on error (setting I<errno>), 0 on success, and 1 if the I<key> was "
625 #: build/C/man3/dbopen.3:251
631 #: build/C/man3/dbopen.3:254
632 msgid "A pointer to a routine to store key/data pairs in the database."
636 #: build/C/man3/dbopen.3:258
637 msgid "The argument I<flag> may be set to one of the following values:"
641 #: build/C/man3/dbopen.3:263
643 "Replace the key/data pair referenced by the cursor. The cursor must have "
644 "previously been initialized."
648 #: build/C/man3/dbopen.3:263
654 #: build/C/man3/dbopen.3:274
656 "Append the data immediately after the data referenced by I<key>, creating a "
657 "new key/data pair. The record number of the appended key/data pair is "
658 "returned in the I<key> structure. (Applicable only to the B<DB_RECNO> "
663 #: build/C/man3/dbopen.3:274
669 #: build/C/man3/dbopen.3:285
671 "Insert the data immediately before the data referenced by I<key>, creating a "
672 "new key/data pair. The record number of the inserted key/data pair is "
673 "returned in the I<key> structure. (Applicable only to the B<DB_RECNO> "
678 #: build/C/man3/dbopen.3:285
680 msgid "B<R_NOOVERWRITE>"
684 #: build/C/man3/dbopen.3:288
685 msgid "Enter the new key/data pair only if the key does not previously exist."
689 #: build/C/man3/dbopen.3:288
691 msgid "B<R_SETCURSOR>"
695 #: build/C/man3/dbopen.3:297
697 "Store the key/data pair, setting or initializing the position of the cursor "
698 "to reference it. (Applicable only to the B<DB_BTREE> and B<DB_RECNO> access "
703 #: build/C/man3/dbopen.3:307
705 "B<R_SETCURSOR> is available only for the B<DB_BTREE> and B<DB_RECNO> access "
706 "methods because it implies that the keys have an inherent order which does "
711 #: build/C/man3/dbopen.3:317
713 "B<R_IAFTER> and B<R_IBEFORE> are available only for the B<DB_RECNO> access "
714 "method because they each imply that the access method is able to create new "
715 "keys. This is true only if the keys are ordered and independent, record "
716 "numbers for example."
720 #: build/C/man3/dbopen.3:322
722 "The default behavior of the I<put> routines is to enter the new key/data "
723 "pair, replacing any previously existing key."
727 #: build/C/man3/dbopen.3:330
729 "I<put> routines return -1 on error (setting I<errno>), 0 on success, and 1 "
730 "if the B<R_NOOVERWRITE> I<flag> was set and the key already exists in the "
735 #: build/C/man3/dbopen.3:330
741 #: build/C/man3/dbopen.3:341
743 "A pointer to a routine which is the interface for sequential retrieval from "
744 "the database. The address and length of the key are returned in the "
745 "structure referenced by I<key>, and the address and length of the data are "
746 "returned in the structure referenced by I<data>."
750 #: build/C/man3/dbopen.3:354
752 "Sequential key/data pair retrieval may begin at any time, and the position "
753 "of the \"cursor\" is not affected by calls to the I<del>, I<get>, I<put>, or "
754 "I<sync> routines. Modifications to the database during a sequential scan "
755 "will be reflected in the scan, that is, records inserted behind the cursor "
756 "will not be returned while records inserted in front of the cursor will be "
761 #: build/C/man3/dbopen.3:358
762 msgid "The flag value B<must> be set to one of the following values:"
766 #: build/C/man3/dbopen.3:372
768 "The data associated with the specified key is returned. This differs from "
769 "the I<get> routines in that it sets or initializes the cursor to the "
770 "location of the key as well. (Note, for the B<DB_BTREE> access method, the "
771 "returned key is not necessarily an exact match for the specified key. The "
772 "returned key is the smallest key greater than or equal to the specified key, "
773 "permitting partial key matches and range searches.)"
777 #: build/C/man3/dbopen.3:372
783 #: build/C/man3/dbopen.3:376
785 "The first key/data pair of the database is returned, and the cursor is set "
786 "or initialized to reference it."
790 #: build/C/man3/dbopen.3:376
796 #: build/C/man3/dbopen.3:385
798 "The last key/data pair of the database is returned, and the cursor is set or "
799 "initialized to reference it. (Applicable only to the B<DB_BTREE> and "
800 "B<DB_RECNO> access methods.)"
804 #: build/C/man3/dbopen.3:385
810 #: build/C/man3/dbopen.3:391
812 "Retrieve the key/data pair immediately after the cursor. If the cursor is "
813 "not yet set, this is the same as the B<R_FIRST> flag."
817 #: build/C/man3/dbopen.3:391
823 #: build/C/man3/dbopen.3:402
825 "Retrieve the key/data pair immediately before the cursor. If the cursor is "
826 "not yet set, this is the same as the B<R_LAST> flag. (Applicable only to "
827 "the B<DB_BTREE> and B<DB_RECNO> access methods.)"
831 #: build/C/man3/dbopen.3:413
833 "B<R_LAST> and B<R_PREV> are available only for the B<DB_BTREE> and "
834 "B<DB_RECNO> access methods because they each imply that the keys have an "
835 "inherent order which does not change."
839 #: build/C/man3/dbopen.3:426
841 "I<seq> routines return -1 on error (setting I<errno>), 0 on success and 1 if "
842 "there are no key/data pairs less than or greater than the specified or "
843 "current key. If the B<DB_RECNO> access method is being used, and if the "
844 "database file is a character special file and no complete key/data pairs are "
845 "currently available, the I<seq> routines return 2."
849 #: build/C/man3/dbopen.3:426
855 #: build/C/man3/dbopen.3:432
857 "A pointer to a routine to flush any cached information to disk. If the "
858 "database is in memory only, the I<sync> routine has no effect and will "
863 #: build/C/man3/dbopen.3:434
864 msgid "The flag value may be set to the following value:"
868 #: build/C/man3/dbopen.3:435
870 msgid "B<R_RECNOSYNC>"
874 #: build/C/man3/dbopen.3:447
876 "If the B<DB_RECNO> access method is being used, this flag causes the sync "
877 "routine to apply to the btree file which underlies the recno file, not the "
878 "recno file itself. (See the I<bfname> field of the B<recno>(3) manual page "
879 "for more information.)"
883 #: build/C/man3/dbopen.3:453
884 msgid "I<sync> routines return -1 on error (setting I<errno>) and 0 on success."
888 #: build/C/man3/dbopen.3:453
890 msgid "Key/data pairs"
894 #: build/C/man3/dbopen.3:456
896 "Access to all file types is based on key/data pairs. Both keys and data are "
897 "represented by the following data structure:"
901 #: build/C/man3/dbopen.3:463
911 #: build/C/man3/dbopen.3:469
912 msgid "The elements of the I<DBT> structure are defined as follows:"
916 #: build/C/man3/dbopen.3:469
922 #: build/C/man3/dbopen.3:472
923 msgid "A pointer to a byte string."
927 #: build/C/man3/dbopen.3:472
933 #: build/C/man3/dbopen.3:475
934 msgid "The length of the byte string."
938 #: build/C/man3/dbopen.3:481
940 "Key and data byte strings may reference strings of essentially unlimited "
941 "length although any two of them must fit into available memory at the same "
942 "time. It should be noted that the access methods provide no guarantees "
943 "about byte string alignment."
947 #: build/C/man3/dbopen.3:491
949 "The B<dbopen>() routine may fail and set I<errno> for any of the errors "
950 "specified for the library routines B<open>(2) and B<malloc>(3) or the "
955 #: build/C/man3/dbopen.3:491
961 #: build/C/man3/dbopen.3:494
962 msgid "A file is incorrectly formatted."
966 #: build/C/man3/dbopen.3:494 build/C/man3/mpool.3:198 build/C/man3/recno.3:218
972 #: build/C/man3/dbopen.3:501
974 "A parameter has been specified (hash function, pad byte, etc.) that is "
975 "incompatible with the current file specification or which is not meaningful "
976 "for the function (for example, use of the cursor without prior "
977 "initialization) or there is a mismatch between the version number of file "
982 #: build/C/man3/dbopen.3:513
984 "The I<close> routines may fail and set I<errno> for any of the errors "
985 "specified for the library routines B<close>(2), B<read>(2), B<write>(2), "
986 "B<free>(3), or B<fsync>(2)."
990 #: build/C/man3/dbopen.3:528
992 "The I<del>, I<get>, I<put>, and I<seq> routines may fail and set I<errno> "
993 "for any of the errors specified for the library routines B<read>(2), "
994 "B<write>(2), B<free>(3) or B<malloc>(3)."
998 #: build/C/man3/dbopen.3:536
1000 "The I<fd> routines will fail and set I<errno> to B<ENOENT> for in memory "
1005 #: build/C/man3/dbopen.3:543
1007 "The I<sync> routines may fail and set I<errno> for any of the errors "
1008 "specified for the library routine B<fsync>(2)."
1012 #: build/C/man3/dbopen.3:548
1014 "The typedef I<DBT> is a mnemonic for \"data base thang\", and was used "
1015 "because no-one could think of a reasonable name that wasn't already used."
1019 #: build/C/man3/dbopen.3:551
1021 "The file descriptor interface is a kludge and will be deleted in a future "
1022 "version of the interface."
1026 #: build/C/man3/dbopen.3:554
1028 "None of the access methods provide any form of concurrent access, locking, "
1033 #: build/C/man3/dbopen.3:559
1034 msgid "B<btree>(3), B<hash>(3), B<mpool>(3), B<recno>(3)"
1038 #: build/C/man3/dbopen.3:562
1040 "I<LIBTP: Portable, Modular Transactions for UNIX>, Margo Seltzer, Michael "
1041 "Olson, USENIX proceedings, Winter 1992."
1045 #: build/C/man3/hash.3:36
1051 #: build/C/man3/hash.3:40
1052 msgid "hash - hash database access method"
1056 #: build/C/man3/hash.3:62
1058 "The routine B<dbopen>(3) is the library interface to database files. One "
1059 "of the supported file formats is hash files. The general description of the "
1060 "database access methods is in B<dbopen>(3), this manual page describes only "
1061 "the hash-specific information."
1065 #: build/C/man3/hash.3:64
1066 msgid "The hash data structure is an extensible, dynamic hashing scheme."
1070 #: build/C/man3/hash.3:70
1072 "The access-method-specific data structure provided to B<dbopen>(3) is "
1073 "defined in the I<E<lt>db.hE<gt>> include file as follows:"
1077 #: build/C/man3/hash.3:81
1080 "typedef struct {\n"
1081 " unsigned int bsize;\n"
1082 " unsigned int ffactor;\n"
1083 " unsigned int nelem;\n"
1084 " unsigned int cachesize;\n"
1085 " uint32_t (*hash)(const void *, size_t);\n"
1091 #: build/C/man3/hash.3:85
1097 #: build/C/man3/hash.3:90
1099 "defines the hash table bucket size, and is, by default, 256 bytes. It may "
1100 "be preferable to increase the page size for disk-resident tables and tables "
1101 "with large data items."
1105 #: build/C/man3/hash.3:90
1111 #: build/C/man3/hash.3:96
1113 "indicates a desired density within the hash table. It is an approximation "
1114 "of the number of keys allowed to accumulate in any one bucket, determining "
1115 "when the hash table grows or shrinks. The default value is 8."
1119 #: build/C/man3/hash.3:96
1125 #: build/C/man3/hash.3:102
1127 "is an estimate of the final size of the hash table. If not set or set too "
1128 "low, hash tables will expand gracefully as keys are entered, although a "
1129 "slight performance degradation may be noticed. The default value is 1."
1133 #: build/C/man3/hash.3:108
1135 "is the suggested maximum size, in bytes, of the memory cache. This value is "
1136 "I<only advisory>, and the access method will allocate more memory rather "
1141 #: build/C/man3/hash.3:108
1147 #: build/C/man3/hash.3:117
1149 "is a user-defined hash function. Since no hash function performs equally "
1150 "well on all possible data, the user may find that the built-in hash function "
1151 "does poorly on a particular data set. A user-specified hash functions must "
1152 "take two arguments (a pointer to a byte string and a length) and return a "
1153 "32-bit quantity to be used as the hash value."
1157 #: build/C/man3/hash.3:127
1159 "is the byte order for integers in the stored database metadata. The number "
1160 "should represent the order as an integer; for example, big endian order "
1161 "would be the number 4,321. If I<lorder> is 0 (no order is specified), the "
1162 "current host order is used. If the file already exists, the specified value "
1163 "is ignored and the value specified when the tree was created is used."
1167 #: build/C/man3/hash.3:139
1169 "If the file already exists (and the B<O_TRUNC> flag is not specified), the "
1170 "values specified for I<bsize>, I<ffactor>, I<lorder>, and I<nelem> are "
1171 "ignored and the values specified when the tree was created are used."
1175 #: build/C/man3/hash.3:144
1177 "If a hash function is specified, I<hash_open> will attempt to determine if "
1178 "the hash function specified is the same as the one with which the database "
1179 "was created, and will fail if it is not."
1183 #: build/C/man3/hash.3:151
1185 "Backward-compatible interfaces to the routines described in B<dbm>(3), and "
1186 "B<ndbm>(3) are provided, however these interfaces are not compatible with "
1187 "previous file formats."
1191 #: build/C/man3/hash.3:158
1193 "The I<hash> access method routines may fail and set I<errno> for any of the "
1194 "errors specified for the library routine B<dbopen>(3)."
1198 #: build/C/man3/hash.3:160
1199 msgid "Only big and little endian byte order are supported."
1203 #: build/C/man3/hash.3:165
1204 msgid "B<btree>(3), B<dbopen>(3), B<mpool>(3), B<recno>(3)"
1208 #: build/C/man3/hash.3:168
1210 "I<Dynamic Hash Tables>, Per-Ake Larson, Communications of the ACM, April "
1215 #: build/C/man3/hash.3:171
1217 "I<A New Hash Package for UNIX>, Margo Seltzer, USENIX Proceedings, Winter "
1222 #: build/C/man3/mpool.3:36
1228 #: build/C/man3/mpool.3:36
1234 #: build/C/man3/mpool.3:40
1235 msgid "mpool - shared memory buffer pool"
1239 #: build/C/man3/mpool.3:44
1242 "B<#include E<lt>db.hE<gt>>\n"
1243 "B<#include E<lt>mpool.hE<gt>>\n"
1247 #: build/C/man3/mpool.3:47
1250 "B<MPOOL *mpool_open(DBT *>I<key>B<, int >I<fd>B<, pgno_t >I<pagesize>B<, "
1251 "pgno_t >I<maxcache>B<);>\n"
1255 #: build/C/man3/mpool.3:51
1258 "B<void mpool_filter(MPOOL *>I<mp>B<, void (*pgin)(void *, pgno_t, void "
1260 "B< void (*>I<pgout>B<)(void *, pgno_t, void *),>\n"
1261 "B< void *>I<pgcookie>B<);>\n"
1265 #: build/C/man3/mpool.3:53
1267 msgid "B<void *mpool_new(MPOOL *>I<mp>B<, pgno_t *>I<pgnoaddr>B<);>\n"
1271 #: build/C/man3/mpool.3:55
1274 "B<void *mpool_get(MPOOL *>I<mp>B<, pgno_t >I<pgno>B<, unsigned int "
1279 #: build/C/man3/mpool.3:57
1282 "B<int mpool_put(MPOOL *>I<mp>B<, void *>I<pgaddr>B<, unsigned int "
1287 #: build/C/man3/mpool.3:59
1289 msgid "B<int mpool_sync(MPOOL *>I<mp>B<);>\n"
1293 #: build/C/man3/mpool.3:61
1295 msgid "B<int mpool_close(MPOOL *>I<mp>B<);>\n"
1299 #: build/C/man3/mpool.3:74
1301 "I<Mpool> is the library interface intended to provide page oriented buffer "
1302 "management of files. The buffers may be shared between processes."
1306 #: build/C/man3/mpool.3:95
1308 "The function B<mpool_open>() initializes a memory pool. The I<key> "
1309 "argument is the byte string used to negotiate between multiple processes "
1310 "wishing to share buffers. If the file buffers are mapped in shared memory, "
1311 "all processes using the same key will share the buffers. If I<key> is NULL, "
1312 "the buffers are mapped into private memory. The I<fd> argument is a file "
1313 "descriptor for the underlying file, which must be seekable. If I<key> is "
1314 "non-NULL and matches a file already being mapped, the I<fd> argument is "
1319 #: build/C/man3/mpool.3:106
1321 "The I<pagesize> argument is the size, in bytes, of the pages into which the "
1322 "file is broken up. The I<maxcache> argument is the maximum number of pages "
1323 "from the underlying file to cache at any one time. This value is not "
1324 "relative to the number of processes which share a file's buffers, but will "
1325 "be the largest value specified by any of the processes sharing the file."
1329 #: build/C/man3/mpool.3:122
1331 "The B<mpool_filter>() function is intended to make transparent input and "
1332 "output processing of the pages possible. If the I<pgin> function is "
1333 "specified, it is called each time a buffer is read into the memory pool from "
1334 "the backing file. If the I<pgout> function is specified, it is called each "
1335 "time a buffer is written into the backing file. Both functions are called "
1336 "with the I<pgcookie> pointer, the page number and a pointer to the page to "
1337 "being read or written."
1341 #: build/C/man3/mpool.3:135
1343 "The function B<mpool_new>() takes an I<MPOOL> pointer and an address as "
1344 "arguments. If a new page can be allocated, a pointer to the page is "
1345 "returned and the page number is stored into the I<pgnoaddr> address. "
1346 "Otherwise, NULL is returned and I<errno> is set."
1350 #: build/C/man3/mpool.3:148
1352 "The function B<mpool_get>() takes an I<MPOOL> pointer and a page number as "
1353 "arguments. If the page exists, a pointer to the page is returned. "
1354 "Otherwise, NULL is returned and I<errno> is set. The I<flags> argument is "
1355 "not currently used."
1359 #: build/C/man3/mpool.3:160
1361 "The function B<mpool_put>() unpins the page referenced by I<pgaddr>. "
1362 "I<pgaddr> must be an address previously returned by B<mpool_get>() or "
1363 "B<mpool_new>(). The flag value is specified by ORing any of the following "
1368 #: build/C/man3/mpool.3:160
1370 msgid "B<MPOOL_DIRTY>"
1374 #: build/C/man3/mpool.3:163
1375 msgid "The page has been modified and needs to be written to the backing file."
1379 #: build/C/man3/mpool.3:166
1380 msgid "B<mpool_put>() returns 0 on success and -1 if an error occurs."
1384 #: build/C/man3/mpool.3:175
1386 "The function B<mpool_sync>() writes all modified pages associated with the "
1387 "I<MPOOL> pointer to the backing file. B<mpool_sync>() returns 0 on success "
1388 "and -1 if an error occurs."
1392 #: build/C/man3/mpool.3:185
1394 "The B<mpool_close>() function free's up any allocated memory associated "
1395 "with the memory pool cookie. Modified pages are B<not> written to the "
1396 "backing file. B<mpool_close>() returns 0 on success and -1 if an error "
1401 #: build/C/man3/mpool.3:192
1403 "The B<mpool_open>() function may fail and set I<errno> for any of the "
1404 "errors specified for the library routine B<malloc>(3)."
1408 #: build/C/man3/mpool.3:198
1409 msgid "The B<mpool_get>() function may fail and set I<errno> for the following:"
1413 #: build/C/man3/mpool.3:201
1414 msgid "The requested record doesn't exist."
1418 #: build/C/man3/mpool.3:213
1420 "The B<mpool_new>() and B<mpool_get>() functions may fail and set I<errno> "
1421 "for any of the errors specified for the library routines B<read>(2), "
1422 "B<write>(2), and B<malloc>(3)."
1426 #: build/C/man3/mpool.3:220
1428 "The B<mpool_sync>() function may fail and set I<errno> for any of the "
1429 "errors specified for the library routine B<write>(2)."
1433 #: build/C/man3/mpool.3:227
1435 "The B<mpool_close>() function may fail and set I<errno> for any of the "
1436 "errors specified for the library routine B<free>(3)."
1440 #: build/C/man3/mpool.3:227
1442 msgid "CONFORMING TO"
1446 #: build/C/man3/mpool.3:230
1447 msgid "Not in POSIX.1-2001. Present on the BSDs."
1451 #: build/C/man3/mpool.3:235
1452 msgid "B<btree>(3), B<dbopen>(3), B<hash>(3), B<recno>(3)"
1456 #: build/C/man3/recno.3:36
1462 #: build/C/man3/recno.3:40
1463 msgid "recno - record number database access method"
1467 #: build/C/man3/recno.3:62
1469 "The routine B<dbopen>(3) is the library interface to database files. One "
1470 "of the supported file formats is record number files. The general "
1471 "description of the database access methods is in B<dbopen>(3), this manual "
1472 "page describes only the recno-specific information."
1476 #: build/C/man3/recno.3:71
1478 "The record number data structure is either variable or fixed-length records "
1479 "stored in a flat-file format, accessed by the logical record number. The "
1480 "existence of record number five implies the existence of records one through "
1481 "four, and the deletion of record number one causes record number five to be "
1482 "renumbered to record number four, as well as the cursor, if positioned after "
1483 "record number one, to shift down one record."
1487 #: build/C/man3/recno.3:77
1489 "The recno access-method-specific data structure provided to B<dbopen>(3) is "
1490 "defined in the I<E<lt>db.hE<gt>> include file as follows:"
1494 #: build/C/man3/recno.3:89
1497 "typedef struct {\n"
1498 " unsigned long flags;\n"
1499 " unsigned int cachesize;\n"
1500 " unsigned int psize;\n"
1503 " unsigned char bval;\n"
1509 #: build/C/man3/recno.3:93
1510 msgid "The elements of this structure are defined as follows:"
1514 #: build/C/man3/recno.3:98
1516 msgid "B<R_FIXEDLEN>"
1520 #: build/C/man3/recno.3:109
1522 "The records are fixed-length, not byte delimited. The structure element "
1523 "I<reclen> specifies the length of the record, and the structure element "
1524 "I<bval> is used as the pad character. Any records, inserted into the "
1525 "database, that are less than I<reclen> bytes long are automatically padded."
1529 #: build/C/man3/recno.3:109
1535 #: build/C/man3/recno.3:122
1537 "In the interface specified by B<dbopen>(3), the sequential record retrieval "
1538 "fills in both the caller's key and data structures. If the B<R_NOKEY> flag "
1539 "is specified, the I<cursor> routines are not required to fill in the key "
1540 "structure. This permits applications to retrieve records at the end of "
1541 "files without reading all of the intervening records."
1545 #: build/C/man3/recno.3:122
1547 msgid "B<R_SNAPSHOT>"
1551 #: build/C/man3/recno.3:128
1553 "This flag requires that a snapshot of the file be taken when B<dbopen>(3) "
1554 "is called, instead of permitting any unmodified records to be read from the "
1559 #: build/C/man3/recno.3:138
1561 "A suggested maximum size, in bytes, of the memory cache. This value is "
1562 "B<only> advisory, and the access method will allocate more memory rather "
1563 "than fail. If I<cachesize> is 0 (no size is specified), a default cache is "
1568 #: build/C/man3/recno.3:150
1570 "The recno access method stores the in-memory copies of its records in a "
1571 "btree. This value is the size (in bytes) of the pages used for nodes in "
1572 "that tree. If I<psize> is 0 (no page size is specified), a page size is "
1573 "chosen based on the underlying filesystem I/O block size. See B<btree>(3) "
1574 "for more information."
1578 #: build/C/man3/recno.3:158
1584 #: build/C/man3/recno.3:161
1585 msgid "The length of a fixed-length record."
1589 #: build/C/man3/recno.3:161
1595 #: build/C/man3/recno.3:169
1597 "The delimiting byte to be used to mark the end of a record for "
1598 "variable-length records, and the pad character for fixed-length records. If "
1599 "no value is specified, newlines (\"\\en\") are used to mark the end of "
1600 "variable-length records and fixed-length records are padded with spaces."
1604 #: build/C/man3/recno.3:169
1610 #: build/C/man3/recno.3:179
1612 "The recno access method stores the in-memory copies of its records in a "
1613 "btree. If I<bfname> is non-NULL, it specifies the name of the btree file, "
1614 "as if specified as the filename for a B<dbopen>(3) of a btree file."
1618 #: build/C/man3/recno.3:197
1620 "The data part of the key/data pair used by the I<recno> access method is the "
1621 "same as other access methods. The key is different. The I<data> field of "
1622 "the key should be a pointer to a memory location of type I<recno_t>, as "
1623 "defined in the I<E<lt>db.hE<gt>> include file. This type is normally the "
1624 "largest unsigned integral type available to the implementation. The I<size> "
1625 "field of the key should be the size of that type."
1629 #: build/C/man3/recno.3:202
1631 "Because there can be no metadata associated with the underlying recno access "
1632 "method files, any changes made to the default values (e.g., fixed record "
1633 "length or byte separator value) must be explicitly specified each time the "
1638 #: build/C/man3/recno.3:210
1640 "In the interface specified by B<dbopen>(3), using the I<put> interface to "
1641 "create a new record will cause the creation of multiple, empty records if "
1642 "the record number is more than one greater than the largest record currently "
1647 #: build/C/man3/recno.3:218
1649 "The I<recno> access method routines may fail and set I<errno> for any of the "
1650 "errors specified for the library routine B<dbopen>(3) or the following:"
1654 #: build/C/man3/recno.3:222
1656 "An attempt was made to add a record to a fixed-length database that was too "
1661 #: build/C/man3/recno.3:229
1662 msgid "B<btree>(3), B<dbopen>(3), B<hash>(3), B<mpool>(3)"
1666 #: build/C/man3/recno.3:233
1668 "I<Document Processing in a Relational Database System>, Michael Stonebraker, "
1669 "Heidi Stettner, Joseph Kalash, Antonin Guttman, Nadene Lynn, Memorandum "
1670 "No. UCB/ERL M82/32, May 1982."