The Record Access Group contains the API for fetching, storing, and deleting records. More...

Classes
struct	mdbm_fetch_info

Macros
#define	MDBM_FETCH_FLAG_DIRTY 0x01
	Cache entry is dirty. More...

#define	MDBM_INSERT 0
	Insert if key does not exist; fail if exists. More...

#define	MDBM_REPLACE 1
	Update if key exists; insert if does not exist. More...

#define	MDBM_INSERT_DUP 2
	Insert new record (creates duplicate if key exists) More...

#define	MDBM_MODIFY 3
	Update if key exists; fail if does not exist. More...

#define	MDBM_STORE_MASK 0x3
	Mask for all store options. More...

#define	MDBM_STORE_MODE(f) ((f) & MDBM_STORE_MASK)
	Extract the store mode from an options mask. More...

#define	MDBM_RESERVE 0x100
	Reserve space; Value not copied. More...

#define	MDBM_CLEAN 0x200
	Mark entry as clean. More...

#define	MDBM_CACHE_ONLY 0x400
	Do not operate on the backing store; use cache only. More...

#define	MDBM_CACHE_REPLACE 0
	Update cache if key exists; insert if does not exist. More...

#define	MDBM_CACHE_MODIFY 0x1000
	Update cache if key exists; do not insert if does not. More...

#define	MDBM_CACHE_UPDATE_MODE(f) ((f) & MDBM_CACHE_MODIFY)

#define	MDBM_STORE_SUCCESS 0
	Returned if store succeeds. More...

#define	MDBM_STORE_ENTRY_EXISTS 1
	Returned if MDBM_INSERT used and key exists. More...

Functions
datum	mdbm_fetch (MDBM *db, datum key)
	Fetches the record specified by the key argument and returns a datum that points to the value. More...

int	mdbm_fetch_r (MDBM db, datum key, datum val, MDBM_ITER iter)
	Fetches the record specified by the key argument. More...

int	mdbm_fetch_buf (MDBM db, datum key, datum val, datum buf, int flags)
	Fetches and copies the record specified by the key argument. More...

int	mdbm_fetch_dup_r (MDBM db, datum key, datum val, MDBM_ITER iter)
	Fetches the next value for a key inserted via mdbm_store_r with the MDBM_INSERT_DUP flag set. More...

char *	mdbm_fetch_str (MDBM db, const char key)
	Fetches a string. More...

int	mdbm_fetch_info (MDBM db, datum key, datum val, datum buf, struct mdbm_fetch_info info, MDBM_ITER iter)
	Fetches and copies the record specified by the key argument. More...

int	mdbm_delete (MDBM *db, datum key)
	Deletes a specific record. More...

int	mdbm_delete_r (MDBM db, MDBM_ITER iter)
	Deletes the record currently addressed by the iter argument. More...

int	mdbm_delete_str (MDBM db, const char key)
	Deletes a string from the MDBM. More...

int	mdbm_store (MDBM *db, datum key, datum val, int flags)
	This is a wrapper around mdbm_store_r, with a static iterator. More...

int	mdbm_store_r (MDBM db, datum key, datum val, int flags, MDBM_ITER iter)
	Stores the record specified by the key and val parameters. More...

int	mdbm_store_str (MDBM db, const char key, const char *val, int flags)
	Stores a string into the MDBM. More...

Detailed Description

The Record Access Group contains the API for fetching, storing, and deleting records.

Macro Definition Documentation

#define MDBM_FETCH_FLAG_DIRTY 0x01

Cache entry is dirty.

#define MDBM_INSERT 0

Insert if key does not exist; fail if exists.

#define MDBM_REPLACE 1

Update if key exists; insert if does not exist.

#define MDBM_INSERT_DUP 2

Insert new record (creates duplicate if key exists)

#define MDBM_MODIFY 3

Update if key exists; fail if does not exist.

#define MDBM_STORE_MASK 0x3

Mask for all store options.

#define MDBM_STORE_MODE ( f ) ((f) & MDBM_STORE_MASK)

Extract the store mode from an options mask.

#define MDBM_RESERVE 0x100

Reserve space; Value not copied.

#define MDBM_CLEAN 0x200

Mark entry as clean.

#define MDBM_CACHE_ONLY 0x400

Do not operate on the backing store; use cache only.

#define MDBM_CACHE_REPLACE 0

Update cache if key exists; insert if does not exist.

#define MDBM_CACHE_MODIFY 0x1000

Update cache if key exists; do not insert if does not.

#define MDBM_CACHE_UPDATE_MODE ( f ) ((f) & MDBM_CACHE_MODIFY)

#define MDBM_STORE_SUCCESS 0

Returned if store succeeds.

#define MDBM_STORE_ENTRY_EXISTS 1

Returned if MDBM_INSERT used and key exists.

Function Documentation

datum mdbm_fetch	(	MDBM *	db,
		datum	key
	)

Fetches the record specified by the key argument and returns a datum that points to the value.

If such a record exists in the database, the size and location (pointer) are stored in the returned datum. If no matching record exists, a null datum (dsize==0, dptr==NULL) is returned.

The contents returned in datum has a pointer to a value in mapped memory. If there is any system-wide process that could modify your MDBM, this value must be accessed in a locked context.

For example, the following is correct code to copy a lookup value for subsequent return:

char* getFoo(int maxLength)
{
  datum key = { "foo", 3 };
  datum value;
  char *buffer = (char*)malloc(maxLength+1);  // Skip return code check.
  mdbm_lock(db);   // Skip return code check.
  value = mdbm_fetch(db, &key);
  if (value.dptr != NULL) {
    strncpy(buffer, value.dptr, maxLength);  // GOOD: copy-out done in locked context.
  } else {
    buffer[0] = '\0';
  };
  mdbm_unlock(db); // Skip return code check.
  return buffer;
}

Parameters

[in,out]	db	Database handle
[in]	key	Lookup key

Returns: datum is returned with found, or not found, information

Return values

datum	found, with size and pointer set, on success
datum	not found, with dsize==0, and dptr==NULL, and errno==ENOENT. errno may have other values for failure (ex., EINVAL).

int mdbm_fetch_r	(	MDBM *	db,
		datum *	key,
		datum *	val,
		MDBM_ITER *	iter
	)

Fetches the record specified by the key argument.

If such a record exists in the database, the size and location (pointer) are stored in the datum pointed to by val. If no matching record exists, a null datum (dsize==0, dptr==NULL) is returned.

The contents returned in val is a pointer to a value in mapped memory. If there is any system-wide process that could modify your MDBM, this value must be accessed in a locked context.

For example, the following is correct code to copy a lookup value for subsequent return:

char* getFoo(int maxLength)
{
  int rc;
  datum key = { "foo", 3 };
  datum value;
  char *buffer = (char*)malloc(maxLength+1);  // Skip return code check.
  mdbm_lock(db);    // Skip return code check.
  rc = mdbm_fetch_r(db, &key, &value, NULL);
  if (!rc) {
    strncpy(buffer, value.dptr, maxLength);  // GOOD: copy-out done in locked context.
  } else {
    buffer[0] = '\0';
  };
  mdbm_unlock(db);  // Skip return code check.
  return buffer;
}

A record can be updated in-place by fetching the value datum, casting the dptr as appropriate, and updating those contents. However, the update must not change the size of the record.

Parameters

[in,out]	db	Database handle
[in]	key	Pointer to datum used as the index key
[out]	val	Pointer to datum returned
[in,out]	iter	MDBM iterator

Returns: Fetch status

Return values

-1	Error, and errno is set
0	Success

int mdbm_fetch_buf	(	MDBM *	db,
		datum *	key,
		datum *	val,
		datum *	buf,
		int	flags
	)

Fetches and copies the record specified by the key argument.

If such a record exists in the database, the size and location are stored in the datum pointed to by val. The same record is also copied into the buf argument. If no matching record exists, a null datum (dsize==0, dptr==NULL) is returned.

Note that a record can be updated in-place by fetching the value datum, casting the dptr as appropriate, and updating the record. However, the update must not change the size of the record.

buf.dptr must point to memory that has been previously malloc'd on the heap. buff.dptr will be realloc'd if is too small.

Parameters

[in,out]	db	Database handle
[in]	key	Lookup key
[out]	val	Lookup value (pointer)
[in,out]	buf	Copy-out of lookup reference returned in val
[in]	flags	Reserved for future use

Returns: Fetch status

Return values

-1	Error, and errno is set
0	Success

int mdbm_fetch_dup_r	(	MDBM *	db,
		datum *	key,
		datum *	val,
		MDBM_ITER *	iter
	)

Fetches the next value for a key inserted via mdbm_store_r with the MDBM_INSERT_DUP flag set.

The order of values returned by iterating via this function is not guaranteed to be the same order as the values were inserted.

As with any db iteration, record insertion and deletion during iteration may cause the iteration to skip and/or repeat records.

Calling this function with an iterator initialized via MDBM_ITER_INIT will cause this function to return the first value for the given key.

Parameters

[in,out]	db	Database handle
[in]	key	Pointer to datum used as the index key
[out]	val	Pointer to datum returned
[in,out]	iter	MDBM iterator

Returns: Fetch duplicate status

Return values

-1	Error, and errno is set
0	Success

char* mdbm_fetch_str	(	MDBM *	db,
		const char *	key
	)

Fetches a string.

Parameters

[in,out]	db	Database handle
[in]	key	Stored key

Returns: Fetched string reference, or NULL

Return values

Pointer	to string, on success
NULL	if key does not exist

int mdbm_fetch_info	(	MDBM *	db,
		datum *	key,
		datum *	val,
		datum *	buf,
		struct mdbm_fetch_info *	info,
		MDBM_ITER *	iter
	)

Fetches and copies the record specified by the key argument.

If such a record exists in the database, the size and location are stored in the datum pointed to by val. The same record is also copied into the buf argument. If no matching record exists, a null datum (dsize==0, dptr==NULL) is returned.

mdbm_fetch_info is only supported by MDBM version 3 or higher.

Note that a record can be updated in-place by fetching the value datum, casting the dptr as appropriate, and updating the record. However, the update must not change the size of the record.

Additional information is passed back in the info argument: entry flags, the number of accesses to cache entry, and the last access time (LRU/LFU only).

buf.dptr cannot point to statically allocated memory. It must point to memory that has been previously malloc'd on the heap.

Parameters

[in,out]	db	Database handle
[in]	key	Pointer to datum used as the index key
[out]	val	Pointer to datum returned
[out]	buf	Copy found datum into this parameter
[out]	info	Pointer to additional information (struct mdbm_fetch_info)
[in,out]	iter	MDBM iterator

Returns: Fetch info status

Return values

-1	Error, and errno is set
0	Success

int mdbm_delete	(	MDBM *	db,
		datum	key
	)

Deletes a specific record.

Parameters

[in,out]	db	Database handle
[in]	key	Key to be removed

Returns: Delete status

Return values

-1	Error, and errno is set
0	Success

int mdbm_delete_r	(	MDBM *	db,
		MDBM_ITER *	iter
	)

Deletes the record currently addressed by the iter argument.

After deletion, the key and/or value returned by the iterating function is no longer valid. Calling mdbm_next_r on the iterator will return the key/value for the entry following the entry that was deleted.

Parameters

[in,out]	db	Database handle
[in,out]	iter	MDBM iterator pointing to item to be deleted

Returns: Delete status

Return values

-1	Error, and errno is set
0	Success

int mdbm_delete_str	(	MDBM *	db,
		const char *	key
	)

Deletes a string from the MDBM.

Parameters

[in,out]	db	Database handle
[in]	key	Stored key

Returns: Delete string status

Return values

-1	Error, and errno is set
0	Success

int mdbm_store	(	MDBM *	db,
		datum	key,
		datum	val,
		int	flags
	)

This is a wrapper around mdbm_store_r, with a static iterator.

Parameters

[in,out]	db	Database handle
[in]	key	Stored key
[in]	val	Key's value
[in]	flags	Store flags

Returns: Store status

Return values

-1	Error, and errno is set
0	Success
1	Flag MDBM_INSERT was specified, and the key already exists

Values for flags mask:

MDBM_INSERT - Operation will fail if a record with the same key already exists in the database.
MDBM_REPLACE - A record with the same key will be replaced. If the key does not exist, the record will be created.
MDBM_INSERT_DUP - allows multiple records with the same key to be inserted. Fetching a record with the key will return only one of the duplicate records, and which record is returned is not defined.
MDBM_MODIFY - Store only if matching entry already exists.
MDBM_RESERVE - Reserve space; value not copied (mdbm_store_r only)
MDBM_CACHE_ONLY (MDBM V3) - Perform store only in the Cache, not in Backing Store.
MDBM_CACHE_MODIFY (MDBM V3) - Update Cache only if key exists; update the Backing Store

Insertion with flag MDBM_MODIFY set will fail if the key does not already exist.

Insertion with flag MDBM_RESERVE set will allocate space within the MDBM for the object; but will not copy it. The caller is responsible for copying the value into the indicated position.

Replacement with flag MDBM_CACHE_MODIFY for a cache with a backing store, has the effect of writing through the cache to the backing store without updating the cache unless that cache entry already exists.

Quick option summary:

MDBM_INSERT - Add if missing, fail if present
MDBM_REPLACE - Add if missing, replace if present
MDBM_MODIFY - Fail if missing, replace if present

NOTE: Ensure that the key and value datum pointers reference storage that is external to the db and not the result of, for example, an mdbm_fetch, mdbm_first, or mdbm_next. A store operation can result in various db internal modifications that invalidate previously returned key and value pointers. Also be aware that mdbm_store_r overwrites key.dptr and val.dptr, so to avoid memory leaks for the case when key.dptr or val.dptr point to malloc-ed or new-ed memory, you should keep a copy of above pointers and deallocate them when done.

NOTE: If you do multiple stores to the same key using MDBM_REPLACE, the corresponding value's location in memory can change after each store. The MDBM_REPLACE flag does not imply that the value will reuse the same location. Even if you store a smaller value for an existing key, it probably won't reuse the existing value's location. In the current implementation, the only time it tries to reuse a value's location is when replacing data with exactly the same size. This internal optimization is subject to change in any future release.

Todo:: doc, example MDBM_RESERVE

int mdbm_store_r	(	MDBM *	db,
		datum *	key,
		datum *	val,
		int	flags,
		MDBM_ITER *	iter
	)

Stores the record specified by the key and val parameters.

Parameters

[in,out]	db	Database handle
[in]	key	datum to be used as the index key
[in]	val	datum containing the value to be stored
[in]	flags	Type of store operation to be performed. See mdbm_store for flag values.
[in,out]	iter	MDBM iterator

Returns: Store status

Return values

-1	Error, and errno is set
0	Success
1	Flag MDBM_INSERT was specified, and the key already exists

See mdbm_store for additional usage information.

int mdbm_store_str	(	MDBM *	db,
		const char *	key,
		const char *	val,
		int	flags
	)

Stores a string into the MDBM.

Parameters

[in,out]	db	Database handle
[in]	key	Key for storage
[in]	val	String to store
[in]	flags	Type of store operation to be performed.

Returns: Store status

Return values

-1	Error, and errno is set
0	Success
1	Flag MDBM_INSERT was specified, and the key already exists

See mdbm_store for additional usage information.

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation