From: aaron Date: Tue, 18 Apr 2000 02:31:31 +0000 (+0000) Subject: Repairs. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=8333266543811e551513d767020f31b854889d1b;p=openbsd Repairs. --- diff --git a/lib/libc/compat-43/getdtablesize.3 b/lib/libc/compat-43/getdtablesize.3 index 01a034b86ca..24a8371758b 100644 --- a/lib/libc/compat-43/getdtablesize.3 +++ b/lib/libc/compat-43/getdtablesize.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: getdtablesize.3,v 1.7 1999/05/23 14:10:57 aaron Exp $ +.\" $OpenBSD: getdtablesize.3,v 1.8 2000/04/18 02:31:31 aaron Exp $ .\" .Dd March 10, 1991 .Dt GETDTABLESIZE 3 @@ -43,7 +43,8 @@ .Fn getdtablesize void .Sh DESCRIPTION Each process has a fixed size descriptor table, -which is guaranteed to have at least 20 slots. The entries in +which is guaranteed to have at least 20 slots. +The entries in the descriptor table are numbered with small integers starting at 0. The call .Fn getdtablesize diff --git a/lib/libc/compat-43/gethostid.3 b/lib/libc/compat-43/gethostid.3 index 638427de545..4fc2d411a29 100644 --- a/lib/libc/compat-43/gethostid.3 +++ b/lib/libc/compat-43/gethostid.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: gethostid.3,v 1.7 2000/04/15 11:46:01 aaron Exp $ +.\" $OpenBSD: gethostid.3,v 1.8 2000/04/18 02:31:31 aaron Exp $ .\" .Dd June 2, 1993 .Dt GETHOSTID 3 @@ -45,12 +45,14 @@ .Ft int .Fn sethostid "long hostid" .Sh DESCRIPTION +The .Fn sethostid -establishes a 32-bit identifier for the +function establishes a 32-bit identifier for the current processor that is intended to be unique among all -UNIX systems in existence. This is normally a DARPA Internet -address for the local machine. This call is allowed only to the -superuser and is normally performed at boot time. +UNIX systems in existence. +This is normally a DARPA Internet address for the local machine. +This call is allowed only to the +superuser and is normally performed at boot-time. .Pp .Fn gethostid returns the 32-bit identifier for the current processor. diff --git a/lib/libc/compat-43/killpg.3 b/lib/libc/compat-43/killpg.3 index 928f188c4d0..7ffe3f5c569 100644 --- a/lib/libc/compat-43/killpg.3 +++ b/lib/libc/compat-43/killpg.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: killpg.3,v 1.7 2000/04/15 11:46:01 aaron Exp $ +.\" $OpenBSD: killpg.3,v 1.8 2000/04/18 02:31:32 aaron Exp $ .\" .Dd March 10, 1991 .Dt KILLPG 3 @@ -62,8 +62,8 @@ the sender must be the superuser. As a single special case the continue signal SIGCONT may be sent to any process that is a descendant of the current process. .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -a value of \-1 is returned and the global variable +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/compat-43/setregid.3 b/lib/libc/compat-43/setregid.3 index cc88faf7850..4a3ab592e52 100644 --- a/lib/libc/compat-43/setregid.3 +++ b/lib/libc/compat-43/setregid.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: setregid.3,v 1.7 2000/04/15 11:46:01 aaron Exp $ +.\" $OpenBSD: setregid.3,v 1.8 2000/04/18 02:31:32 aaron Exp $ .\" .Dd March 10, 1991 .Dt SETREGID 3 @@ -56,7 +56,8 @@ The .Fn setregid function was intended to allow swapping the real and effective group IDs in set-group-ID programs to temporarily relinquish -the set-group-ID value. This function did not work correctly, and its +the set-group-ID value. +This function did not work correctly, and its purpose is now better served by the use of the .Fn setegid function (see @@ -67,8 +68,8 @@ standard .Fn setgid function is preferred. .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -a value of \-1 is returned and +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/compat-43/setreuid.3 b/lib/libc/compat-43/setreuid.3 index 72e0408d075..2c031b31d74 100644 --- a/lib/libc/compat-43/setreuid.3 +++ b/lib/libc/compat-43/setreuid.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: setreuid.3,v 1.7 2000/04/15 11:46:01 aaron Exp $ +.\" $OpenBSD: setreuid.3,v 1.8 2000/04/18 02:31:32 aaron Exp $ .\" .Dd March 10, 1991 .Dt SETREUID 3 @@ -57,7 +57,8 @@ The .Fn setreuid function has been used to swap the real and effective user IDs in set-user-ID programs to temporarily relinquish the set-user-ID -value. This purpose is now better served by the use of the +value. +This purpose is now better served by the use of the .Fn seteuid function (see .Xr setuid 2 ) . @@ -66,8 +67,8 @@ When setting the real and effective user IDs to the same value, the standard .Fn setuid function is preferred. .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -a value of \-1 is returned and +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/compat-43/sigvec.3 b/lib/libc/compat-43/sigvec.3 index 02d1ada17fb..450a1f9dfc1 100644 --- a/lib/libc/compat-43/sigvec.3 +++ b/lib/libc/compat-43/sigvec.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: sigvec.3,v 1.16 2000/01/22 12:05:48 aaron Exp $ +.\" $OpenBSD: sigvec.3,v 1.17 2000/04/18 02:31:32 aaron Exp $ .\" .Dd April 29, 1991 .Dt SIGVEC 3 @@ -58,7 +58,8 @@ This interface is made obsolete by The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurrence of a hardware interrupt: the signal is blocked from further occurrence, the current process -context is saved, and a new one is built. A process may specify a +context is saved, and a new one is built. +A process may specify a .Em handler to which a signal is delivered, or specify that a signal is to be .Em blocked @@ -73,7 +74,8 @@ in which case its delivery is postponed until it is The action to be taken on delivery is determined at the time of delivery. Normally, signal handlers execute on the current stack -of the process. This may be changed, on a per-handler basis, +of the process. +This may be changed, on a per-handler basis, so that signals are taken on a special .Em "signal stack" . .Pp @@ -86,9 +88,10 @@ but other signals may yet occur. A global .Em "signal mask" defines the set of signals currently blocked from delivery -to a process. The signal mask for a process is initialized -from that of its parent (normally 0). It -may be changed with a +to a process. +The signal mask for a process is initialized +from that of its parent (normally 0). +It may be changed with a .Xr sigblock 3 or .Xr sigsetmask 3 @@ -96,13 +99,15 @@ call, or when a signal is delivered to the process. .Pp When a signal condition arises for a process, the signal is added to a set of -signals pending for the process. If the signal is not currently +signals pending for the process. +If the signal is not currently .Em blocked by the process then it is delivered to the process. When a caught signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), -and the signal handler is invoked. The call to the handler +and the signal handler is invoked. +The call to the handler is arranged so that if the signal handling routine returns normally the process will resume execution in the context from before the signal's delivery. @@ -121,7 +126,8 @@ the signal to be delivered, and the signal mask associated with the handler to be invoked. .Pp .Fn sigvec -assigns a handler for a specific signal. If +assigns a handler for a specific signal. +If .Fa vec is non-zero, it specifies an action @@ -277,8 +283,8 @@ flag is not available in .Bx 4.2 , hence it should not be used if backward compatibility is needed. .Sh RETURN VALUES -A 0 value indicated that the call succeeded. A \-1 return value -indicates an error occurred and +A 0 value indicated that the call succeeded. +A \-1 return value indicates an error occurred and .Va errno is set to indicated the reason. .Sh ERRORS diff --git a/lib/libc/crypt/arc4random.3 b/lib/libc/crypt/arc4random.3 index f4116a1e826..2bf63eca726 100644 --- a/lib/libc/crypt/arc4random.3 +++ b/lib/libc/crypt/arc4random.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: arc4random.3,v 1.13 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: arc4random.3,v 1.14 2000/04/18 02:31:34 aaron Exp $ .\" .\" Copyright 1997 Niels Provos .\" All rights reserved. @@ -50,8 +50,8 @@ The .Fn arc4random function uses the key stream generator employed by the -arc4 cipher, which uses 8*8 8 bit S-Boxes. The S-Boxes -can be in about (2**1700) states. +arc4 cipher, which uses 8*8 8 bit S-Boxes. +The S-Boxes can be in about (2**1700) states. .Pp The .Fn arc4random_stir @@ -74,8 +74,8 @@ automatically initializes itself. .Sh HISTORY An algorithm call .Pa RC4 -was designed by RSA Data Security, Inc. It was considered a trade secret, -but not trademarked. +was designed by RSA Data Security, Inc. +It was considered a trade secret, but not trademarked. A clone of this was posted anonymously to the USENET and was confirmed to be equivalent by several sources who had access to the original cipher. Because of the trade secret situation, RSA Data Security, Inc. can do diff --git a/lib/libc/crypt/blowfish.3 b/lib/libc/crypt/blowfish.3 index b5fdae92b19..6d8c5db88d9 100644 --- a/lib/libc/crypt/blowfish.3 +++ b/lib/libc/crypt/blowfish.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: blowfish.3,v 1.8 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: blowfish.3,v 1.9 2000/04/18 02:31:34 aaron Exp $ .\" .\" Copyright 1997 Niels Provos .\" All rights reserved. @@ -63,7 +63,8 @@ The block size is 64 bit and the key size is maximal 448 bit. The .Fn blf_key function initializes the 4 8bit S-boxes and the 18 Subkeys with -the hexadecimal digits of Pi. The key is used for further randomization. +the hexadecimal digits of Pi. +The key is used for further randomization. The first argument to .Fn blf_enc is the initialized state derived from diff --git a/lib/libc/crypt/crypt.3 b/lib/libc/crypt/crypt.3 index daa9c4d844a..36058c75671 100644 --- a/lib/libc/crypt/crypt.3 +++ b/lib/libc/crypt/crypt.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: crypt.3,v 1.15 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: crypt.3,v 1.16 2000/04/18 02:31:34 aaron Exp $ .\" .\" FreeSec: libcrypt .\" @@ -56,24 +56,32 @@ .Sh DESCRIPTION The .Fn crypt -function performs password encryption, based on the +function performs password encryption based on the .Tn NBS Data Encryption Standard (DES). Additional code has been added to deter key search attempts and to use stronger hashing algorithms. +.Pp The first argument to .Fn crypt is a .Dv null Ns -terminated string, typically a user's typed password. The second is in one of three forms: -if it begins with an underscore (``_'') then an extended format is used -in interpreting both the key and the setting, as outlined below. If it begins -with an string character (``$'') and a number then a different algorithm -is used depending on the number. At the moment a ``$1'' chooses MD5 hashing -and a ``$2'' chooses Blowfish hashing, see below for more information. -.Ss Extended crypt: -.Pp +if it begins with an underscore +.Pq Ql _ +then an extended format is used +in interpreting both the key and the setting, as outlined below. +If it begins +with a string character +.Pq Ql $ +and a number then a different algorithm is used depending on the number. +At the moment a +.Ql $1 +chooses MD5 hashing and a +.Ql $2 +chooses Blowfish hashing; see below for more information. +.Ss Extended crypt The .Ar key is divided into groups of 8 characters (the last group is null-padded) @@ -87,61 +95,68 @@ The setting is a 9-character array consisting of an underscore followed by 4 bytes of iteration count and 4 bytes of salt. These are encoded as printable characters, 6 bits per character, least significant character first. -The values 0 to 63 are encoded as ``./0-9A-Za-z''. +The values 0 to 63 are encoded as +.Dq \&./0-9A-Za-z . This allows 24 bits for both .Fa count and .Fa salt . -.Ss "MD5" crypt: -.Pp +.Ss "MD5" crypt For .Tn MD5 crypt the version number, .Fa salt -and the hashed password are separated -by the ``$'' character. The maximum length of a password is limited by +and the hashed password are separated by the +.Ql $ +character. +The maximum length of a password is limited by the length counter of the MD5 context, which is about -2**64. A valid MD5 password entry looks like this: +2**64. +A valid MD5 password entry looks like this: .Pp -``$1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1''. +.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 . .Pp The whole MD5 password string is passed as .Fa setting for interpretation. -.Ss "Blowfish" crypt: -.Pp +.Ss "Blowfish" crypt The .Tn Blowfish version of crypt has 128 bits of .Fa salt -in order to make building -dictionaries of common passwords space consuming. The initial state -of the +in order to make building dictionaries of common passwords space consuming. +The initial state of the .Tn Blowfish cipher is expanded using the .Fa salt and the .Fa password repeating the process a variable number of rounds, which is encoded in -the password string. The maximum password length is 72. The final Blowfish -password entry is created by encrypting -the string ``OrpheanBeholderScryDoubt'' with the +the password string. +The maximum password length is 72. +The final Blowfish password entry is created by encrypting the string +.Pp +.Dq OrpheanBeholderScryDoubt +.Pp +with the .Tn Blowfish state 64 times. .Pp The version number, the logarithm of the number of rounds and -the concatenation of salt and -hashed password are separated by the ``$'' character. An encoded ``8'' +the concatenation of salt and hashed password are separated by the +.Ql $ +character. +An encoded +.Sq 8 would specify 256 rounds. A valid Blowfish password looks like this: .Pp -``$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC''. +.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC . .Pp The whole Blowfish password string is passed as .Fa setting for interpretation. -.Ss "Traditional" crypt: -.Pp +.Ss "Traditional" crypt The first 8 bytes of the key are null-padded, and the low-order 7 bits of each character is used to form the 56-bit .Tn DES @@ -153,8 +168,7 @@ Thus only 12 bits of are used. .Fa count is set to 25. -.Ss DES Algorithm: -.Pp +.Ss DES Algorithm The .Fa salt introduces disorder in the @@ -182,10 +196,10 @@ string, 20 or 13 bytes (plus null) in length, consisting of the .Ar setting followed by the encoded 64-bit encryption. .Pp -The functions, +The functions .Fn encrypt , .Fn setkey , -.Fn des_setkey +.Fn des_setkey , and .Fn des_cipher provide access to the @@ -243,7 +257,9 @@ E-box output as described above. .Pp The function .Fn crypt -returns a pointer to the encrypted value on success, and NULL on failure. +returns a pointer to the encrypted value on success, and +.Dv NULL +on failure. The functions .Fn setkey , .Fn encrypt , @@ -254,7 +270,7 @@ return 0 on success and 1 on failure. .Pp The .Fn crypt , -.Fn setkey +.Fn setkey , and .Fn des_setkey functions all manipulate the same key space. @@ -265,12 +281,8 @@ functions all manipulate the same key space. .Xr getpass 3 , .Xr md5 3 , .Xr passwd 5 -.Sh BUGS -The -.Fn crypt -function returns a pointer to static data, and subsequent calls to -.Fn crypt -will modify the same object. +.Sh AUTHOR +David Burren .Sh HISTORY A rotor-based .Fn crypt @@ -289,9 +301,14 @@ Programs linked against the interface may be exported from the U.S.A. only if they use .Fn crypt solely for authentication purposes and avoid use of -the other programmer interfaces listed above. Special care has been taken +the other programmer interfaces listed above. +Special care has been taken in the library so that programs which only use the .Fn crypt interface do not pull in the other components. -.Sh AUTHOR -David Burren +.Sh BUGS +The +.Fn crypt +function returns a pointer to static data, and subsequent calls to +.Fn crypt +will modify the same object. diff --git a/lib/libc/db/man/btree.3 b/lib/libc/db/man/btree.3 index 097f529ebf3..b85ad22786b 100644 --- a/lib/libc/db/man/btree.3 +++ b/lib/libc/db/man/btree.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: btree.3,v 1.13 2000/03/14 21:31:39 aaron Exp $ +.\" $OpenBSD: btree.3,v 1.14 2000/04/18 02:31:35 aaron Exp $ .\" $NetBSD: btree.3,v 1.6 1996/05/03 21:26:48 cgd Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. @@ -46,9 +46,9 @@ .Fd #include .Fd #include .Sh DESCRIPTION -The routine +The .Fn dbopen -is the library interface to database files. +routine is the library interface to database files. One of the supported file formats is btree files. The general description of the database access methods is in .Xr dbopen 3 . @@ -60,7 +60,7 @@ associated key/data pairs. The btree access method specific data structure provided to .Fn dbopen is defined in the -.Em +.Aq Pa db.h include file as follows: .Pp .Bl -item -compact @@ -90,7 +90,7 @@ int lorder; .Pp The elements of this structure are as follows: .Bl -tag -width "XXXXXX" -.It flags +.It Fa flags The flag value is specified by .Tn OR Ns 'ing any of the following values: @@ -123,7 +123,7 @@ routine calls with the flag set will always return the logical ``first'' of any group of duplicate keys. .El -.It cachesize +.It Fa cachesize A suggested maximum size (in bytes) of the memory cache. This value is .Em only @@ -137,56 +137,60 @@ corruption or lost data if the system crashes while a tree is being modified. If .Fa cachesize is 0 (no size is specified) a default cache is used. -.It maxkeypage +.It Fa maxkeypage The maximum number of keys which will be stored on any single page. Not currently implemented. -.It minkeypage +.It Fa minkeypage The minimum number of keys which will be stored on any single page. This value is used to determine which keys will be stored on overflow pages, i.e., if a key or data item is longer than the pagesize divided by the minkeypage value, it will be stored on overflow pages instead -of in the page itself. If +of in the page itself. +If .Fa minkeypage is 0 (no minimum number of keys is specified) a value of 2 is used. -.It psize +.It Fa psize Page size is the size (in bytes) of the pages used for nodes in the tree. The minimum page size is 512 bytes and the maximum page size is 64K. If .Fa psize is 0 (no page size is specified) a page size is chosen based on the underlying file system I/O block size. -.It compare +.It Fa compare Compare is the key comparison function. It must return an integer less than, equal to, or greater than zero if the first key argument is considered to be respectively less than, equal to, or greater than the second key argument. The same comparison function must be used on a given tree every time it is opened. +If .Fa compare is .Dv NULL (no comparison function is specified), the keys are compared lexically, with shorter keys considered less than longer keys. -.It prefix +.It Fa prefix Prefix is the prefix comparison function. If specified, this routine must return the number of bytes of the second key argument which are necessary to determine that it is greater than the first key argument. If the keys are equal, the key length should be returned. -Note, the usefulness of this routine is very data dependent, but, in some -data sets can produce significantly reduced tree sizes and search times. If +Note, the usefulness of this routine is very data dependent, but in some +data sets can produce significantly reduced tree sizes and search times. +If .Fa prefix is .Dv NULL (no prefix function is specified), .Em and no comparison function is specified, a default lexical comparison routine -is used. If +is used. +If .Fa prefix is .Dv NULL and a comparison routine is specified, no prefix comparison is done. -.It lorder +.It Fa lorder The byte order for integers in the stored database metadata. The number should represent the order as an integer; for example, big endian order would be the number 4,321. @@ -198,8 +202,12 @@ is 0 (no order is specified) the current host order is used. If the file already exists (and the .Dv O_TRUNC flag is not specified), the -values specified for the parameters flags, lorder and psize are ignored -in favor of the values used when the tree was created. +values specified for the parameters +.Fa flags , +.Fa lorder , +and +.Fa psize +are ignored in favor of the values used when the tree was created. .Pp Forward sequential scans of a tree are from the least key to the greatest. .Pp diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3 index 17d1c4628ad..3246d58b1bd 100644 --- a/lib/libc/db/man/dbm.3 +++ b/lib/libc/db/man/dbm.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: dbm.3,v 1.5 1999/07/07 10:50:04 aaron Exp $ +.\" $OpenBSD: dbm.3,v 1.6 2000/04/18 02:31:35 aaron Exp $ .\" .\" Copyright (c) 1999 Todd C. Miller .\" All rights reserved. @@ -29,14 +29,13 @@ .Dt DBM 3 .Os .Sh NAME -.Nm dbm , .Nm dbminit , +.Nm dbmclose , .Nm fetch , .Nm store , .Nm delete , .Nm firstkey , -.Nm nextkey , -.Nm dbmclose +.Nm nextkey .Nd database subroutines .Sh SYNOPSIS .Fd #include @@ -72,29 +71,34 @@ typedef struct { .Pp The .Fn dbminit -function is used to open a database. Before the call to +function is used to open a database. +Before the call to .Fn dbminit , the files -.Fa file.pag +.Pa file.pag and -.Fa file.dir -must exist. The user is responsible for creating the zero-length -\&.pag and .dir files. +.Pa file.dir +must exist. +The user is responsible for creating the zero-length +.Pa \&.pag +and +.Pa \&.dir +files. .Pp Once the database is open, .Fn fetch -is used to retrieve the data content associated with the key +is used to retrieve the data content associated with the specified .Fa key . Similarly, .Fn store is used to store the .Fa content -data with the key +data with the specified .Fa key . .Pp The .Fn delete -function removes the key +function removes the specified .Fa key and its associated content from the database. .Pp @@ -151,7 +155,8 @@ Because the routines are implemented on top of the .Xr db 3 , only a single file, -.Ar file.pag , -is used to actually store the database. The references to -.Ar file.dir +.Pa file.pag , +is used to actually store the database. +The references to +.Pa file.dir are purely for backwards compatibility with historic implementations. diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3 index 8f0f5c46ffb..cd7568670ce 100644 --- a/lib/libc/db/man/dbopen.3 +++ b/lib/libc/db/man/dbopen.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: dbopen.3,v 1.14 2000/03/14 21:31:39 aaron Exp $ +.\" $OpenBSD: dbopen.3,v 1.15 2000/04/18 02:31:35 aaron Exp $ .\" $NetBSD: dbopen.3,v 1.6 1995/02/27 13:23:25 cgd Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. @@ -50,9 +50,10 @@ .Ft DB * .Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" .Sh DESCRIPTION -.Nm -is the library interface to database files. -The supported file formats are btree, hashed and UNIX file oriented. +The +.Fn dbopen +function is the library interface to database files. +The supported file formats are btree, hashed, and UNIX file oriented. The btree format is a representation of a sorted, balanced tree structure. The hashed format is an extensible, dynamic hashing scheme. The flat-file format is a byte stream file with fixed or variable length @@ -64,7 +65,7 @@ in their respective manual pages and .Xr recno 3 . .Pp -.Nm +.Fn dbopen opens .Fa file for reading and/or writing. @@ -86,7 +87,7 @@ routine; however, only the .Dv O_NONBLOCK , .Dv O_RDONLY , .Dv O_RDWR , -.Dv O_SHLOCK +.Dv O_SHLOCK , and .Dv O_TRUNC flags are meaningful. @@ -117,10 +118,11 @@ The .Fa type argument is of type .Fa DBTYPE -(as defined in the include file) and -may be set to +(as defined in the +.Aq Pa db.h +include file) and may be set to .Dv DB_BTREE , -.Dv DB_HASH +.Dv DB_HASH , or .Dv DB_RECNO . .Pp @@ -135,11 +137,13 @@ is each access method will use defaults appropriate for the system and the access method. .Pp -.Nm +.Fn dbopen returns a pointer to a DB structure on success and .Dv NULL -on error. The DB structure is defined in the include file, -and contains at least the following fields: +on error. +The DB structure is defined in the +.Aq Pa db.h +include file, and contains at least the following fields: .Pp .Bl -item -compact typedef struct { @@ -169,13 +173,13 @@ int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); These elements describe a database type and a set of functions performing various actions. These functions take a pointer to a structure as returned by -.Nm dbopen , +.Fn dbopen dbopen , and sometimes one or more pointers to key/data structures and a flag value. .Pp .Bl -tag -width XXXXX -offset indent -.It type +.It Fa type The type of the underlying access method (and file format). -.It close +.It Fa close A pointer to a routine to flush any cached information to disk, free any allocated resources, and close the underlying file(s). Since key/data pairs may be cached in memory, failing to sync the file @@ -188,14 +192,14 @@ function may result in inconsistent or lost information. routines return \-1 on error (setting .Va errno ) and 0 on success. -.It del +.It Fa del A pointer to a routine to remove key/data pairs from the database. .Pp The parameter .Fa flag may be set to the following value: .Bl -tag -width XXXXX -.It R_CURSOR +.It Dv R_CURSOR Delete the record referenced by the cursor. The cursor must have previously been initialized. .El @@ -206,12 +210,12 @@ routines return \-1 on error (setting 0 on success, and 1 if the specified .Fa key was not in the file. -.It fd +.It Fa fd A pointer to a routine which returns a file descriptor representative of the underlying database. A file descriptor referencing the same file will be returned to all processes which call -.Nm +.Fn dbopen with the same .Fa file name. @@ -227,7 +231,7 @@ No file descriptor is available for in memory databases. routines return \-1 on error (setting .Va errno ) , and the file descriptor on success. -.It get +.It Fa get A pointer to a routine which is the interface for keyed retrieval from the database. The address and length of the data associated with the specified @@ -240,45 +244,61 @@ routines return \-1 on error (setting 0 on success, and 1 if the .Fa key was not in the file. -.It put +.It Fa put A pointer to a routine to store key/data pairs in the database. .Pp The parameter .Fa flag may be set to one of the following values: .Bl -tag -width XXXXX -.It R_CURSOR +.It Dv R_CURSOR Replace the key/data pair referenced by the cursor. The cursor must have previously been initialized. -.It R_IAFTER +.It Dv R_IAFTER Append the data immediately after the data referenced by .Fa key , creating a new key/data pair. The record number of the appended key/data pair is returned in the .Fa key structure. -(Applicable only to the DB_RECNO access method.) -.It R_IBEFORE +(Applicable only to the +.Dv DB_RECNO +access method.) +.It Dv R_IBEFORE Insert the data immediately before the data referenced by .Fa key , creating a new key/data pair. The record number of the inserted key/data pair is returned in the .Fa key structure. -(Applicable only to the DB_RECNO access method.) -.It R_NOOVERWRITE +(Applicable only to the +.Dv DB_RECNO +access method.) +.It Dv R_NOOVERWRITE Enter the new key/data pair only if the key does not previously exist. -.It R_SETCURSOR +.It Dv R_SETCURSOR Store the key/data pair, setting or initializing the position of the cursor to reference it. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) .El .Pp -R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access -methods because it implies that the keys have an inherent order +.Dv R_SETCURSOR +is available only for the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods because it implies that the keys have an inherent order which does not change. .Pp -R_IAFTER and R_IBEFORE are available only for the DB_RECNO +.Dv R_IAFTER +and +.Dv R_IBEFORE +are available only for the +.Dv DB_RECNO access method because they each imply that the access method is able to create new keys. This is only true if the keys are ordered and independent, record numbers @@ -292,10 +312,11 @@ existing key. .Fa put routines return \-1 on error (setting .Va errno ) , -0 on success, and 1 if the R_NOOVERWRITE +0 on success, and 1 if the +.Dv R_NOOVERWRITE .Fa flag was set and the key already exists in the file. -.It seq +.It Fa seq A pointer to a routine which is the interface for sequential retrieval from the database. The address and length of the key are returned in the structure @@ -307,7 +328,9 @@ by .Fa data . .Pp Sequential key/data pair retrieval may begin at any time, and the -position of the ``cursor'' is not affected by calls to the +position of the +.Dq cursor +is not affected by calls to the .Fa del , .Fa get , .Fa put , @@ -322,33 +345,53 @@ The flag value .Sy must be set to one of the following values: .Bl -tag -width XXXXX -.It R_CURSOR +.It Dv R_CURSOR The data associated with the specified key is returned. This differs from the .Fa get routines in that it sets or initializes the cursor to the location of the key as well. -(Note, for the DB_BTREE access method, the returned key is not necessarily an +(Note, for the +.Dv DB_BTREE +access method, the returned key is not necessarily an exact match for the specified key. The returned key is the smallest key greater than or equal to the specified key, permitting partial key matches and range searches.) -.It R_FIRST +.It Dv R_FIRST The first key/data pair of the database is returned, and the cursor is set or initialized to reference it. -.It R_LAST +.It Dv R_LAST The last key/data pair of the database is returned, and the cursor is set or initialized to reference it. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) -.It R_NEXT +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) +.It Dv R_NEXT Retrieve the key/data pair immediately after the cursor. -If the cursor is not yet set, this is the same as the R_FIRST flag. -.It R_PREV +If the cursor is not yet set, this is the same as the +.Dv R_FIRST +flag. +.It Dv R_PREV Retrieve the key/data pair immediately before the cursor. -If the cursor is not yet set, this is the same as the R_LAST flag. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) +If the cursor is not yet set, this is the same as the +.Dv R_LAST +flag. +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) .El .Pp -R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO +.Dv R_LAST +and +.Dv R_PREV +are available only for the +.Dv DB_BTREE +and +.Dv DB_RECNO access methods because they each imply that the keys have an inherent order which does not change. .Pp @@ -357,12 +400,14 @@ routines return \-1 on error (setting .Va errno ) , 0 on success and 1 if there are no key/data pairs less than or greater than the specified or current key. -If the DB_RECNO access method is being used, and if the database file +If the +.Dv DB_RECNO +access method is being used, and if the database file is a character special file and no complete key/data pairs are currently available, the .Fa seq routines return 2. -.It sync +.It Fa sync A pointer to a routine to flush any cached information to disk. If the database is in memory only, the .Fa sync @@ -370,8 +415,10 @@ routine has no effect and will always succeed. .Pp The flag value may be set to the following value: .Bl -tag -width XXXXX -.It R_RECNOSYNC -If the DB_RECNO access method is being used, this flag causes +.It Dv R_RECNOSYNC +If the +.Dv DB_RECNO +access method is being used, this flag causes the sync routine to apply to the btree file which underlies the recno file, not the recno file itself. (See the @@ -406,9 +453,9 @@ size_t size; .Pp The elements of the DBT structure are defined as follows: .Bl -tag -width XXXXX -.It data +.It Fa data A pointer to a byte string. -.It size +.It Fa size The length of the byte string. .El .Pp @@ -419,7 +466,7 @@ It should be noted that the access methods provide no guarantees about byte string alignment. .Sh ERRORS The -.Nm +.Fn dbopen routine may fail and set .Va errno for any of the errors specified for the library routines @@ -469,7 +516,9 @@ The .Fa fd routines will fail and set .Va errno -to ENOENT for in memory databases. +to +.Er ENOENT +for in memory databases. .Pp The .Fa sync @@ -491,7 +540,9 @@ for any of the errors specified for the library routine .%D Winter 1992 .Re .Sh BUGS -The typedef DBT is a mnemonic for ``data base thang'', and was used +The typedef DBT is a mnemonic for +.Dq data base thang , +and was used because noone could think of a reasonable name that wasn't already used. .Pp The file descriptor interface is a kluge and will be deleted in a diff --git a/lib/libc/db/man/hash.3 b/lib/libc/db/man/hash.3 index 55492dd9564..3aeab2ff800 100644 --- a/lib/libc/db/man/hash.3 +++ b/lib/libc/db/man/hash.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hash.3,v 1.9 1999/07/09 13:35:15 aaron Exp $ +.\" $OpenBSD: hash.3,v 1.10 2000/04/18 02:31:35 aaron Exp $ .\" $NetBSD: hash.3,v 1.6 1996/05/03 21:26:50 cgd Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. @@ -85,30 +85,30 @@ int lorder; .Pp The elements of this structure are as follows: .Bl -tag -width XXXXXX -offset indent -.It bsize +.It Fa bsize .Fa bsize defines the hash table bucket size, and is, by default, 256 bytes. It may be preferable to increase the page size for disk-resident tables and tables with large data items. -.It ffactor +.It Fa ffactor .Fa ffactor indicates a desired density within the hash table. It is an approximation of the number of keys allowed to accumulate in any one bucket, determining when the hash table grows or shrinks. The default value is 8. -.It nelem +.It Fa nelem .Fa nelem is an estimate of the final size of the hash table. If not set or set too low, hash tables will expand gracefully as keys are entered, although a slight performance degradation may be noticed. The default value is 1. -.It cachesize +.It Fa cachesize A suggested maximum size, in bytes, of the memory cache. This value is .Em only advisory, and the access method will allocate more memory rather than fail. -.It hash +.It Fa hash .Fa hash is a user defined hash function. Since no hash function performs equally well on all possible data, the @@ -117,13 +117,14 @@ data set. User specified hash functions must take two arguments (a pointer to a byte string and a length) and return a 32-bit quantity to be used as the hash value. -.It lorder +.It Fa lorder The byte order for integers in the stored database metadata. The number should represent the order as an integer; for example, -big endian order would be the number 4,321. If +big endian order would be the number 4,321. +If .Fa lorder is 0 (no order is specified) the current host order is used. -If the file already exists, the specified value is ignored and the +If the file already exists, the specified value is ignored and the value specified when the tree was created is used. .El .Pp diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3 index e7f767e89a0..c35a6a61588 100644 --- a/lib/libc/db/man/mpool.3 +++ b/lib/libc/db/man/mpool.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mpool.3,v 1.11 2000/01/22 12:00:42 aaron Exp $ +.\" $OpenBSD: mpool.3,v 1.12 2000/04/18 02:31:36 aaron Exp $ .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -37,7 +37,14 @@ .Dt MPOOL 3 .Os .Sh NAME -.Nm mpool +.Nm mpool_open , +.Nm mpool_filter , +.Nm mpool_new , +.Nm mpool_delete , +.Nm mpool_get , +.Nm mpool_put , +.Nm mpool_sync , +.Nm mpool_close .Nd shared memory buffer pool .Sh SYNOPSIS .Fd #include @@ -59,7 +66,7 @@ .Ft int .Fn mpool_close "MPOOL *mp" .Sh DESCRIPTION -.Nm +.Nm mpool is the library interface intended to provide page oriented buffer management of files. The buffers may be shared between processes. @@ -116,7 +123,9 @@ pointer, the page number and a pointer to the page to being read or written. .Pp The function .Fn mpool_new -takes an MPOOL pointer, an address, and a set of flags as arguments. +takes an +.Dv MPOOL +pointer, an address, and a set of flags as arguments. If a new page can be allocated, a pointer to the page is returned and the page number is stored into the .Fa pgnoaddr @@ -125,31 +134,38 @@ Otherwise, .Dv NULL is returned and .Va errno -is set. The flags value is formed by +is set. +The flags value is formed by .Tn OR Ns 'ing the following values: .Bl -tag -width Ds -.It MPOOL_PAGE_REQUEST +.It Dv MPOOL_PAGE_REQUEST Allocate a new page with a specific page number. -.It MPOOL_PAGE_NEXT +.It Dv MPOOL_PAGE_NEXT Allocate a new page with the next page number. .El .Pp The function .Fn mpool_delete -deletes the specified page from a pool and frees the page. It takes -an MPOOL pointer and a page as arguments. The page must have been -generated by +deletes the specified page from a pool and frees the page. +It takes an +.Dv MPOOL +pointer and a page as arguments. +The page must have been generated by .Fn mpool_new . .Pp The function .Fn mpool_get -takes an MPOOL pointer and a page number as arguments. If the page -exists, a pointer to the page is returned. Otherwise, +takes an +.Dv MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, .Dv NULL is returned and .Va errno -is set. The flags parameter is not currently used. +is set. +The flags parameter is not currently used. .Pp The function .Fn mpool_put @@ -164,7 +180,7 @@ The flags value is formed by .Tn OR Ns 'ing the following values: .Bl -tag -width Ds -.It MPOOL_DIRTY +.It Dv MPOOL_DIRTY The page has been modified and needs to be written to the backing file. .El .Pp @@ -173,8 +189,9 @@ returns 0 on success and \-1 if an error occurs. .Pp The function .Fn mpool_sync -writes all modified pages associated with the MPOOL pointer to the -backing file. +writes all modified pages associated with the +.Dv MPOOL +pointer to the backing file. .Fn mpool_sync returns 0 on success and \-1 if an error occurs. .Pp diff --git a/lib/libc/db/man/ndbm.3 b/lib/libc/db/man/ndbm.3 index 60dcaba64c7..fe1f0e9e0a9 100644 --- a/lib/libc/db/man/ndbm.3 +++ b/lib/libc/db/man/ndbm.3 @@ -1,10 +1,20 @@ .\" David Leonard, 1998. Placed in the public domain. -.\" $OpenBSD: ndbm.3,v 1.9 1999/07/09 13:35:15 aaron Exp $ +.\" $OpenBSD: ndbm.3,v 1.10 2000/04/18 02:31:36 aaron Exp $ .Dd May 13, 1998 .Dt NDBM 3 .Os .Sh NAME -.Nm ndbm +.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_store .Nd database access methods .Sh SYNOPSIS .Fd #include @@ -122,23 +132,23 @@ function clears the error condition of the database. 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, +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 datbase 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 +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 +function. +Thereafter, the .Fa db handle is invalid. .Ss Implementation notes diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3 index 871e3c7b7e9..e75373de5c2 100644 --- a/lib/libc/db/man/recno.3 +++ b/lib/libc/db/man/recno.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: recno.3,v 1.9 2000/03/14 21:31:39 aaron Exp $ +.\" $OpenBSD: recno.3,v 1.10 2000/04/18 02:31:36 aaron Exp $ .\" $NetBSD: recno.3,v 1.6 1996/05/03 21:26:51 cgd Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. @@ -46,9 +46,9 @@ .Fd #include .Fd #include .Sh DESCRIPTION -The routine +The .Fn dbopen -is the library interface to database files. +routine is the library interface to database files. One of the supported file formats is record number files. The general description of the database access methods is in .Xr dbopen 3 , @@ -95,12 +95,12 @@ char *bfname; .Pp The elements of this structure are defined as follows: .Bl -tag -width XXXXXX -.It flags +.It Fa flags The flag value is specified by .Tn OR Ns 'ing any of the following values: .Bl -tag -width XXXXXX -.It R_FIXEDLEN +.It Dv R_FIXEDLEN The records are fixed-length, not byte delimited. The structure element .Fa reclen @@ -110,7 +110,7 @@ is used as the pad character. Any records, inserted into the database, that are less than .Fa reclen bytes long are automatically padded. -.It R_NOKEY +.It Dv R_NOKEY In the interface specified by .Fn dbopen , the sequential record retrieval fills in both the caller's key and @@ -120,21 +120,21 @@ If the R_NOKEY flag is specified, the routines are not required to fill in the key structure. This permits applications to retrieve records at the end of files without reading all of the intervening records. -.It R_SNAPSHOT +.It Dv R_SNAPSHOT This flag requires that a snapshot of the file be taken when .Fn dbopen is called, instead of permitting any unmodified records to be read from the original file. .El -.It cachesize +.It Fa cachesize A suggested maximum size, in bytes, of the memory cache. This value is .Em only advisory, and the access method will allocate more memory rather than fail. If .Fa cachesize -is 0 (no size is specified) a default cache is used. -.It psize +is 0 (no size is specified) a default cache is used. +.It Fa psize The recno access method stores the in-memory copies of its records in a btree. This value is the size (in bytes) of the pages used for nodes in that tree. @@ -145,23 +145,25 @@ underlying file system I/O block size. See .Xr btree 3 for more information. -.It lorder +.It Fa lorder The byte order for integers in the stored database metadata. The number should represent the order as an integer; for example, big endian order would be the number 4,321. If .Fa lorder is 0 (no order is specified) the current host order is used. -.It reclen +.It Fa reclen The length of a fixed-length record. -.It bval +.It Fa bval The delimiting byte to be used to mark the end of a record for variable-length records, and the pad character for fixed-length records. -If no value is specified, newlines (``\en'') are used to mark the end +If no value is specified, newlines +.Pq Ql \en +are used to mark the end of variable-length records and fixed-length records are padded with spaces. -.It bfname +.It Fa bfname The recno access method stores the in-memory copies of its records in a btree. If bfname is non-NULL, it specifies the name of the btree file,