aboutsummaryrefslogtreecommitdiff
path: root/_db1.85/man/ndbm.3
diff options
context:
space:
mode:
Diffstat (limited to '_db1.85/man/ndbm.3')
-rw-r--r--_db1.85/man/ndbm.3209
1 files changed, 209 insertions, 0 deletions
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