The File Management Group contains the API the affects an MDBM at a file level. More...

Macros
#define	MDBM_O_RDONLY 0x00000000
	Read-only access. More...

#define	MDBM_O_WRONLY 0x00000001
	Write-only access (deprecated in V3) More...

#define	MDBM_O_RDWR 0x00000002
	Read and write access. More...

#define	MDBM_O_ACCMODE (MDBM_O_RDONLY \| MDBM_O_WRONLY \| MDBM_O_RDWR)

#define	MDBM_O_ASYNC 0x00000040
	Perform asynchronous writes. More...

#define	MDBM_O_FSYNC 0x00000080
	Sync file on close. More...

#define	MDBM_O_CREAT 0x00000200
	Create file if it does not exist. More...

#define	MDBM_O_TRUNC 0x00000400
	Truncate file. More...

#define	MDBM_O_DIRECT 0x00004000
	Perform direction I/O. More...

#define	MDBM_NO_DIRTY 0x00010000
	Do not not track clean/dirty status. More...

#define	MDBM_SINGLE_ARCH 0x00080000
	User promises not to mix 32/64-bit access. More...

#define	MDBM_OPEN_WINDOWED 0x00100000
	Use windowing to access db. More...

#define	MDBM_PROTECT 0x00200000
	Protect database except when locked. More...

#define	MDBM_DBSIZE_MB 0x00400000
	Dbsize is specific in MB. More...

#define	MDBM_STAT_OPERATIONS 0x00800000
	collect stats for fetch, store, delete More...

#define	MDBM_LARGE_OBJECTS 0x01000000
	Support large objects - obsolete. More...

#define	MDBM_PARTITIONED_LOCKS 0x02000000
	Partitioned locks. More...

#define	MDBM_RW_LOCKS 0x08000000
	Read-write locks. More...

#define	MDBM_ANY_LOCKS 0x00020000
	Open, even if existing locks don't match flags. More...

#define	MDBM_CREATE_V3 0x20000000
	Create a V3 db. More...

#define	MDBM_OPEN_NOLOCK 0x80000000
	Don't lock during open. More...

#define	MDBM_DEMAND_PAGING 0x04000000
	(v2 only) More...

#define	MDBM_DBSIZE_MB_OLD 0x04000000
	(don't use – conflicts with above) More...

#define	MDBM_COPY_LOCK_ALL 0x01

#define	MDBM_SAVE_COMPRESS_TREE 0x01000000 /* compress mdbm before saving */
	Compress MDBM before saving. More...

#define	MDBM_SAVE_COMPRESS_TREE 0x01000000
	Compress MDBM before saving. More...

Functions
MDBM *	mdbm_open (const char *file, int flags, int mode, int psize, int presize)
	Creates and/or opens a database. More...

void	mdbm_close (MDBM *db)
	Closes the database. More...

void	mdbm_close_fd (MDBM *db)
	Closes an MDBM's underlying file descriptor. More...

MDBM *	mdbm_dup_handle (MDBM *db, int flags)
	Duplicate an existing database handle. More...

int	mdbm_sync (MDBM *db)
	msync's all pages to disk asynchronously. More...

int	mdbm_fsync (MDBM *db)
	fsync's an MDBM. More...

int	mdbm_replace_db (MDBM db, const char newfile)
	Atomically replaces the database currently in oldfile db with the new database in newfile. More...

int	mdbm_replace_file (const char oldfile, const char newfile)
	Atomically replaces an old database in oldfile with a new database in newfile. More...

int	mdbm_pre_split (MDBM *db, mdbm_ubig_t N)
	Forces a db to split, creating N pages. More...

int	mdbm_fcopy (MDBM *db, int fd, int flags)
	Copies the contents of a database to an open file handle. More...

int	mdbm_save (MDBM db, const char file, int flags, int mode, int compressionLevel)
	DEPRECATED!! mdbm_save is only supported for V2 MDBMs. More...

int	mdbm_restore (MDBM db, const char file)
	DEPRECATED!! mdbm_restore is only supported for V2 MDBMs. More...

Detailed Description

The File Management Group contains the API the affects an MDBM at a file level.

Macro Definition Documentation

#define MDBM_O_RDONLY 0x00000000

Read-only access.

#define MDBM_O_WRONLY 0x00000001

Write-only access (deprecated in V3)

#define MDBM_O_RDWR 0x00000002

Read and write access.

#define MDBM_O_ACCMODE (MDBM_O_RDONLY | MDBM_O_WRONLY | MDBM_O_RDWR)

#define MDBM_O_ASYNC 0x00000040

Perform asynchronous writes.

#define MDBM_O_FSYNC 0x00000080

Sync file on close.

#define MDBM_O_CREAT 0x00000200

Create file if it does not exist.

#define MDBM_O_TRUNC 0x00000400

Truncate file.

#define MDBM_O_DIRECT 0x00004000

Perform direction I/O.

#define MDBM_NO_DIRTY 0x00010000

Do not not track clean/dirty status.

#define MDBM_SINGLE_ARCH 0x00080000

User promises not to mix 32/64-bit access.

#define MDBM_OPEN_WINDOWED 0x00100000

Use windowing to access db.

#define MDBM_PROTECT 0x00200000

Protect database except when locked.

#define MDBM_DBSIZE_MB 0x00400000

Dbsize is specific in MB.

#define MDBM_STAT_OPERATIONS 0x00800000

collect stats for fetch, store, delete

#define MDBM_LARGE_OBJECTS 0x01000000

Support large objects - obsolete.

#define MDBM_PARTITIONED_LOCKS 0x02000000

Partitioned locks.

#define MDBM_RW_LOCKS 0x08000000

Read-write locks.

#define MDBM_ANY_LOCKS 0x00020000

Open, even if existing locks don't match flags.

#define MDBM_CREATE_V3 0x20000000

Create a V3 db.

#define MDBM_OPEN_NOLOCK 0x80000000

Don't lock during open.

#define MDBM_DEMAND_PAGING 0x04000000

(v2 only)

#define MDBM_DBSIZE_MB_OLD 0x04000000

(don't use – conflicts with above)

#define MDBM_COPY_LOCK_ALL 0x01

#define MDBM_SAVE_COMPRESS_TREE 0x01000000 /* compress mdbm before saving */

Compress MDBM before saving.

#define MDBM_SAVE_COMPRESS_TREE 0x01000000

Compress MDBM before saving.

Function Documentation

MDBM* mdbm_open	(	const char *	file,
		int	flags,
		int	mode,
		int	psize,
		int	presize
	)

Creates and/or opens a database.

Parameters

[in]	file	Name of the backing file for the database.
[in]	flags	Specifies the open-mode for the file, usually either (MDBM_O_RDWR\|MDBM_O_CREAT) or (MDBM_O_RDONLY). Flag MDBM_LARGE_OBJECTS may be used to enable large object support. Large object support can only be enabled when the database is first created. Subsequent mdbm_open calls will ignore the flag. Flag MDBM_PARTITIONED_LOCKS may be used to enable partition locking a per mdbm_open basis.
[in]	mode	Used to set the file permissions if the file needs to be created.
[in]	psize	Specifies the page size for the database and is set when the database is created. The minimum page size is 128. In v2, the maximum is 64K. In v3, the maximum is 16M - 64. The default, if 0 is specified, is 4096.
[in]	presize	Specifies the initial size for the database. The database will dynamically grow as records are added, but specifying an initial size may improve efficiency. If this is not a multiple of psize, it will be increased to the next psize multiple.

Returns: MDBM handle or failure indicator

Return values

Pointer	to an MDBM handle, on success
NULL	on error, and errno is set

Values for flags mask:

MDBM_O_RDONLY - open for reading only
MDBM_O_RDWR - open for reading and writing
MDBM_O_WRONLY - same as RDWR (deprecated)
MDBM_O_CREAT - create file if it does not exist (requires flag MDBM_O_RDWR)
MDBM_O_TRUNC - truncate size to 0
MDBM_O_ASYNC - enable asynchronous sync'ing by the kernel syncing process.
MDBM_O_FSYNC - sync MDBM upon mdbm_close
MDBM_O_DIRECT - use O_DIRECT when accessing backing-store files
MDBM_NO_DIRTY - do not not track clean/dirty status
MDBM_OPEN_WINDOWED - use windowing to access db, only available with MDBM_O_RDWR
MDBM_PROTECT - protect database except when locked (MDBM V3 only)
MDBM_DBSIZE_MB - dbsize is specific in MB (MDBM V3 only)
MDBM_LARGE_OBJECTS - support large objects
MDBM_PARTITIONED_LOCKS - partitioned locks
MDBM_RW_LOCKS - read-write locks
MDBM_CREATE_V2 - create a V2 db
MDBM_CREATE_V3 - create a V3 db
MDBM_HEADER_ONLY - map header only (internal use)
MDBM_OPEN_NOLOCK - do not lock during open
MDBM_ANY_LOCKS - (V4 only) treat the locking flags as only a suggestion
MDBM_SINGLE_ARCH - (V4 only) user guarantees no mixed (32/64-bit) access in exchange for faster (pthreads) locking

More information about the differences between V2 and V3 mdbm_open behavior:

In V2, when the psize (page size) parameter is invalid, the page size is silently converted to a valid value: if non-zero but less than 128, it becomes 128. Page size is always rounded to the next power of 2. If greater than 64K, it becomes 64K.
In V3, when the page size is invalid(less than 128, or greater than 16MB) mdbm_open detects an error and returns NULL. Page size is always a multiple of 64 bytes.

void mdbm_close ( MDBM * db )

Closes the database.

Parameters

[in,out] db Database handle

mdbm_close closes the database specified by the db argument. The in-memory pages are not flushed to disk by close. They will be written to disk over time as they are paged out, but an explicit mdbm_sync call is necessary before closing if on-disk consistency is required.

void mdbm_close_fd ( MDBM * db )

Closes an MDBM's underlying file descriptor.

Parameters

[in,out] db Database handle

MDBM* mdbm_dup_handle	(	MDBM *	db,
		int	flags
	)

Duplicate an existing database handle.

The advantage of dup'ing a handle over doing a separate mdbm_open is that dup's handle share the same virtual page mapping within the process space (saving memory). Threaded applications should use pthread_mutex_lock and unlock around calls to mdbm_dup_handle.

Parameters

[in,out]	db	Database handle
[in]	flags	Reserved for future use

Returns: Dup'd handle

Return values

Pointer	to an MDBM handle, on success
NULL	on error, and errno is set

int mdbm_sync ( MDBM * db )

msync's all pages to disk asynchronously.

The mdbm_sync call will return, and mapped pages are scheduled to be flushed to disk.

Parameters

[in,out] db Database handle

Returns: Sync status

Return values

-1	Error, and errno is set
0	Success

int mdbm_fsync ( MDBM * db )

fsync's an MDBM.

Syncs all pages to disk synchronously. The mdbm_fsync call will return after all pages have been flushed to disk. The database is locked while pages are flushed.

Parameters

[in,out] db Database handle

Returns: fsync status

Return values

-1	Error, and errno is set
0	Success

int mdbm_replace_db	(	MDBM *	db,
		const char *	newfile
	)

Atomically replaces the database currently in oldfile db with the new database in newfile.

The old database is locked while the new database is renamed from newfile to oldfile and the old database is marked as having been replaced. This causes all processes that have the old database open to reopen the new database on their next access. Only database files of the same version may be specified for oldfile and new file. For example, mix and matching of v2 and v3 with oldfile and newfile is not allowed.

This function will delete the old file; and rename the new file.

Parameters

[in,out]	db	Database handle
[in]	newfile	Path of new file

Returns: Replace status

Return values

-1	Error and errno is set. The MDBM was not replaced.
0	Success and the MDBM was replaced

int mdbm_replace_file	(	const char *	oldfile,
		const char *	newfile
	)

Atomically replaces an old database in oldfile with a new database in newfile.

oldfile is deleted, and newfile is renamed to oldfile.

The old database is locked (if the MDBM were opened with locking) while the new database is renamed from newfile to oldfile, and the old database is marked as having been replaced. The marked old database causes all processes that have the old database open to reopen using the new database on their next access.

Only database files of the same version may be specified for oldfile and newfile. For example, mixing and matching of v2 and v3 for oldfile and newfile is not allowed.

mdbm_replace_file may be used if the MDBM is opened with locking or without locking (using mdbm_open flag MDBM_OPEN_NOLOCK), and without per-access locking, if all accesses are read (fetches) accesses across all programs that open that MDBM. If there are any write (store/delete) accesses, you must open the MDBM with locking, and you must lock around all operations (fetch, store, delete, iterate).

Parameters

[in]	oldfile	File to be replaced
[in]	newfile	Path of new file

Returns: Replace status

Return values

-1	Error, and errno is set. The MDBM was not replaced
0	Success, and the MDBM was replaced

int mdbm_pre_split	(	MDBM *	db,
		mdbm_ubig_t	N
	)

Forces a db to split, creating N pages.

Must be called before any data is inserted. If N is not a multiple of 2, it will be rounded up.

Parameters

[in,out]	db	Database handle
[in]	N	Target number of pages post split. If N is not larger than the initial size (ex., 0), a split will not be done and a success status is returned.

Returns: Split status

Return values

-1	Error, and errno is set. errno=EFBIG if MDBM not empty.
0	Success

int mdbm_fcopy	(	MDBM *	db,
		int	fd,
		int	flags
	)

Copies the contents of a database to an open file handle.

Parameters

[in,out]	db	Database handle
[in]	fd	Open file descriptor
[in]	flags

Returns: fcopy status

Return values

-1	Error, and errno is set
0	Success

Values for flags mask:

MDBM_COPY_LOCK_ALL - Whether lock for the duration of the copy. For a consistent snapshot of the entire database, this flag must be used. Otherwise, consistency will only be on a per-page level.

int mdbm_save	(	MDBM *	db,
		const char *	file,
		int	flags,
		int	mode,
		int	compressionLevel
	)

DEPRECATED!! mdbm_save is only supported for V2 MDBMs.

Saves the current contents of the database in a transportable format (i.e., without all of the holes normally found in an MDBM database). Include MDBM_O_CREAT in flags to create a new save file, MDBM_O_TRUNC to truncate an existing file. Include both to either create a new file or truncate an existing one, as required.

Parameters

[in,out]	db	Database handle
[in]	file	File to save to
[in]	flags	Mask indicating how file should be created Supported flags are: MDBM_O_CREAT, MDBM_O_TRUNC, MDBM_SAVE_COMPRESS_TREE(used to compress a database internally before saving to file)
[in]	mode	Set as file mode permissions (ex: 0644); If 0 then ignored
[in]	compressionLevel	If <= 0, then file is saved without compressing. If > zero, zlib compression at the specified level is applied

Returns: Save status

Return values

0	Success
-1	Error, and errno is set

int mdbm_restore	(	MDBM *	db,
		const char *	file
	)

DEPRECATED!! mdbm_restore is only supported for V2 MDBMs.

Restores a database from the specified file (which was created using the mdbm_save function). Any existing contents in the database are truncated before restoring.

Parameters

[in,out]	db	Database handle
[in]	file	File to restore from

Returns: Restore status

Return values

0	Success
-1	Error, and errno is set

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation