From 38e876d964346d3e4b88c52732b7ce5966d796a5 Mon Sep 17 00:00:00 2001 From: Dimitri Sokolyuk Date: Thu, 1 Nov 2018 13:35:40 +0100 Subject: import original 1.85 implementation from openbsd libc --- _db1.85/man/ndbm.3 | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 _db1.85/man/ndbm.3 (limited to '_db1.85/man/ndbm.3') diff --git a/_db1.85/man/ndbm.3 b/_db1.85/man/ndbm.3 new file mode 100644 index 0000000..9cdaed3 --- /dev/null +++ b/_db1.85/man/ndbm.3 @@ -0,0 +1,209 @@ +.\" David Leonard, 1998. Placed in the public domain. +.\" $OpenBSD: ndbm.3,v 1.20 2016/05/07 23:35:45 naddy Exp $ +.Dd $Mdocdate: May 7 2016 $ +.Dt DBM_OPEN 3 +.Os +.Sh NAME +.Nm dbm_clearerr , +.Nm dbm_close , +.Nm dbm_delete , +.Nm dbm_dirfno , +.Nm dbm_error , +.Nm dbm_fetch , +.Nm dbm_firstkey , +.Nm dbm_nextkey , +.Nm dbm_open , +.Nm dbm_pagfno , +.Nm dbm_rdonly , +.Nm dbm_store +.Nd database access methods +.Sh SYNOPSIS +.In ndbm.h +.Ft int +.Fn dbm_clearerr "DBM *db" +.Ft void +.Fn dbm_close "DBM *db" +.Ft int +.Fn dbm_delete "DBM *db" "datum key" +.Ft int +.Fn dbm_dirfno "DBM *db" +.Ft int +.Fn dbm_error "DBM *db" +.Ft datum +.Fn dbm_fetch "DBM *db" "datum key" +.Ft datum +.Fn dbm_firstkey "DBM *db" +.Ft datum +.Fn dbm_nextkey "DBM *db" +.Ft "DBM *" +.Fn dbm_open "const char *file" "int flags" "mode_t mode" +.Ft int +.Fn dbm_pagfno "DBM *db" +.Ft int +.Fn dbm_rdonly "DBM *db" +.Ft int +.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode" +.Sh DESCRIPTION +These functions provide a ndbm-compatible interface to the +database access methods described in +.Xr dbopen 3 . +Each unique record in the database is a key/content pair, +the components of which may be any arbitrary binary data. +The key and the content data are described by the +.Ft datum +data structure: +.Bd -literal -offset indent +typedef struct { + void *dptr; + size_t dsize; +} datum; +.Ed +.Pp +The +.Fn dbm_open +function is used to open a database in the file named by +.Fa file , +suffixed with +.Dv DBM_SUFFIX +.Pq Sq Pa .db . +If necessary, the file is created with mode +.Ar mode . +Access to this file depends on the +.Fa flags +parameter (see +.Xr open 2 ) . +Read-only access may be indicated by specifying +.Dv DBM_RDONLY . +The +.Fn dbm_rdonly +function may be used to determine if a database is opened for read-only +access. +.Pp +Once the database is open, +.Fn dbm_fetch +is used to retrieve the data content associated with the key +.Fa key . +Similarly, +.Fn dbm_store +is used to store the +.Fa content +data with the key +.Fa key . +When storing, the +.Fa store_mode +parameter must be one of: +.Bl -tag -width DBM_REPLACE -offset indent +.It Dv DBM_INSERT +Only insert new keys into the database. +Existing key/content pairs are untouched. +.It Dv DBM_REPLACE +Replace any existing entry with the same key. +Any previously stored records with the same key are lost. +.El +.Pp +The +.Fn dbm_delete +function removes the key +.Fa key +and its associated content from the database. +.Pp +The functions +.Fn dbm_firstkey +and +.Fn dbm_nextkey +are used to iterate over all of the records in the database. +Each record will be reached exactly once, but in no particular order. +The +.Fn dbm_firstkey +function returns the first record of the database, and thereafter +.Fn dbm_nextkey +returns the following records. +The following code traverses the entire database: +.Bd -literal -offset indent +for (key = dbm_firstkey(db); key.dptr != NULL; + key = dbm_nextkey(db)) +.Ed +.Pp +The behaviour of +.Fn dbm_nextkey +is undefined if the database is modified after a call to +.Fn dbm_firstkey . +.Pp +The +.Fn dbm_error +function returns the last error condition of the database, +or 0 if no error had occurred or had been cleared. +The +.Fn dbm_clearerr +function clears the error condition of the database. +.Pp +The +.Fn dbm_dirfno +function is used to find the file descriptor associated with the +directory file of an open database. +Since a directory bitmap file is not used in this implementation, +this function returns the file descriptor of the database file opened with +.Fn dbm_open . +.Pp +The +.Fn dbm_pagfno +function is used to find the file descriptor associated with the +page file of an open database. +Since a page file is not used in this implementation, this function +is implemented as a macro that always returns the (undefined) value +.Dv DBM_PAGFNO_NOT_AVAILABLE . +.Pp +The database is closed with the +.Fn dbm_close +function. +Thereafter, the +.Fa db +handle is invalid. +.Ss Implementation notes +The underlying database is a +.Xr hash 3 +database with a +bucket size of 4096, +a filling factor of 40, +default hashing function and cache size, +and uses the host's native byte order. +.Sh RETURN VALUES +Upon successful completion, all functions that return +.Ft int +return a value of 0, otherwise a negative value is returned. +.Pp +Routines that return a +.Ft datum +indicate errors by setting the +.Va dptr +field to +.Dv NULL . +.Pp +The +.Fn dbm_open +function returns +.Dv NULL +on error, and sets +.Va errno +appropriately. +On success, it returns a handle to the database that should be +used as the +.Fa db +argument in the other functions. +.Pp +The +.Fn dbm_store +function returns 1 when it is called with a +.Fa flags +value of +.Dv DBM_INSERT +and a record with the specified key already exists. +.Sh ERRORS +If an error occurs, the error can be retrieved with +.Fn dbm_error +and corresponds to those errors described in +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr open 2 , +.Xr dbopen 3 , +.Xr hash 3 -- cgit v1.2.3