netatalk: dbif.h File Reference

netatalk 4.5.1
Free and Open Source Apple Filing Protocol (AFP) Server
Loading...
Searching...
No Matches
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 | ) |