diff options
author | Aaron Campbell <aaron@cvs.openbsd.org> | 2000-04-20 13:50:04 +0000 |
---|---|---|
committer | Aaron Campbell <aaron@cvs.openbsd.org> | 2000-04-20 13:50:04 +0000 |
commit | ba6b056376adedc82f4ac0f41b5eed2fa3f30c75 (patch) | |
tree | e5c095a3d4f9afb3b98cca651e27f12c8880ffbd /lib/libc | |
parent | 51643f419480d5bdfbed4ef6c16cf20340d8a357 (diff) |
Flesh out stdlib function man pages.
Diffstat (limited to 'lib/libc')
28 files changed, 195 insertions, 246 deletions
diff --git a/lib/libc/stdlib/a64l.3 b/lib/libc/stdlib/a64l.3 index 1074dbff2e7..787634303c3 100644 --- a/lib/libc/stdlib/a64l.3 +++ b/lib/libc/stdlib/a64l.3 @@ -1,4 +1,3 @@ -.\" .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> .\" All rights reserved. .\" @@ -24,7 +23,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: a64l.3,v 1.4 1999/06/29 18:36:15 aaron Exp $ +.\" $OpenBSD: a64l.3,v 1.5 2000/04/20 13:50:01 aaron Exp $ .\" .Dd August 17, 1997 .Dt A64L 3 @@ -46,9 +45,9 @@ and .Fn l64a functions are used to maintain numbers stored in radix-64 .Tn ASCII -characters. This is a notation by which 32-bit integers -can be represented by up to six characters; each character -represents a +characters. +This is a notation by which 32-bit integers +can be represented by up to six characters; each character represents a .Dq digit in a radix-64 notation. .Pp @@ -73,14 +72,16 @@ for 38-63. The .Fn a64l function takes a pointer to a null-terminated radix-64 representation -and returns a corresponding 32-bit value. If the string pointed to by +and returns a corresponding 32-bit value. +If the string pointed to by .Fa s contains more than six characters, .Fn a64l will use the first six. .Fn a64l scans the character string from left to right, decoding -each character as a 6-bit radix-64 number. If a long integer is +each character as a 6-bit radix-64 number. +If a long integer is larger than 32 bits, the return value will be sign-extended. .Pp .Fn l64a diff --git a/lib/libc/stdlib/abort.3 b/lib/libc/stdlib/abort.3 index a0dfba7e802..743d42dd8a2 100644 --- a/lib/libc/stdlib/abort.3 +++ b/lib/libc/stdlib/abort.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: abort.3,v 1.5 1999/06/29 18:36:17 aaron Exp $ +.\" $OpenBSD: abort.3,v 1.6 2000/04/20 13:50:01 aaron Exp $ .\" .Dd June 29, 1991 .Dt ABORT 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn abort -function causes abnormal program termination to occur, unless the -signal +function causes abnormal program termination to occur, unless the signal .Dv SIGABRT is being caught and the signal handler does not return. .Pp @@ -57,14 +56,12 @@ Any open streams are flushed and closed. .Sh RETURN VALUES The .Fn abort -function -never returns. +function never returns. .Sh SEE ALSO .Xr sigaction 2 , .Xr exit 3 .Sh STANDARDS The .Fn abort -function -conforms to +function conforms to .St -p1003.1-90 . diff --git a/lib/libc/stdlib/abs.3 b/lib/libc/stdlib/abs.3 index 1e3675d7b56..0f7c097adea 100644 --- a/lib/libc/stdlib/abs.3 +++ b/lib/libc/stdlib/abs.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: abs.3,v 1.4 1999/06/29 18:36:17 aaron Exp $ +.\" $OpenBSD: abs.3,v 1.5 2000/04/20 13:50:01 aaron Exp $ .\" .Dd June 29, 1991 .Dt ABS 3 @@ -48,16 +48,12 @@ .Sh DESCRIPTION The .Fn abs -function -computes -the absolute value of the integer +function computes the absolute value of the integer .Fa j . .Sh RETURN VALUES The .Fn abs -function -returns -the absolute value. +function returns the absolute value. .Sh SEE ALSO .Xr cabs 3 , .Xr floor 3 , diff --git a/lib/libc/stdlib/alloca.3 b/lib/libc/stdlib/alloca.3 index 56d52ebe1b6..e9e0b67ee32 100644 --- a/lib/libc/stdlib/alloca.3 +++ b/lib/libc/stdlib/alloca.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: alloca.3,v 1.7 1999/06/29 18:36:18 aaron Exp $ +.\" $OpenBSD: alloca.3,v 1.8 2000/04/20 13:50:01 aaron Exp $ .\" .Dd May 2, 1991 .Dt ALLOCA 3 @@ -44,12 +44,10 @@ .Sh DESCRIPTION The .Fn alloca -function -allocates +function allocates .Fa size bytes of space in the stack frame of the caller. -This temporary space is automatically freed on -return. +This temporary space is automatically freed on return. .Sh RETURN VALUES The .Fn alloca @@ -63,8 +61,7 @@ function returns a pointer to the beginning of the allocated space. .Sh BUGS The .Fn alloca -function -is machine dependent; its use is discouraged. +function is machine dependent; its use is discouraged. .\" .Sh HISTORY .\" The .\" .Fn alloca diff --git a/lib/libc/stdlib/atexit.3 b/lib/libc/stdlib/atexit.3 index cc37d08b00c..5d79ede6493 100644 --- a/lib/libc/stdlib/atexit.3 +++ b/lib/libc/stdlib/atexit.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: atexit.3,v 1.3 1999/06/29 18:36:18 aaron Exp $ +.\" $OpenBSD: atexit.3,v 1.4 2000/04/20 13:50:01 aaron Exp $ .\" .Dd June 29, 1991 .Dt ATEXIT 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn atexit -function -registers the given +function registers the given .Fa function to be called at program exit, whether via .Xr exit 3 @@ -72,6 +71,5 @@ The existing list of functions is unmodified. .Sh STANDARDS The .Fn atexit -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/atoi.3 b/lib/libc/stdlib/atoi.3 index 80831bdd2fa..69b94be70c2 100644 --- a/lib/libc/stdlib/atoi.3 +++ b/lib/libc/stdlib/atoi.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: atoi.3,v 1.4 1999/09/13 07:14:13 deraadt Exp $ +.\" $OpenBSD: atoi.3,v 1.5 2000/04/20 13:50:01 aaron Exp $ .\" .Dd June 4, 1993 .Dt ATOI 3 @@ -66,7 +66,8 @@ does no overflow checking, handles unsigned numbers poorly, and handles strings containing trailing extra characters (like .Dq "123abc" Ns ) -poorly. Careful use of +poorly. +Careful use of .Xr strtol 3 and .Xr strtoul 3 diff --git a/lib/libc/stdlib/atol.3 b/lib/libc/stdlib/atol.3 index c7b4ff30daa..53a518997f9 100644 --- a/lib/libc/stdlib/atol.3 +++ b/lib/libc/stdlib/atol.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: atol.3,v 1.3 1999/06/29 18:36:19 aaron Exp $ +.\" $OpenBSD: atol.3,v 1.4 2000/04/20 13:50:01 aaron Exp $ .\" .Dd June 29, 1991 .Dt ATOL 3 @@ -69,6 +69,5 @@ strtol(nptr, (char **)NULL, 10); .Sh STANDARDS The .Fn atol -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/bsearch.3 b/lib/libc/stdlib/bsearch.3 index 63d4e6af69f..9bb9d4ece4a 100644 --- a/lib/libc/stdlib/bsearch.3 +++ b/lib/libc/stdlib/bsearch.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: bsearch.3,v 1.4 1999/06/29 18:36:19 aaron Exp $ +.\" $OpenBSD: bsearch.3,v 1.5 2000/04/20 13:50:01 aaron Exp $ .\" .Dd April 19, 1994 .Dt BSEARCH 3 @@ -63,9 +63,7 @@ to the comparison function referenced by .Fa compar . The .Fa compar -routine -is expected to have -two arguments which point to the +routine is expected to have two arguments which point to the .Fa key object and to an array member, in that order, and should return an integer less than, equal to, or greater than zero if the diff --git a/lib/libc/stdlib/div.3 b/lib/libc/stdlib/div.3 index 5cc3b8757c8..1f651d7fd37 100644 --- a/lib/libc/stdlib/div.3 +++ b/lib/libc/stdlib/div.3 @@ -31,7 +31,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: div.3,v 1.4 1999/06/29 18:36:19 aaron Exp $ +.\" $OpenBSD: div.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd April 19, 1991 .Dt DIV 3 @@ -46,8 +46,7 @@ .Sh DESCRIPTION The .Fn div -function -computes the value +function computes the value .Fa num Ns No / Ns Fa denom and returns the quotient and remainder in a structure named .Fa div_t @@ -64,6 +63,5 @@ and .Sh STANDARDS The .Fn div -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/exit.3 b/lib/libc/stdlib/exit.3 index 326c5539a88..a17c1805f2a 100644 --- a/lib/libc/stdlib/exit.3 +++ b/lib/libc/stdlib/exit.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: exit.3,v 1.3 1999/02/27 21:55:55 deraadt Exp $ +.\" $OpenBSD: exit.3,v 1.4 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 29, 1991 .Dt EXIT 3 @@ -46,8 +46,9 @@ .Ft void .Fn exit "int status" .Sh DESCRIPTION +The .Fn exit -terminates a process. +function terminates a process. .Pp Before termination it performs the following functions in the order listed: @@ -68,8 +69,7 @@ function. .Sh RETURN VALUES The .Fn exit -function -never returns. +function never returns. .Sh SEE ALSO .Xr _exit 2 , .Xr atexit 3 , @@ -78,6 +78,5 @@ never returns. .Sh STANDARDS The .Fn exit -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/getenv.3 b/lib/libc/stdlib/getenv.3 index d6ffc8b1ddd..b2aa0080d67 100644 --- a/lib/libc/stdlib/getenv.3 +++ b/lib/libc/stdlib/getenv.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: getenv.3,v 1.6 1999/09/06 23:26:30 aaron Exp $ +.\" $OpenBSD: getenv.3,v 1.7 2000/04/20 13:50:02 aaron Exp $ .\" .Dd December 11, 1993 .Dt GETENV 3 @@ -55,17 +55,13 @@ .Ft void .Fn unsetenv "const char *name" .Sh DESCRIPTION -These functions set, unset and fetch environment variables from the -host +These functions set, unset, and fetch environment variables from the host .Em environment list . -For compatibility with differing environment conventions, -the given arguments +For compatibility with differing environment conventions, the given arguments .Fa name and .Fa value -may be appended and prepended, -respectively, -with an equal sign +may be appended and prepended, respectively, with an equal sign .Dq Li \&= . .Pp The @@ -74,8 +70,7 @@ function obtains the current value of the environment variable, .Fa name . If the variable .Fa name -is not in the current environment, -a null pointer is returned. +is not in the current environment, a null pointer is returned. .Pp The .Fn setenv @@ -84,30 +79,27 @@ function inserts or resets the environment variable in the current environment list. If the variable .Fa name -does not exist in the list, -it is inserted with the given +does not exist in the list, it is inserted with the given .Fa value . If the variable does exist, the argument .Fa overwrite is tested; if .Fa overwrite -is zero, -the variable is not reset, otherwise it is reset -to the given +is zero, the variable is not reset, otherwise it is reset to the given .Fa value . .Pp The .Fn putenv -function takes an argument of the form ``name=value'' and is -equivalent to: +function takes an argument of the form +.Ar name Ns No = Ns Ar value +and is equivalent to: .Bd -literal -offset indent setenv(name, value, 1); .Ed .Pp The .Fn unsetenv -function -deletes all instances of the variable name pointed to by +function deletes all instances of the variable name pointed to by .Fa name from the list. .Sh RETURN VALUES @@ -117,8 +109,7 @@ and .Fn putenv return zero if successful; otherwise the global variable .Va errno -is set to indicate the error and a -\-1 is returned. +is set to indicate the error and \-1 is returned. .Pp If .Fn getenv diff --git a/lib/libc/stdlib/getopt.3 b/lib/libc/stdlib/getopt.3 index 637a81f1f0f..ef132cafc59 100644 --- a/lib/libc/stdlib/getopt.3 +++ b/lib/libc/stdlib/getopt.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: getopt.3,v 1.12 2000/03/04 22:19:31 aaron Exp $ +.\" $OpenBSD: getopt.3,v 1.13 2000/04/20 13:50:02 aaron Exp $ .\" .Dd April 19, 1994 .Dt GETOPT 3 @@ -51,27 +51,25 @@ The .Fn getopt function incrementally parses a command line argument list .Fa argv -and returns the next -.Em known -option character. +and returns the next known option character. An option character is -.Em known +.Dq known if it has been specified in the string of accepted option characters, .Fa optstring . .Pp The option string .Fa optstring -may contain the following elements: individual characters, and +may contain the following elements: individual characters and characters followed by a colon to indicate an option argument is to follow. For example, an option string -.Li "\&""x"" +.Qq x recognizes an option -.Dq Fl x , +.Fl x , and an option string -.Li "\&""x:"" +.Qq Li x: recognizes an option and argument -.Dq Fl x Ar argument . +.Fl x Ar argument . It does not matter to .Fn getopt if a following argument has leading whitespace. @@ -89,12 +87,10 @@ to .Fn getopt . The variable .Va optopt -saves the last -.Em known -option character returned by +saves the last known option character returned by .Fn getopt . .Pp -The variable +The variables .Va opterr and .Va optind @@ -119,9 +115,7 @@ must be reinitialized. .Pp The .Fn getopt -function -returns \-1 -when the argument list is exhausted. +function returns \-1 when the argument list is exhausted. The interpretation of options in the argument list may be cancelled by the option .Ql -- @@ -157,9 +151,8 @@ then a missing option argument causes a to be returned in addition to suppressing any error messages. .Pp Option arguments are allowed to begin with -.Dq Li \- ; -this is reasonable but -reduces the amount of error checking possible. +.Ql - ; +this is reasonable but reduces the amount of error checking possible. .Sh EXTENSIONS The .Va optreset diff --git a/lib/libc/stdlib/getsubopt.3 b/lib/libc/stdlib/getsubopt.3 index 0ea48864c33..a5f98e5d96b 100644 --- a/lib/libc/stdlib/getsubopt.3 +++ b/lib/libc/stdlib/getsubopt.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getsubopt.3,v 1.3 1999/06/29 18:36:20 aaron Exp $ +.\" $OpenBSD: getsubopt.3,v 1.4 2000/04/20 13:50:02 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -41,15 +41,14 @@ .Nd get sub options from an argument .Sh SYNOPSIS .Fd #include <stdlib.h> -.Vt extern char *suboptarg +.Vt extern char *suboptarg; .Ft int .Fn getsubopt "char **optionp" "char * const *tokens" "char **valuep" .Sh DESCRIPTION The .Fn getsubopt -function -parses a string containing tokens delimited by one or more tab, space or -comma +function parses a string containing tokens delimited by one or more +tab, space or comma .Pq Ql \&, characters. It is intended for use in parsing groups of option arguments provided @@ -60,22 +59,24 @@ The argument is a pointer to a pointer to the string. The argument .Fa tokens -is a pointer to a null-terminated -array of pointers to strings. +is a pointer to a null-terminated array of pointers to strings. .Pp The .Fn getsubopt -function -returns the zero-based offset of the pointer in the +function returns the zero-based offset of the pointer in the .Fa tokens array referencing a string which matches the first token in the string, or, \-1 if the string contains no tokens or .Fa tokens does not contain a matching string. .Pp -If the token is of the form ``name=value'', the location referenced by +If the token is of the form +.Ar name Ns No = Ns Ar value , +the location referenced by .Fa valuep -will be set to point to the start of the ``value'' portion of the token. +will be set to point to the start of the +.Dq value +portion of the token. .Pp On return from .Fn getsubopt , @@ -86,13 +87,12 @@ The external variable .Fa suboptarg will be set to point to the start of the current token, or .Dv NULL -if no -tokens were present. +if no tokens were present. The argument .Fa valuep -will be set to point to the ``value'' portion of the token, or +will be set to point to the value portion of the token, or .Dv NULL -if no ``value'' portion was present. +if no value portion was present. .Sh EXAMPLE .Bd -literal -compact char *tokens[] = { diff --git a/lib/libc/stdlib/labs.3 b/lib/libc/stdlib/labs.3 index de0b76ba1fc..fe39ca24dcb 100644 --- a/lib/libc/stdlib/labs.3 +++ b/lib/libc/stdlib/labs.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: labs.3,v 1.4 1999/06/29 18:36:20 aaron Exp $ +.\" $OpenBSD: labs.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 29, 1991 .Dt LABS 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn labs -function -returns the absolute value of the long integer +function returns the absolute value of the long integer .Fa j . .Sh SEE ALSO .Xr abs 3 , @@ -59,8 +58,7 @@ returns the absolute value of the long integer .Sh STANDARDS The .Fn labs -function -conforms to +function conforms to .St -ansiC . .Sh BUGS The absolute value of the most negative integer remains negative. diff --git a/lib/libc/stdlib/ldiv.3 b/lib/libc/stdlib/ldiv.3 index 60b35dc98f3..b5301b1b21c 100644 --- a/lib/libc/stdlib/ldiv.3 +++ b/lib/libc/stdlib/ldiv.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: ldiv.3,v 1.4 1999/06/29 18:36:21 aaron Exp $ +.\" $OpenBSD: ldiv.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 29, 1991 .Dt LDIV 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn ldiv -function -computes the value +function computes the value .Fa num Ns No / Ns Fa denom and returns the quotient and remainder in a structure named .Li ldiv_t @@ -66,6 +65,5 @@ and .Sh STANDARDS The .Fn ldiv -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/memory.3 b/lib/libc/stdlib/memory.3 index 61bae4cc3c6..959a173a037 100644 --- a/lib/libc/stdlib/memory.3 +++ b/lib/libc/stdlib/memory.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: memory.3,v 1.4 1999/05/23 14:11:03 aaron Exp $ +.\" $OpenBSD: memory.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd May 2, 1991 .Dt MEMORY 3 @@ -55,8 +55,7 @@ .Fn alloca "size_t size" .Sh DESCRIPTION These functions allocate and free memory for the calling process. -They are described in the -individual manual pages. +They are described in the individual man pages. .Sh SEE ALSO .Xr alloca 3 , .Xr calloc 3 , @@ -65,6 +64,6 @@ individual manual pages. .Xr realloc 3 .Sh STANDARDS These functions, with the exception of -.Fn alloca +.Fn alloca , conform to .St -ansiC . diff --git a/lib/libc/stdlib/qabs.3 b/lib/libc/stdlib/qabs.3 index 0f7ccdc78f0..ef0307ab25d 100644 --- a/lib/libc/stdlib/qabs.3 +++ b/lib/libc/stdlib/qabs.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: qabs.3,v 1.4 1999/06/29 18:36:21 aaron Exp $ +.\" $OpenBSD: qabs.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 29, 1991 .Dt QABS 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn qabs -function -returns the absolute value of the quad integer +function returns the absolute value of the quad integer .Fa j . .Sh SEE ALSO .Xr abs 3 , diff --git a/lib/libc/stdlib/qsort.3 b/lib/libc/stdlib/qsort.3 index 8d665187bf6..632909dd3ca 100644 --- a/lib/libc/stdlib/qsort.3 +++ b/lib/libc/stdlib/qsort.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: qsort.3,v 1.4 1999/06/29 18:36:22 aaron Exp $ +.\" $OpenBSD: qsort.3,v 1.5 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 4, 1993 .Dt QSORT 3 @@ -105,7 +105,9 @@ is stable. .Pp The .Fn qsort -function is an implementation of C.A.R. Hoare's ``quicksort'' algorithm, +function is an implementation of C.A.R. Hoare's +.Dq quicksort +algorithm, a variant of partition-exchange sorting; in particular, see D.E. Knuth's Algorithm Q. .Fn qsort @@ -115,7 +117,9 @@ O N**2 worst-case behavior. .Pp The .Fn heapsort -function is an implementation of J.W.J. William's ``heapsort'' algorithm, +function is an implementation of J.W.J. William's +.Dq heapsort +algorithm, a variant of selection sorting; in particular, see D.E. Knuth's Algorithm H. .Fn heapsort takes O N lg N worst-case time. @@ -143,13 +147,11 @@ is faster than .Fn mergesort is faster than .Fn heapsort . -Memory availability and pre-existing order in the data can make this -untrue. +Memory availability and pre-existing order in the data can make this untrue. .Sh RETURN VALUES The .Fn qsort -function -returns no value. +function returns no value. .Pp Upon successful completion, .Fn heapsort @@ -167,8 +169,7 @@ function succeeds unless: .It Bq Er EINVAL The .Fa size -argument is zero, or, -the +argument is zero, or, the .Fa size argument to .Fn mergesort @@ -228,6 +229,5 @@ This is no longer true. .Sh STANDARDS The .Fn qsort -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/radixsort.3 b/lib/libc/stdlib/radixsort.3 index a1a4ee4eabf..64cc841a49f 100644 --- a/lib/libc/stdlib/radixsort.3 +++ b/lib/libc/stdlib/radixsort.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: radixsort.3,v 1.5 1999/06/29 18:36:22 aaron Exp $ +.\" $OpenBSD: radixsort.3,v 1.6 2000/04/20 13:50:02 aaron Exp $ .\" .Dd January 27, 1994 .Dt RADIXSORT 3 @@ -49,8 +49,7 @@ The .Fn radixsort and .Fn sradixsort -functions -are implementations of radix sort. +functions are implementations of radix sort. .Pp These functions sort an array of pointers to byte strings, the initial member of which is referenced by @@ -66,23 +65,20 @@ If non-null, .Fa table must reference an array of .Dv UCHAR_MAX -+ 1 bytes which contains the sort -weight of each possible byte value. ++ 1 bytes which contains the sort weight of each possible byte value. The end-of-string byte must have a sort weight of 0 or 255 (for sorting in reverse order). More than one byte may have the same sort weight. The .Fa table -argument -is useful for applications which wish to sort different characters +argument is useful for applications which wish to sort different characters equally, for example, providing a table with the same weights for A-Z as for a-z will result in a case-insensitive sort. If .Fa table is .Dv NULL , -the contents of the array are sorted in ascending order -according to the +the contents of the array are sorted in ascending order according to the .Tn ASCII order of the byte strings they reference and .Fa endbyte @@ -122,8 +118,7 @@ is not 0 or 255. .Pp Additionally, the .Fn sradixsort -function -may fail and set +function may fail and set .Va errno for any of the errors specified for the library routine .Xr malloc 3 . diff --git a/lib/libc/stdlib/rand.3 b/lib/libc/stdlib/rand.3 index d5686e5f4ce..4d4e91efe45 100644 --- a/lib/libc/stdlib/rand.3 +++ b/lib/libc/stdlib/rand.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: rand.3,v 1.6 1999/06/29 18:36:22 aaron Exp $ +.\" $OpenBSD: rand.3,v 1.7 2000/04/20 13:50:02 aaron Exp $ .\" .Dd June 29, 1991 .Dt RAND 3 @@ -92,13 +92,11 @@ The .Fn rand and .Fn srand -functions -conform to +functions conform to .St -ansiC . .Pp The .Fn rand_r -function -conforms to ISO/IEC 9945-1 ANSI/IEEE +function conforms to ISO/IEC 9945-1 ANSI/IEEE .Pq Dq Tn POSIX Std 1003.1c Draft 10. diff --git a/lib/libc/stdlib/rand48.3 b/lib/libc/stdlib/rand48.3 index 3d8d53862d4..886e5273d9e 100644 --- a/lib/libc/stdlib/rand48.3 +++ b/lib/libc/stdlib/rand48.3 @@ -9,7 +9,7 @@ .\" of any kind. I shall in no event be liable for anything that happens .\" to anyone/anything when using this software. .\" -.\" $OpenBSD: rand48.3,v 1.6 1999/09/27 02:00:13 aaron Exp $ +.\" $OpenBSD: rand48.3,v 1.7 2000/04/20 13:50:02 aaron Exp $ .\" .Dd October 8, 1993 .Dt RAND48 3 @@ -49,12 +49,13 @@ The .Fn rand48 family of functions generates pseudo-random numbers using a linear -congruential algorithm working on integers 48 bits in size. The -particular formula employed is +congruential algorithm working on integers 48 bits in size. +The particular formula employed is r(n+1) = (a * r(n) + c) mod m where the default values are for the multiplicand a = 0xfdeece66d = 25214903917 and -the addend c = 0xb = 11. The modulus is always fixed at m = 2 ** 48. +the addend c = 0xb = 11. +The modulus is always fixed at m = 2 ** 48. r(n) is called the seed of the random number generator. .Pp For all the six generator routines described next, the first @@ -63,7 +64,8 @@ computational step is to perform a single iteration of the algorithm. .Fn drand48 and .Fn erand48 -return values of type double. The full 48 bits of r(n+1) are +return values of type double. +The full 48 bits of r(n+1) are loaded into the mantissa of the returned value, with the exponent set such that the values produced lie in the interval [0.0, 1.0). .Pp @@ -71,7 +73,8 @@ such that the values produced lie in the interval [0.0, 1.0). and .Fn nrand48 return values of type long in the range -[0, 2**31-1]. The high-order (31) bits of +[0, 2**31-1]. +The high-order (31) bits of r(n+1) are loaded into the lower bits of the returned value, with the topmost (sign) bit set to zero. .Pp @@ -79,14 +82,15 @@ the topmost (sign) bit set to zero. and .Fn jrand48 return values of type long in the range -[-2**31, 2**31-1]. The high-order (32) bits of -r(n+1) are loaded into the returned value. +[-2**31, 2**31-1]. +The high-order (32) bits of r(n+1) are loaded into the returned value. .Pp .Fn drand48 , .Fn lrand48 , and .Fn mrand48 -use an internal buffer to store r(n). For these functions +use an internal buffer to store r(n). +For these functions the initial value of r(0) = 0x1234abcd330e = 20017429951246. .Pp On the other hand, @@ -118,8 +122,8 @@ also initializes the internal buffer r(n) of and .Fn mrand48 , but here all 48 bits of the seed can be specified in an array of 3 shorts, -where the zeroth member specifies the lowest bits. Again, -the constant multiplicand and addend of the algorithm are +where the zeroth member specifies the lowest bits. +Again, the constant multiplicand and addend of the algorithm are reset to the default values given above. .Fn seed48 returns a pointer to an array of 3 shorts which contains the old seed. diff --git a/lib/libc/stdlib/random.3 b/lib/libc/stdlib/random.3 index 260c2398164..d3a3198ebfb 100644 --- a/lib/libc/stdlib/random.3 +++ b/lib/libc/stdlib/random.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: random.3,v 1.11 2000/04/03 23:23:48 millert Exp $ +.\" $OpenBSD: random.3,v 1.12 2000/04/20 13:50:02 aaron Exp $ .\" .Dd April 19, 1991 .Dt RANDOM 3 @@ -56,23 +56,27 @@ .Sh DESCRIPTION The .Fn random -function -uses a non-linear additive feedback random number generator employing a -default table of size 31 long integers to return successive pseudo-random +function uses a non-linear additive feedback random number generator employing +a default table of size 31 long integers to return successive pseudo-random numbers in the range from 0 to (2**31)\-1. The period of this random number generator is very large, approximately 16*((2**31)\-1. .Pp The -.Fn random Ns / Fn srandom -have (almost) the same calling sequence and initialization properties as +.Fn random +and +.Fn srandom +functions have (almost) the same calling sequence and initialization +properties as .Xr rand 3 Ns / Xr srand 3 . The difference is that .Xr rand produces a much less random sequence \(em in fact, the low dozen bits -generated by rand go through a cyclic pattern. All the bits generated by +generated by rand go through a cyclic pattern. +All the bits generated by .Fn random -are usable. For example, +are usable. +For example, .Sq Li random()&01 will produce a random binary value. @@ -81,9 +85,10 @@ Unlike .Xr srand , .Fn srandom does not return the old seed; the reason for this is that the amount of -state information used is much more than a single word. (Two other -routines are provided to deal with restarting/changing random -number generators). Like +state information used is much more than a single word. +(Two other routines are provided to deal with restarting/changing random +number generators). +Like .Xr rand 3 , however, .Fn random @@ -110,28 +115,28 @@ a fixed seed. The .Fn initstate routine allows a state array, passed in as an argument, to be initialized -for future use. The size of the state array (in bytes) is used by +for future use. +The size of the state array (in bytes) is used by .Fn initstate to decide how sophisticated a random number generator it should use \(em the more state, the better the random numbers will be. (Current "optimal" values for the amount of state information are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to -the nearest known amount. Using less than 8 bytes will cause an error.) +the nearest known amount. +Using less than 8 bytes will cause an error.) The seed for the initialization (which specifies a starting point for the random number sequence, and provides for restarting at the same point) is also an argument. The .Fn initstate -function -returns a pointer to the previous state information array. +function returns a pointer to the previous state information array. .Pp Once a state has been initialized, the .Fn setstate routine provides for rapid switching between states. The .Fn setstate -function -returns a pointer to the previous state array; its +function returns a pointer to the previous state array; its argument state array is used for further random number generation until the next call to .Fn initstate diff --git a/lib/libc/stdlib/realpath.3 b/lib/libc/stdlib/realpath.3 index 95c57b2e516..ffb763d475d 100644 --- a/lib/libc/stdlib/realpath.3 +++ b/lib/libc/stdlib/realpath.3 @@ -32,7 +32,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: realpath.3,v 1.6 1999/07/02 16:57:49 aaron Exp $ +.\" $OpenBSD: realpath.3,v 1.7 2000/04/20 13:50:02 aaron Exp $ .\" .Dd February 16, 1994 .Dt REALPATH 3 @@ -56,8 +56,7 @@ and .Pa /../ in .Fa pathname , -and copies the resulting absolute pathname into -the memory referenced by +and copies the resulting absolute pathname into the memory referenced by .Fa resolvedname . The .Fa resolvedname @@ -101,7 +100,7 @@ for any of the errors specified for the library functions .Xr fchdir 2 , .Xr lstat 2 , .Xr open 2 , -.Xr readlink 2 +.Xr readlink 2 , and .Xr getcwd 3 . .Sh CAVEATS diff --git a/lib/libc/stdlib/strtod.3 b/lib/libc/stdlib/strtod.3 index 143fea34dca..4e04f6738e2 100644 --- a/lib/libc/stdlib/strtod.3 +++ b/lib/libc/stdlib/strtod.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: strtod.3,v 1.6 2000/03/04 22:19:31 aaron Exp $ +.\" $OpenBSD: strtod.3,v 1.7 2000/04/20 13:50:03 aaron Exp $ .\" .Dd June 29, 1991 .Dt STRTOD 3 @@ -50,18 +50,23 @@ string to double .Sh DESCRIPTION The .Fn strtod -function converts the initial portion of the string -pointed to by +function converts the initial portion of the string pointed to by .Fa nptr to .Li double representation. .Pp -The expected form of the string is an optional plus (``+'') or minus -sign (``-'') followed by a sequence of digits optionally containing +The expected form of the string is an optional plus +.Pq Ql + +or minus sign +.Pq Ql - +followed by a sequence of digits optionally containing a decimal-point character, optionally followed by an exponent. -An exponent consists of an ``E'' or ``e'', followed by an optional plus -or minus sign, followed by a sequence of digits. +An exponent consists of an +.Sq E +or +.Sq e , +followed by an optional plus or minus sign, followed by a sequence of digits. .Pp Leading whitespace characters in the string (as defined by the .Xr isspace 3 @@ -90,8 +95,7 @@ is returned (according to the sign of the value), and .Er ERANGE is stored in .Va errno . -If the correct value would cause underflow, zero is -returned and +If the correct value would cause underflow, zero is returned and .Er ERANGE is stored in .Va errno . @@ -109,6 +113,5 @@ Overflow or underflow occurred. .Sh STANDARDS The .Fn strtod -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdlib/strtol.3 b/lib/libc/stdlib/strtol.3 index df696b7b859..fdc02b20b89 100644 --- a/lib/libc/stdlib/strtol.3 +++ b/lib/libc/stdlib/strtol.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: strtol.3,v 1.7 2000/03/04 22:19:31 aaron Exp $ +.\" $OpenBSD: strtol.3,v 1.8 2000/04/20 13:50:03 aaron Exp $ .\" .Dd June 25, 1992 .Dt STRTOL 3 @@ -46,7 +46,7 @@ .Fd #include <limits.h> .Ft long .Fn strtol "const char *nptr" "char **endptr" "int base" - +.Pp .Fd #include <sys/types.h> .Fd #include <stdlib.h> .Fd #include <limits.h> @@ -55,24 +55,21 @@ .Sh DESCRIPTION The .Fn strtol -function -converts the string in +function converts the string in .Fa nptr to a .Li long value. The .Fn strtoq -function -converts the string in +function converts the string in .Fa nptr to a .Li quad_t value. The conversion is done according to the given .Fa base , -which must be a number between 2 and 36 inclusive -or the special value 0. +which must be a number between 2 and 36 inclusive or the special value 0. .Pp The string may begin with an arbitrary amount of whitespace (as determined by @@ -84,11 +81,9 @@ or sign. If .Fa base -is zero or 16, -the string may then include a +is zero or 16, the string may then include a .Ql 0x -prefix, -and the number will be read in base 16; otherwise, a zero +prefix, and the number will be read in base 16; otherwise, a zero .Fa base is taken as 10 (decimal) unless the next character is .Ql 0 , @@ -101,8 +96,7 @@ stopping at the first character which is not a valid digit in the given base. (In bases above 10, the letter .Ql A -in either upper or lower case -represents 10, +in either upper or lower case represents 10, .Ql B represents 11, and so forth, with .Ql Z @@ -110,7 +104,7 @@ representing 35.) .Pp If .Fa endptr -is non nil, +is non-null, .Fn strtol stores the address of the first invalid character in .Fa *endptr . @@ -132,8 +126,7 @@ on return, the entire string was valid.) .Sh RETURN VALUES The .Fn strtol -function -returns the result of the conversion, +function returns the result of the conversion, unless the value would underflow or overflow. If an underflow occurs, .Fn strtol @@ -191,8 +184,8 @@ error checking is further complicated because the desired return value is an .Li int rather than a .Li long ; -however, on some architectures integers and long integers are the same -size. Thus the following is necessary: +however, on some architectures integers and long integers are the same size. +Thus the following is necessary: .Bd -literal -offset indent char *ep; int ival; @@ -224,8 +217,7 @@ The given string was out of range; the value converted has been clamped. .Sh STANDARDS The .Fn strtol -function -conforms to +function conforms to .St -ansiC . .Sh BUGS Ignores the current locale. diff --git a/lib/libc/stdlib/strtoul.3 b/lib/libc/stdlib/strtoul.3 index 572658bf7fe..e0902535669 100644 --- a/lib/libc/stdlib/strtoul.3 +++ b/lib/libc/stdlib/strtoul.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: strtoul.3,v 1.6 2000/03/04 22:19:31 aaron Exp $ +.\" $OpenBSD: strtoul.3,v 1.7 2000/04/20 13:50:03 aaron Exp $ .\" .Dd June 25, 1992 .Dt STRTOUL 3 @@ -55,16 +55,14 @@ .Sh DESCRIPTION The .Fn strtoul -function -converts the string in +function converts the string in .Fa nptr to an .Li unsigned long value. The .Fn strtouq -function -converts the string in +function converts the string in .Fa nptr to a .Li u_quad_t @@ -84,11 +82,9 @@ or sign. If .Fa base -is zero or 16, -the string may then include a +is zero or 16, the string may then include a .Ql 0x -prefix, -and the number will be read in base 16; otherwise, a zero +prefix, and the number will be read in base 16; otherwise, a zero .Fa base is taken as 10 (decimal) unless the next character is .Ql 0 , @@ -96,14 +92,12 @@ in which case it is taken as 8 (octal). .Pp The remainder of the string is converted to an .Li unsigned long -value in the obvious manner, -stopping at the end of the string +value in the obvious manner, stopping at the end of the string or at the first character that does not produce a valid digit in the given base. (In bases above 10, the letter .Ql A -in either upper or lower case -represents 10, +in either upper or lower case represents 10, .Ql B represents 11, and so forth, with .Ql Z @@ -111,7 +105,7 @@ representing 35.) .Pp If .Fa endptr -is non nil, +is non-null, .Fn strtoul stores the address of the first invalid character in .Fa *endptr . @@ -133,8 +127,7 @@ on return, the entire string was valid.) .Sh RETURN VALUES The .Fn strtoul -function -returns the result of the conversion, +function returns the result of the conversion, unless the value would overflow, in which case .Dv ULONG_MAX is returned and @@ -206,8 +199,7 @@ The given string was out of range; the value converted has been clamped. .Sh STANDARDS The .Fn strtoul -function -conforms to +function conforms to .St -ansiC . .Sh BUGS Ignores the current locale. diff --git a/lib/libc/stdlib/system.3 b/lib/libc/stdlib/system.3 index f2d26936779..2db413934e1 100644 --- a/lib/libc/stdlib/system.3 +++ b/lib/libc/stdlib/system.3 @@ -33,7 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: system.3,v 1.6 1999/06/29 18:36:24 aaron Exp $ +.\" $OpenBSD: system.3,v 1.7 2000/04/20 13:50:03 aaron Exp $ .\" .Dd June 29, 1991 .Dt SYSTEM 3 @@ -48,8 +48,7 @@ .Sh DESCRIPTION The .Fn system -function -hands the argument +function hands the argument .Fa string to the command interpreter .Xr sh 1 . @@ -63,9 +62,8 @@ and blocking .Pp If .Fa string -is a -.Dv NULL -pointer, +is +.Dv NULL , .Fn system will return non-zero. Otherwise, @@ -91,8 +89,7 @@ returns the termination status for a program that terminates with a call of .Sh STANDARDS The .Fn system -function -conforms to +function conforms to .St -ansiC and .St -p1003.2-92 . diff --git a/lib/libc/stdlib/tsearch.3 b/lib/libc/stdlib/tsearch.3 index fa1d34afbbe..72048a19fb5 100644 --- a/lib/libc/stdlib/tsearch.3 +++ b/lib/libc/stdlib/tsearch.3 @@ -23,7 +23,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: tsearch.3,v 1.7 2000/02/25 07:53:09 deraadt Exp $ +.\" $OpenBSD: tsearch.3,v 1.8 2000/04/20 13:50:03 aaron Exp $ .\" .Dd June 15, 1997 .Dt TSEARCH 3 @@ -49,7 +49,8 @@ The and .Fn twalk functions manage binary search trees based on algorithms T and D -from Knuth (6.2.2). The comparison function passed in by +from Knuth (6.2.2). +The comparison function passed in by the user has the same style of return values as .Xr strcmp 3 . .Pp @@ -67,7 +68,8 @@ is identical to .Fn tfind except that if no match is found, .Fa key -is inserted into the tree and a pointer to it is returned. If +is inserted into the tree and a pointer to it is returned. +If .Fa rootp points to a null value a new binary search tree is created. .Pp |