FreeBSD Manual Pages
RELIC(3) Quick Database Manager RELIC(3) NAME Relic - the NDBM-compatible API of QDBM SYNOPSIS #include <relic.h> #include <stdlib.h> #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> typedef struct { void *dptr; size_t dsize; } datum; DBM *dbm_open(char *name, int flags, int mode); void dbm_close(DBM *db); int dbm_store(DBM *db, datum key, datum content, int flags); int dbm_delete(DBM *db, datum key); datum dbm_fetch(DBM *db, datum key); datum dbm_firstkey(DBM *db); datum dbm_nextkey(DBM *db); int dbm_error(DBM *db); int dbm_clearerr(DBM *db); int dbm_rdonly(DBM *db); int dbm_dirfno(DBM *db); int dbm_pagfno(DBM *db); DESCRIPTION Relic is the API which is compatible with NDBM. So, Relic wraps func- tions of Depot as API of NDBM. It is easy to port an application from NDBM to QDBM. In most cases, you should only replace the includings of `ndbm.h' with `relic.h' and replace the linking option `-lndbm' with `-lqdbm'. The original NDBM treats a database as a pair of files. One, `a direc- tory file', has a name with suffix `.dir' and stores a bit map of keys. The other, `a data file', has a name with suffix `.pag' and stores en- tities of each records. Relic creates the directory file as a mere dummy file and creates the data file as a database. Relic has no re- striction about the size of each record. Relic cannot handle database files made by the original NDBM. In order to use Relic, you should include `relic.h', `stdlib.h', `sys/types.h', `sys/stat.h' and `fcntl.h' in the source files. Usu- ally, the following description will be near the beginning of a source file. #include <relic.h> #include <stdlib.h> #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> A pointer to `DBM' is used as a database handle. A database handle is opened with the function `dbm_open' and closed with `dbm_close'. You should not refer directly to any member of a handle. Structures of `datum' type is used in order to give and receive data of keys and values with functions of Relic. typedef struct { void *dptr; size_t dsize; } datum; `dptr' specifies the pointer to the region of a key or a value. `dsize' specifies the size of the region. The function `dbm_open' is used in order to get a database handle. DBM *dbm_open(char *name, int flags, int mode); `name' specifies the name of a database. The file names are concatenated with suffixes. `flags' is the same as one of `open' call, although `O_WRONLY' is treated as `O_RDWR' and ad- ditional flags except for `O_CREAT' and `O_TRUNC' have no ef- fect. `mode' specifies the mode of the database file as one of `open' call does. The return value is the database handle or `NULL' if it is not successful. The function `dbm_close' is used in order to close a database handle. void dbm_close(DBM *db); `db' specifies a database handle. Because the region of the closed handle is released, it becomes impossible to use the han- dle. The function `dbm_store' is used in order to store a record. int dbm_store(DBM *db, datum key, datum content, int flags); `db' specifies a database handle. `key' specifies a structure of a key. `content' specifies a structure of a value. `flags' specifies behavior when the key overlaps, by the following val- ues: `DBM_REPLACE', which means the specified value overwrites the existing one, `DBM_INSERT', which means the existing value is kept. The return value is 0 if it is successful, 1 if it gives up because of overlaps of the key, -1 if other error oc- curs. The function `dbm_delete' is used in order to delete a record. int dbm_delete(DBM *db, datum key); `db' specifies a database handle. `key' specifies a structure of a key. The return value is 0 if it is successful, -1 if some errors occur. The function `dbm_fetch' is used in order to retrieve a record. datum dbm_fetch(DBM *db, datum key); `db' specifies a database handle. `key' specifies a structure of a key. The return value is a structure of the result. If a record corresponds, the member `dptr' of the structure is the pointer to the region of the value. If no record corresponds or some errors occur, `dptr' is `NULL'. `dptr' points to the re- gion related with the handle. The region is available until the next time of calling this function with the same handle. The function `dbm_firstkey' is used in order to get the first key of a database. datum dbm_firstkey(DBM *db); `db' specifies a database handle. The return value is a struc- ture of the result. If a record corresponds, the member `dptr' of the structure is the pointer to the region of the first key. If no record corresponds or some errors occur, `dptr' is `NULL'. `dptr' points to the region related with the handle. The region is available until the next time of calling this function or the function `dbm_nextkey' with the same handle. The function `dbm_nextkey' is used in order to get the next key of a database. datum dbm_nextkey(DBM *db); `db' specifies a database handle. The return value is a struc- ture of the result. If a record corresponds, the member `dptr' of the structure is the pointer to the region of the next key. If no record corresponds or some errors occur, `dptr' is `NULL'. `dptr' points to the region related with the handle. The region is available until the next time of calling this function or the function `dbm_firstkey' with the same handle. The function `dbm_error' is used in order to check whether a database has a fatal error or not. int dbm_error(DBM *db); `db' specifies a database handle. The return value is true if the database has a fatal error, false if not. The function `dbm_clearerr' has no effect. int dbm_clearerr(DBM *db); `db' specifies a database handle. The return value is 0. The function is only for compatibility. The function `dbm_rdonly' is used in order to check whether a handle is read-only or not. int dbm_rdonly(DBM *db); `db' specifies a database handle. The return value is true if the handle is read-only, or false if not read-only. The function `dbm_dirfno' is used in order to get the file descriptor of a directory file. int dbm_dirfno(DBM *db); `db' specifies a database handle. The return value is the file descriptor of the directory file. The function `dbm_pagfno' is used in order to get the file descriptor of a data file. int dbm_pagfno(DBM *db); `db' specifies a database handle. The return value is the file descriptor of the data file. Functions of Relic are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe. SEE ALSO qdbm(3), depot(3), curia(3), hovel(3), cabin(3), villa(3), odeum(3), ndbm(3), gdbm(3) Man Page 2004-04-22 RELIC(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=relic&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>