diff options
66 files changed, 1345 insertions, 778 deletions
diff --git a/usr.bin/at/at.1 b/usr.bin/at/at.1 index a22a42fc5fe..d90c2f5131e 100644 --- a/usr.bin/at/at.1 +++ b/usr.bin/at/at.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: at.1,v 1.18 2002/02/08 01:36:18 ross Exp $ +.\" $NetBSD: at.1,v 1.19 2002/09/30 11:08:56 grant Exp $ .\" $OpenBSD: at.1,v 1.6 1998/06/05 00:47:46 deraadt Exp $ .\" $FreeBSD: at.man,v 1.6 1997/02/22 19:54:05 peter Exp $ .Dd October 15, 2000 @@ -62,7 +62,8 @@ In that case, everybody's jobs are listed. .It Nm atrm Deletes jobs. .It Nm batch -Executes commands when system load levels permit. In other words, when +Executes commands when system load levels permit. +In other words, when the load average drops below 1.5, or the value specified in the invocation of .Xr atrun 8 . .El @@ -70,7 +71,8 @@ the load average drops below 1.5, or the value specified in the invocation of .Nm allows some moderately complex .Ar time -specifications. It accepts times of the form +specifications. +It accepts times of the form .Ar HHMM or .Ar HH:MM @@ -153,7 +155,8 @@ command invoked from a .Xr su 1 shell will retain the current userid. The user will be mailed standard error and standard output from his -commands, if any. Mail will be sent using the command +commands, if any. +Mail will be sent using the command .Xr sendmail 8 . If .Nm @@ -201,7 +204,8 @@ the time may be specified in a language-neutral format consisting of: .It Ar CC The first two digits of the year (the century). .It Ar YY -The second two digits of the year. If +The second two digits of the year. +If .Ar YY is specified, but .Ar CC @@ -209,7 +213,8 @@ is not, a value for .Ar YY between 69 and 99 results in a .Ar CC -value of 19. Otherwise, a +value of 19. +Otherwise, a .Ar CC value of 20 is used. .It Ar MM @@ -225,7 +230,8 @@ The second of the minute, from 00 to 61. .El .It Fl q Ar queue Uses the specified queue. -A queue designation consists of a single letter. Valid queue designations +A queue designation consists of a single letter. +Valid queue designations range from .Sq a to @@ -270,8 +276,8 @@ Is an alias for .It Fl v For .Nm atq , -shows completed but not yet deleted jobs in the queue. Otherwise -shows the time the job will be executed. +shows completed but not yet deleted jobs in the queue. +Otherwise shows the time the job will be executed. .It Fl c Cats the jobs listed on the command line to standard output. .El diff --git a/usr.bin/awk/awk.1 b/usr.bin/awk/awk.1 index ec966d14706..2ee198c1817 100644 --- a/usr.bin/awk/awk.1 +++ b/usr.bin/awk/awk.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: awk.1,v 1.10 2002/05/15 19:00:32 fredb Exp $ +.\" $NetBSD: awk.1,v 1.11 2002/09/30 11:08:57 grant Exp $ .\" .\" Copyright (C) Lucent Technologies 1997 .\" All Rights Reserved @@ -725,7 +725,8 @@ Print all lines between start/stop pairs. .Pp A. V. Aho, B. W. Kernighan, P. J. Weinberger, .Em The AWK Programming Language , -Addison-Wesley, 1988. ISBN 0-201-07981-X +Addison-Wesley, 1988. +ISBN 0-201-07981-X .Pp .Em AWK Language Programming , Edition 1.0, published by the Free Software Foundation, 1995 diff --git a/usr.bin/bdes/bdes.1 b/usr.bin/bdes/bdes.1 index 927a38e071f..1e53383861c 100644 --- a/usr.bin/bdes/bdes.1 +++ b/usr.bin/bdes/bdes.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: bdes.1,v 1.8 2002/02/08 01:36:19 ross Exp $ +.\" $NetBSD: bdes.1,v 1.9 2002/09/30 11:08:57 grant Exp $ .\" .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -84,7 +84,8 @@ This flag applies to .Em both the key and initialization vector. .It Fl b -Use electronic code book mode. This is not recommended for messages +Use electronic code book mode. +This is not recommended for messages longer than 8 bytes, as patterns in the input will show through to the output. .It Fl d @@ -138,8 +139,9 @@ It is used only if the key is given in ASCII. .It Fl v Ar vector Set the initialization vector to .Ar vector ; -the vector is interpreted in the same way as the key. The vector is -ignored in electronic codebook mode. For best security, a different +the vector is interpreted in the same way as the key. +The vector is ignored in electronic codebook mode. +For best security, a different initialization vector should be used for each file. .El .Pp @@ -186,7 +188,8 @@ The DES is considered a very strong cryptosystem hobbled by a short key, and other than table lookup attacks, key search attacks, and Hellman's time-memory tradeoff (all of which are very expensive and time-consuming), no practical cryptanalytic methods for breaking the -DES are known in the open literature. As of this writing, the best +DES are known in the open literature. +As of this writing, the best known cryptanalytic method is linear cryptanalysis, which requires an average of .if t 2\u\s-343\s0\d @@ -319,13 +322,15 @@ SUCH DAMAGE. When this document was originally written, there was a controversy raging over whether the DES would still be secure in a few years. There is now near-universal consensus in the cryptographic community -that the key length of the DES is far too short. The advent of +that the key length of the DES is far too short. +The advent of special-purpose hardware could reduce the cost of any of the methods of attack named above so that they are no longer computationally infeasible; in addition, the explosive growth in the number and speed of modern microprocessors as well as advances in programmable logic devices has brought an attack using only commodity hardware into the -realm of possibility. Schneier and others currently recommend using +realm of possibility. +Schneier and others currently recommend using cryptosystems with keys of at least 90 bits when long-term security is needed. .Pp diff --git a/usr.bin/cap_mkdb/cap_mkdb.1 b/usr.bin/cap_mkdb/cap_mkdb.1 index 2d88598b23c..f76b84c9ba8 100644 --- a/usr.bin/cap_mkdb/cap_mkdb.1 +++ b/usr.bin/cap_mkdb/cap_mkdb.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: cap_mkdb.1,v 1.12 2002/02/08 01:36:20 ross Exp $ +.\" $NetBSD: cap_mkdb.1,v 1.13 2002/09/30 11:08:58 grant Exp $ .\" .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. @@ -80,8 +80,8 @@ The .Fl b and the .Fl l -flags are mutually exclusive. The default byte ordering is -the current host order. +flags are mutually exclusive. +The default byte ordering is the current host order. .Sh FORMAT Each record is stored in the database using two different types of keys. .Pp diff --git a/usr.bin/cksum/cksum.1 b/usr.bin/cksum/cksum.1 index 317fac54e9d..c04621ea0f4 100644 --- a/usr.bin/cksum/cksum.1 +++ b/usr.bin/cksum/cksum.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: cksum.1,v 1.17 2002/02/08 01:36:20 ross Exp $ +.\" $NetBSD: cksum.1,v 1.18 2002/09/30 11:08:58 grant Exp $ .\" .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -118,9 +118,11 @@ as output a 128-bit .Dq fingerprint or .Dq message digest -of the input. It is conjectured that it is computationally infeasible +of the input. +It is conjectured that it is computationally infeasible to product two messages having the same message digest, or to produce -any message having a given prespecified target message digest. The +any message having a given prespecified target message digest. +The MD5 algorithm is intended for digital signature applications, where a large file must be .Dq compressed @@ -205,10 +207,12 @@ selected message digest. .It Fl t Run a built-in message digest time trial. .It Fl x -Run a built-in message digest test script. The tests that are run +Run a built-in message digest test script. +The tests that are run are supposed to encompass all the various tests in the suites that accompany the algorithms' descriptions with the exception of the the -last test for the SHA-1 algorithm and the RIPEMD-160 algorithm. The +last test for the SHA-1 algorithm and the RIPEMD-160 algorithm. +The last test for these is one million copies of the lower letter a. .El .Pp diff --git a/usr.bin/elf2aout/elf2aout.1 b/usr.bin/elf2aout/elf2aout.1 index 56aced6fc34..9ad38dfb92d 100644 --- a/usr.bin/elf2aout/elf2aout.1 +++ b/usr.bin/elf2aout/elf2aout.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: elf2aout.1,v 1.7 2001/12/01 19:05:04 wiz Exp $ +.\" $NetBSD: elf2aout.1,v 1.8 2002/09/30 11:08:58 grant Exp $ .\" .\" Copyright 1996 The Board of Trustees of The Leland Stanford .\" Junior University. All Rights Reserved. @@ -55,7 +55,8 @@ and was first distributed with the pmax port of .Sh BUGS .Nm assumes there are no multiply-referenced symbols in the input ELF symbol -section. It may be necessary to link with +section. +It may be necessary to link with .Fl x to avoid such duplicate symbols. .Pp diff --git a/usr.bin/elf2ecoff/elf2ecoff.1 b/usr.bin/elf2ecoff/elf2ecoff.1 index b31ff7bd24a..1e9f5033c35 100644 --- a/usr.bin/elf2ecoff/elf2ecoff.1 +++ b/usr.bin/elf2ecoff/elf2ecoff.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: elf2ecoff.1,v 1.7 2001/12/01 19:06:01 wiz Exp $ +.\" $NetBSD: elf2ecoff.1,v 1.8 2002/09/30 11:08:59 grant Exp $ .\" .\" Copyright 1996 The Board of Trustees of The Leland Stanford .\" Junior University. All Rights Reserved. @@ -51,7 +51,8 @@ and was first distributed with the pmax port of .Sh BUGS .Nm assumes there are no multiply-referenced symbols in the input ELF symbol -section. It may be necessary to link with +section. +It may be necessary to link with .Fl x to avoid duplicate symbols. .Pp diff --git a/usr.bin/env/env.1 b/usr.bin/env/env.1 index 20e3b87703c..75cac316737 100644 --- a/usr.bin/env/env.1 +++ b/usr.bin/env/env.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: env.1,v 1.9 2001/12/01 19:07:26 wiz Exp $ +.\" $NetBSD: env.1,v 1.10 2002/09/30 11:08:59 grant Exp $ .\" .\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. @@ -34,7 +34,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)printenv.1 6.7 (Berkeley) 7/28/91 -.\" $NetBSD: env.1,v 1.9 2001/12/01 19:07:26 wiz Exp $ +.\" $NetBSD: env.1,v 1.10 2002/09/30 11:08:59 grant Exp $ .\" .Dd August 27, 1993 .Dt ENV 1 @@ -55,7 +55,8 @@ executes .Ar utility after modifying the environment as -specified on the command line. The option +specified on the command line. +The option .Ar name=value specifies an environmental variable, diff --git a/usr.bin/expand/expand.1 b/usr.bin/expand/expand.1 index 1846dd21dec..80a8bdaaaa6 100644 --- a/usr.bin/expand/expand.1 +++ b/usr.bin/expand/expand.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: expand.1,v 1.6 1999/03/22 18:16:36 garbled Exp $ +.\" $NetBSD: expand.1,v 1.7 2002/09/30 11:08:59 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -77,7 +77,8 @@ only): .Bl -tag -width flag .It Fl a By default, only leading blanks and tabs -are reconverted to maximal strings of tabs. If the +are reconverted to maximal strings of tabs. +If the .Fl a option is given, then tabs are inserted whenever they would compress the resultant file by replacing two or more characters. diff --git a/usr.bin/fdformat/fdformat.1 b/usr.bin/fdformat/fdformat.1 index 116683a4378..0470af65651 100644 --- a/usr.bin/fdformat/fdformat.1 +++ b/usr.bin/fdformat/fdformat.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: fdformat.1,v 1.13 2001/12/01 19:09:41 wiz Exp $ +.\" $NetBSD: fdformat.1,v 1.14 2002/09/30 11:08:59 grant Exp $ .\" .\" Copyright (c) 1996, 1997 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -84,7 +84,8 @@ With no arguments, it formats the default floppy device with the default density parameters (as provided by the floppy diskette device driver). .Pp As the each track of the floppy diskette is formatted, it is read to -verify the format was successful. A status is printed for each track. +verify the format was successful. +A status is printed for each track. .Em F indicates a track was formatted. .Em V @@ -94,7 +95,8 @@ indicates an error in formatting or verifying a track. .Pp The .Nm -utility does not create a filesystem of any kind. Use tools like +utility does not create a filesystem of any kind. +Use tools like .Xr newfs 8 , .Xr newfs_msdos 8 , or @@ -147,6 +149,7 @@ utility appeared in .Sh BUGS Some floppy drive units have physical diskette format sensors which automatically select a diskette -density for reading. Such drives can format at alternate densities, but +density for reading. +Such drives can format at alternate densities, but they cannot successfully verify the formatted diskette except at the diskette's normal density. diff --git a/usr.bin/file/file.1 b/usr.bin/file/file.1 index fc836079200..2ecc13d0ee5 100644 --- a/usr.bin/file/file.1 +++ b/usr.bin/file/file.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: file.1,v 1.28 2002/07/10 16:15:53 pooka Exp $ +.\" $NetBSD: file.1,v 1.29 2002/09/30 11:09:00 grant Exp $ .\" .TH FILE 1 "Copyright but distributable" .\" Id: file.man,v 1.42 2002/07/03 18:26:37 christos Exp @@ -176,10 +176,12 @@ to test the standard input, use ``\-'' as a filename argument. .TP 8 .B \-i Causes the file command to output mime type strings rather than the more -traditional human readable ones. Thus it may say +traditional human readable ones. +Thus it may say ``text/plain; charset=us-ascii'' rather -than ``ASCII text''. In order for this option to work, file changes the way +than ``ASCII text''. +In order for this option to work, file changes the way it handles files recognised by the command itself (such as many of the text file types, directories etc), and makes use of an alternative ``magic'' file. @@ -193,8 +195,10 @@ Specify an alternate list of files containing magic numbers. This can be a single file, or a colon-separated list of files. .TP 8 .B \-n -Force stdout to be flushed after checking each file. This is only useful if -checking a list of files. It is intended to be used by programs that want +Force stdout to be flushed after checking each file. +This is only useful if +checking a list of files. +It is intended to be used by programs that want filetype output from a pipe. .TP 8 .B \-v @@ -270,7 +274,8 @@ in an existing magic file would have to be changed to \*[Gt]10 string language\e impress (imPRESS data) .br In addition, in this version, if a pattern string contains a backslash, -it must be escaped. For example +it must be escaped. +For example .br 0 string \ebegindata Andrew Toolkit document .br @@ -370,7 +375,8 @@ of non-ASCII files. .PP The list of contributors to the "Magdir" directory (source for the /etc/magic -file) is too long to include here. You know who you are; thank you. +file) is too long to include here. +You know who you are; thank you. .SH LEGAL NOTICE Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999. Covered by the standard Berkeley Software Distribution copyright; see the file @@ -385,7 +391,8 @@ were written by John Gilmore from his public-domain program, and are not covered by the above license. .SH BUGS There must be a better way to automate the construction of the Magic -file from all the glop in Magdir. What is it? +file from all the glop in Magdir. +What is it? Better yet, the magic file should be compiled into binary (say, .BR ndbm (3) or, better yet, fixed-length @@ -432,7 +439,8 @@ This could be done by using some keyword like `*' for the offset value. Another optimisation would be to sort the magic file so that we can just run down all the tests for the first byte, first word, first long, etc, once we -have fetched it. Complain about conflicts in the magic file entries. +have fetched it. +Complain about conflicts in the magic file entries. Make a rule that the magic entries sort based on file offset rather than position within the magic file? .PP @@ -440,7 +448,8 @@ The program should provide a way to give an estimate of ``how good'' a guess is. We end up removing guesses (e.g. ``From '' as first 5 chars of file) because they are not as good as other guesses (e.g. ``Newsgroups:'' versus -``Return-Path:''). Still, if the others don't pan out, it should be +``Return-Path:''). +Still, if the others don't pan out, it should be possible to use the first guess. .PP This program is slower than some vendors' file commands. diff --git a/usr.bin/file/magic.5 b/usr.bin/file/magic.5 index 22797394999..0dac70d1f99 100644 --- a/usr.bin/file/magic.5 +++ b/usr.bin/file/magic.5 @@ -1,4 +1,4 @@ -.\" $NetBSD: magic.5,v 1.22 2002/07/09 14:59:54 pooka Exp $ +.\" $NetBSD: magic.5,v 1.23 2002/09/30 11:09:00 grant Exp $ .\" .TH MAGIC 5 "Public Domain" .\" install as magic.4 on USG, magic.5 on V7 or Berkeley systems. @@ -8,7 +8,8 @@ magic \- file command's magic number file This manual page documents the format of the magic file as used by the .BR file (1) -command, version 3.39. The +command, version 3.39. +The .BR file command identifies the type of a file using, among other tests, @@ -23,13 +24,15 @@ and additional information to extract from the file. Each line of the file specifies a test to be performed. A test compares the data starting at a particular offset in the file with a 1-byte, 2-byte, or 4-byte numeric value or -a string. If the test succeeds, a message is printed. +a string. +If the test succeeds, a message is printed. The line consists of the following fields: .IP offset \w'message'u+2n A number specifying the offset, in bytes, into the file of the data which is to be tested. .IP type -The type of the data to be tested. The possible values are: +The type of the data to be tested. +The possible values are: .RS .IP byte \w'message'u+2n A one-byte value. @@ -38,11 +41,16 @@ A two-byte value (on most systems) in this machine's native byte order. .IP long A four-byte value (on most systems) in this machine's native byte order. .IP string -A string of bytes. The string type specification can be optionally followed -by /[Bbc]*. The ``B'' flag compacts whitespace in the target, which must -contain at least one whitespace character. If the magic has "n" consecutive -blanks, the target needs at least "n" consecutive blanks to match. The ``b'' -flag treats every blank in the target as an optional blank. Finally the ``c'' +A string of bytes. +The string type specification can be optionally followed +by /[Bbc]*. +The ``B'' flag compacts whitespace in the target, which must +contain at least one whitespace character. +If the magic has "n" consecutive +blanks, the target needs at least "n" consecutive blanks to match. +The ``b'' +flag treats every blank in the target as an optional blank. +Finally the ``c'' flag, specifies case insensitive matching: lowercase characters in the magic match both lower and upper case characters in the targer, whereas upper case characters in the magic, only much uppercase characters in the target. @@ -75,11 +83,13 @@ The numeric types may optionally be followed by .B \*[Am] and a numeric value, to specify that the value is to be AND'ed with the -numeric value before any comparisons are done. Prepending a +numeric value before any comparisons are done. +Prepending a .B u to the type indicates that ordered comparisons should be unsigned. .IP test -The value to be compared with the value from the file. If the type is +The value to be compared with the value from the file. +If the type is numeric, this value is specified in C form; if it is a string, it is specified as a C string with the usual escapes permitted (e.g. \en for new-line). @@ -102,7 +112,8 @@ that are set in the specified value, to specify that the value from the file must have clear any of the bits that are set in the specified value, or .BR x , -to specify that any value will match. If the character is omitted, +to specify that any value will match. +If the character is omitted, it is assumed to be .BR = . .IP @@ -125,21 +136,25 @@ and .BR \*[Am] ) can be applied to strings. The length used for matching is that of the string argument -in the magic file. This means that a line can match any string, and +in the magic file. +This means that a line can match any string, and then presumably print that string, by doing .B \*[Gt]\e0 (because all strings are greater than the null string). .IP message -The message to be printed if the comparison succeeds. If the string +The message to be printed if the comparison succeeds. +If the string contains a .BR printf (3) format specification, the value from the file (with any specified masking performed) is printed using the message as the format string. .PP Some file formats contain additional information which is to be printed -along with the file type. A line which begins with the character +along with the file type. +A line which begins with the character .B \*[Gt] -indicates additional tests and messages to be printed. The number of +indicates additional tests and messages to be printed. +The number of .B \*[Gt] on the line indicates the level of the test; a line with no .B \*[Gt] @@ -153,7 +168,8 @@ If the test on a line at level .I n succeeds, the tests specified in all the subsequent lines at level .IB n \(pl1 -are performed, and the messages printed if the tests succeed. The next +are performed, and the messages printed if the tests succeed. +The next line at level .I n terminates this. @@ -163,27 +179,35 @@ is a .B ( then the string after the parenthesis is interpreted as an indirect offset. That means that the number after the parenthesis is used as an offset in -the file. The value at that offset is read, and is used again as an offset -in the file. Indirect offsets are of the form: +the file. +The value at that offset is read, and is used again as an offset +in the file. +Indirect offsets are of the form: .BI (( x [.[bslBSL]][+-][ y ]). The value of .I x -is used as an offset in the file. A byte, short or long is read at that offset +is used as an offset in the file. +A byte, short or long is read at that offset depending on the .B [bslBSL] -type specifier. The capitalized types interpret the number as a big endian +type specifier. +The capitalized types interpret the number as a big endian value, whereas the small letter versions interpet the number as a little -endian value. To that number the value of +endian value. +To that number the value of .I y -is added and the result is used as an offset in the file. The default type +is added and the result is used as an offset in the file. +The default type if one is not specified is long. .PP Sometimes you do not know the exact offset as this depends on the length of -preceding fields. You can specify an offset relative to the end of the +preceding fields. +You can specify an offset relative to the end of the last uplevel field (of course this may only be done for sublevel tests, i.e. test beginning with .B \*[Gt] -). Such a relative offset is specified using +). +Such a relative offset is specified using .B \*[Am] as a prefix to the offset. .SH BUGS diff --git a/usr.bin/finger/finger.1 b/usr.bin/finger/finger.1 index 7125b9bee63..8b202370d36 100644 --- a/usr.bin/finger/finger.1 +++ b/usr.bin/finger/finger.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: finger.1,v 1.13 2002/09/12 10:06:12 wiz Exp $ +.\" $NetBSD: finger.1,v 1.14 2002/09/30 11:09:00 grant Exp $ .\" .\" Copyright (c) 1989, 1990, 1993, 1994 .\" The Regents of the University of California. All rights reserved. @@ -52,10 +52,12 @@ displays information about the system users. Options are: .Bl -tag -width flag .It Fl 8 -Pass through 8-bit data. This option is intended for enabling 8-bit +Pass through 8-bit data. +This option is intended for enabling 8-bit data output in the .Xr fingerd 8 -service. Using this from the command line is +service. +Using this from the command line is .Em dangerous , as the output data may include control characters for your terminal. .It Fl g diff --git a/usr.bin/fpr/fpr.1 b/usr.bin/fpr/fpr.1 index 50abee9f07a..85f67181066 100644 --- a/usr.bin/fpr/fpr.1 +++ b/usr.bin/fpr/fpr.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: fpr.1,v 1.6 2002/02/08 01:36:23 ross Exp $ +.\" $NetBSD: fpr.1,v 1.7 2002/09/30 11:09:01 grant Exp $ .\" .\" Copyright (c) 1989, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -67,9 +67,12 @@ The first character of each line determines the vertical spacing as follows: .Ed .Pp A blank line is treated as if its first -character is a blank. A blank that appears as a carriage control -character is deleted. A zero is changed to a newline. A one is -changed to a form feed. The effects of a "+" are simulated using +character is a blank. +A blank that appears as a carriage control +character is deleted. +A zero is changed to a newline. +A one is changed to a form feed. +The effects of a "+" are simulated using backspaces. .Sh EXAMPLES .Dl a.out \&| fpr \&| lpr diff --git a/usr.bin/fsplit/fsplit.1 b/usr.bin/fsplit/fsplit.1 index 2c763b846a8..b3e46b90f7c 100644 --- a/usr.bin/fsplit/fsplit.1 +++ b/usr.bin/fsplit/fsplit.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: fsplit.1,v 1.6 2001/12/01 16:43:14 wiz Exp $ +.\" $NetBSD: fsplit.1,v 1.7 2002/09/30 11:09:01 grant Exp $ .\" .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -55,7 +55,8 @@ form where .Ar name is the name of the program unit (e.g. function, subroutine, block data or -program). The name for unnamed block data subprograms has the form +program). +The name for unnamed block data subprograms has the form .Ar blkdtaNNN.f where NNN is three digits and a file of this name does not already exist. For unnamed main programs the name has the form @@ -71,10 +72,12 @@ does not already exist. .Pp .Bl -tag -width Fl .It Fl e Ar efile -Normally each subprogram unit is split into a separate file. When the +Normally each subprogram unit is split into a separate file. +When the .Fl e option is used, only the specified subprogram units are split into separate -files. E.g.: +files. +E.g.: .Pp .Dl fsplit -e readit -e doit prog.f .Pp @@ -96,7 +99,8 @@ Asa Romberger and Jerry Berkman .Sh BUGS .Nm assumes the subprogram name is on the first noncomment line of the subprogram -unit. Nonstandard source formats may confuse +unit. +Nonstandard source formats may confuse .Nm "" . .Pp It is hard to use diff --git a/usr.bin/fstat/fstat.1 b/usr.bin/fstat/fstat.1 index b302a99d7be..f5c4567d043 100644 --- a/usr.bin/fstat/fstat.1 +++ b/usr.bin/fstat/fstat.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: fstat.1,v 1.20 2002/02/08 01:36:23 ross Exp $ +.\" $NetBSD: fstat.1,v 1.21 2002/09/30 11:09:01 grant Exp $ .\" .\" Copyright (c) 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -32,7 +32,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)fstat.1 8.3 (Berkeley) 2/25/94 -.\" $NetBSD: fstat.1,v 1.20 2002/02/08 01:36:23 ross Exp $ +.\" $NetBSD: fstat.1,v 1.21 2002/09/30 11:09:01 grant Exp $ .\" .Dd February 18, 1999 .Dt FSTAT 1 @@ -77,7 +77,8 @@ instead of the default Extract the name list from the specified system instead of the default .Pa /netbsd . .It Fl n -Numerical format. Print the device number (maj,min) of the filesystem +Numerical format. +Print the device number (maj,min) of the filesystem the file resides in rather than the mount point name; for special files, print the device number that the special device refers to rather than the filename @@ -89,12 +90,15 @@ Report all files open by the specified process. .It Fl u Report all files open by the specified user. .It Fl v -Verbose mode. Print error messages upon failures to locate particular -system data structures rather than silently ignoring them. Most of +Verbose mode. +Print error messages upon failures to locate particular +system data structures rather than silently ignoring them. +Most of these data structures are dynamically created or deleted and it is possible for them to disappear while .Nm -is running. This +is running. +This is normal and unavoidable since the rest of the system is running while .Nm itself is running. @@ -147,7 +151,8 @@ major/minor number of the device that this file resides in. .It Li INUM The inode number of the file. .It Li MODE -The mode of the file. If the +The mode of the file. +If the .Fl n flag isn't specified, the mode is printed using a symbolic format (see @@ -156,7 +161,8 @@ otherwise, the mode is printed as an octal number. .It Li SZ\&|DV If the file is not a character or block special file, prints the size of -the file in bytes. Otherwise, if the +the file in bytes. +Otherwise, if the .Fl n flag is not specified, prints the name of the special file as located in @@ -183,7 +189,8 @@ flag is not, then this field is present and is the name associated with the given file. Normally the name cannot be determined since there is no mapping from an open file back to the directory entry that was used to open -that file. Also, since different directory entries may reference +that file. +Also, since different directory entries may reference the same file (via .Xr ln 1 ) , the name printed may not be the actual diff --git a/usr.bin/ftp/ftp.1 b/usr.bin/ftp/ftp.1 index c65e3ce1c72..9d8baf4010f 100644 --- a/usr.bin/ftp/ftp.1 +++ b/usr.bin/ftp/ftp.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: ftp.1,v 1.86 2002/08/27 13:11:02 christos Exp $ +.\" $NetBSD: ftp.1,v 1.87 2002/09/30 11:09:02 grant Exp $ .\" .\" Copyright (c) 1996-2002 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -935,14 +935,17 @@ will send a .Dv PASV command for all data connections instead of a .Dv PORT -command. The +command. +The .Dv PASV command requests that the remote server open a port for the data connection -and return the address of that port. The remote server listens on that -port and the client connects to it. When using the more traditional +and return the address of that port. +The remote server listens on that port and the client connects to it. +When using the more traditional .Dv PORT command, the client listens on a port and sends that address to the remote -server, who connects back to it. Passive mode is useful when using +server, who connects back to it. +Passive mode is useful when using .Nm through a gateway router or host that controls the directionality of traffic. @@ -1455,7 +1458,8 @@ interpretation of the argument. Supported suffixes are: .Bl -tag -width 3n -offset indent -compact .It Li b -Causes no modification. (Optional) +Causes no modification. +(Optional) .It Li k Kilo; multiply the argument by 1024 .It Li m diff --git a/usr.bin/getopt/getopt.1 b/usr.bin/getopt/getopt.1 index c6af44e22cb..61f415ba859 100644 --- a/usr.bin/getopt/getopt.1 +++ b/usr.bin/getopt/getopt.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: getopt.1,v 1.13 2001/12/01 19:20:32 wiz Exp $ +.\" $NetBSD: getopt.1,v 1.14 2002/09/30 11:09:02 grant Exp $ .Dd November 9, 2000 .Dt GETOPT 1 .Os @@ -78,15 +78,15 @@ cmd \-a \-carg \-\- file file .St -p1003.2 mandates that the .Xr sh 1 -set command return the value of 0 for the exit status. Therefore, -the exit status of the +set command return the value of 0 for the exit status. +Therefore, the exit status of the .Nm command is lost when .Nm and the .Xr sh 1 -set command are used on the same line. The example given -is one way to detect errors found by +set command are used on the same line. +The example given is one way to detect errors found by .Nm "" . .Sh DIAGNOSTICS .Nm diff --git a/usr.bin/hesinfo/hesinfo.1 b/usr.bin/hesinfo/hesinfo.1 index 27d8f80f791..9ced5f53055 100644 --- a/usr.bin/hesinfo/hesinfo.1 +++ b/usr.bin/hesinfo/hesinfo.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: hesinfo.1,v 1.4 2002/02/08 01:36:24 ross Exp $ +.\" $NetBSD: hesinfo.1,v 1.5 2002/09/30 11:09:03 grant Exp $ .\" .\" from: #Id: hesinfo.1,v 1.9 1996/11/07 01:57:12 ghudson Exp # .\" @@ -25,7 +25,8 @@ hesinfo \fI[-bl]\fR \fIHesiodName\fR \fIHesiodNameType\fR .SH DESCRIPTION .I hesinfo takes two arguments, a name to be resolved and a string, known -as a HesiodNameType. It then prints the information returned by +as a HesiodNameType. +It then prints the information returned by the Hesiod nameserver. .PP The value returned by @@ -116,7 +117,8 @@ calls (e.g. .B prclusterlist ) do not require a specific .I HesiodName -argument. However, you must include a dummy string (e.g. 'foo') for +argument. +However, you must include a dummy string (e.g. 'foo') for .B hesinfo to work properly. diff --git a/usr.bin/hexdump/od.1 b/usr.bin/hexdump/od.1 index 95db5897220..131babf7d98 100644 --- a/usr.bin/hexdump/od.1 +++ b/usr.bin/hexdump/od.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: od.1,v 1.17 2002/02/08 01:36:24 ross Exp $ +.\" $NetBSD: od.1,v 1.18 2002/09/30 11:09:03 grant Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -88,7 +88,8 @@ The options are as follows: .Em One-byte character display . Display the input offset in octal, followed by sixteen space-separated, three column, space-filled, characters of input data -per line. Control characters are printed as their names instead of as +per line. +Control characters are printed as their names instead of as c style escapes. .It Fl B Same as @@ -97,13 +98,15 @@ Same as .Em One-byte octal display . Display the input offset in octal, followed by sixteen space-separated, three column, zero-filled, bytes of input data, in -octal, per line. This is the default output style if no other is +octal, per line. +This is the default output style if no other is selected. .It Fl c .Em One-byte character display . Display the input offset in octal, followed by sixteen space-separated, three column, space-filled, characters of input data -per line. Control characters are printed at c style escapes, or as +per line. +Control characters are printed at c style escapes, or as three octal digits, if no c escape exists for the character. .It Fl d .Em Two-byte decimal display . @@ -194,26 +197,29 @@ Display the input offset in octal, followed by eight space-separated, six column, zero-filled, two-byte units of input data, in octal, per line. .It Fl t Ar type_string -Specify one or more output types. The +Specify one or more output types. +The .Em type_string option-argument must be a string specifying the types to be used when -writing the input data. The string must consist of the type -specification characters: +writing the input data. +The string must consist of the type specification characters: .Pp .Cm a selects US-ASCII output, with control characters replaced with their -names instead of as c escape sequences. See also the +names instead of as c escape sequences. +See also the .Cm _u conversion provided by hexdump(1). .Pp .Cm c -selects a standard character based conversion. See also the +selects a standard character based conversion. +See also the .Cm _c conversion provided by hexdump(1). .Pp .Cm f -selects the floating point output format. This type character can be -optionally followed by the characters +selects the floating point output format. +This type character can be optionally followed by the characters .Cm 4 or .Cm F @@ -221,8 +227,9 @@ to specify four byte floating point output, or .Cm 8 or .Cm L -to specify eight byte floating point output. The default output -format is eight byte floats. See also the +to specify eight byte floating point output. +The default output format is eight byte floats. +See also the .Cm e conversion provided by hexdump(1). .Pp @@ -256,8 +263,9 @@ to specify two-byte output, .Cm 4 to specify four-byte output, or .Cm 8 -to specify eight-byte output. The default output format is in -four-byte quantities. See also the +to specify eight-byte output. +The default output format is in four-byte quantities. +See also the .Cm d , .Cm o , .Cm u , @@ -288,7 +296,8 @@ Same as For each input file, .Nm sequentially copies the input to standard output, transforming the -data according to the options given. If no options are specified, the +data according to the options given. +If no options are specified, the default display is equivalent to specifying the .Fl o option. diff --git a/usr.bin/ipcrm/ipcrm.1 b/usr.bin/ipcrm/ipcrm.1 index 3aeb8f16132..3e070d8cab3 100644 --- a/usr.bin/ipcrm/ipcrm.1 +++ b/usr.bin/ipcrm/ipcrm.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: ipcrm.1,v 1.8 2002/06/16 22:43:30 wiz Exp $ +.\" $NetBSD: ipcrm.1,v 1.9 2002/09/30 11:09:03 grant Exp $ .\" .\" Copyright (c) 1994 Adam Glass .\" All rights reserved. @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $NetBSD: ipcrm.1,v 1.8 2002/06/16 22:43:30 wiz Exp $ +.\" $NetBSD: ipcrm.1,v 1.9 2002/09/30 11:09:03 grant Exp $ .\"" .Dd June 17, 2002 .Dt IPCRM 1 @@ -56,10 +56,12 @@ and shared memory segments .Sh DESCRIPTION .Nm removes the specified message queues, semaphores and shared memory -segments. These System V IPC objects can be specified by their +segments. +These System V IPC objects can be specified by their creation id or any associated key. .Pp -The following options are used to specify which IPC objects will be removed. Any number and combination of these options can be used: +The following options are used to specify which IPC objects will be removed. +Any number and combination of these options can be used: .Bl -tag -width indent .It Fl q Ar msqid Remove the message queue associated with the id diff --git a/usr.bin/last/last.1 b/usr.bin/last/last.1 index b4e23032387..f36809accdd 100644 --- a/usr.bin/last/last.1 +++ b/usr.bin/last/last.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: last.1,v 1.8 2001/08/21 23:55:25 simonb Exp $ +.\" $NetBSD: last.1,v 1.9 2002/09/30 11:09:04 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -54,10 +54,12 @@ will list the sessions of specified .Ar ttys , and .Ar hosts , -in reverse time order. Each line of output contains +in reverse time order. +Each line of output contains the user name, the tty from which the session was conducted, any hostname, the start and stop times for the session, and the duration -of the session. If the session is still continuing or was cut short by +of the session. +If the session is still continuing or was cut short by a crash or shutdown, .Nm will so indicate. @@ -94,8 +96,8 @@ arguments is printed, e.g., .Dq Li "last root -t console" would list all of .Dq Li root Ns 's -sessions as well as all sessions on the console terminal. If no -users, hostnames or terminals are specified, +sessions as well as all sessions on the console terminal. +If no users, hostnames or terminals are specified, .Nm prints a record of all logins and logouts. @@ -109,7 +111,8 @@ will give an indication of mean time between reboot. If .Nm is interrupted, it indicates to what date the search has -progressed. If interrupted with a quit signal +progressed. +If interrupted with a quit signal .Nm indicates how far the search has progressed and then continues. diff --git a/usr.bin/lex/flex.1 b/usr.bin/lex/flex.1 index 6ab49fde135..c73ade53025 100644 --- a/usr.bin/lex/flex.1 +++ b/usr.bin/lex/flex.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: flex.1,v 1.10 2002/02/08 01:36:26 ross Exp $ +.\" $NetBSD: flex.1,v 1.11 2002/09/30 11:09:04 grant Exp $ .\" .TH FLEX 1 "April 1995" "Version 2.5" .SH NAME @@ -11,8 +11,8 @@ flex, lex \- fast lexical analyzer generator .SH OVERVIEW This manual describes .I flex, -a tool for generating programs that perform pattern-matching on text. The -manual includes both tutorial and reference sections: +a tool for generating programs that perform pattern-matching on text. +The manual includes both tutorial and reference sections: .nf Description @@ -95,8 +95,8 @@ programs which recognized lexical patterns in text. .I flex reads the given input files, or its standard input if no file names are given, -for a description of a scanner to generate. The description is in -the form of pairs +for a description of a scanner to generate. +The description is in the form of pairs of regular expressions and C code, called .I rules. flex generates as output a C source file, @@ -105,9 +105,11 @@ which defines a routine .B yylex(). This file is compiled and linked with the .B \-lfl -library to produce an executable. When the executable is run, +library to produce an executable. +When the executable is run, it analyzes its input for occurrences -of the regular expressions. Whenever it finds one, it executes +of the regular expressions. +Whenever it finds one, it executes the corresponding C code. .SH SOME SIMPLE EXAMPLES .PP @@ -129,7 +131,8 @@ scanner is copied to the output, so the net effect of this scanner is to copy its input file to its output with each occurrence of "username" expanded. -In this input, there is just one rule. "username" is the +In this input, there is just one rule. +"username" is the .I pattern and the "printf" is the .I action. @@ -155,13 +158,15 @@ Here's another simple example: .fi This scanner counts the number of characters and the number of lines in its input (it produces no output other than the -final report on the counts). The first line +final report on the counts). +The first line declares two globals, "num_lines" and "num_chars", which are accessible both inside .B yylex() and in the .B main() -routine declared after the second "%%". There are two rules, one +routine declared after the second "%%". +There are two rules, one which matches a newline ("\\n") and increments both the line count and the character count, and one which matches any character other than a newline (indicated by the "." regular expression). @@ -222,7 +227,8 @@ A somewhat more complicated example: .fi This is the beginnings of a simple scanner for a language like -Pascal. It identifies different types of +Pascal. +It identifies different types of .I tokens and reports on what it has seen. .PP @@ -262,7 +268,8 @@ followed by zero or more letters, digits, '_', or '-' (dash). The definition is taken to begin at the first non-white-space character following the name and continuing to the end of the line. The definition can subsequently be referred to using "{name}", which -will expand to "(definition)". For example, +will expand to "(definition)". +For example, .nf DIGIT [0-9] @@ -307,7 +314,8 @@ Finally, the user code section is simply copied to .B lex.yy.c verbatim. It is used for companion routines which call or are called -by the scanner. The presence of this section is optional; +by the scanner. +The presence of this section is optional; if it is missing, the second .B %% in the input file may be skipped, too. @@ -338,7 +346,8 @@ beginning with "/*") is also copied verbatim to the output up to the next "*/". .SH PATTERNS The patterns in the input are written using an extended set of regular -expressions. These are: +expressions. +These are: .nf x match the character 'x' @@ -424,7 +433,8 @@ operators, '-', ']', and, at the beginning of the class, '^'. .PP The regular expressions listed above are grouped according to precedence, from highest precedence at the top to lowest at the bottom. -Those grouped together have equal precedence. For example, +Those grouped together have equal precedence. +For example, .nf foo|bar* @@ -437,7 +447,8 @@ is the same as .fi since the '*' operator has higher precedence than concatenation, -and concatenation higher than alternation ('|'). This pattern +and concatenation higher than alternation ('|'). +This pattern therefore matches .I either the string "foo" @@ -477,7 +488,8 @@ The valid expressions are: These expressions all designate a set of characters equivalent to the corresponding standard C .B isXXX -function. For example, +function. +For example, .B [:alnum:] designates those characters for which .B isalnum() @@ -513,16 +525,19 @@ above .I will match a newline unless "\\n" (or an equivalent escape sequence) is one of the characters explicitly present in the negated character class -(e.g., "[^A-Z\\n]"). This is unlike how many other regular +(e.g., "[^A-Z\\n]"). +This is unlike how many other regular expression tools treat negated character classes, but unfortunately the inconsistency is historically entrenched. Matching newlines means that a pattern like [^"]* can match the entire input unless there's another quote in the input. .IP - A rule can have at most one instance of trailing context (the '/' operator -or the '$' operator). The start condition, '^', and "\*[Lt]\*[Lt]EOF\*[Gt]\*[Gt]" patterns +or the '$' operator). +The start condition, '^', and "\*[Lt]\*[Lt]EOF\*[Gt]\*[Gt]" patterns can only occur at the beginning of a pattern, and, as well as with '/' and '$', -cannot be grouped inside parentheses. A '^' which does not occur at +cannot be grouped inside parentheses. +A '^' which does not occur at the beginning of a rule or a '$' which does not occur at the end of a rule loses its special properties and is treated as a normal character. .IP @@ -554,10 +569,12 @@ A similar trick will work for matching a foo or a bar-at-the-beginning-of-a-line. .SH HOW THE INPUT IS MATCHED When the generated scanner is run, it analyzes its input looking -for strings which match any of its patterns. If it finds more than +for strings which match any of its patterns. +If it finds more than one match, it takes the one matching the most text (for trailing context rules, this includes the length of the trailing part, even -though it will then be returned to the input). If it finds two +though it will then be returned to the input). +If it finds two or more matches of the same length, the rule listed first in the .I flex @@ -579,7 +596,8 @@ input is scanned for another match. If no match is found, then the .I default rule is executed: the next character in the input is considered matched and -copied to the standard output. Thus, the simplest legal +copied to the standard output. +Thus, the simplest legal .I flex input is: .nf @@ -602,7 +620,8 @@ uses by including one of the special directives .B %pointer or .B %array -in the first (definitions) section of your flex input. The default is +in the first (definitions) section of your flex input. +The default is .B %pointer, unless you use the .B -l @@ -612,7 +631,8 @@ will be an array. The advantage of using .B %pointer is substantially faster scanning and no buffer overflow when matching -very large tokens (unless you run out of dynamic memory). The disadvantage +very large tokens (unless you run out of dynamic memory). +The disadvantage is that you are restricted in how your actions can modify .B yytext (see the next section), and calls to the @@ -631,7 +651,8 @@ to your heart's content, and calls to .B unput() do not destroy .B yytext -(see below). Furthermore, existing +(see below). +Furthermore, existing .I lex programs sometimes access .B yytext @@ -649,14 +670,17 @@ defines .B yytext to be an array of .B YYLMAX -characters, which defaults to a fairly large value. You can change +characters, which defaults to a fairly large value. +You can change the size by simply #define'ing .B YYLMAX to a different value in the first section of your .I flex -input. As mentioned above, with +input. +As mentioned above, with .B %pointer -yytext grows dynamically to accommodate large tokens. While this means your +yytext grows dynamically to accommodate large tokens. +While this means your .B %pointer scanner can accommodate very large tokens (such as matching entire blocks of comments), bear in mind that each time the scanner must resize @@ -678,10 +702,13 @@ with C++ scanner classes option; see below). .SH ACTIONS Each pattern in a rule has a corresponding action, which can be any -arbitrary C statement. The pattern ends at the first non-escaped -whitespace character; the remainder of the line is its action. If the +arbitrary C statement. +The pattern ends at the first non-escaped +whitespace character; the remainder of the line is its action. +If the action is empty, then when the pattern is matched the input token -is simply discarded. For example, here is the specification for a program +is simply discarded. +For example, here is the specification for a program which deletes all occurrences of "zap me" from its input: .nf @@ -729,7 +756,8 @@ Actions are free to modify .B yytext except for lengthening it (adding characters to its end--these will overwrite later characters in the -input stream). This however does not apply when using +input stream). +This however does not apply when using .B %array (see above); in that case, .B yytext @@ -753,7 +781,8 @@ corresponding start condition (see below). .IP - .B REJECT directs the scanner to proceed on to the "second best" rule which matched the -input (or a prefix of the input). The rule is chosen as described +input (or a prefix of the input). +The rule is chosen as described above in "How the Input is Matched", and .B yytext and @@ -781,7 +810,8 @@ scanner normally executes only one action per token. Multiple .B REJECT's are allowed, each one finding the next best choice to the currently -active rule. For example, when the following scanner scans the token +active rule. +For example, when the following scanner scans the token "abcd", it will write "abcdabcaba" to the output: .nf @@ -801,7 +831,8 @@ if it is used in .I any of the scanner's actions it will slow down .I all -of the scanner's matching. Furthermore, +of the scanner's matching. +Furthermore, .B REJECT cannot be used with the .I -Cf @@ -823,7 +854,8 @@ token should be .I appended onto the current value of .B yytext -rather than replacing it. For example, given the input "mega-kludge" +rather than replacing it. +For example, given the input "mega-kludge" the following will write "mega-mega-kludge" to the output: .nf @@ -832,7 +864,8 @@ the following will write "mega-mega-kludge" to the output: kludge ECHO; .fi -First "mega-" is matched and echoed to the output. Then "kludge" +First "mega-" is matched and echoed to the output. +Then "kludge" is matched, but the previous "mega-" is still hanging around at the beginning of .B yytext @@ -868,7 +901,8 @@ are adjusted appropriately (e.g., .B yyleng will now be equal to .I n -). For example, on the input "foobar" the following will write out +). +For example, on the input "foobar" the following will write out "foobarbar": .nf @@ -879,7 +913,8 @@ will now be equal to .fi An argument of 0 to .B yyless -will cause the entire current input string to be scanned again. Unless you've +will cause the entire current input string to be scanned again. +Unless you've changed how the scanner will subsequently process its input (using .B BEGIN, for example), this will result in an endless loop. @@ -892,7 +927,8 @@ other source files. .B unput(c) puts the character .I c -back onto the input stream. It will be the next character scanned. +back onto the input stream. +It will be the next character scanned. The following action will take the current token and cause it to be rescanned enclosed in parentheses. .nf @@ -925,7 +961,8 @@ is that if you are using the contents of .I yytext, starting with its rightmost character and devouring one character to -the left with each call. If you need the value of yytext preserved +the left with each call. +If you need the value of yytext preserved after a call to .B unput() (as in the above example), @@ -938,7 +975,8 @@ Finally, note that you cannot put back to attempt to mark the input stream with an end-of-file. .IP - .B input() -reads the next character from the input stream. For example, +reads the next character from the input stream. +For example, the following is one way to eat up C comments: .nf @@ -985,18 +1023,20 @@ flushes the scanner's internal buffer so that the next time the scanner attempts to match a token, it will first refill the buffer using .B YY_INPUT -(see The Generated Scanner, below). This action is a special case +(see The Generated Scanner, below). +This action is a special case of the more general .B yy_flush_buffer() function, described below in the section Multiple Input Buffers. .IP - .B yyterminate() -can be used in lieu of a return statement in an action. It terminates +can be used in lieu of a return statement in an action. +It terminates the scanner and returns a 0 to the scanner's caller, indicating "all done". By default, .B yyterminate() -is also called when an end-of-file is encountered. It is a macro and -may be redefined. +is also called when an end-of-file is encountered. +It is a macro and may be redefined. .SH THE GENERATED SCANNER The output of .I flex @@ -1005,7 +1045,8 @@ is the file which contains the scanning routine .B yylex(), a number of tables used by it for matching tokens, and a number -of auxiliary routines and macros. By default, +of auxiliary routines and macros. +By default, .B yylex() is declared as follows: .nf @@ -1018,7 +1059,8 @@ is declared as follows: .fi (If your environment supports function prototypes, then it will be "int yylex( void )".) This definition may be changed by defining -the "YY_DECL" macro. For example, you could use: +the "YY_DECL" macro. +For example, you could use: .nf #define YY_DECL float lexscan( a, b ) float a, b; @@ -1026,7 +1068,8 @@ the "YY_DECL" macro. For example, you could use: .fi to give the scanning routine the name .I lexscan, -returning a float, and taking two floats as arguments. Note that +returning a float, and taking two floats as arguments. +Note that if you give arguments to the scanning routine using a K\*[Am]R-style/non-prototyped function declaration, you must terminate the definition with a semi-colon (;). @@ -1035,7 +1078,8 @@ Whenever .B yylex() is called, it scans tokens from the global input file .I yyin -(which defaults to stdin). It continues until it either reaches +(which defaults to stdin). +It continues until it either reaches an end-of-file (at which point it returns the value 0) or one of its actions executes a .I return @@ -1057,7 +1101,8 @@ to scan from a source other than .I yyin), and initializes .I yyin -for scanning from that file. Essentially there is no difference between +for scanning from that file. +Essentially there is no difference between just assigning .I yyin to a new input file or using @@ -1095,8 +1140,8 @@ calls to read characters from The nature of how it gets its input can be controlled by defining the .B YY_INPUT macro. -YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its -action is to place up to +YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". +Its action is to place up to .I max_size characters in the character array .I buf @@ -1104,7 +1149,8 @@ and return in the integer variable .I result either the number of characters read or the constant YY_NULL (0 on Unix systems) -to indicate EOF. The default YY_INPUT reads from the +to indicate EOF. +The default YY_INPUT reads from the global file-pointer "yyin". .PP A sample definition of YY_INPUT (in the definitions @@ -1126,14 +1172,17 @@ one character at a time. When the scanner receives an end-of-file indication from YY_INPUT, it then checks the .B yywrap() -function. If +function. +If .B yywrap() returns false (zero), then it is assumed that the function has gone ahead and set up .I yyin -to point to another input file, and scanning continues. If it returns +to point to another input file, and scanning continues. +If it returns true (non-zero), then the scanner terminates, returning 0 to its -caller. Note that in either case, the start condition remains unchanged; +caller. +Note that in either case, the start condition remains unchanged; it does .I not revert to @@ -1166,9 +1215,11 @@ by assigning it to some other pointer. .SH START CONDITIONS .I flex -provides a mechanism for conditionally activating rules. Any rule +provides a mechanism for conditionally activating rules. +Any rule whose pattern is prefixed with "\*[Lt]sc\*[Gt]" will only be active when -the scanner is in the start condition named "sc". For example, +the scanner is in the start condition named "sc". +For example, .nf \*[Lt]STRING\*[Gt][^"]* { /* eat up the string body ... */ @@ -1199,9 +1250,11 @@ The former declares .I inclusive start conditions, the latter .I exclusive -start conditions. A start condition is activated using the +start conditions. +A start condition is activated using the .B BEGIN -action. Until the next +action. +Until the next .B BEGIN action is executed, rules with the given start condition will be active and @@ -1217,14 +1270,15 @@ rules qualified with the start condition will be active. A set of rules contingent on the same exclusive start condition describe a scanner which is independent of any of the other rules in the .I flex -input. Because of this, +input. +Because of this, exclusive start conditions make it easy to specify "mini-scanners" which scan portions of the input that are syntactically different from the rest (e.g., comments). .PP If the distinction between inclusive and exclusive start conditions is still a little vague, here's a simple example illustrating the -connection between the two. The set of rules: +connection between the two. The set of rules: .nf %s example @@ -1271,8 +1325,8 @@ start condition. .PP Also note that the special start-condition specifier .B \*[Lt]*\*[Gt] -matches every start condition. Thus, the above example could also -have been written; +matches every start condition. +Thus, the above example could also have been written; .nf %x example @@ -1286,7 +1340,8 @@ have been written; .PP The default rule (to .B ECHO -any unmatched character) remains active in start conditions. It +any unmatched character) remains active in start conditions. +It is equivalent to: .nf @@ -1296,7 +1351,8 @@ is equivalent to: .PP .B BEGIN(0) returns to the original state where only the rules with -no start conditions are active. This state can also be +no start conditions are active. +This state can also be referred to as the start-condition "INITIAL", so .B BEGIN(INITIAL) is equivalent to @@ -1306,7 +1362,8 @@ are considered good style.) .PP .B BEGIN actions can also be given as indented code at the beginning -of the rules section. For example, the following will cause +of the rules section. +For example, the following will cause the scanner to enter the "SPECIAL" start condition whenever .B yylex() is called and the global variable @@ -1328,7 +1385,8 @@ is true: .PP To illustrate the uses of start conditions, here is a scanner which provides two different interpretations -of a string like "123.456". By default it will treat it as +of a string like "123.456". +By default it will treat it as three tokens, the integer "123", a dot ('.'), and the integer "456". But if the string is preceded earlier in the line by the string "expect-floats" @@ -1382,12 +1440,14 @@ maintaining a count of the current input line. .fi This scanner goes to a bit of trouble to match as much -text as possible with each rule. In general, when attempting to write +text as possible with each rule. +In general, when attempting to write a high-speed scanner try to match as much possible in each rule, as it's a big win. .PP Note that start-conditions names are really integer values and -can be stored as such. Thus, the above could be extended in the +can be stored as such. +Thus, the above could be extended in the following fashion: .nf @@ -1417,7 +1477,8 @@ following fashion: Furthermore, you can access the current start condition using the integer-valued .B YY_START -macro. For example, the above assignments to +macro. +For example, the above assignments to .I comment_caller could instead be written .nf @@ -1498,8 +1559,8 @@ not including checking for a string that's too long): .fi .PP Often, such as in some of the examples above, you wind up writing a -whole bunch of rules all preceded by the same start condition(s). Flex -makes this a little easier and cleaner by introducing a notion of +whole bunch of rules all preceded by the same start condition(s). +Flex makes this a little easier and cleaner by introducing a notion of start condition .I scope. A start condition scope is begun with: @@ -1510,7 +1571,8 @@ A start condition scope is begun with: .fi where .I SCs -is a list of one or more start conditions. Inside the start condition +is a list of one or more start conditions. +Inside the start condition scope, every rule automatically has the prefix .I \*[Lt]SCs\*[Gt] applied to it, until a @@ -1557,14 +1619,16 @@ pops the top of the stack and switches to it via returns the top of the stack without altering the stack's contents. .PP The start condition stack grows dynamically and so has no built-in -size limitation. If memory is exhausted, program execution aborts. +size limitation. +If memory is exhausted, program execution aborts. .PP To use start condition stacks, your scanner must include a .B %option stack directive (see Options below). .SH MULTIPLE INPUT BUFFERS Some scanners (such as those which support "include" files) -require reading from several input streams. As +require reading from several input streams. +As .I flex scanners do a large amount of buffering, one cannot control where the next input will be read from by simply writing a @@ -1578,7 +1642,8 @@ which requires switching the input source. To negotiate these sorts of problems, .I flex provides a mechanism for creating and switching between multiple -input buffers. An input buffer is created by using: +input buffers. +An input buffer is created by using: .nf YY_BUFFER_STATE yy_create_buffer( FILE *file, int size ) @@ -1591,9 +1656,11 @@ file and large enough to hold .I size characters (when in doubt, use .B YY_BUF_SIZE -for the size). It returns a +for the size). +It returns a .B YY_BUFFER_STATE -handle, which may then be passed to other routines (see below). The +handle, which may then be passed to other routines (see below). +The .B YY_BUFFER_STATE type is a pointer to an opaque .B struct yy_buffer_state @@ -1601,7 +1668,8 @@ structure, so you may safely initialize YY_BUFFER_STATE variables to .B ((YY_BUFFER_STATE) 0) if you wish, and also refer to the opaque structure in order to correctly declare input buffers in source files other than that -of your scanner. Note that the +of your scanner. +Note that the .I FILE pointer in the call to .B yy_create_buffer @@ -1631,7 +1699,8 @@ Note that may be used by yywrap() to set things up for continued scanning, instead of opening a new file and pointing .I yyin -at it. Note also that switching input sources via either +at it. +Note also that switching input sources via either .B yy_switch_to_buffer() or .B yywrap() @@ -1643,7 +1712,8 @@ change the start condition. void yy_delete_buffer( YY_BUFFER_STATE buffer ) .fi -is used to reclaim the storage associated with a buffer. ( +is used to reclaim the storage associated with a buffer. +( .B buffer can be nil, in which case the routine does nothing.) You can also clear the current contents of a buffer using: @@ -1733,12 +1803,14 @@ feature is discussed below): .fi Three routines are available for setting up input buffers for -scanning in-memory strings instead of files. All of them create +scanning in-memory strings instead of files. +All of them create a new input buffer for scanning the string, and return a corresponding .B YY_BUFFER_STATE handle (which you should delete with .B yy_delete_buffer() -when done with it). They also switch to the new buffer using +when done with it). +They also switch to the new buffer using .B yy_switch_to_buffer(), so the next call to .B yylex() @@ -1756,7 +1828,8 @@ starting at location .PP Note that both of these functions create and scan a .I copy -of the string or bytes. (This may be desirable, since +of the string or bytes. +(This may be desirable, since .B yylex() modifies the contents of the buffer it is scanning.) You can avoid the copy by using: @@ -1794,7 +1867,8 @@ reflecting the size of the buffer. The special rule "\*[Lt]\*[Lt]EOF\*[Gt]\*[Gt]" indicates actions which are to be taken when an end-of-file is encountered and yywrap() returns non-zero (i.e., indicates -no further files to process). The action must finish +no further files to process). +The action must finish by doing one of four things: .IP - assigning @@ -1818,10 +1892,12 @@ as shown in the example above. .PP \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] rules may not be used with other patterns; they may only be qualified with a list of start -conditions. If an unqualified \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] rule is given, it +conditions. +If an unqualified \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] rule is given, it applies to .I all -start conditions which do not already have \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] actions. To +start conditions which do not already have \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] actions. +To specify an \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] rule for only the initial start condition, use .nf @@ -1854,15 +1930,16 @@ An example: The macro .B YY_USER_ACTION can be defined to provide an action -which is always executed prior to the matched rule's action. For example, +which is always executed prior to the matched rule's action. +For example, it could be #define'd to call a routine to convert yytext to lower-case. When .B YY_USER_ACTION is invoked, the variable .I yy_act gives the number of the matched rule (rules are numbered starting with 1). -Suppose you want to profile how often each of your rules is matched. The -following would do the trick: +Suppose you want to profile how often each of your rules is matched. +The following would do the trick: .nf #define YY_USER_ACTION ++ctr[yy_act] @@ -1870,8 +1947,8 @@ following would do the trick: .fi where .I ctr -is an array to hold the counts for the different rules. Note that -the macro +is an array to hold the counts for the different rules. +Note that the macro .B YY_NUM_RULES gives the total number of rules (including the default rule, even if you use @@ -1901,9 +1978,11 @@ but must be used when the scanner's input source is indeed interactive to avoid problems due to waiting to fill buffers (see the discussion of the .B \-I -flag below). A non-zero value +flag below). +A non-zero value in the macro invocation marks the buffer as interactive, a zero -value as non-interactive. Note that use of this macro overrides +value as non-interactive. +Note that use of this macro overrides .B %option always-interactive or .B %option never-interactive @@ -1916,7 +1995,8 @@ The macro .B yy_set_bol(at_bol) can be used to control whether the current buffer's scanning context for the next token match is done as though at the -beginning of a line. A non-zero macro argument makes rules anchored with +beginning of a line. +A non-zero macro argument makes rules anchored with '^' active, while a zero argument makes '^' rules inactive. .PP The macro @@ -1927,7 +2007,8 @@ will have '^' rules active, false otherwise. In the generated scanner, the actions are all gathered in one large switch statement and separated using .B YY_BREAK, -which may be redefined. By default, it is simply a "break", to separate +which may be redefined. +By default, it is simply a "break", to separate each rule's action from the following rule's. Redefining .B YY_BREAK @@ -1943,7 +2024,8 @@ This section summarizes the various values available to the user in the rule actions. .IP - .B char *yytext -holds the text of the current token. It may be modified but not lengthened +holds the text of the current token. +It may be modified but not lengthened (you cannot append characters to the end). .IP If the special directive @@ -1955,7 +2037,8 @@ is instead declared where .B YYLMAX is a macro definition that you can redefine in the first section -if you don't like the default value (generally 8KB). Using +if you don't like the default value (generally 8KB). +Using .B %array results in somewhat slower scanners, but the value of .B yytext @@ -1965,7 +2048,8 @@ and .I unput(), which potentially destroy its value when .B yytext -is a character pointer. The opposite of +is a character pointer. +The opposite of .B %array is .B %pointer, @@ -1984,9 +2068,10 @@ holds the length of the current token. .B FILE *yyin is the file which by default .I flex -reads from. It may be redefined but doing so only makes sense before -scanning begins or after an EOF has been encountered. Changing it in -the midst of scanning will have unexpected results since +reads from. +It may be redefined but doing so only makes sense before +scanning begins or after an EOF has been encountered. +Changing it in the midst of scanning will have unexpected results since .I flex buffers its input; use .B yyrestart() @@ -1999,8 +2084,10 @@ at the new input file and then call the scanner again to continue scanning. .B void yyrestart( FILE *new_file ) may be called to point .I yyin -at the new input file. The switch-over to the new file is immediate -(any previously buffered-up input is lost). Note that calling +at the new input file. +The switch-over to the new file is immediate +(any previously buffered-up input is lost). +Note that calling .B yyrestart() with .I yyin @@ -2010,7 +2097,8 @@ scanning the same input file. .B FILE *yyout is the file to which .B ECHO -actions are done. It can be reassigned by the user. +actions are done. +It can be reassigned by the user. .IP - .B YY_CURRENT_BUFFER returns a @@ -2019,7 +2107,8 @@ handle to the current buffer. .IP - .B YY_START returns an integer value corresponding to the current start -condition. You can subsequently use this value with +condition. +You can subsequently use this value with .B BEGIN to return to that start condition. .SH INTERFACING WITH YACC @@ -2031,7 +2120,8 @@ parser-generator. .I yacc parsers expect to call a routine named .B yylex() -to find the next input token. The routine is supposed to +to find the next input token. +The routine is supposed to return the type of the next token as well as putting any associated value in the global .B yylval. @@ -2049,9 +2139,11 @@ containing definitions of all the .B %tokens appearing in the .I yacc -input. This file is then included in the +input. +This file is then included in the .I flex -scanner. For example, if one of the tokens is "TOK_NUMBER", +scanner. +For example, if one of the tokens is "TOK_NUMBER", part of the scanner might look like: .nf @@ -2072,8 +2164,10 @@ has the following options: Generate backing-up information to .I lex.backup. This is a list of scanner states which require backing up -and the input characters on which they do so. By adding rules one -can remove backing-up states. If +and the input characters on which they do so. +By adding rules one +can remove backing-up states. +If .I all backing-up states are eliminated and .B \-Cf @@ -2081,9 +2175,10 @@ or .B \-CF is used, the generated scanner will run faster (see the .B \-p -flag). Only users who wish to squeeze every last cycle out of their -scanners need worry about this option. (See the section on Performance -Considerations below.) +flag). +Only users who wish to squeeze every last cycle out of their +scanners need worry about this option. +(See the section on Performance Considerations below.) .TP .B \-c is a do-nothing, deprecated option included for POSIX compliance. @@ -2091,7 +2186,8 @@ is a do-nothing, deprecated option included for POSIX compliance. .B \-d makes the generated scanner run in .I debug -mode. Whenever a pattern is recognized and the global +mode. +Whenever a pattern is recognized and the global .B yy_flex_debug is non-zero (which is the default), the scanner will write to @@ -2103,8 +2199,8 @@ a line of the form: .fi The line number refers to the location of the rule in the file -defining the scanner (i.e., the file that was fed to flex). Messages -are also generated when the scanner backs up, accepts the +defining the scanner (i.e., the file that was fed to flex). +Messages are also generated when the scanner backs up, accepts the default rule, reaches the end of its input buffer (or encounters a NUL; at this point, the two look the same as far as the scanner's concerned), or reaches an end-of-file. @@ -2113,7 +2209,8 @@ or reaches an end-of-file. specifies .I fast scanner. No table compression is done and stdio is bypassed. -The result is large but fast. This option is equivalent to +The result is large but fast. +This option is equivalent to .B \-Cfr (see below). .TP @@ -2134,26 +2231,31 @@ instructs .I flex to generate a .I case-insensitive -scanner. The case of letters given in the +scanner. +The case of letters given in the .I flex input patterns will -be ignored, and tokens in the input will be matched regardless of case. The -matched text given in +be ignored, and tokens in the input will be matched regardless of case. +The matched text given in .I yytext will have the preserved case (i.e., it will not be folded). .TP .B \-l turns on maximum compatibility with the original AT\*[Am]T .I lex -implementation. Note that this does not mean +implementation. +Note that this does not mean .I full -compatibility. Use of this option costs a considerable amount of +compatibility. +Use of this option costs a considerable amount of performance, and it cannot be used with the .B \-+, -f, -F, -Cf, or .B -CF -options. For details on the compatibilities it provides, see the section -"Incompatibilities With Lex And POSIX" below. This option also results +options. +For details on the compatibilities it provides, see the section +"Incompatibilities With Lex And POSIX" below. +This option also results in the name .B YY_FLEX_LEX_COMPAT being #define'd in the generated scanner. @@ -2163,11 +2265,12 @@ is another do-nothing, deprecated option included only for POSIX compliance. .TP .B \-p -generates a performance report to stderr. The report -consists of comments regarding features of the +generates a performance report to stderr. +The report consists of comments regarding features of the .I flex input file which will cause a serious loss of performance in the resulting -scanner. If you give the flag twice, you will also get comments regarding +scanner. +If you give the flag twice, you will also get comments regarding features that lead to minor performance losses. .IP Note that the use of @@ -2188,8 +2291,10 @@ causes the .I default rule (that unmatched scanner input is echoed to .I stdout) -to be suppressed. If the scanner encounters input that does not -match any of its rules, it aborts with an error. This option is +to be suppressed. +If the scanner encounters input that does not +match any of its rules, it aborts with an error. +This option is useful for finding holes in a scanner's rule set. .TP .B \-t @@ -2226,14 +2331,16 @@ scanner, the opposite of .I interactive scanners generated by .B \-I -(see below). In general, you use +(see below). +In general, you use .B \-B when you are .I certain that your scanner will never be used interactively, and you want to squeeze a .I little -more performance out of it. If your goal is instead to squeeze out a +more performance out of it. +If your goal is instead to squeeze out a .I lot more performance, you should be using the .B \-Cf @@ -2248,11 +2355,12 @@ specifies that the .ul fast scanner table representation should be used (and stdio -bypassed). This representation is -about as fast as the full table representation +bypassed). +This representation is about as fast as the full table representation .B (-f), and for some sets of patterns will be considerably smaller (and for -others, larger). In general, if the pattern set contains both "keywords" +others, larger). +In general, if the pattern set contains both "keywords" and a catch-all, "identifier" rule, such as in the set: .nf @@ -2263,14 +2371,16 @@ and a catch-all, "identifier" rule, such as in the set: [a-z]+ return TOK_ID; .fi -then you're better off using the full table representation. If only +then you're better off using the full table representation. +If only the "identifier" rule is present and you then use a hash table or some such to detect the keywords, you're better off using .B -F. .IP This option is equivalent to .B \-CFr -(see below). It cannot be used with +(see below). +It cannot be used with .B \-+. .TP .B \-I @@ -2278,11 +2388,14 @@ instructs .I flex to generate an .I interactive -scanner. An interactive scanner is one that only looks ahead to decide -what token has been matched if it absolutely must. It turns out that +scanner. +An interactive scanner is one that only looks ahead to decide +what token has been matched if it absolutely must. +It turns out that always looking one extra character ahead, even if the scanner has already seen enough text to disambiguate the current token, is a bit faster than -only looking ahead when necessary. But scanners that always look ahead +only looking ahead when necessary. +But scanners that always look ahead give dreadful interactive performance; for example, when a user types a newline, it is not recognized as a newline token until they enter .I another @@ -2295,12 +2408,14 @@ unless you use the .B \-Cf or .B \-CF -table-compression options (see below). That's because if you're looking +table-compression options (see below). +That's because if you're looking for high-performance you should be using one of these options, so if you didn't, .I flex assumes you'd rather trade off a bit of run-time performance for intuitive -interactive behavior. Note also that you +interactive behavior. +Note also that you .I cannot use .B \-I @@ -2322,7 +2437,8 @@ instructs .I flex not to generate .B #line -directives. Without this option, +directives. +Without this option, .I flex peppers the generated scanner with #line directives so error messages in the actions will be correctly @@ -2340,11 +2456,13 @@ makes .I flex run in .I trace -mode. It will generate a lot of messages to +mode. +It will generate a lot of messages to .I stderr concerning the form of the input and the resultant non-deterministic and deterministic -finite automata. This option is mostly for use in maintaining +finite automata. +This option is mostly for use in maintaining .I flex. .TP .B \-V @@ -2359,12 +2477,14 @@ is a synonym for instructs .I flex to generate a 7-bit scanner, i.e., one which can only recognized 7-bit -characters in its input. The advantage of using +characters in its input. +The advantage of using .B \-7 is that the scanner's tables can be up to half the size of those generated using the .B \-8 -option (see below). The disadvantage is that such scanners often hang +option (see below). +The disadvantage is that such scanners often hang or crash if their input contains an 8-bit character. .IP Note, however, that unless you generate your scanner using the @@ -2384,7 +2504,8 @@ in which case .I flex defaults to generating 7-bit scanners unless your site was always configured to generate 8-bit scanners (as will often be the case -with non-USA sites). You can tell whether flex generated a 7-bit +with non-USA sites). +You can tell whether flex generated a 7-bit or an 8-bit scanner by inspecting the flag summary in the .B \-v output as described above. @@ -2402,7 +2523,8 @@ are not much more expensive than 7-bit tables. instructs .I flex to generate an 8-bit scanner, i.e., one which can recognize 8-bit -characters. This flag is only needed for scanners generated using +characters. +This flag is only needed for scanners generated using .B \-Cf or .B \-CF, @@ -2415,7 +2537,8 @@ and 8-bit scanners. .TP .B \-+ specifies that you want flex to generate a C++ -scanner class. See the section on Generating C++ Scanners below for +scanner class. +See the section on Generating C++ Scanners below for details. .TP .B \-C[aefFmr] @@ -2425,9 +2548,11 @@ between small scanners and fast scanners. .B \-Ca ("align") instructs flex to trade off larger tables in the generated scanner for faster performance because the elements of -the tables are better aligned for memory access and computation. On some +the tables are better aligned for memory access and computation. +On some RISC architectures, fetching and manipulating longwords is more efficient -than with smaller-sized units such as shortwords. This option can +than with smaller-sized units such as shortwords. +This option can double the size of the tables used by your scanner. .IP .B \-Ce @@ -2441,7 +2566,8 @@ appearance of digits in the .I flex input is in the character class "[0-9]" then the digits '0', '1', ..., '9' will all be put -in the same equivalence class). Equivalence classes usually give +in the same equivalence class). +Equivalence classes usually give dramatic reductions in the final table/object file sizes (typically a factor of 2-5) and are pretty cheap performance-wise (one array look-up per character scanned). @@ -2460,7 +2586,8 @@ specifies that the alternative fast scanner representation (described above under the .B \-F flag) -should be used. This option cannot be used with +should be used. +This option cannot be used with .B \-+. .IP .B \-Cm @@ -2469,7 +2596,8 @@ directs to construct .I meta-equivalence classes, which are sets of equivalence classes (or characters, if equivalence -classes are not being used) that are commonly used together. Meta-equivalence +classes are not being used) that are commonly used together. +Meta-equivalence classes are often a big win when using compressed tables, but they have a moderate performance impact (one or two "if" tests and one array look-up per character scanned). @@ -2477,7 +2605,8 @@ array look-up per character scanned). .B \-Cr causes the generated scanner to .I bypass -use of the standard I/O library (stdio) for input. Instead of calling +use of the standard I/O library (stdio) for input. +Instead of calling .B fread() or .B getc(), @@ -2512,7 +2641,8 @@ or and .B \-Cm do not make sense together - there is no opportunity for meta-equivalence -classes if the table is not being compressed. Otherwise the options +classes if the table is not being compressed. +Otherwise the options may be freely mixed, and are cumulative. .IP The default setting is @@ -2520,8 +2650,9 @@ The default setting is which specifies that .I flex should generate equivalence classes -and meta-equivalence classes. This setting provides the highest -degree of table compression. You can trade off +and meta-equivalence classes. +This setting provides the highest degree of table compression. +You can trade off faster-executing scanners at the cost of larger tables with the following generally being true: .nf @@ -2612,8 +2743,8 @@ have the modified name. .IP This option lets you easily link together multiple .I flex -programs into the same executable. Note, though, that using this -option also renames +programs into the same executable. +Note, though, that using this option also renames .B yywrap(), so you now .I must @@ -2628,7 +2759,8 @@ no longer provides one for you by default. .B \-Sskeleton_file overrides the default skeleton file from which .I flex -constructs its scanners. You'll never need this option unless you are doing +constructs its scanners. +You'll never need this option unless you are doing .I flex maintenance or development. .PP @@ -2686,11 +2818,13 @@ provide features otherwise not available: .TP .B always-interactive instructs flex to generate a scanner which always considers its input -"interactive". Normally, on each new input file the scanner calls +"interactive". +Normally, on each new input file the scanner calls .B isatty() in an attempt to determine whether the scanner's input source is interactive and thus should be read a -character at a time. When this option is used, however, then no +character at a time. +When this option is used, however, then no such call is made. .TP .B main @@ -2760,7 +2894,8 @@ scans your rule actions to determine whether you use the .B REJECT or .B yymore() -features. The +features. +The .B reject and .B yymore @@ -2796,7 +2931,8 @@ Finally, .fi only applies when generating a C++ scanner ( .B \-+ -option). It informs +option). +It informs .I flex that you have derived .B foo @@ -2816,8 +2952,8 @@ if called. See Generating C++ Scanners, below, for additional information. .PP A number of options are available for lint purists who want to suppress -the appearance of unneeded routines in the generated scanner. Each of the -following, if unset +the appearance of unneeded routines in the generated scanner. +Each of the following, if unset (e.g., .B %option nounput ), results in the corresponding routine not appearing in @@ -2836,13 +2972,14 @@ and friends won't appear anyway unless you use .SH PERFORMANCE CONSIDERATIONS The main design goal of .I flex -is that it generate high-performance scanners. It has been optimized -for dealing well with large sets of rules. Aside from the effects on -scanner speed of the table compression +is that it generate high-performance scanners. +It has been optimized +for dealing well with large sets of rules. +Aside from the effects on scanner speed of the table compression .B \-C options outlined above, -there are a number of options/actions which degrade performance. These -are, from most expensive to least: +there are a number of options/actions which degrade performance. +These are, from most expensive to least: .nf REJECT @@ -2859,7 +2996,8 @@ are, from most expensive to least: .fi with the first three all being quite expensive and the last two -being quite cheap. Note also that +being quite cheap. +Note also that .B unput() is implemented as a routine call that potentially does quite a bit of work, while @@ -2873,12 +3011,13 @@ should be avoided at all costs when performance is important. It is a particularly expensive option. .PP Getting rid of backing up is messy and often may be an enormous -amount of work for a complicated scanner. In principal, one begins -by using the +amount of work for a complicated scanner. +In principal, one begins by using the .B \-b flag to generate a .I lex.backup -file. For example, on the input +file. +For example, on the input .nf %% @@ -2913,18 +3052,21 @@ the file looks like: The first few lines tell us that there's a scanner state in which it can make a transition on an 'o' but not on any other character, and that in that state the currently scanned text does not match -any rule. The state occurs when trying to match the rules found +any rule. +The state occurs when trying to match the rules found at lines 2 and 3 in the input file. If the scanner is in that state and then reads something other than an 'o', it will have to back up to find -a rule which is matched. With -a bit of headscratching one can see that this must be the -state it's in when it has seen "fo". When this has happened, +a rule which is matched. +With a bit of headscratching one can see that this must be the +state it's in when it has seen "fo". +When this has happened, if anything other than another 'o' is seen, the scanner will have to back up to simply match the 'f' (by the default rule). .PP The comment regarding State #8 indicates there's a problem -when "foob" has been scanned. Indeed, on any character other +when "foob" has been scanned. +Indeed, on any character other than an 'a', the scanner will have to back up to accept "foo". Similarly, the comment for State #9 concerns when "fooba" has been scanned and an 'r' does not follow. @@ -2968,23 +3110,27 @@ This is usually the best solution when appropriate. .PP Backing up messages tend to cascade. With a complicated set of rules it's not uncommon to get hundreds -of messages. If one can decipher them, though, it often +of messages. +If one can decipher them, though, it often only takes a dozen or so rules to eliminate the backing up (though it's easy to make a mistake and have an error rule accidentally match -a valid token. A possible future +a valid token. +A possible future .I flex feature will be to automatically add rules to eliminate backing up). .PP It's important to keep in mind that you gain the benefits of eliminating backing up only if you eliminate .I every -instance of backing up. Leaving just one means you gain nothing. +instance of backing up. +Leaving just one means you gain nothing. .PP .I Variable trailing context (where both the leading and trailing parts do not have a fixed length) entails almost the same performance loss as .B REJECT -(i.e., substantial). So when possible a rule like: +(i.e., substantial). +So when possible a rule like: .nf %% @@ -3020,7 +3166,8 @@ characters takes place in the (short) inner scanning loop, and does not often have to go through the additional work of setting up the scanning environment (e.g., .B yytext) -for the action. Recall the scanner for C comments: +for the action. +Recall the scanner for C comments: .nf %x comment @@ -3053,7 +3200,8 @@ This could be sped up by writing it as: .fi Now instead of each newline requiring the processing of another action, recognizing the newlines is "distributed" over the other rules -to keep the matched text as long as possible. Note that +to keep the matched text as long as possible. +Note that .I adding rules does .I not @@ -3065,7 +3213,8 @@ regard to operators such as '*' and '|'. A final example in speeding up a scanner: suppose you want to scan through a file containing identifiers and keywords, one per line and with no other extraneous characters, and recognize all the -keywords. A natural first approach is: +keywords. +A natural first approach is: .nf %% @@ -3113,16 +3262,19 @@ tokens: .fi One has to be careful here, as we have now reintroduced backing up -into the scanner. In particular, while +into the scanner. +In particular, while .I we know that there will never be any characters in the input stream other than letters or newlines, .I flex can't figure this out, and it will plan for possibly needing to back up when it has scanned a token like "auto" and then the next character -is something other than a newline or a letter. Previously it would +is something other than a newline or a letter. +Previously it would then just match the "auto" rule and be done, but now it has no "auto" -rule, only a "auto\\n" rule. To eliminate the possibility of backing up, +rule, only a "auto\\n" rule. +To eliminate the possibility of backing up, we could either duplicate all rules but without final newlines, or, since we never expect to encounter such an input and therefore don't how it's classified, we can introduce one more catch-all rule, this @@ -3160,20 +3312,22 @@ Another final note regarding performance: as mentioned above in the section How the Input is Matched, dynamically resizing .B yytext to accommodate huge tokens is a slow process because it presently requires that -the (huge) token be rescanned from the beginning. Thus if performance is +the (huge) token be rescanned from the beginning. +Thus if performance is vital, you should attempt to match "large" quantities of text but not "huge" quantities, where the cutoff between the two is at about 8K characters/token. .SH GENERATING C++ SCANNERS .I flex -provides two different ways to generate scanners for use with C++. The -first way is to simply compile a scanner generated by +provides two different ways to generate scanners for use with C++. +The first way is to simply compile a scanner generated by .I flex -using a C++ compiler instead of a C compiler. You should not encounter +using a C++ compiler instead of a C compiler. +You should not encounter any compilations errors (please report any you find to the email address -given in the Author section below). You can then use C++ code in your -rule actions instead of C code. Note that the default input source for -your scanner remains +given in the Author section below). +You can then use C++ code in your rule actions instead of C code. +Note that the default input source for your scanner remains .I yyin, and default echoing is still done to .I yyout. @@ -3202,7 +3356,8 @@ which defines the interface to two C++ classes. The first class, .B FlexLexer, provides an abstract base class defining the general scanner class -interface. It provides the following member functions: +interface. +It provides the following member functions: .TP .B const char* YYText() returns the text of the most recently matched token, the equivalent of @@ -3225,8 +3380,8 @@ was not used. .B void set_debug( int flag ) sets the debugging flag for the scanner, equivalent to assigning to .B yy_flex_debug -(see the Options section above). Note that you must build the scanner -using +(see the Options section above). +Note that you must build the scanner using .B %option debug to include debugging information in it. .TP @@ -3260,8 +3415,8 @@ It defines the following additional member functions: yyFlexLexer( istream* arg_yyin = 0, ostream* arg_yyout = 0 ) constructs a .B yyFlexLexer -object using the given streams for input and output. If not specified, -the streams default to +object using the given streams for input and output. +If not specified, the streams default to .B cin and .B cout, @@ -3271,7 +3426,8 @@ respectively. performs the same role is .B yylex() does for ordinary flex scanners: it scans the input stream, consuming -tokens, until a rule's action returns a value. If you derive a subclass +tokens, until a rule's action returns a value. +If you derive a subclass .B S from .B yyFlexLexer @@ -3331,8 +3487,9 @@ reads up to .B max_size characters into .B buf -and returns the number of characters read. To indicate end-of-input, -return 0 characters. Note that "interactive" scanners (see the +and returns the number of characters read. +To indicate end-of-input, return 0 characters. +Note that "interactive" scanners (see the .B \-B and .B \-I @@ -3356,8 +3513,8 @@ the scanner's rules can match text with NUL's in them. .TP .B virtual void LexerError( const char* msg ) -reports a fatal error message. The default version of this function -writes the message to the stream +reports a fatal error message. +The default version of this function writes the message to the stream .B cerr and exits. .PP @@ -3365,8 +3522,9 @@ Note that a .B yyFlexLexer object contains its .I entire -scanning state. Thus you can use such objects to create reentrant -scanners. You can instantiate multiple instances of the same +scanning state. +Thus you can use such objects to create reentrant scanners. +You can instantiate multiple instances of the same .B yyFlexLexer class, and you can also combine multiple C++ scanner classes together in the same program using the @@ -3479,7 +3637,8 @@ is a rewrite of the AT\*[Am]T Unix tool (the two implementations do not share any code, though), with some extensions and incompatibilities, both of which are of concern to those who wish to write scanners acceptable -to either implementation. Flex is fully compliant with the POSIX +to either implementation. +Flex is fully compliant with the POSIX .I lex specification, except that when using .B %pointer @@ -3497,7 +3656,8 @@ between flex, AT\*[Am]T lex, and the POSIX specification. option turns on maximum compatibility with the original AT\*[Am]T .I lex implementation, at the cost of a major loss in the generated scanner's -performance. We note below which incompatibilities can be overcome +performance. +We note below which incompatibilities can be overcome using the .B \-l option. @@ -3527,11 +3687,13 @@ is not part of the POSIX specification. The .B input() routine is not redefinable, though it may be called to read characters -following whatever has been matched by a rule. If +following whatever has been matched by a rule. +If .B input() encounters an end-of-file the normal .B yywrap() -processing is done. A ``real'' end-of-file is returned by +processing is done. +A ``real'' end-of-file is returned by .B input() as .I EOF. @@ -3551,12 +3713,14 @@ scanner's input other than by making an initial assignment to .IP - The .B unput() -routine is not redefinable. This restriction is in accordance with POSIX. +routine is not redefinable. +This restriction is in accordance with POSIX. .IP - .I flex scanners are not as reentrant as .I lex -scanners. In particular, if you have an interactive scanner and +scanners. +In particular, if you have an interactive scanner and an interrupt handler which long-jumps out of the scanner, and the scanner is subsequently called again, you may get the following message: @@ -3577,7 +3741,8 @@ isn't a problem with an interactive scanner. Also note that flex C++ scanner classes .I are reentrant, so if using C++ is an option for you, you should use -them instead. See "Generating C++ Scanners" above for details. +them instead. +See "Generating C++ Scanners" above for details. .IP - .B output() is not supported. @@ -3610,7 +3775,8 @@ With lex, the following: will not match the string "foo" because when the macro is expanded the rule is equivalent to "foo[A-Z][A-Z0-9]*?" and the precedence is such that the '?' is associated with -"[A-Z0-9]*". With +"[A-Z0-9]*". +With .I flex, the rule will be expanded to "foo([A-Z][A-Z0-9]*)?" and so the string "foo" will match. @@ -3622,7 +3788,8 @@ or ends with then it is .I not expanded with parentheses, to allow these operators to appear in -definitions without losing their special meanings. But the +definitions without losing their special meanings. +But the .B \*[Lt]s\*[Gt], /, and .B \*[Lt]\*[Lt]EOF\*[Gt]\*[Gt] @@ -3655,7 +3822,8 @@ does not support this feature. The .I lex .B %r -(generate a Ratfor scanner) option is not supported. It is not part +(generate a Ratfor scanner) option is not supported. +It is not part of the POSIX specification. .IP - After a call to @@ -3666,7 +3834,8 @@ was built using .B %array. This is not the case with .I lex -or the POSIX specification. The +or the POSIX specification. +The .B \-l option does away with this incompatibility. .IP - @@ -3678,8 +3847,8 @@ interprets "abc{1,3}" as "match one, two, or three occurrences of 'abc'", whereas .I flex interprets it as "match 'ab' -followed by one, two, or three occurrences of 'c'". The latter is -in agreement with the POSIX specification. +followed by one, two, or three occurrences of 'c'". +The latter is in agreement with the POSIX specification. .IP - The precedence of the .B ^ @@ -3689,7 +3858,8 @@ interprets "^foo|bar" as "match either 'foo' at the beginning of a line, or 'bar' anywhere", whereas .I flex interprets it as "match either 'foo' or 'bar' if they come at the beginning -of a line". The latter is in agreement with the POSIX specification. +of a line". +The latter is in agreement with the POSIX specification. .IP - The special table-size declarations such as .B %a @@ -3765,14 +3935,16 @@ is (rather surprisingly) truncated to .fi .I flex -does not truncate the action. Actions that are not enclosed in +does not truncate the action. +Actions that are not enclosed in braces are simply terminated at the end of the line. .SH DIAGNOSTICS .PP .I warning, rule cannot be matched indicates that the given rule cannot be matched because it follows other rules that will -always match the same text as it. For +always match the same text as it. +For example, in the following "foo" cannot be matched because it comes after an identifier "catch-all" rule: .nf @@ -3791,15 +3963,16 @@ in a scanner suppresses this warning. option given but default rule can be matched means that it is possible (perhaps only in a particular start condition) that the default rule (match any single character) is the only one -that will match a particular input. Since +that will match a particular input. +Since .B \-s was given, presumably this is not intended. .PP .I reject_used_but_not_detected undefined or .I yymore_used_but_not_detected undefined - -These errors can occur at compile time. They indicate that the -scanner uses +These errors can occur at compile time. +They indicate that the scanner uses .B REJECT or .B yymore() @@ -3809,7 +3982,8 @@ failed to notice the fact, meaning that .I flex scanned the first two sections looking for occurrences of these actions and failed to find any, but somehow you snuck some in (via a #include -file, for example). Use +file, for example). +Use .B %option reject or .B %option yymore @@ -3819,14 +3993,16 @@ to indicate to flex that you really do use these features. a scanner compiled with .B \-s has encountered an input string which wasn't matched by -any of its rules. This error can also occur due to internal problems. +any of its rules. +This error can also occur due to internal problems. .PP .I token too large, exceeds YYLMAX - your scanner uses .B %array and one of its rules matched a string longer than the .B YYLMAX -constant (8K bytes by default). You can increase the value by +constant (8K bytes by default). +You can increase the value by #define'ing .B YYLMAX in the definitions section of your @@ -3842,7 +4018,8 @@ because you used the .B \-Cf or .B \-CF -table compression options. See the discussion of the +table compression options. +See the discussion of the .B \-7 flag for details. .PP @@ -3858,15 +4035,16 @@ present it does not. .I input buffer overflow, can't enlarge buffer because scanner uses REJECT - the scanner was working on matching an extremely large token and needed -to expand the input buffer. This doesn't work with scanners that use +to expand the input buffer. +This doesn't work with scanners that use .B REJECT. .PP .I fatal flex scanner internal error--end of buffer missed - This can occur in an scanner which is reentered after a long-jump -has jumped out (or over) the scanner's activation frame. Before -reentering the scanner, use: +has jumped out (or over) the scanner's activation frame. +Before reentering the scanner, use: .nf yyrestart( yyin ); @@ -3898,8 +4076,8 @@ and its derived class, .B yyFlexLexer. .TP .I flex.skl -skeleton scanner. This file is only used when building flex, not when -flex executes. +skeleton scanner. +This file is only used when building flex, not when flex executes. .TP .I lex.backup backing-up information for @@ -3911,11 +4089,12 @@ on some systems). .PP Some trailing context patterns cannot be properly matched and generate -warning messages ("dangerous trailing context"). These are -patterns where the ending of the +warning messages ("dangerous trailing context"). +These are patterns where the ending of the first part of the rule matches the beginning of the second part, such as "zx*/xy*", where the 'x*' matches the 'x' at -the beginning of the trailing context. (Note that the POSIX draft +the beginning of the trailing context. +(Note that the POSIX draft states that the text matched by such patterns is undefined.) .PP For some trailing context rules, parts which are actually fixed-length are @@ -3927,7 +4106,8 @@ Combining trailing context with the special '|' action can result in .I fixed trailing context being turned into the more expensive .I variable -trailing context. For example, in the following: +trailing context. +For example, in the following: .nf %% @@ -3956,14 +4136,16 @@ calls to \*[Lt]stdio.h\*[Gt] routines, such as, for example, .B getchar(), with .I flex -rules and expect it to work. Call +rules and expect it to work. +Call .B input() instead. .PP The total table entries listed by the .B \-v flag excludes the number of table entries needed to determine -what rule has been matched. The number of entries is equal +what rule has been matched. +The number of entries is equal to the number of DFA states if the scanner does not use .B REJECT, and somewhat greater than the number of states if it does. @@ -3984,21 +4166,26 @@ lex(1), yacc(1), sed(1), awk(1). .PP John Levine, Tony Mason, and Doug Brown, .I Lex \*[Am] Yacc, -O'Reilly and Associates. Be sure to get the 2nd edition. +O'Reilly and Associates. +Be sure to get the 2nd edition. .PP M. E. Lesk and E. Schmidt, .I LEX \- Lexical Analyzer Generator .PP Alfred Aho, Ravi Sethi and Jeffrey Ullman, .I Compilers: Principles, Techniques and Tools, -Addison-Wesley (1986). Describes the pattern-matching techniques used by +Addison-Wesley (1986). +Describes the pattern-matching techniques used by .I flex (deterministic finite automata). .SH AUTHOR Vern Paxson, with the help of many ideas and much inspiration from -Van Jacobson. Original version by Jef Poskanzer. The fast table +Van Jacobson. +Original version by Jef Poskanzer. +The fast table representation is a partial implementation of a design done by Van -Jacobson. The implementation was done by Kevin Gong and Vern Paxson. +Jacobson. +The implementation was done by Kevin Gong and Vern Paxson. .PP Thanks to the many .I flex @@ -4056,7 +4243,7 @@ Epperly for C++ class support; to Ove Ewerlid for support of NUL's; and to Eric Hughes for support of multiple buffers. .PP This work was primarily done when I was with the Real Time Systems Group -at the Lawrence Berkeley Laboratory in Berkeley, CA. Many thanks to all there -for the support I received. +at the Lawrence Berkeley Laboratory in Berkeley, CA. +Many thanks to all there for the support I received. .PP Send comments to vern@ee.lbl.gov. diff --git a/usr.bin/make/make.1 b/usr.bin/make/make.1 index e94397654af..5fe0261be0c 100644 --- a/usr.bin/make/make.1 +++ b/usr.bin/make/make.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: make.1,v 1.66 2002/09/24 15:31:30 wiz Exp $ +.\" $NetBSD: make.1,v 1.67 2002/09/30 11:09:05 grant Exp $ .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -177,7 +177,8 @@ cooperate to avoid overloading the system. .It Fl j Ar max_jobs Specify the maximum number of jobs that .Nm -may have running at any one time. Turns compatibility mode off, unless the +may have running at any one time. +Turns compatibility mode off, unless the .Ar B flag is also specified. .It Fl k @@ -185,7 +186,8 @@ Continue processing after errors are encountered, but only on those targets that do not depend on the target whose creation caused the error. .It Fl m Ar directory Specify a directory in which to search for sys.mk and makefiles included -via the \*[Lt]...\*[Gt] style. Multiple directories can be added to form a search path. +via the \*[Lt]...\*[Gt] style. +Multiple directories can be added to form a search path. This path will override the default system include path: /usr/share/mk. Furthermore the system include path will be appended to the search path used for "..."-style inclusions (see the @@ -452,7 +454,8 @@ expands to a single dollar sign. .Pq Va argv[0] .It Va .ALLTARGETS -The list of all targets encountered in the Makefile. If evaluated during +The list of all targets encountered in the Makefile. +If evaluated during Makefile parsing, lists only those targets encountered thus far. .It Va .CURDIR A path to the directory where @@ -483,7 +486,8 @@ on the command line, so that they may be exported as part of .Ql Ev MAKEFLAGS . This behaviour can be disabled by assigning an empty value to .Ql Va .MAKEOVERRIDES -within a makefile. Extra variables can be exported from a makefile +within a makefile. +Extra variables can be exported from a makefile by appending their names to .Ql Va .MAKEOVERRIDES . .Ql Ev MAKEFLAGS @@ -500,7 +504,8 @@ as well as the value of any variables named in .It Va .newline This variable is simply assigned a newline character as its value. This allows expansions using the :@ modifier to put a newline between -iterations of the loop rather than a space. For example, the printing of +iterations of the loop rather than a space. +For example, the printing of .Ql Va MAKE_PRINT_VAR_ON_ERROR could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. .It Va .OBJDIR @@ -533,7 +538,8 @@ sets .Ql Va .CURDIR to the value of .Ql Ev PWD -instead. This behaviour is disabled if +instead. +This behaviour is disabled if .Ql Ev MAKEOBJDIRPREFIX is set. .Ql Ev PWD @@ -655,13 +661,16 @@ simple strings, are a regular expression (see .Xr regex 3 ) and an .Xr ed 1 Ns \-style -replacement string. Normally, the first occurrence of the pattern in -each word of the value is changed. The +replacement string. +Normally, the first occurrence of the pattern in +each word of the value is changed. +The .Ql 1 modifier causes the substitution to apply to at most one word; the .Ql g modifier causes the substitution to apply to as many instances of the -search pattern as occur in the word or words it is found in. Note that +search pattern as occur in the word or words it is found in. +Note that .Ql 1 and .Ql g @@ -691,7 +700,8 @@ do not contain the pattern matching character .Ar % then it is assumed that they are anchored at the end of each word, so only suffixes or entire -words may be replaced. Otherwise +words may be replaced. +Otherwise .Ar % is the substring of .Ar old_string @@ -701,24 +711,27 @@ to be replaced in .No Ar string Cm @ .Xc This is the loop expansion mechanism from the OSF Development -Environment (ODE) make. Unlike +Environment (ODE) make. +Unlike .Cm \&.for loops expansion occurs at the time of -reference. Assign +reference. +Assign .Ar temp to each word in the variable and evaluate .Ar string . The ODE convention is that .Ar temp -should start and end with a period. For example. +should start and end with a period. +For example. .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} .It Cm U Ar newval If the variable is undefined .Ar newval is the value. If the variable is defined, the existing value is returned. -This is another ODE make feature. It is handy for -setting per-target CFLAGS for instance: +This is another ODE make feature. +It is handy for setting per-target CFLAGS for instance: .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}} If a value is only required if the variable is undefined, use: .Dl ${VAR:D:Unewval} @@ -730,7 +743,8 @@ is the value. The name of the variable is the value. .It Cm P The path of the node which has the same name as the variable -is the value. If no such node exists or its path is null, then the +is the value. +If no such node exists or its path is null, then the name of the variable is used. .It Cm ! Ar cmd Cm ! The output of running @@ -742,16 +756,19 @@ becomes the new value. .It Cm \&:= Ar str The variable is assigned the value .Ar str -after substitution. This modifier and its variations are useful in +after substitution. +This modifier and its variations are useful in obscure situations such as wanting to apply modifiers to .Cm \&.for loop iteration variables which won't work due to the way .Cm \&.for -loops are implemented. These assignment modifiers always expand to +loops are implemented. +These assignment modifiers always expand to nothing, so if appearing in a rule line by themselves should be preceded with something to keep .Nm -happy. As in: +happy. +As in: .Bd -literal use_foo: \&.USE \&.for i in ${\&.TARGET} ${\&.TARGET:R}\&.gz @@ -806,7 +823,8 @@ makefile directory. For compatibility with other versions of .Nm .Ql include file ... -is also accepted. If the include statement is written as +is also accepted. +If the include statement is written as .Cm .-include or as .Cm .sinclude @@ -956,11 +974,14 @@ has been defined and has commands associated with it. .El .Pp .Ar Expression -may also be an arithmetic or string comparison. Variable expansion is +may also be an arithmetic or string comparison. +Variable expansion is performed on both sides of the comparison, after which the integral -values are compared. A value is interpreted as hexadecimal if it is +values are compared. +A value is interpreted as hexadecimal if it is preceded by 0x, otherwise it is decimal; octal numbers are not supported. -The standard C relational operators are all supported. If after +The standard C relational operators are all supported. +If after variable expansion, either the left or right hand side of a .Ql Ic == or @@ -1016,8 +1037,8 @@ The syntax of a for loop is: .Pp After the for .Ic expression -is evaluated, it is split into words. On each iteration of the loop, -one word is taken and assigned to each +is evaluated, it is split into words. +On each iteration of the loop, one word is taken and assigned to each .Ic variable , in order, and these .Ic variables @@ -1091,7 +1112,8 @@ target commands to the target. If special .Ic .WAIT source is appears in a dependency line, the sources that precede it are -made before the sources that succeed it in the line. Loops are not being +made before the sources that succeed it in the line. +Loops are not being detected and targets that form loops will be silently ignored. .El .Sh SPECIAL TARGETS @@ -1148,7 +1170,8 @@ no effect. .It Ic .NOPATH Apply the .Ic .NOPATH -attribute to any specified sources. Targets with this attribute are not +attribute to any specified sources. +Targets with this attribute are not searched for in the directories specified by .Ic .PATH . .It Ic .NOTPARALLEL @@ -1173,7 +1196,8 @@ directory is searched last. .It Ic .PHONY Apply the .Ic .PHONY -attribute to any specified sources. Targets with this attribute do not +attribute to any specified sources. +Targets with this attribute do not correspond to actual files; they are always considered to be out of date, and will not be created with the .Fl t diff --git a/usr.bin/midiplay/midiplay.1 b/usr.bin/midiplay/midiplay.1 index b8ab4ad74a5..eb48a1a6758 100644 --- a/usr.bin/midiplay/midiplay.1 +++ b/usr.bin/midiplay/midiplay.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: midiplay.1,v 1.11 2002/01/05 20:55:16 wiz Exp $ +.\" $NetBSD: midiplay.1,v 1.12 2002/09/30 11:09:05 grant Exp $ .\" Copyright (c) 1998 The NetBSD Foundation, Inc. .\" All rights reserved. .\" @@ -63,7 +63,8 @@ The program accepts the following options: specifies the number of the MIDI device used for output (as listed by the .Fl l -flag). The default is device is given by environment variable +flag). +The default is device is given by environment variable .Ev MIDIUNIT . .It Fl f Ar file specifies the name of the sequencer device. @@ -76,16 +77,19 @@ use only this program (range 1-128) for all channels. .It Fl q specifies that the MIDI file should not be played, just parsed. .It Fl t Ar tempo -specifies the tempo. The default tempo is 100. +specifies the tempo. +The default tempo is 100. .It Fl v -be verbose. If the flag is repeated the verbosity increases. +be verbose. +If the flag is repeated the verbosity increases. .It Fl x play a small sample sound instead of the a file. .El .Sh ENVIRONMENT .Bl -tag -width MIDIUNIT .It Ev MIDIUNIT -the default number of the MIDI device used for output. The default is 0. +the default number of the MIDI device used for output. +The default is 0. .El .Sh FILES .Bl -tag -width /dev/music diff --git a/usr.bin/mklocale/mklocale.1 b/usr.bin/mklocale/mklocale.1 index 8071389fd3b..32a3c1883dc 100644 --- a/usr.bin/mklocale/mklocale.1 +++ b/usr.bin/mklocale/mklocale.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: mklocale.1,v 1.7 2002/02/08 01:36:29 ross Exp $ +.\" $NetBSD: mklocale.1,v 1.8 2002/09/30 11:09:05 grant Exp $ .\" FreeBSD: src/usr.bin/mklocale/mklocale.1,v 1.6 1999/09/20 09:15:21 phantom Exp .\" .\" Copyright (c) 1993, 1994 @@ -67,7 +67,8 @@ The format of .Ar src-file is quite simple. It consists of a series of lines which start with a keyword and have -associated data following. C style comments are used +associated data following. +C style comments are used to place comments in the file. .Pp Following options are available: @@ -123,9 +124,11 @@ Used to indicate ranges. The follow characters are taken literally: .Bl -tag -width "\*[Lt]\|\|(\|\|[" .It Dv "\*[Lt]\|(\|[" -Used to start a mapping. All are equivalent. +Used to start a mapping. +All are equivalent. .It Dv "\*[Gt]\|\^)\|]" -Used to end a mapping. All are equivalent. +Used to end a mapping. +All are equivalent. .It Dv : Used as a delimiter in mappings. .El diff --git a/usr.bin/mktemp/mktemp.1 b/usr.bin/mktemp/mktemp.1 index f2ec466c000..11bc9245201 100644 --- a/usr.bin/mktemp/mktemp.1 +++ b/usr.bin/mktemp/mktemp.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: mktemp.1,v 1.7 2002/02/08 01:36:29 ross Exp $ +.\" $NetBSD: mktemp.1,v 1.8 2002/09/30 11:09:06 grant Exp $ .\" From: $FreeBSD: src/usr.bin/mktemp/mktemp.1,v 1.5 1999/08/28 01:04:13 peter Exp $ .\" From: $OpenBSD: mktemp.1,v 1.8 1998/03/19 06:13:37 millert Exp $ .\" @@ -52,8 +52,10 @@ The .Nm utility takes each of the given file name templates and overwrites a -portion of it to create a file name. This file name is unique -and suitable for use by the application. The template may be +portion of it to create a file name. +This file name is unique +and suitable for use by the application. +The template may be any file name with some number of .Ql X Ns s appended @@ -90,7 +92,8 @@ will generate an template string based on the .Ar prefix and the .Ev TMPDIR -environment variable if set. The default location if +environment variable if set. +The default location if .Ev TMPDIR is not set is .Pa /tmp . @@ -106,12 +109,16 @@ flag. .Nm is provided to allow shell scripts to safely use temporary files. Traditionally, many shell scripts take the name of the program with -the pid as a suffix and use that as a temporary file name. This +the pid as a suffix and use that as a temporary file name. +This kind of naming scheme is predictable and the race condition it creates -is easy for an attacker to win. A safer, though still inferior, approach -is to make a temporary directory using the same naming scheme. While +is easy for an attacker to win. +A safer, though still inferior, approach +is to make a temporary directory using the same naming scheme. +While this does allow one to guarantee that a temporary file will not be -subverted, it still allows a simple denial of service attack. For these +subverted, it still allows a simple denial of service attack. +For these reasons it is suggested that .Nm be used instead. @@ -121,7 +128,8 @@ The available options are as follows: .It Fl d Make a directory instead of a file. .It Fl q -Fail silently if an error occurs. This is useful if +Fail silently if an error occurs. +This is useful if a script does not want error output to go to standard error. .It Fl t Ar prefix Generate a template (using the supplied @@ -132,11 +140,14 @@ if set) to create a filename template. .It Fl u Operate in .Dq unsafe -mode. The temp file will be unlinked before +mode. +The temp file will be unlinked before .Nm -exits. This is slightly better than +exits. +This is slightly better than .Xr mktemp 3 -but still introduces a race condition. Use of this +but still introduces a race condition. +Use of this option is not encouraged. .El .Sh EXIT STATUS diff --git a/usr.bin/msgs/msgs.1 b/usr.bin/msgs/msgs.1 index 45917f0d274..99b4dc6a5c7 100644 --- a/usr.bin/msgs/msgs.1 +++ b/usr.bin/msgs/msgs.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: msgs.1,v 1.12 2001/12/01 20:44:29 wiz Exp $ +.\" $NetBSD: msgs.1,v 1.13 2002/09/30 11:09:06 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -88,7 +88,8 @@ the next time will pick up where it last left off. .It Ic s Append the current message to the file ``Messages'' in the current directory; -`s\-' will save the previously displayed message. A `s' or `s\-' may +`s\-' will save the previously displayed message. +A `s' or `s\-' may be followed by a space and a file name to receive the message replacing the default ``Messages''. .It Ic m @@ -130,7 +131,8 @@ file the next time it is run. .Pp The .Fl s -option is used for setting up the posting of messages. The line +option is used for setting up the posting of messages. +The line .Pp .Dl msgs: \&"\&| /usr/bin/msgs \-s\&" .Pp @@ -148,7 +150,8 @@ An entry with the .Fl c option should be placed in .Pa /etc/crontab -to run every night. This will remove all messages over 21 days old. +to run every night. +This will remove all messages over 21 days old. A different expiration may be specified on the command line to override the default. .Pp @@ -166,7 +169,8 @@ The command ``msgs \-q'' is often used in login scripts. .It Fl h Print the first part of messages only. .It Fl r -Disables the ability to save messages or enter the mailer. It is +Disables the ability to save messages or enter the mailer. +It is assumed that .Ev PAGER is set to something secure. diff --git a/usr.bin/netgroup/netgroup.1 b/usr.bin/netgroup/netgroup.1 index 6fad5fe4f27..76147f12244 100644 --- a/usr.bin/netgroup/netgroup.1 +++ b/usr.bin/netgroup/netgroup.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: netgroup.1,v 1.4 2001/12/01 16:43:21 wiz Exp $ +.\" $NetBSD: netgroup.1,v 1.5 2002/09/30 11:09:07 grant Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -46,8 +46,8 @@ .Ar netgroup .Sh DESCRIPTION .Nm -lists the members of specified netgroups. The type of members -is selected using the following options: +lists the members of specified netgroups. +The type of members is selected using the following options: .Bl -tag -width Ds .It Fl d list domains diff --git a/usr.bin/netstat/netstat.1 b/usr.bin/netstat/netstat.1 index 80e29f3ef11..b6b7bd342cb 100644 --- a/usr.bin/netstat/netstat.1 +++ b/usr.bin/netstat/netstat.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: netstat.1,v 1.35 2002/07/03 01:42:59 enami Exp $ +.\" $NetBSD: netstat.1,v 1.36 2002/09/30 11:09:07 grant Exp $ .\" .\" Copyright (c) 1983, 1990, 1992, 1993 .\" The Regents of the University of California. All rights reserved. @@ -218,14 +218,15 @@ virtual address .Ar pcbaddr . This address may be obtained using the .Fl A -flag. The default protocol is TCP, but may be overridden using the +flag. +The default protocol is TCP, but may be overridden using the .Fl p flag. .It Fl p Ar protocol Show statistics about .Ar protocol , -which is either a well-known name for a protocol or an alias for it. Some -protocol names and aliases are listed in the file +which is either a well-known name for a protocol or an alias for it. +Some protocol names and aliases are listed in the file .Pa /etc/protocols . A null response typically means that there are no interesting numbers to report. @@ -262,7 +263,8 @@ according to the data bases .Pa /etc/hosts and .Pa /etc/networks , -respectively. If a symbolic name for an address is unknown, or if +respectively. +If a symbolic name for an address is unknown, or if the .Fl n option is specified, the address is printed numerically, according @@ -283,10 +285,13 @@ The network addresses of the interface and the maximum transmission unit (``mtu'') are also displayed. .Pp The routing table display indicates the available routes and -their status. Each route consists of a destination host or network -and a gateway to use in forwarding packets. The flags field shows +their status. +Each route consists of a destination host or network +and a gateway to use in forwarding packets. +The flags field shows a collection of information about the route stored as -binary choices. The individual flags are discussed in more +binary choices. +The individual flags are discussed in more detail in the .Xr route 8 and @@ -314,20 +319,25 @@ Direct routes are created for each interface attached to the local host; the gateway field for such entries shows the address of the outgoing interface. The refcnt field gives the -current number of active uses of the route. Connection oriented +current number of active uses of the route. +Connection oriented protocols normally hold on to a single route for the duration of a connection while connectionless protocols obtain a route while sending to the same destination. The use field provides a count of the number of packets -sent using that route. The mtu entry shows the mtu associated with -that route. This mtu value is used as the basis for the TCP maximum -segment size. The 'L' flag appended to the mtu value indicates that +sent using that route. +The mtu entry shows the mtu associated with +that route. +This mtu value is used as the basis for the TCP maximum +segment size. +The 'L' flag appended to the mtu value indicates that the value is locked, and that path mtu discovery is turned off for that route. A .Sq - indicates that the mtu for this route has not been set, and a default -TCP maximum segment size will be used. The interface entry indicates +TCP maximum segment size will be used. +The interface entry indicates the network interface utilized for the route. .Pp When @@ -347,7 +357,8 @@ The primary interface may be replaced with another interface with the .Fl I option. The first line of each screen of information contains a summary since the -system was last rebooted. Subsequent lines of output show values +system was last rebooted. +Subsequent lines of output show values accumulated over the preceding interval. .Sh SEE ALSO .Xr fstat 1 , diff --git a/usr.bin/nice/nice.1 b/usr.bin/nice/nice.1 index d3ace5e2eda..1b5f6600154 100644 --- a/usr.bin/nice/nice.1 +++ b/usr.bin/nice/nice.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: nice.1,v 1.12 2001/12/08 19:09:35 wiz Exp $ +.\" $NetBSD: nice.1,v 1.13 2002/09/30 11:09:07 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -57,7 +57,8 @@ The super-user can run utilities with priorities higher than normal by using a negative .Ar increment . The priority can be adjusted over a -range of -20 (the highest) to 20 (the lowest). A priority of 19 or 20 +range of -20 (the highest) to 20 (the lowest). +A priority of 19 or 20 will prevent a process from taking any cycles from others at nice 0 or better. .Pp @@ -114,7 +115,8 @@ utility appeared in .Nm is built into .Xr csh 1 -with a slightly different syntax than described here. The form +with a slightly different syntax than described here. +The form .Ql nice +10 nices to positive nice, and .Ql nice \-10 diff --git a/usr.bin/passwd/passwd.1 b/usr.bin/passwd/passwd.1 index 8a666bcb1a0..46a9738c6fa 100644 --- a/usr.bin/passwd/passwd.1 +++ b/usr.bin/passwd/passwd.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: passwd.1,v 1.18 2001/12/01 16:43:22 wiz Exp $ +.\" $NetBSD: passwd.1,v 1.19 2002/09/30 11:09:08 grant Exp $ .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -76,7 +76,8 @@ .Op Ar user .Sh DESCRIPTION .Nm -changes the user's local, YP, or kerberos password. First, the user is +changes the user's local, YP, or kerberos password. +First, the user is prompted for their current password. If the current password is correctly typed, a new password is requested. @@ -94,12 +95,14 @@ All options may not be available on all systems. .Bl -tag -width flag .It Fl l This option causes the password to be updated only in the local -password file. When changing only the local password, +password file. +When changing only the local password, .Xr pwd_mkdb 8 is used to update the password databases. .It Fl y This forces the YP password database entry to be changed, even if -the user has an entry in the local database. The +the user has an entry in the local database. +The .Xr rpc.yppasswdd 8 daemon should be running on the YP master server. .Nm yppasswd diff --git a/usr.bin/patch/patch.1 b/usr.bin/patch/patch.1 index 46d5c6c072e..9f8c438ffc6 100644 --- a/usr.bin/patch/patch.1 +++ b/usr.bin/patch/patch.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: patch.1,v 1.7 2002/02/08 01:36:30 ross Exp $ -*- nroff -*- +.\" $NetBSD: patch.1,v 1.8 2002/09/30 11:09:08 grant Exp $ -*- nroff -*- .rn '' }` .de Sh .br @@ -70,9 +70,11 @@ environment variable, which is overridden by above switches. If the backup file already exists, .B patch creates a new backup file name by changing the first lowercase letter -in the last component of the file's name into uppercase. If there are +in the last component of the file's name into uppercase. +If there are no more lowercase letters in the name, it removes the first character -from the name. It repeats this process until it comes up with a +from the name. +It repeats this process until it comes up with a backup file that does not already exist. .PP You may also specify where you want the output to go with a @@ -216,7 +218,8 @@ used in place of \*(L".orig\*(R" or \*(L"~\*(R". .TP 5 .B \-B or \-\-prefix causes the next argument to be interpreted as a prefix to the backup file -name. If this argument is specified any argument from -b will be ignored. +name. +If this argument is specified any argument from -b will be ignored. .TP 5 .B \-c or \-\-context forces @@ -252,7 +255,8 @@ to remove output files that are empty after the patches have been applied. forces .I patch to assume that the user knows exactly what he or she is doing, and to not -ask any questions. It assumes the following: skip patches for which a +ask any questions. +It assumes the following: skip patches for which a file to patch can't be found; patch files even though they have the wrong version for the ``Prereq:'' line in the patch; and assume that patches are not reversed even if they look like they are. @@ -402,7 +406,8 @@ to print out its revision header and patch level. .TP 5 .B \-V or \-\-version-control causes the next argument to be interpreted as a method for creating -backup file names. The type of backups made can also be given in the +backup file names. +The type of backups made can also be given in the .B VERSION_CONTROL environment variable, which is overridden by this option. The @@ -415,7 +420,8 @@ environment variable and the argument to the .B -V option are like the GNU Emacs `version-control' variable; they also recognize synonyms that -are more descriptive. The valid values are (unique abbreviations are +are more descriptive. +The valid values are (unique abbreviations are accepted): .RS .TP diff --git a/usr.bin/pmap/pmap.1 b/usr.bin/pmap/pmap.1 index f740825f472..09b168e33fe 100644 --- a/usr.bin/pmap/pmap.1 +++ b/usr.bin/pmap/pmap.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: pmap.1,v 1.3 2002/09/17 19:54:28 atatat Exp $ +.\" $NetBSD: pmap.1,v 1.4 2002/09/30 11:09:08 grant Exp $ .\" .\" Copyright (c) 2002 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -52,7 +52,8 @@ The .Nm utility lists the virtual memory mappings underlying the given -process. The start address of each entry is always given, and, +process. +The start address of each entry is always given, and, depending on the options given, other information such as the end address, the underlying file's device and inode numbers, and various protection information will be displayed, along with the path to the @@ -61,15 +62,18 @@ file, if such data is available. By default, .Nm displays information for its parent process, so that when run from a -shell prompt, the shell's memory information is displayed. If other +shell prompt, the shell's memory information is displayed. +If other pids are given as arguments on the command line, information for those -processes will be printed also. If the special pid of 0 is given, +processes will be printed also. +If the special pid of 0 is given, then information for the kernel's memory map is printed. .Pp The options are as follows: .Bl -tag -width XXXnumberXX .It Fl D Ar number -Enable various debug facilities. The +Enable various debug facilities. +The .Ar number is a bit mask of the values: .Pp @@ -99,7 +103,8 @@ to print information about itself. .It Fl a Display .Dq all -information from the process's memory map. This output +information from the process's memory map. +This output mode is an amalgam of the contents of the Solaris, Linux, and .Nx style output modes. @@ -118,36 +123,44 @@ pseudo-file under the file system which was, in turn, modeled after the similarly named entry in the Linux .Pa /proc -file system. When combined with the +file system. +When combined with the .Fl v option, identifiers for all entries are printed. .It Fl m Dumps information in the same format as the map pseudo-file of the .Pa /proc -file system. When the +file system. +When the .Fl v option is also given, device number, inode number, and filename or other identifying information is printed. .It Fl p Ar pid Tells .Nm -to print information about the given process. If +to print information about the given process. +If .Fl p Ar pid occurs last on the command line, the .Fl p is optional. .It Fl R -Recurse into submaps. In some cases, a vm_map_entry in the kernel -will point to a submap. Using this flag tells +Recurse into submaps. +In some cases, a vm_map_entry in the kernel +will point to a submap. +Using this flag tells .Nm -to print the entries of the submap as well. The submap output is +to print the entries of the submap as well. +The submap output is indented, and does not affect any total printed at the bottom of the output. .It Fl s The Solaris style output format, modeled after the Solaris command of -the same name. This is the default output style. +the same name. +This is the default output style. .It Fl v -Verbose output. When used with +Verbose output. +When used with .Fl d , .Fl l , or @@ -161,7 +174,8 @@ The and .Fl p options override each other, so the last one to appear on the command -line takes effect. If you do wish to see information about +line takes effect. +If you do wish to see information about .Nm and another process as the same time, simply omit the .Fl p @@ -238,7 +252,8 @@ The and .Dq Tn amap fields are pointers to, and offsets into, the underlying uvm_object or -amap. The value for resident is always unknown because digging such +amap. +The value for resident is always unknown because digging such information out of the kernel is beyond the scope of this application. .Pp The two output styles that mirror the contents of the @@ -267,16 +282,19 @@ Here the protection and maximum protection values are indicated with and .Dq Tn x characters, indicating read permission, write permission, and execute -permission, respectively. The +permission, respectively. +The .Dq Tn COW , .Dq Tn NC , and .Dq Tn NNC values that follow indicate, again, that the map is marked for copy on -write and either needs or does not need a copy. It is also possible +write and either needs or does not need a copy. +It is also possible to see the value .Dq Tn NCOW -here, which indicates that an entry will not be copied. The three +here, which indicates that an entry will not be copied. +The three following numbers indicate the inheritance type of the map, the wired count of the map, and any advice value assigned via .Xr madvise 2 . @@ -311,7 +329,8 @@ copied on write or has already been copied .Pq Dq \&- and is followed by a column that indicates the maximum permissions for -the map entry. The column labeled +the map entry. +The column labeled .Dq Tn I/W/A indicates the inheritance, wired, and advice values for the map entry, as previously described. @@ -341,7 +360,8 @@ proper symbol information. .Pp Since processes can change state while .Nm -is running, some of the information printed may be inaccurate. This +is running, some of the information printed may be inaccurate. +This is especially important to consider when examining the kernel's map since merely executing .Nm @@ -349,9 +369,11 @@ will cause some of the information to change. .Pp The pathnames to files backing certain vnodes (such as the text and data sections of programs and shared libraries) are extracted from the -kernel's namei cache which is considerably volatile. If a path is not +kernel's namei cache which is considerably volatile. +If a path is not found there in its entirety, as much information as was available -will be printed. In most cases, simply running +will be printed. +In most cases, simply running .Xr ls 1 or .Xr stat 1 @@ -359,7 +381,8 @@ with the expected path to the file will cause the information to be reentered into the cache. .Pp The Solaris command by the same name has some interesting command line -flags that would be nice to emulate here. In particular, the +flags that would be nice to emulate here. +In particular, the .Fl r option that lists a process's reserved addresses, and the .Fl x @@ -367,12 +390,14 @@ option that prints resident/shared/private mapping details for each entry. .Pp Some of the output modes can be or are wider than the standard 80 -columns of a terminal. Some sort of formatting might be nice. +columns of a terminal. +Some sort of formatting might be nice. .Sh SECURITY CONSIDERATIONS The Solaris command controls access to processes the user does not own via the permissions of its .Pa /proc -file system. Since +file system. +Since .Nm uses .Xr kvm 3 diff --git a/usr.bin/pmc/pmc.1 b/usr.bin/pmc/pmc.1 index 7e37737af2d..5ea9c9d03c0 100644 --- a/usr.bin/pmc/pmc.1 +++ b/usr.bin/pmc/pmc.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: pmc.1,v 1.5 2002/06/07 01:38:17 gmcgarry Exp $ +.\" $NetBSD: pmc.1,v 1.6 2002/09/30 11:09:08 grant Exp $ .\" .\" Copyright (c) 2000 Zembu Labs, Inc. .\" All rights reserved. @@ -53,7 +53,8 @@ .Sh DESCRIPTION .Nm is a means of using a processor's performance-monitoring counter (PMC) -facility to measure various aspects of a program's execution. It is +facility to measure various aspects of a program's execution. +It is meant to be used in a fashion similar to .Xr time 1 . .Pp @@ -73,9 +74,11 @@ while running the command. .Bl -diag .It PMC support is not compiled into the kernel Performance-monitoring counter support has not been compiled into the -kernel. It may be included using the +kernel. +It may be included using the .Em PERFCTRS -option. See +option. +See .Xr options 4 for details. .It PMC counters are not supported by CPU diff --git a/usr.bin/printenv/printenv.1 b/usr.bin/printenv/printenv.1 index ea3fb0f35f4..ec03e2746fe 100644 --- a/usr.bin/printenv/printenv.1 +++ b/usr.bin/printenv/printenv.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: printenv.1,v 1.5 1997/10/19 12:44:21 lukem Exp $ +.\" $NetBSD: printenv.1,v 1.6 2002/09/30 11:09:09 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -34,7 +34,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)printenv.1 8.1 (Berkeley) 6/6/93 -.\" $NetBSD: printenv.1,v 1.5 1997/10/19 12:44:21 lukem Exp $ +.\" $NetBSD: printenv.1,v 1.6 2002/09/30 11:09:09 grant Exp $ .\" .Dd June 6, 1993 .Dt PRINTENV 1 @@ -48,7 +48,8 @@ .Sh DESCRIPTION .Nm prints out the names and values of the variables in the environment, -with one name/value pair per line. If +with one name/value pair per line. +If .Ar name is specified, only its value is printed. diff --git a/usr.bin/printf/printf.1 b/usr.bin/printf/printf.1 index b039d21e94d..87acf11d883 100644 --- a/usr.bin/printf/printf.1 +++ b/usr.bin/printf/printf.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: printf.1,v 1.15 2002/02/08 01:36:31 ross Exp $ +.\" $NetBSD: printf.1,v 1.16 2002/09/30 11:09:09 grant Exp $ .\" .\" Copyright (c) 1989, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -131,16 +131,19 @@ For .Cm d , and .Cm s , -formats, this option has no effect. For the +formats, this option has no effect. +For the .Cm o formats the precision of the number is increased to force the first -character of the output string to a zero. For the +character of the output string to a zero. +For the .Cm x .Pq Cm X format, a non-zero result has the string .Li 0x .Pq Li 0X -prepended to it. For +prepended to it. +For .Cm e , .Cm E , .Cm f , @@ -149,7 +152,8 @@ and .Cm G , formats, the result will always contain a decimal point, even if no digits follow the point (normally, a decimal point only appears in the -results of those formats if a digit follows the decimal point). For +results of those formats if a digit follows the decimal point). +For .Cm g and .Cm G @@ -164,10 +168,12 @@ A `+' character specifying that there should always be a sign placed before the number when using signed formats. .It Sq \&\ \& A space specifying that a blank should be left before a positive number -for a signed format. A `+' overrides a space if both are used; +for a signed format. +A `+' overrides a space if both are used; .It Cm \&0 A zero `0' character indicating that zero-padding should be used -rather than blank-padding. A `\-' overrides a `0' if both are used; +rather than blank-padding. +A `\-' overrides a `0' if both are used; .El .It "Field Width:" An optional digit string specifying a diff --git a/usr.bin/rdist/rdist.1 b/usr.bin/rdist/rdist.1 index 2d357ef627a..b23929a882a 100644 --- a/usr.bin/rdist/rdist.1 +++ b/usr.bin/rdist/rdist.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rdist.1,v 1.14 2002/02/08 01:36:31 ross Exp $ +.\" $NetBSD: rdist.1,v 1.15 2002/09/30 11:09:10 grant Exp $ .\" .\" Copyright (c) 1985, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -89,8 +89,8 @@ If no names are specified on the command line, will update all of the files and directories listed in .Ar distfile . Otherwise, the argument is taken to be the name of a file to be updated -or the label of a command to execute. If label and file names conflict, -it is assumed to be a label. +or the label of a command to execute. +If label and file names conflict, it is assumed to be a label. These may be used together to update specific files using specific commands. .Pp @@ -121,7 +121,8 @@ Options common to both forms: .Pp .Bl -tag -width Ic .It Fl b -Binary comparison. Perform a binary comparison and update files if they differ +Binary comparison. +Perform a binary comparison and update files if they differ rather than comparing dates and sizes. .It Fl d Ar var=value Define @@ -138,7 +139,8 @@ parentheses and separated by tabs and/or spaces. .It Fl D Turn on debugging. .It Fl h -Follow symbolic links. Copy the file that the link points to rather than the +Follow symbolic links. +Copy the file that the link points to rather than the link itself. .It Fl i Ignore unresolved links. @@ -146,42 +148,53 @@ Ignore unresolved links. will normally try to maintain the link structure of files being transferred and warn the user if all the links cannot be found. .It Fl m Ar host -Limit which machines are to be updated. Multiple +Limit which machines are to be updated. +Multiple .Fl m arguments can be given to limit updates to a subset of the hosts listed in the .Ar distfile . .It Fl n -Print the commands without executing them. This option is +Print the commands without executing them. +This option is useful for debugging .Ar distfile . .It Fl q -Quiet mode. Files that are being modified are normally -printed on standard output. The +Quiet mode. +Files that are being modified are normally +printed on standard output. +The .Fl q option suppresses this. .It Fl R -Remove extraneous files. If a directory is being updated, any files that exist +Remove extraneous files. +If a directory is being updated, any files that exist on the remote host that do not exist in the master directory are removed. This is useful for maintaining truly identical copies of directories. .It Fl v -Verify that the files are up to date on all the hosts. Any files +Verify that the files are up to date on all the hosts. +Any files that are out of date will be displayed but no files will be changed nor any mail sent. .It Fl w -Whole mode. The whole file name is appended to the destination directory -name. Normally, only the last component of a name is used when renaming files. +Whole mode. +The whole file name is appended to the destination directory +name. +Normally, only the last component of a name is used when renaming files. This will preserve the directory structure of the files being -copied instead of flattening the directory structure. For example, +copied instead of flattening the directory structure. +For example, renaming a list of files such as ( dir1/f1 dir2/f2 ) to dir3 would create files dir3/dir1/f1 and dir3/dir2/f2 instead of dir3/f1 and dir3/f2. .It Fl y -Younger mode. Files are normally updated if their +Younger mode. +Files are normally updated if their .Ar mtime and .Ar size (see .Xr stat 2 ) -disagree. The +disagree. +The .Fl y option causes .Nm @@ -194,7 +207,8 @@ A warning message is printed for files which are newer than the master copy. .Ar Distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what operations to perform -to do the updating. Each entry has one of the following formats. +to do the updating. +Each entry has one of the following formats. .Pp .Bd -literal -offset indent -compact \*[Lt]variable name\*[Gt] `=' \*[Lt]name list\*[Gt] @@ -214,14 +228,17 @@ as the master copy for distribution. The .Ar destination list is the list of hosts to which these files are to be -copied. Each file in the source list is added to a list of changes +copied. +Each file in the source list is added to a list of changes if the file is out of date on the host which is being updated (second format) or the file is newer than the time stamp file (third format). .Pp -Labels are optional. They are used to identify a command for partial updates. +Labels are optional. +They are used to identify a command for partial updates. .Pp Newlines, tabs, and blanks are only used as separators and are -otherwise ignored. Comments begin with `#' and end with a newline. +otherwise ignored. +Comments begin with `#' and end with a newline. .Pp Variables to be expanded begin with `$' followed by one character or a name enclosed in curly braces (see the examples at the end). @@ -317,9 +334,11 @@ for details). If one of the patterns matches some string within a file name, that file will be ignored. Note that since `\e' is a quote character, it must be doubled to become -part of the regular expression. Variables are expanded in +part of the regular expression. +Variables are expanded in .Ar pattern list -but not shell file pattern matching characters. To include a `$', it +but not shell file pattern matching characters. +To include a `$', it must be escaped with `\e'. .Pp The @@ -333,7 +352,8 @@ is updated or installed. If the .Ar name list is omitted then the shell commands will be executed -for every file updated or installed. The shell variable `FILE' is set +for every file updated or installed. +The shell variable `FILE' is set to the current filename before executing the commands in .Ar string . .Ar String @@ -412,5 +432,6 @@ facility. aborts on files which have a negative mtime (before Jan 1, 1970). .Pp There should be a `force' option to allow replacement of non-empty directories -by regular files or symlinks. A means of updating file modes and owners +by regular files or symlinks. +A means of updating file modes and owners of otherwise identical files is also needed. diff --git a/usr.bin/rpcgen/rpcgen.1 b/usr.bin/rpcgen/rpcgen.1 index e630ce8ec9e..3f2622a7bf1 100644 --- a/usr.bin/rpcgen/rpcgen.1 +++ b/usr.bin/rpcgen/rpcgen.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rpcgen.1,v 1.11 2001/12/08 19:12:34 wiz Exp $ +.\" $NetBSD: rpcgen.1,v 1.12 2002/09/30 11:09:10 grant Exp $ .\" from: @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89 .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved. .Dd April 3, 2001 @@ -77,13 +77,15 @@ With the .Fl S\&c option, it will also generate sample code which would illustrate how to use the -remote procedures on the client side. This code would be created in +remote procedures on the client side. +This code would be created in .Pa proto_client.c . With the .Fl S\&s option, it will also generate a sample server code which would illustrate how to write -the remote procedures. This code would be created in +the remote procedures. +This code would be created in .Pa proto_server.c . .Pp The server created can be started both by the port monitors @@ -298,8 +300,10 @@ and for users who need to write their own .Fn main routine to do initialization. .It Fl M -Generate thread-safe stubs. This alters the calling pattern of client and -server stubs so that storage for results is allocated by the caller. Note +Generate thread-safe stubs. +This alters the calling pattern of client and +server stubs so that storage for results is allocated by the caller. +Note that all components for a particular service (stubs, client and service wrappers, etc.) must be built either with or without the .Fl M @@ -367,7 +371,8 @@ Generate sample code to show the use of remote procedure and how to bind to the server before calling the client side stubs generated by .Nm "" . .It Fl S\&s -Generate skeleton code for the remote procedures on the server side. You would need +Generate skeleton code for the remote procedures on the server side. +You would need to fill in the actual code for the remote procedures. .It Fl t Compile into diff --git a/usr.bin/rup/rup.1 b/usr.bin/rup/rup.1 index 94dcf6e3b99..9f052c87230 100644 --- a/usr.bin/rup/rup.1 +++ b/usr.bin/rup/rup.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rup.1,v 1.15 2001/12/08 19:13:08 wiz Exp $ +.\" $NetBSD: rup.1,v 1.16 2002/09/30 11:09:11 grant Exp $ .\" .\" Copyright (c) 1985, 1991 The Regents of the University of California. .\" All rights reserved. @@ -84,14 +84,16 @@ The .Xr rpc.rstatd 8 daemon has not been started on the remote host. .It rup: RPC: Timed out -A communication error occurred. Either the network is +A communication error occurred. +Either the network is excessively congested, or the .Xr rpc.rstatd 8 daemon has terminated on the remote host. .It rup: RPC: Port mapper failure - RPC: Timed out The remote host is not running the portmapper (see .Xr rpcbind 8 ) , -and cannot accommodate any RPC-based services. The host may be down. +and cannot accommodate any RPC-based services. +The host may be down. .El .Sh SEE ALSO .Xr ruptime 1 , diff --git a/usr.bin/rusers/rusers.1 b/usr.bin/rusers/rusers.1 index 37111928d1d..f0d4186a208 100644 --- a/usr.bin/rusers/rusers.1 +++ b/usr.bin/rusers/rusers.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rusers.1,v 1.12 2001/12/08 19:13:31 wiz Exp $ +.\" $NetBSD: rusers.1,v 1.13 2002/09/30 11:09:11 grant Exp $ .\" .\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. @@ -32,7 +32,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)rusers.1 6.7 (Berkeley) 4/23/91 -.\" $NetBSD: rusers.1,v 1.12 2001/12/08 19:13:31 wiz Exp $ +.\" $NetBSD: rusers.1,v 1.13 2002/09/30 11:09:11 grant Exp $ .\" .Dd April 23, 1991 .Dt RUSERS 1 @@ -50,9 +50,11 @@ The command produces output similar to .Xr who 1 , but for the list of hosts or all machines on the local -network. For each host responding to the rusers query, +network. +For each host responding to the rusers query, the hostname with the names of the users currently logged -on is printed on each line. The rusers command will wait for +on is printed on each line. +The rusers command will wait for one minute to catch late responders. .Pp The following options are available: @@ -60,7 +62,8 @@ The following options are available: .It Fl a Print all machines responding even if no one is currently logged in. .It Fl l -Print a long format listing. This includes the user name, host name, +Print a long format listing. +This includes the user name, host name, tty that the user is logged in to, the date and time the user logged in, the idle time (in minutes), and the remote host they logged in from (if applicable). @@ -72,14 +75,16 @@ The .Xr rpc.rusersd 8 daemon has not been started on the remote host. .It rusers: RPC: Timed out -A communication error occurred. Either the network is +A communication error occurred. +Either the network is excessively congested, or the .Xr rpc.rusersd 8 daemon has terminated on the remote host. .It rusers: RPC: Port mapper failure - RPC: Timed out The remote host is not running the portmapper (see .Xr rpcbind 8 ) , -and cannot accommodate any RPC-based services. The host may be down. +and cannot accommodate any RPC-based services. +The host may be down. .El .Sh SEE ALSO .Xr rwho 1 , diff --git a/usr.bin/rwall/rwall.1 b/usr.bin/rwall/rwall.1 index ffa8c6512b0..b4393050e96 100644 --- a/usr.bin/rwall/rwall.1 +++ b/usr.bin/rwall/rwall.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rwall.1,v 1.10 2001/12/08 19:13:43 wiz Exp $ +.\" $NetBSD: rwall.1,v 1.11 2002/09/30 11:09:11 grant Exp $ .\" .\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. @@ -32,7 +32,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)rwall.1 6.7 (Berkeley) 4/23/91 -.\" $NetBSD: rwall.1,v 1.10 2001/12/08 19:13:43 wiz Exp $ +.\" $NetBSD: rwall.1,v 1.11 2002/09/30 11:09:11 grant Exp $ .\" .Dd April 23, 1991 .Dt RWALL 1 @@ -47,7 +47,8 @@ .Sh DESCRIPTION The .Nm -command sends a message to the users logged into the specified host. The +command sends a message to the users logged into the specified host. +The message to be sent can be typed in and terminated with EOF or it can be in a .Ar file . @@ -58,14 +59,16 @@ The .Xr rpc.rwalld 8 daemon has not been started on the remote host. .It rwall: RPC: Timed out -A communication error occurred. Either the network is +A communication error occurred. +Either the network is excessively congested, or the .Xr rpc.rwalld 8 daemon has terminated on the remote host. .It rwall: RPC: Port mapper failure - RPC: Timed out The remote host is not running the portmapper (see .Xr rpcbind 8 ) , -and cannot accommodate any RPC-based services. The host may be down. +and cannot accommodate any RPC-based services. +The host may be down. .El .Sh SEE ALSO .Xr wall 1 , diff --git a/usr.bin/rwho/rwho.1 b/usr.bin/rwho/rwho.1 index 20432984cbf..bf0cd37eb21 100644 --- a/usr.bin/rwho/rwho.1 +++ b/usr.bin/rwho/rwho.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: rwho.1,v 1.7 2001/04/04 09:44:08 wiz Exp $ +.\" $NetBSD: rwho.1,v 1.8 2002/09/30 11:09:12 grant Exp $ .\" .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -32,7 +32,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)rwho.1 8.1 (Berkeley) 6/6/93 -.\" $NetBSD: rwho.1,v 1.7 2001/04/04 09:44:08 wiz Exp $ +.\" $NetBSD: rwho.1,v 1.8 2002/09/30 11:09:12 grant Exp $ .\" .Dd June 6, 1993 .Dt RWHO 1 @@ -57,7 +57,8 @@ to be logged into that machine. .Pp If a users hasn't typed to the system for a minute or more, then .Nm -reports this idle time. If a user hasn't typed to the system for +reports this idle time. +If a user hasn't typed to the system for an hour or more, then the user will be omitted from the output of .Nm diff --git a/usr.bin/stat/stat.1 b/usr.bin/stat/stat.1 index 2d06640f750..77bc616f666 100644 --- a/usr.bin/stat/stat.1 +++ b/usr.bin/stat/stat.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: stat.1,v 1.6 2002/08/13 14:05:41 atatat Exp $ +.\" $NetBSD: stat.1,v 1.7 2002/09/30 11:09:12 grant Exp $ .\" .\" Copyright (c) 2002 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -63,14 +63,15 @@ utility displays information about the file pointed to by .Ar file . Read, write or execute permissions of the named file are not required, but all directories listed in the path name leading to the file must be -searchable. If no argument is given, +searchable. +If no argument is given, .Nm displays information about the file descriptor for standard input. .Pp When invoked as .Nm readlink , -only the target of the symbolic link is printed. If the given argument -is not a symbolic link, +only the target of the symbolic link is printed. +If the given argument is not a symbolic link, .Nm readlink will print nothing and exit with an error. .Pp @@ -86,7 +87,8 @@ As in display a slash (/) immediately after each pathname that is a directory, an asterisk (*) after each that is executable, an at sign (@) after each symbolic link, a percent sign (%) after each whiteout, an equal sign (=) after each -socket, and a vertical bar (|) after each that is a FIFO. The use of +socket, and a vertical bar (|) after each that is a FIFO. +The use of .Fl F implies .Fl l . @@ -109,18 +111,21 @@ Suppress failure messages if calls to .Xr stat 2 or .Xr lstat 2 -fail. When run as +fail. +When run as .Nm readlink , error messages are automatically suppressed. .It Fl f Ar format -Display information using the specified format. See the FORMATS section +Display information using the specified format. +See the FORMATS section for a description of valid formats. .It Fl l Display output in .Ic ls Fl lT format. .It Fl r -Display raw information. That is, for all the fields in the stat-structure, +Display raw information. +That is, for all the fields in the stat-structure, display the raw, numerical value (for example, times in seconds since the epoch, etc.) .It Fl s @@ -129,7 +134,8 @@ Display information in ``shell output'', suitable for initializing variables. Display information in a more verbose way as known from some Linux distributions. .It Fl t Ar timefmt -Display timestamps using the specified format. This format is +Display timestamps using the specified format. +This format is passed directly to .Xr strftime 3 . .El @@ -140,7 +146,8 @@ formats in that they start with .Cm % , are then followed by a sequence of formatting characters, and end in a character that selects the field of the struct stat which is to be -formatted. If the +formatted. +If the .Cm % is immediately followed by one of .Cm n , @@ -160,7 +167,8 @@ Non-zero octal output will have a leading zero, and non-zero hexadecimal output will have ``0x'' prepended to it. .It Cm + Asserts that a sign indicating whether a number is positive or negative -should always be printed. Non-negative numbers are not usually printed +should always be printed. +Non-negative numbers are not usually printed with a sign. .It Cm - Aligns string output to the left of the field, instead of to the right. @@ -168,7 +176,8 @@ Aligns string output to the left of the field, instead of to the right. Sets the fill character for left padding to the 0 character, instead of a space. .It space -Reserves a space at the front of non-negative signed output fields. A +Reserves a space at the front of non-negative signed output fields. +A .Sq Cm + overrides a space if both are used. .El @@ -194,7 +203,8 @@ or .Cm S . These represent signed decimal output, octal output, unsigned decimal output, hexadecimal output, floating point output, and string output, -respectively. Some output formats do not apply to all fields. +respectively. +Some output formats do not apply to all fields. Floating point output only applies to timespec fields (the .Cm a , .Cm m , @@ -205,7 +215,8 @@ fields). The special output specifier .Cm S may be used to indicate that the output, if -applicable, should be in string format. May be used in combination with +applicable, should be in string format. +May be used in combination with .Bl -tag -width Ds .It Cm amc Display date in strftime(3) format. @@ -225,21 +236,24 @@ Displays the name of Displays the type of .Ar file . .It Cm Y -Insert a `` -\*[Gt] '' into the output. Note that the default output format +Insert a `` -\*[Gt] '' into the output. +Note that the default output format for .Cm Y is a string, but if specified explicitly, these four characters are prepended. .El .It Cm sub -An optional sub field specifier (high, middle, low). Only applies to +An optional sub field specifier (high, middle, low). +Only applies to the .Cm p , .Cm d , .Cm r , and .Cm T -output formats. It can be one of the following: +output formats. +It can be one of the following: .Bl -tag -width Ds .It Cm H ``High'' -- specifies the major number for devices from @@ -337,8 +351,8 @@ special devices and gives size output for all others. .Pp Only the .Cm % -and the field specifier are required. Most field -specifiers default to +and the field specifier are required. +Most field specifiers default to .Cm U as an output form, with the exception of diff --git a/usr.bin/talk/talk.1 b/usr.bin/talk/talk.1 index 252923a8363..d261b3c5e9f 100644 --- a/usr.bin/talk/talk.1 +++ b/usr.bin/talk/talk.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: talk.1,v 1.6 2001/12/08 19:17:46 wiz Exp $ +.\" $NetBSD: talk.1,v 1.7 2002/09/30 11:09:12 grant Exp $ .\" .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -53,8 +53,8 @@ Options available: .It Ar person If you wish to talk to someone on your own machine, then .Ar person -is just the person's login name. If you wish to talk to a user on -another host, then +is just the person's login name. +If you wish to talk to a user on another host, then .Ar person is of the form .Ql user@host . @@ -77,26 +77,32 @@ talk: connection requested by your_name@your_machine. talk: respond with: talk your_name@your_machine .Ed .Pp -to the user you wish to talk to. At this point, the recipient +to the user you wish to talk to. +At this point, the recipient of the message should reply by typing .Pp .Dl talk \ your_name@your_machine .Pp It doesn't matter from which machine the recipient replies, as -long as his login-name is the same. Once communication is established, +long as his login-name is the same. +Once communication is established, the two parties may type simultaneously, with their output appearing -in separate windows. Typing control-L +in separate windows. +Typing control-L .Ql ^L will cause the screen to be reprinted, while your erase, kill, and word kill characters will -behave normally. To exit, just type your interrupt character; +behave normally. +To exit, just type your interrupt character; .Nm then moves the cursor to the bottom of the screen and restores the terminal to its previous state. .Pp Permission to talk may be denied or granted by use of the .Xr mesg 1 -command. At the outset talking is allowed. Certain commands, in +command. +At the outset talking is allowed. +Certain commands, in particular .Xr nroff 1 and diff --git a/usr.bin/tcopy/tcopy.1 b/usr.bin/tcopy/tcopy.1 index d09080bfc62..6307e50e12b 100644 --- a/usr.bin/tcopy/tcopy.1 +++ b/usr.bin/tcopy/tcopy.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: tcopy.1,v 1.6 1999/03/22 18:16:44 garbled Exp $ +.\" $NetBSD: tcopy.1,v 1.7 2002/09/30 11:09:12 grant Exp $ .\" .\" Copyright (c) 1985, 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -47,15 +47,19 @@ .Oc .Sh DESCRIPTION .Nm -is designed to copy magnetic tapes. The only assumption made +is designed to copy magnetic tapes. +The only assumption made about the tape is that there are two tape marks at the end. .Nm with only a source tape .Pf ( Ar /dev/rst0 by default) specified will print -information about the sizes of records and tape files. If a destination -is specified a copy will be made of the source tape. The blocking on the -destination tape will be identical to that used on the source tape. Copying +information about the sizes of records and tape files. +If a destination +is specified a copy will be made of the source tape. +The blocking on the +destination tape will be identical to that used on the source tape. +Copying a tape will yield the same output as if just printing the sizes. .Pp Options: diff --git a/usr.bin/telnet/telnet.1 b/usr.bin/telnet/telnet.1 index 5e60690e1ac..c25165efec0 100644 --- a/usr.bin/telnet/telnet.1 +++ b/usr.bin/telnet/telnet.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: telnet.1,v 1.24 2002/08/23 10:39:46 wiz Exp $ +.\" $NetBSD: telnet.1,v 1.25 2002/09/30 11:09:13 grant Exp $ .\" .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -112,7 +112,8 @@ Forces .Nm to use IPv6 addresses only. .It Fl 8 -Specifies an 8-bit data path. This causes an attempt to +Specifies an 8-bit data path. +This causes an attempt to negotiate the .Dv TELNET BINARY option on both input and output. @@ -127,10 +128,12 @@ have already been forwarded into the local environment. .It Fl K Specifies no automatic login to the remote system. .It Fl L -Specifies an 8-bit data path on output. This causes the +Specifies an 8-bit data path on output. +This causes the BINARY option to be negotiated on output. .It Fl N -Numeric host address. No attempt will be made to look up +Numeric host address. +No attempt will be made to look up symbolic names for host addresses. .It Fl S Ar tos Sets the IP type-of-service (TOS) option for the telnet @@ -158,7 +161,8 @@ otherwise it is the name associated with the user ID. .It Fl c Disables the reading of the user's .Pa \&.telnetrc -file. (See the +file. +(See the .Ic toggle skiprc command on this man page.) .It Fl d @@ -223,20 +227,23 @@ unless modified by the .Fl e option. .It Fl x -Turns on encryption of the data stream if possible. This +Turns on encryption of the data stream if possible. +This option is not available outside of the United States and Canada. .It Ar host Indicates the official name, an alias, or the Internet address of a remote host. .It Ar port -Indicates a port number (address of an application). If a number is +Indicates a port number (address of an application). +If a number is not specified, the default .Nm port is used. .El .Pp -When in rlogin mode, a line of the form ~. disconnects from the +When in rlogin mode, a line of the form ~. +disconnects from the remote host; ~ is the telnet escape character. Similarly, the line ~^Z suspends the telnet session. The line ~^] escapes to the normal telnet escape prompt. @@ -256,9 +263,11 @@ depending on what the remote system supports. When .Dv LINEMODE is enabled, character processing is done on the -local system, under the control of the remote system. When input +local system, under the control of the remote system. +When input editing or character echoing is to be disabled, the remote system -will relay that information. The remote system will also relay +will relay that information. +The remote system will also relay changes to any special characters that happen on the remote system, so that they can take effect on the local system. .Pp @@ -344,17 +353,18 @@ commands). .It Ic auth Ar argument ... The auth command manipulates the information sent through the .Dv TELNET AUTHENTICATE -option. Valid arguments for the +option. +Valid arguments for the auth command are as follows: .Bl -tag -width "disable type" .It Ic disable Ar type -Disables the specified type of authentication. To -obtain a list of available types, use the +Disables the specified type of authentication. +To obtain a list of available types, use the .Ic auth disable \&? command. .It Ic enable Ar type -Enables the specified type of authentication. To -obtain a list of available types, use the +Enables the specified type of authentication. +To obtain a list of available types, use the .Ic auth enable \&? command. .It Ic status @@ -383,16 +393,17 @@ option is not supported outside of the United States and Canada. Valid arguments for the encrypt command are: .Bl -tag -width Ar .It Ic disable Ar type Ic [input|output] -Disables the specified type of encryption. If you -omit the input and output, both input and output -are disabled. To obtain a list of available -types, use the +Disables the specified type of encryption. +If you omit the input and output, both input and output +are disabled. +To obtain a list of available types, use the .Ic encrypt disable \&? command. .It Ic enable Ar type Ic [input|output] -Enables the specified type of encryption. If you -omit input and output, both input and output are -enabled. To obtain a list of available types, use the +Enables the specified type of encryption. +If you omit input and output, both input and output are +enabled. +To obtain a list of available types, use the .Ic encrypt enable \&? command. .It Ic input @@ -412,18 +423,20 @@ This is the same as the .Ic encrypt stop output command. .It Ic start Ic [input|output] -Attempts to start encryption. If you omit +Attempts to start encryption. +If you omit .Ic input and .Ic output , -both input and output are enabled. To -obtain a list of available types, use the +both input and output are enabled. +To obtain a list of available types, use the .Ic encrypt enable \&? command. .It Ic status Lists the current status of encryption. .It Ic stop Ic [input|output] -Stops encryption. If you omit input and output, +Stops encryption. +If you omit input and output, encryption is on both input and output. .It Ic type Ar type Sets the default type of encryption to be used @@ -600,16 +613,22 @@ If a port is specified .Nm omits any automatic initialisation of .Tn TELNET -options. When the port number is preceded by a minus sign, +options. +When the port number is preceded by a minus sign, the initial option negotiation is done. After establishing a connection, the file .Pa \&.telnetrc in the -user's home directory is opened. Lines beginning with a # are -comment lines. Blank lines are ignored. Lines that begin -without white space are the start of a machine entry. The +user's home directory is opened. +Lines beginning with a # are +comment lines. +Blank lines are ignored. +Lines that begin +without white space are the start of a machine entry. +The first thing on the line is the name of the machine that is -being connected to. The rest of the line, and successive +being connected to. +The rest of the line, and successive lines that begin with white space are assumed to be .Nm commands and are processed as if they had been typed @@ -770,7 +789,8 @@ The values of variables may be interrogated with the .Ic display command. The variables which may be set or unset, but not toggled, are -listed here. In addition, any of the variables for the +listed here. +In addition, any of the variables for the .Ic toggle command may be explicitly set or unset using the @@ -789,7 +809,8 @@ is enabled, and the status character is typed, a sequence (see .Ic send ayt above) is sent to the -remote host. The initial value for the "Are You There" +remote host. +The initial value for the "Are You There" character is the terminal's status character. .It Ic echo This is the value (initially \*(Lq^E\*(Rq) which, when in @@ -868,7 +889,8 @@ is operating in .Dv LINEMODE , these are the characters that, when typed, cause partial lines to be -forwarded to the remote system. The initial value for +forwarded to the remote system. +The initial value for the forwarding characters are taken from the terminal's eol and eol2 characters. .It Ic interrupt @@ -975,7 +997,8 @@ This character, at the beginning of a line followed by a "." closes the connection; when followed by a ^Z it suspends the .Nm -command. The initial state is to +command. +The initial state is to disable the rlogin escape character. .It Ic start If the @@ -1028,7 +1051,8 @@ or .Ic option tracing being .Dv TRUE , -will be written. If it is set to +will be written. +If it is set to .Dq Fl , then tracing information will be written to standard output (the default). .It Ic worderase @@ -1058,7 +1082,8 @@ or change the state of the special characters when the .Dv TELNET LINEMODE option has -been enabled. Special characters are characters that get +been enabled. +Special characters are characters that get mapped to .Tn TELNET commands sequences (like @@ -1077,7 +1102,8 @@ The remote side is requested to send all the current special character settings, and if there are any discrepancies with the local side, the local side will switch to the remote value. .It Ic export -Switch to the local defaults for the special characters. The +Switch to the local defaults for the special characters. +The local default characters are those of the local terminal at the time when .Nm @@ -1159,7 +1185,8 @@ When the .Dv TELNET ENCRYPT option is negotiated, by default the actual encryption (decryption) of the data -stream does not start automatically. The autoencrypt +stream does not start automatically. +The autoencrypt (autodecrypt) command states that encryption of the output (input) stream should be enabled as soon as possible. @@ -1172,7 +1199,8 @@ If the remote side supports the .Dv TELNET AUTHENTICATION option .Tn TELNET -attempts to use it to perform automatic authentication. If the +attempts to use it to perform automatic authentication. +If the .Dv AUTHENTICATION option is not supported, the user's login name are propagated through the @@ -1337,7 +1365,8 @@ When the skiprc toggle is skips the reading of the .Pa \&.telnetrc file in the users home -directory when connections are opened. The initial +directory when connections are opened. +The initial value for this toggle is .Dv FALSE . .It Ic termdata @@ -1351,7 +1380,8 @@ toggle is .Dv TRUE , .Nm prints out a message each time encryption is enabled or -disabled. The initial value for this toggle is +disabled. +The initial value for this toggle is .Dv FALSE . Note: Because of export controls, data encryption is not supported outside of the United States and Canada. @@ -1367,12 +1397,14 @@ This command only works when the user is using the .Xr csh 1 . .It Ic \&! Op Ar command Execute a single command in a subshell on the local -system. If +system. +If .Ar command is omitted, then an interactive subshell is invoked. .It Ic \&? Op Ar command -Get help. With no arguments, +Get help. +With no arguments, .Nm prints a help summary. If a command is specified, diff --git a/usr.bin/tftp/tftp.1 b/usr.bin/tftp/tftp.1 index 7ebb2830db1..b30d95a1d51 100644 --- a/usr.bin/tftp/tftp.1 +++ b/usr.bin/tftp/tftp.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: tftp.1,v 1.13 2002/02/08 01:36:34 ross Exp $ +.\" $NetBSD: tftp.1,v 1.14 2002/09/30 11:09:13 grant Exp $ .\" .\" Copyright (c) 1990, 1993, 1994 .\" The Regents of the University of California. All rights reserved. @@ -175,6 +175,6 @@ Because there is no user-login or validation within the .Tn TFTP protocol, the remote site will probably have some -sort of file-access restrictions in place. The -exact methods are specific to each site and therefore +sort of file-access restrictions in place. +The exact methods are specific to each site and therefore difficult to document here. diff --git a/usr.bin/tip/tip.1 b/usr.bin/tip/tip.1 index 2807c120019..2f0bbaa3b51 100644 --- a/usr.bin/tip/tip.1 +++ b/usr.bin/tip/tip.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: tip.1,v 1.15 2002/05/03 22:43:59 mjl Exp $ +.\" $NetBSD: tip.1,v 1.16 2002/09/30 11:09:13 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -62,7 +62,8 @@ .\" .Nm cu establish a full-duplex connection to another machine, giving the appearance of being logged in directly on the -remote cpu. It goes without saying that you must have a login +remote cpu. +It goes without saying that you must have a login on the machine (or equivalent) to which you wish to connect. .\" The preferred interface is .\" .Nm tip . @@ -71,7 +72,8 @@ on the machine (or equivalent) to which you wish to connect. .\" interface is included for those people attached to the .\" ``call .\" .Ux Ns '' -.\" command of version 7. This manual page +.\" command of version 7. +This manual page .\" describes only .\" .Nm tip . .Pp @@ -82,7 +84,8 @@ Set verbose mode. .El .Pp Typed characters are normally transmitted directly to the remote -machine (which does the echoing as well). A tilde (`~') appearing +machine (which does the echoing as well). +A tilde (`~') appearing as the first character of a line is an escape signal; the following are recognized: .Bl -tag -width flag @@ -110,12 +113,14 @@ a command to be executed on the remote machine. .It Ic \&~p Ar from Op Ar to Send a file to a remote .Ux -host. The put command causes the remote +host. +The put command causes the remote .Ux system to run the command string ``cat \*[Gt] 'to''', while .Nm sends it the ``from'' -file. If the ``to'' file isn't specified the ``from'' file name is used. +file. +If the ``to'' file isn't specified the ``from'' file name is used. This command is actually a .Ux specific version of the ``~\*[Gt]'' command. @@ -144,7 +149,8 @@ The command string sent to the local system is processed by the shell. .It Ic \&~C Fork a child process on the local system to perform special protocols -such as \s-1XMODEM\s+1. The child program will be run with the following +such as \s-1XMODEM\s+1. +The child program will be run with the following somewhat unusual arrangement of file descriptors: .nf .in +1i @@ -193,7 +199,8 @@ refer to .Xr remote 5 for a full description. Each system has a default baud rate with which to -establish a connection. If this value is not suitable, the baud rate +establish a connection. +If this value is not suitable, the baud rate to be used may be specified on the command line, e.g. .Ql "tip -300 mds" . .Pp @@ -210,7 +217,8 @@ When .Nm prompts for an argument (e.g. during setup of a file transfer) the line typed may be edited with the standard -erase and kill characters. A null line in response to a prompt, +erase and kill characters. +A null line in response to a prompt, or an interrupt, will abort the dialogue and return you to the remote machine. .Pp @@ -225,8 +233,9 @@ During file transfers provides a running count of the number of lines transferred. When using the ~\*[Gt] and ~\*[Lt] commands, the ``eofread'' and ``eofwrite'' variables are used to recognize end-of-file when reading, and -specify end-of-file when writing (see below). File transfers -normally depend on tandem mode for flow control. If the remote +specify end-of-file when writing (see below). +File transfers normally depend on tandem mode for flow control. +If the remote system does not support tandem mode, ``echocheck'' may be set to indicate .Nm @@ -254,28 +263,37 @@ maintains a set of .Ar variables which control its operation. Some of these variables are read-only to normal users (root is allowed -to change anything of interest). Variables may be displayed -and set through the ``s'' escape. The syntax for variables is patterned +to change anything of interest). +Variables may be displayed +and set through the ``s'' escape. +The syntax for variables is patterned after .Xr vi 1 and .Xr Mail 1 . Supplying ``all'' as an argument to the set command displays all variables readable by -the user. Alternatively, the user may request display of a particular -variable by attaching a `?' to the end. For example ``escape?'' displays +the user. +Alternatively, the user may request display of a particular +variable by attaching a `?' to the end. +For example ``escape?'' displays the current escape character. .Pp -Variables are numeric, string, character, or boolean values. Boolean +Variables are numeric, string, character, or boolean values. +Boolean variables are set merely by specifying their name; they may be reset -by prepending a `!' to the name. Other variable types are set by -concatenating an `=' and the value. The entire assignment must not -have any blanks in it. A single set command may be used to interrogate +by prepending a `!' to the name. +Other variable types are set by +concatenating an `=' and the value. +The entire assignment must not +have any blanks in it. +A single set command may be used to interrogate as well as set a number of variables. Variables may be initialized at run time by placing set commands (without the ``~s'' prefix in a file .Pa .tiprc -in one's home directory). The +in one's home directory). +The .Fl v option causes .Nm @@ -337,8 +355,10 @@ writes when receiving files; abbreviated (char) The character which indicates an end-of-line on the remote host; abbreviated .Ar pr ; -default value is `\en'. This value is used to synchronize during -data transfers. The count of lines transferred during a file transfer +default value is `\en'. +This value is used to synchronize during +data transfers. +The count of lines transferred during a file transfer command is based on receipt of this character. .It Ar raise (bool) Upper case mapping mode; abbreviated @@ -377,7 +397,8 @@ If the switch is on, only printable .Tn ASCII characters will be included in -the script file (those characters between 040 and 0177). The +the script file (those characters between 040 and 0177). +The variable .Ar exceptions is used to indicate characters which are an exception to the normal diff --git a/usr.bin/tset/tset.1 b/usr.bin/tset/tset.1 index c4f70b34bd8..d654a32efd2 100644 --- a/usr.bin/tset/tset.1 +++ b/usr.bin/tset/tset.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: tset.1,v 1.11 2002/02/08 01:36:36 ross Exp $ +.\" $NetBSD: tset.1,v 1.12 2002/09/30 11:09:14 grant Exp $ .\" .\" Copyright (c) 1985, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -124,9 +124,11 @@ not initialized in any way. Set the erase character to .Ar ch . .It Fl E -Emit the extended termcap entry. By default the termcap entry is +Emit the extended termcap entry. +By default the termcap entry is truncated to 1024 bytes, this flag specifies the untruncated termcap -entry is to be output. Using this flag may cause problems with some +entry is to be output. +Using this flag may cause problems with some shells. .It Fl I Do not send the terminal or tab initialization strings to the terminal. diff --git a/usr.bin/tsort/tsort.1 b/usr.bin/tsort/tsort.1 index 51d989575f9..39238793748 100644 --- a/usr.bin/tsort/tsort.1 +++ b/usr.bin/tsort/tsort.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: tsort.1,v 1.8 2000/11/08 00:56:26 wiz Exp $ +.\" $NetBSD: tsort.1,v 1.9 2002/09/30 11:09:14 grant Exp $ .\" .\" Copyright (c) 1990, 1993, 1994 .\" The Regents of the University of California. All rights reserved. @@ -73,7 +73,8 @@ The options are as follows: Search for and display the longest cycle. Can take a very long time. .It Fl q -Do not display informational messages about cycles. This is primarily +Do not display informational messages about cycles. +This is primarily intended for building libraries, where optimal ordering is not critical, and cycles occur often. .El diff --git a/usr.bin/units/units.1 b/usr.bin/units/units.1 index a033a11bb4e..263fd2ce270 100644 --- a/usr.bin/units/units.1 +++ b/usr.bin/units/units.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: units.1,v 1.11 2002/04/02 18:08:28 atatat Exp $ +.\" $NetBSD: units.1,v 1.12 2002/09/30 11:09:15 grant Exp $ .Dd December 18, 2001 .Dt UNITS 1 .Os @@ -15,9 +15,9 @@ .Oc .Sh DESCRIPTION The units program converts quantities expression in various scales to -their equivalents in other scales. The units program can only -handle multiplicative scale changes. It cannot convert Centigrade -to Fahrenheit, for example. +their equivalents in other scales. +The units program can only handle multiplicative scale changes. +It cannot convert Centigrade to Fahrenheit, for example. .Pp The following options are supported: .Bl -tag -width "from-unit to-unit" -offset indent @@ -30,8 +30,11 @@ about the number of units loaded. Prints the version number. .It Ar from-unit Ar to-unit Allows a single unit conversion to be done directly from the command -line. No prompting will occur. The units program will print out -only the result of this single conversion. The +line. +No prompting will occur. +The units program will print out +only the result of this single conversion. +The .Ar count argument can be prepended to the .Ar from-unit @@ -59,7 +62,8 @@ character as shown in the example, or by simple concatenation: is equivalent to .Dq cm^3 . Multiplication of units can be specified by using spaces, a dash or -an asterisk. Division of units is indicated by the slash +an asterisk. +Division of units is indicated by the slash .Pq Sq \&/ . Note that multiplication has a higher precedence than division, so @@ -79,9 +83,11 @@ it will display the reduced form for each unit: 2.1166667e-05 kg^2 m / sec .Ed .Pp -The conversion information is read from a units data file. The default +The conversion information is read from a units data file. +The default file includes definitions for most familiar units, abbreviations and -metric prefixes. Some constants of nature included are: +metric prefixes. +Some constants of nature included are: .Bl -tag -width mercury -compact -offset indent .It pi ratio of circumference to diameter @@ -104,10 +110,12 @@ astronomical unit .El .Pp .Dq pound -is a unit of mass. Compound names are run together +is a unit of mass. +Compound names are run together so .Dq poundforce -is a unit of force. British units that differ from their +is a unit of force. +British units that differ from their US counterparts are prefixed with .Dq br , and currency is prefixed with @@ -123,8 +131,10 @@ or a trailing and check again for a match. .Pp All of these definitions can be read in the standard units file, or you -can supply your own file. A unit is specified on a single line by -giving its name and an equivalence. One should be careful to define +can supply your own file. +A unit is specified on a single line by +giving its name and an equivalence. +One should be careful to define new units in terms of old ones so that a reduction leads to the primitive units which are marked with .Sq \&! @@ -155,8 +165,8 @@ The user must use .Sq \&| to indicate division of numbers and .Sq \&/ -to indicate division of symbols. This distinction should not -be necessary. +to indicate division of symbols. +This distinction should not be necessary. .Pp The program contains various arbitrary limits on the length of the units converted and on the length of the data file. diff --git a/usr.bin/usbhidaction/usbhidaction.1 b/usr.bin/usbhidaction/usbhidaction.1 index 7e4288696cc..cd1d6d6357c 100644 --- a/usr.bin/usbhidaction/usbhidaction.1 +++ b/usr.bin/usbhidaction/usbhidaction.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbhidaction.1,v 1.6 2002/01/18 14:38:59 augustss Exp $ +.\" $NetBSD: usbhidaction.1,v 1.7 2002/09/30 11:09:15 grant Exp $ .\" .\" Copyright (c) 2000 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -65,9 +65,11 @@ Toggle the daemon flag. .It Fl i Ignore HID items in the config file that does not exist in the device. .It Fl f Ar device -Specify a path name for the device to operate on. If +Specify a path name for the device to operate on. +If .Ar device -is numeric, it is taken to be the USB HID device number. If it is a relative +is numeric, it is taken to be the USB HID device number. +If it is a relative path, it is taken to be the name of the device under .Pa /dev . An absolute path is taken to be the literal device pathname. @@ -77,18 +79,22 @@ Be verbose, and do not become a daemon. .Pp The config file will be re-read if the process gets a HUP signal. .Sh CONFIGURATION -The configuration file has a very simple format. Each line describes an +The configuration file has a very simple format. +Each line describes an action; if a line begins with a whitespace it is considered a continuation -of the previous line. Lines beginning with `#' are considered as comments. +of the previous line. +Lines beginning with `#' are considered as comments. .Pp Each line has three parts: a name of a USB HID item, a value for that item, -and an action. There must be whitespace between the parts. +and an action. +There must be whitespace between the parts. .Pp The item names are similar to those used by .Xr usbhidctl 1 , but each part must be prefixed by its page name. .Pp -The value is simply a numeric value. When the item reports this value +The value is simply a numeric value. +When the item reports this value the action will be performed. If the value is `*' it will match any value. .Pp diff --git a/usr.bin/usbhidctl/usbhidctl.1 b/usr.bin/usbhidctl/usbhidctl.1 index 2f90400daeb..23acbca9f03 100644 --- a/usr.bin/usbhidctl/usbhidctl.1 +++ b/usr.bin/usbhidctl/usbhidctl.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: usbhidctl.1,v 1.14 2001/12/28 17:49:32 augustss Exp $ +.\" $NetBSD: usbhidctl.1,v 1.15 2002/09/30 11:09:15 grant Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -67,9 +67,11 @@ .Sh DESCRIPTION .Nm can be used to output or modify the state of a USB HID (Human Interface -Device). If a list of items is present on the command line, then +Device). +If a list of items is present on the command line, then .Nm -prints the current value of those items for the specified device. If the +prints the current value of those items for the specified device. +If the .Fl w flag is specified .Nm @@ -81,26 +83,30 @@ The options are as follows: Show all items and their current values. This option fails if the device does not support the GET_REPORT command. .It Fl f Ar device -Specify a path name for the device to operate on. If +Specify a path name for the device to operate on. +If .Ar device -is numeric, it is taken to be the USB HID device number. If it is a relative +is numeric, it is taken to be the USB HID device number. +If it is a relative path, it is taken to be the name of the device under .Pa /dev . An absolute path is taken to be the literal device pathname. .It Fl l -Loop and dump the device data every time it changes. Only 'input' items are -displayed in this mode. +Loop and dump the device data every time it changes. +Only 'input' items are displayed in this mode. .It Fl n -Suppress printing of the item name when querying specific items. Only output -the current value. +Suppress printing of the item name when querying specific items. +Only output the current value. .It Fl r Dump the USB HID report descriptor. .It Fl t Ar table Specify a path name for the HID usage table file. .It Fl v -Be verbose. Repeating this option increases verbosity. +Be verbose. +Repeating this option increases verbosity. .It Fl w -Change item values. Only 'output' and 'feature' kinds can be set with this +Change item values. +Only 'output' and 'feature' kinds can be set with this option. .El .Sh FILES @@ -109,9 +115,11 @@ The default HID usage table. .Sh SYNTAX .Nm parses the names of items specified on the command line against the human -interface items reported by the USB device. Each human interface item is +interface items reported by the USB device. +Each human interface item is mapped from its native form to a human readable name, using the HID usage -table file. Command line items are compared with the generated item names, +table file. +Command line items are compared with the generated item names, and the USB HID device is operated on when a match is found. .Pp Each human interface item is named by the @@ -120,7 +128,8 @@ it appears in, the .Qq usage within that page, and the list of .Qq collections -containing the item. Each collection in turn is also identified by page, and +containing the item. +Each collection in turn is also identified by page, and the usage within that page. .Pp On the @@ -132,12 +141,14 @@ The collections are separated by the character .Pp As an alternative notation in items on the command line, the native numeric value for the page name or usage can be used instead of the full human -readable page name or usage name. Numeric values can be specified in decimal, +readable page name or usage name. +Numeric values can be specified in decimal, octal or hexadecimal. .Sh EXAMPLES On a standard USB mouse the item .Dl Generic_Desktop:Mouse.Generic_Desktop:Pointer.Button:Button_2 -reflects the current status of button 2. The +reflects the current status of button 2. +The .Qq button 2 item is encapsulated within two collections, the .Qq Mouse @@ -147,22 +158,24 @@ page, and the .Qq Pointer collection in the .Qq Generic Desktop -page. The item itself is the usage +page. +The item itself is the usage .Qq Button_2 in the .Qq Button page. .Pp -An item can generally be named by omitting one or more of the page names. For -example the +An item can generally be named by omitting one or more of the page names. +For example the .Qq button 2 item would usually just be referred to on the command line as: .Dl usbhidctl -f /dev/mouse Mouse.Pointer.Button_2 .Pp Items can also be named by referring to parts of the item name with the -numeric representation of the native HID usage identifiers. This is most -useful when items are missing from the HID usage table. The page identifier -for the +numeric representation of the native HID usage identifiers. +This is most +useful when items are missing from the HID usage table. +The page identifier for the .Qq Generic Desktop page is 1, and the usage identifier for the usage .Qq Button_2 @@ -173,10 +186,12 @@ item: .Pp Devices with human interface outputs can be manipulated with the .Fl w -option. For example, some USB mice have a Light Emitting Diode under software +option. +For example, some USB mice have a Light Emitting Diode under software control as usage 2 under page 0xffff, in the .Qq Mouse -collection. The following can be used to switch this LED off: +collection. +The following can be used to switch this LED off: .Dl usbhidctl -f /dev/mouse -w Mouse.0xffff:2=0 .Sh SEE ALSO .Xr usbhidaction 1 , @@ -192,5 +207,6 @@ command first appeared in .An David Sainty Aq David.Sainty@dtsp.co.nz .Sh BUGS Some USB HID devices report multiple items with exactly the same usage -identifiers. The current naming scheme does not provide the means to specify +identifiers. +The current naming scheme does not provide the means to specify which of a set of identically named items you are referring to. diff --git a/usr.bin/uuencode/uuencode.5 b/usr.bin/uuencode/uuencode.5 index e531b7ad113..9b50f7dc080 100644 --- a/usr.bin/uuencode/uuencode.5 +++ b/usr.bin/uuencode/uuencode.5 @@ -1,4 +1,4 @@ -.\" $NetBSD: uuencode.5,v 1.7 2002/08/06 15:26:04 soren Exp $ +.\" $NetBSD: uuencode.5,v 1.8 2002/09/30 11:09:15 grant Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -123,7 +123,8 @@ Obviously, not every input file will be a multiple of three bytes in size. In these cases, .Xr uuencode 1 will pad the remaining one or two bytes of data with garbage bytes until -a three byte group is created. The byte count in a line containing +a three byte group is created. +The byte count in a line containing garbage padding will reflect the actual number of bytes encoded, making it possible to convey how many bytes are garbage. .Pp diff --git a/usr.bin/vacation/vacation.1 b/usr.bin/vacation/vacation.1 index 8ea3e48b6cf..6569f311046 100644 --- a/usr.bin/vacation/vacation.1 +++ b/usr.bin/vacation/vacation.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: vacation.1,v 1.14 2002/02/08 01:36:36 ross Exp $ +.\" $NetBSD: vacation.1,v 1.15 2002/09/30 11:09:16 grant Exp $ .\" .\" Copyright (c) 1985, 1987, 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -51,9 +51,11 @@ indication .Sh DESCRIPTION .Nm returns a message to the sender of a message telling them that you -are currently not reading your mail. The intended use is in a +are currently not reading your mail. +The intended use is in a .Pa .forward -file. For example, your +file. +For example, your .Pa .forward file might have: .Bd -literal -offset indent @@ -73,20 +75,23 @@ Handle messages for in the same manner as those received for the user's login name. .It Fl i -Initialize the vacation database files. It should be used -before you modify your +Initialize the vacation database files. +It should be used before you modify your .Pa .forward file. .It Fl r Set the reply interval to .Ar interval -days. The default is one week. An interval of +days. +The default is one week. +An interval of .Dq 0 means that a reply is sent to each message, and an interval of .Dq Li infinite (actually, any non-numeric character) will never send more than -one reply. It should be noted that intervals of +one reply. +It should be noted that intervals of .Dq Li \&0 are quite dangerous, as it allows mailers to get into @@ -129,8 +134,9 @@ in your home directory. expects a file .Pa .vacation.msg , in your home directory, containing a message to be sent back to each -sender. It should be an entire message (including headers). For -example, it might contain: +sender. +It should be an entire message (including headers). +For example, it might contain: .Pp .Bd -literal -offset indent -compact From: eric@CS.Berkeley.EDU (Eric Allman) @@ -138,7 +144,7 @@ Subject: I am on vacation Delivered-By-The-Graces-Of: The Vacation program Precedence: bulk -I am on vacation until July 22. If you have something urgent, +I am on vacation until July 22. If you have something urgent, please contact Keith Bostic \*[Lt]bostic@CS.Berkeley.EDU\*[Gt]. --eric .Ed diff --git a/usr.bin/vgrind/vgrind.1 b/usr.bin/vgrind/vgrind.1 index 5ed82a0022d..588e896503b 100644 --- a/usr.bin/vgrind/vgrind.1 +++ b/usr.bin/vgrind/vgrind.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: vgrind.1,v 1.10 2001/12/08 19:22:17 wiz Exp $ +.\" $NetBSD: vgrind.1,v 1.11 2002/09/30 11:09:16 grant Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -70,7 +70,8 @@ page as it is encountered. .Nm runs in two basic modes, filter mode (see the .Fl f -option) or regular mode. In filter mode +option) or regular mode. +In filter mode .Nm acts as a filter in a manner similar to .Xr tbl 1 . @@ -85,10 +86,11 @@ starts processing ends processing .El .Pp -These lines are formatted as described above. The output from this -filter can be passed to +These lines are formatted as described above. +The output from this filter can be passed to .Xr troff 1 -for output. There need be no particular ordering with +for output. +There need be no particular ordering with .Xr eqn 1 or .Xr tbl 1 . @@ -122,7 +124,8 @@ forces filter mode specifies a particular header to put on every output page (default is the file name) .It Fl l -specifies the language to use. Currently known are +specifies the language to use. +Currently known are .Tn PASCAL .Pq Fl l Ns Ar p , .Tn MODEL @@ -197,7 +200,8 @@ Vfontedpr assumes that a certain programming style is followed: For .Tn C \- function names can be preceded on a line only by spaces, tabs, or an -asterisk. The parenthesized arguments must also be on the same line. +asterisk. +The parenthesized arguments must also be on the same line. .Pp For .Tn PASCAL @@ -217,8 +221,8 @@ name comment mechanisms will fail. More generally, arbitrary formatting styles for programs mostly look bad. The use of spaces to align source code fails miserably; if you plan to .Nm -your program you should use tabs. This is somewhat inevitable since the -font used by +your program you should use tabs. +This is somewhat inevitable since the font used by .Nm is variable width. .Pp diff --git a/usr.bin/vgrind/vgrindefs.5 b/usr.bin/vgrind/vgrindefs.5 index 007c025c103..9b817035438 100644 --- a/usr.bin/vgrind/vgrindefs.5 +++ b/usr.bin/vgrind/vgrindefs.5 @@ -1,4 +1,4 @@ -.\" $NetBSD: vgrindefs.5,v 1.7 2001/12/08 19:23:05 wiz Exp $ +.\" $NetBSD: vgrindefs.5,v 1.8 2002/09/30 11:09:16 grant Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -84,7 +84,8 @@ if ifdef ifndef include undef: .Ed .Pp Note that the first field is just the language name (and any variants -of it). Thus the C language could be specified to +of it). +Thus the C language could be specified to .Xr vgrind 1 as "c" or "C". .Pp @@ -121,7 +122,8 @@ a delimiter (space, tab, newline, start of line) .It \ea matches any string of symbols (like .* in lex) .It \ep -matches any alphanumeric name. In a procedure definition (pb) the string +matches any alphanumeric name. +In a procedure definition (pb) the string that matches this symbol is used as the procedure name. .It () grouping @@ -137,11 +139,13 @@ string delimiter in a string by escaping it. .El .Pp Unlike other regular expressions in the system, these match words -and not characters. Hence something like "(tramp|steamer)flies?" +and not characters. +Hence something like "(tramp|steamer)flies?" would match "tramp", "steamer", "trampflies", or "steamerflies". .Sh KEYWORD LIST The keyword list is just a list of keywords in the language separated -by spaces. If the "oc" boolean is specified, indicating that upper +by spaces. +If the "oc" boolean is specified, indicating that upper and lower case are equivalent, then all the keywords should be specified in lower case. .Sh FILES diff --git a/usr.bin/vis/vis.1 b/usr.bin/vis/vis.1 index e9a0b11ecfd..c8a54f0f268 100644 --- a/usr.bin/vis/vis.1 +++ b/usr.bin/vis/vis.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: vis.1,v 1.8 2000/10/05 17:50:56 wennmach Exp $ +.\" $NetBSD: vis.1,v 1.9 2002/09/30 11:09:16 grant Exp $ .\" .\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. @@ -47,10 +47,12 @@ .Sh DESCRIPTION .Nm is a filter for converting non-printable characters -into a visual representation. It differs from +into a visual representation. +It differs from .Ql cat -v in that -the form is unique and invertible. By default, all non-graphic +the form is unique and invertible. +By default, all non-graphic characters except space, tab, and newline are encoded. A detailed description of the various visual formats is given in @@ -60,9 +62,11 @@ The options are as follows: .Bl -tag -width Ds .It Fl b Turns off prepending of backslash before up-arrow control sequences -and meta characters, and disables the doubling of backslashes. This +and meta characters, and disables the doubling of backslashes. +This produces output which is neither invertible or precise, but does -represent a minimum of change to the input. It is similar to +represent a minimum of change to the input. +It is similar to .Dq Li cat -v . .It Fl c Request a format which displays a small subset of the @@ -94,15 +98,16 @@ still doubled and hidden newline sequences inserted if .Fl f or .Fl F -is selected. When combined with the +is selected. +When combined with the .Fl f flag, .Nm becomes like an invertible version of the .Xr fold 1 -utility. That is, the output -can be unfolded by running the output through +utility. +That is, the output can be unfolded by running the output through .Xr unvis 1 . .It Fl o Request a format which displays non-printable characters as diff --git a/usr.bin/vmstat/vmstat.1 b/usr.bin/vmstat/vmstat.1 index 214cd1b39e5..61b56d1ec38 100644 --- a/usr.bin/vmstat/vmstat.1 +++ b/usr.bin/vmstat/vmstat.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: vmstat.1,v 1.6 2002/02/08 01:36:37 ross Exp $ +.\" $NetBSD: vmstat.1,v 1.7 2002/09/30 11:09:17 grant Exp $ .\" .\" Copyright (c) 2000 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -139,13 +139,15 @@ allocation and then by type of usage. .It Fl s Display the contents of the .Dv uvmexp -structure. This contains various paging event and memory status counters. +structure. +This contains various paging event and memory status counters. .It Fl u Ar histname Dump the specified UVM history. .It Fl U Dump all UVM histories. .It Fl v -Print more verbose information. When used with the +Print more verbose information. +When used with the .Fl i or .Fl e diff --git a/usr.bin/what/what.1 b/usr.bin/what/what.1 index bbdb013a72c..01f371feb2d 100644 --- a/usr.bin/what/what.1 +++ b/usr.bin/what/what.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: what.1,v 1.10 2002/02/08 01:36:37 ross Exp $ +.\" $NetBSD: what.1,v 1.11 2002/09/30 11:09:17 grant Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -50,7 +50,8 @@ utility reads each .Ar file operand and searches for sequences of the form .Dq \&@(#) -as inserted by the source code control system. It prints the remainder +as inserted by the source code control system. +It prints the remainder of the string following this marker, up to a null character, newline, double quote, backslash or .Dq \&\*[Gt] diff --git a/usr.bin/who/who.1 b/usr.bin/who/who.1 index aadd7987687..f1647068c0d 100644 --- a/usr.bin/who/who.1 +++ b/usr.bin/who/who.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: who.1,v 1.10 2001/12/01 16:43:28 wiz Exp $ +.\" $NetBSD: who.1,v 1.11 2002/09/30 11:09:17 grant Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -56,7 +56,8 @@ Available options: .Pp .Bl -tag -width file .It Fl m -Only print information about the current terminal. This is the +Only print information about the current terminal. +This is the .Tn POSIX way of saying .Nm @@ -106,8 +107,9 @@ created. If .Pa /var/log/wtmp is being used as the file, the user name may be empty -or one of the special characters '|', '}' and '~'. Logouts produce -an output line without any user name. For more information on the +or one of the special characters '|', '}' and '~'. +Logouts produce an output line without any user name. +For more information on the special characters, see .Xr utmp 5 . .Sh FILES diff --git a/usr.bin/xargs/xargs.1 b/usr.bin/xargs/xargs.1 index 720c74c6743..db22b122a83 100644 --- a/usr.bin/xargs/xargs.1 +++ b/usr.bin/xargs/xargs.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: xargs.1,v 1.14 2002/01/28 13:49:49 wiz Exp $ +.\" $NetBSD: xargs.1,v 1.15 2002/09/30 11:09:18 grant Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -110,8 +110,8 @@ The current default value for is 5000. .It Fl p Prompt mode: immediately before each command execution the user is prompted -whether to execute the command instance. If an affirmative response is read -from +whether to execute the command instance. +If an affirmative response is read from .Pa /dev/tty the command will be executed; otherwise this particular invocation will be skipped. diff --git a/usr.bin/xinstall/install.1 b/usr.bin/xinstall/install.1 index c7483457c38..e6626fd8878 100644 --- a/usr.bin/xinstall/install.1 +++ b/usr.bin/xinstall/install.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: install.1,v 1.30 2002/03/19 14:17:04 lukem Exp $ +.\" $NetBSD: install.1,v 1.31 2002/09/30 11:09:18 grant Exp $ .\" .\" Copyright (c) 1987, 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -180,7 +180,8 @@ Use .Ar suffix as the backup suffix if .Fl b -is given. If +is given. +If .Ar suffix contains a '%' sign, a numbered backup will be performed, and the %-pattern will be expanded using @@ -219,10 +220,11 @@ The specified mode may be either an octal or symbolic value; see .Xr chmod 1 for a description of possible mode values. .It Fl l Ar linkflags -Instead of copying the file make a link to the source. The type of the -link is determined by the +Instead of copying the file make a link to the source. +The type of the link is determined by the .Ar linkflags -argument. Valid +argument. +Valid .Ar linkflags are: .Ar a @@ -234,7 +236,9 @@ are: .Ar s (symbolic), .Ar m -(mixed). Absolute and relative have effect only for symbolic links. Mixed links +(mixed). +Absolute and relative have effect only for symbolic links. +Mixed links are hard links for files on the same filesystem, symbolic otherwise. .It Fl o Ar owner Specify an owner. @@ -242,14 +246,16 @@ Specify an owner. Preserve the source files access and modification times. .It Fl r Install to a temporary file and then rename the file to its final destination -name. This can be used for precious files, to avoid truncation of the original +name. +This can be used for precious files, to avoid truncation of the original when error conditions (filesystem full etc.) occur. .It Fl s .Nm exec's the command .Xr strip 1 to strip binaries so that install can be portable over a large -number of systems and binary types. If the environment variable +number of systems and binary types. +If the environment variable .Ev STRIP is set, it is used as the .Xr strip 1 @@ -270,11 +276,13 @@ shell, allowing a single .Fl S argument be to specified to .Nm -which the shell can then tokenize. Normally, +which the shell can then tokenize. +Normally, .Nm invokes .Xr strip 1 -directly. This flag implies +directly. +This flag implies .Fl s . .It Fl T Ar tags Specify the @@ -310,7 +318,8 @@ and \*[Gt]0 if an error occurs. .It Ev STRIP The program used to strip installed binaries when the .Fl s -option is used. If unspecified, +option is used. +If unspecified, .Pa /usr/bin/strip is used. .El diff --git a/usr.bin/xstr/xstr.1 b/usr.bin/xstr/xstr.1 index 4abfed50f23..257b94b8916 100644 --- a/usr.bin/xstr/xstr.1 +++ b/usr.bin/xstr/xstr.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: xstr.1,v 1.9 2002/02/08 01:36:38 ross Exp $ +.\" $NetBSD: xstr.1,v 1.10 2002/09/30 11:09:18 grant Exp $ .\" .\" Copyright (c) 1980, 1993 .\" The Regents of the University of California. All rights reserved. @@ -81,7 +81,8 @@ Repeated strings and strings which are suffixes of existing strings do not cause changes to the data base. .It Fl l Ar array Specify the named array in program references to abstracted -strings. The default array name is xstr. +strings. +The default array name is xstr. .El .Pp After all components of a large program have been compiled a file diff --git a/usr.bin/ypwhich/ypwhich.1 b/usr.bin/ypwhich/ypwhich.1 index 9df42a447dc..0d80509bebc 100644 --- a/usr.bin/ypwhich/ypwhich.1 +++ b/usr.bin/ypwhich/ypwhich.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: ypwhich.1,v 1.9 2001/12/08 19:29:20 wiz Exp $ +.\" $NetBSD: ypwhich.1,v 1.10 2002/09/30 11:09:19 grant Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou .\" All rights reserved. @@ -89,7 +89,8 @@ Find the master .Tn YP server for the named map. .Ar mname -can be a map name or nickname. If +can be a map name or nickname. +If .Ar mname is ommitted, .Nm |
