dbif.h File Reference

CNID DBD (Database Daemon) Backend interface definitions. More...

#include <stdbool.h>
#include <stdint.h>
#include <db.h>
#include <atalk/adouble.h>
#include "db_param.h"

Go to the source code of this file.

Data Structures
struct	db_table
struct	DBD

Macros
#define	DBIF_DB_CNT   4
#define	DBIF_CNID   0
#define	DBIF_IDX_DEVINO   1
#define	DBIF_IDX_DIDNAME   2
#define	DBIF_IDX_NAME   3
#define	LOCKFILENAME   "lock"
#define	LOCK_FREE   0
#define	LOCK_UNLOCK   1
#define	LOCK_EXCL   2
#define	LOCK_SHRD   3

Functions
DBD *	dbif_init (const char *envhome, const char *dbname)
int	dbif_env_open (DBD *dbd, struct db_param *dbp, uint32_t dbenv_oflags)
int	dbif_open (DBD *dbd, struct db_param *dbp, int reindex)
int	dbif_close (DBD *dbd)
int	dbif_env_remove (const char *path)
int	dbif_get (DBD *, const int, DBT *, DBT *, uint32_t)
int	dbif_pget (DBD *, const int, DBT *, DBT *, DBT *, uint32_t)
int	dbif_put (DBD *, const int, DBT *, DBT *, uint32_t)
int	dbif_del (DBD *, const int, DBT *, uint32_t)
int	dbif_count (DBD *, const int, uint32_t *)
int	dbif_search (DBD *dbd, DBT *key, char *resbuf, uint32_t offset, bool *more)
	Paginated substring cursor scan over the name index.
int	dbif_copy_rootinfokey (DBD *srcdbd, DBD *destdbd)
int	dbif_txn_begin (DBD *)
int	dbif_txn_commit (DBD *)
int	dbif_txn_abort (DBD *)
int	dbif_txn_close (DBD *dbd, int ret)
	Close a transaction based on ret code.
int	dbif_txn_checkpoint (DBD *, uint32_t, uint32_t, uint32_t)
int	dbif_dump (DBD *dbd, int dumpindexes)
int	dbif_idwalk (DBD *dbd, cnid_t *cnid, int close)
	Iterates over dbd, returning cnids.

Detailed Description

CNID DBD (Database Daemon) Backend interface definitions.

API usage

Initialization

1. Provide storage for a DBD * handle: DBD *dbd;
2. Call dbif_init with a filename to receive a DBD handle: dbd = dbif_init("cnid2.db"); Pass NULL to create an in-memory db. Note: the DBD type is NOT from BerkeleyDB ! We've defined it.
3. Call dbif_env_open to open an dbd environment if you called dbif_init with a filename. Pass a db_param here for on-disk databases.
4. Call dbif_open to finally open the CNID database itself. Pass db_param here for in-memory database.

Querying the CNID database

Call dbif_[get|pget|put|del]. They map to the corresponding BerkeleyDB calls with the same names.

Transactions

We use AUTO_COMMIT for the BDB database accesses. This avoids explicit transactions for every bdb access which speeds up reads. But in order to be able to rollback in case of errors we start a transaction once we encounter the first write from dbif_put or dbif_del. Thus you shouldn't call dbif_txn_[begin|abort|commit], they're used internally.

Checkpoiting

Call dbif_txn_checkpoint.

Closing

Call dbif_close.

Silent Upgrade Support

On cnid_dbd shutdown we reopen the environment with recovery, close and then remove it. This enables an upgraded netatalk installation possibly linked against a newer bdb lib to succesfully open/create an environment and then silently upgrade the database itself. How nice!

Macro Definition Documentation

DBIF_CNID

#define DBIF_CNID   0

DBIF_DB_CNT

#define DBIF_DB_CNT   4

DBIF_IDX_DEVINO

#define DBIF_IDX_DEVINO   1

DBIF_IDX_DIDNAME

#define DBIF_IDX_DIDNAME   2

DBIF_IDX_NAME

#define DBIF_IDX_NAME   3

LOCK_EXCL

#define LOCK_EXCL   2

LOCK_FREE

#define LOCK_FREE   0

LOCK_SHRD

#define LOCK_SHRD   3

LOCK_UNLOCK

#define LOCK_UNLOCK   1

LOCKFILENAME

#define LOCKFILENAME   "lock"

Function Documentation

dbif_close()

int dbif_close

(

DBD *

dbd

)

dbif_copy_rootinfokey()

int dbif_copy_rootinfokey	(	DBD *	srcdbd,
		DBD *	destdbd )

dbif_count()

int dbif_count	(	DBD *	dbd,
		const int	dbi,
		uint32_t *	count )

dbif_del()

int dbif_del	(	DBD *	dbd,
		const int	dbi,
		DBT *	key,
		uint32_t	flags )

dbif_dump()

int dbif_dump	(	DBD *	dbd,
		int	dumpindexes )

dbif_env_open()

int dbif_env_open	(	DBD *	dbd,
		struct db_param *	dbp,
		uint32_t	dbenv_oflags )

We must open the db_env with an absolute pathname, as 'dbd' keeps chdir'ing, which breaks e.g. bdb logfile-rotation with relative pathnames. But still we use relative paths with DB_ERRLOGFILE in order to avoid creating absolute paths by copying. Both have no problem with a relative path.

dbif_env_remove()

int dbif_env_remove

(

const char *

path

)

dbif_get()

int dbif_get	(	DBD *	dbd,
		const int	dbi,
		DBT *	key,
		DBT *	val,
		uint32_t	flags )

dbif_idwalk()

int dbif_idwalk	(	DBD *	dbd,
		cnid_t *	cnid,
		int	close )

Iterates over dbd, returning cnids.

Uses in-value of cnid to seek to that cnid, then gets next and return that in cnid. If close=1, close cursor.

Returns

-1 on error, 0 on EOD (end-of-database), 1 if returning cnid.

dbif_init()

DBD * dbif_init	(	const char *	envhome,
		const char *	dbname )

dbif_open()

int dbif_open	(	DBD *	dbd,
		struct db_param *	dbp,
		int	reindex )

dbif_pget()

int dbif_pget	(	DBD *	,
		const int	,
		DBT *	,
		DBT *	,
		DBT *	,
		uint32_t	)

dbif_put()

int dbif_put	(	DBD *	dbd,
		const int	dbi,
		DBT *	key,
		DBT *	val,
		uint32_t	flags )

dbif_search()

int dbif_search	(	DBD *	dbd,
		DBT *	key,
		char *	resbuf,
		uint32_t	offset,
		bool *	more )

Paginated substring cursor scan over the name index.

Skips offset matching entries before emitting up to DBD_MAX_SRCH_RSLTS results into resbuf. After the buffer fills, continues until the next matching entry to decide whether further matches exist; reports the result via more.

The caller MUST keep a separate backup of the original name bytes because BDB takes ownership of key->data after each pget() call.

Parameters

[in]	dbd	database handle
[in]	key	initialised with the search name (key->data, key->size)
[out]	resbuf	buffer for matching CNIDs in network byte order, must have capacity for DBD_MAX_SRCH_RSLTS * sizeof(cnid_t) bytes
[in]	offset	number of leading matches to skip, range 0..DBD_SEARCH_MAX_OFFSET
[out]	more	set to true iff a (offset + DBD_MAX_SRCH_RSLTS + 1)-th matching entry exists in the index, false otherwise. MUST be non-NULL.

Returns

-1 on BDB engine error, else the number of matches written to resbuf (0..DBD_MAX_SRCH_RSLTS)

dbif_txn_abort()

int dbif_txn_abort

(

DBD *

dbd

)

dbif_txn_begin()

int dbif_txn_begin

(

DBD *

dbd

)

dbif_txn_checkpoint()

int dbif_txn_checkpoint	(	DBD *	dbd,
		uint32_t	kbyte,
		uint32_t	min,
		uint32_t	flags )

dbif_txn_close()

int dbif_txn_close	(	DBD *	dbd,
		int	ret )

Close a transaction based on ret code.

Switch between commit+abort

Note

ret = 1 -> commit txn if db_param.txn_frequency

ret = 0 -> abort txn db_param.txn_frequency -> exit!

anything else -> exit!

Returns

0 on success (abort or commit), -1 on error

dbif_txn_commit()

int dbif_txn_commit

(

DBD *

dbd

)