From b5dc137726916848863400739477947b564cfad0 Mon Sep 17 00:00:00 2001 From: "Cynthia A. E. Livingston" Date: Mon, 11 Jun 1990 13:01:23 -0800 Subject: [PATCH] converted man page SCCS-vsn: old/adb/common_source/adb.1 5.7 SCCS-vsn: old/refer/addbib/addbib.1 6.2 SCCS-vsn: usr.bin/apply/apply.1 6.2 SCCS-vsn: usr.bin/apropos/apropos.1 6.8 SCCS-vsn: usr.bin/ar/ar.1 6.2 SCCS-vsn: old/as.vax/as.1 6.4 SCCS-vsn: usr.bin/at/at/at.1 6.3 SCCS-vsn: usr.bin/at/atq/atq.1 6.3 SCCS-vsn: usr.bin/at/atrm/atrm.1 6.3 SCCS-vsn: old/awk/awk.1 6.2 SCCS-vsn: usr.bin/basename/basename.1 6.3 SCCS-vsn: usr.bin/bc/bc.1 6.3 SCCS-vsn: usr.bin/biff/biff.1 6.3 SCCS-vsn: usr.bin/cal/cal.1 6.6 SCCS-vsn: usr.bin/calendar/calendar.1 6.8 SCCS-vsn: bin/cat/cat.1 6.8 SCCS-vsn: old/pcc/cc/cc.1 6.4 SCCS-vsn: share/man/man1/cd.1 6.2 SCCS-vsn: usr.bin/checknr/checknr.1 6.4 SCCS-vsn: usr.sbin/chown/chgrp.1 6.4 SCCS-vsn: bin/chmod/chmod.1 6.7 SCCS-vsn: usr.bin/chpass/chpass.1 5.8 SCCS-vsn: usr.bin/cmp/cmp.1 6.3 SCCS-vsn: usr.bin/col/col.1 6.4 SCCS-vsn: usr.bin/colcrt/colcrt.1 6.4 SCCS-vsn: usr.bin/colrm/colrm.1 6.4 SCCS-vsn: usr.bin/column/column.1 5.5 SCCS-vsn: usr.bin/comm/comm.1 6.3 SCCS-vsn: usr.bin/compress/compress.1 6.7 SCCS-vsn: bin/cp/cp.1 6.9 SCCS-vsn: old/cpio/cpio.1 5.4 SCCS-vsn: bin/csh/csh.1 6.13 SCCS-vsn: usr.bin/ctags/ctags.1 6.6 SCCS-vsn: usr.bin/cut/cut.1 5.2 SCCS-vsn: bin/date/date.1 6.7 SCCS-vsn: old/dbx/dbx.1 6.4 SCCS-vsn: libexec/mail.local/mail.local.8 6.3 SCCS-vsn: bin/ed/ed.1 6.3 SCCS-vsn: usr.bin/find/find.1 6.13 SCCS-vsn: usr.bin/fpr/fpr.1 6.4 SCCS-vsn: usr.bin/ftp/ftp.1 6.14 SCCS-vsn: usr.bin/indent/indent.1 6.7 SCCS-vsn: usr.sbin/lpr/lpr/lpr.1 6.4 SCCS-vsn: usr.sbin/lpr/lprm/lprm.1 6.3 SCCS-vsn: usr.bin/m4/m4.1 6.4 SCCS-vsn: usr.bin/mail/mail.1 6.14 SCCS-vsn: usr.bin/make/make.1 5.2 SCCS-vsn: usr.bin/more/more.1 5.12 SCCS-vsn: usr.bin/tn3270/mset/mset.1 4.3 SCCS-vsn: usr.bin/msgs/msgs.1 6.5 SCCS-vsn: usr.bin/mt/mt.1 6.4 SCCS-vsn: usr.sbin/mtree/mtree.8 5.6 SCCS-vsn: bin/mv/mv.1 6.4 SCCS-vsn: usr.bin/netstat/netstat.1 6.9 SCCS-vsn: usr.bin/nfsstat/nfsstat.1 5.2 SCCS-vsn: usr.bin/nice/nice.1 6.4 SCCS-vsn: usr.bin/nm/nm.1 6.3 SCCS-vsn: usr.bin/nohup/nohup.1 6.4 SCCS-vsn: old/roff/nroff/nroff.1 6.3 SCCS-vsn: usr.bin/pagesize/pagesize.1 6.2 SCCS-vsn: usr.bin/passwd/passwd.1 6.6 SCCS-vsn: usr.bin/paste/paste.1 5.2 SCCS-vsn: usr.bin/pascal/pc/pc.1 6.2 SCCS-vsn: usr.bin/pascal/pdx/pdx.1 6.2 SCCS-vsn: usr.bin/pascal/pi/pi.1 6.2 SCCS-vsn: usr.bin/pascal/pix/pix.1 6.3 SCCS-vsn: usr.bin/plot/plot.1 6.4 SCCS-vsn: usr.bin/pascal/pmerge/pmerge.1 6.2 SCCS-vsn: old/pr/pr.1 6.2 SCCS-vsn: usr.bin/printenv/printenv.1 6.3 SCCS-vsn: usr.bin/printf/printf.1 5.7 SCCS-vsn: bin/ps/ps.1 6.6 SCCS-vsn: usr.bin/ptx/ptx.1 6.2 SCCS-vsn: bin/pwd/pwd.1 6.2 SCCS-vsn: usr.bin/pascal/px/px.1 6.3 SCCS-vsn: usr.bin/pascal/pxp/pxp.1 6.2 SCCS-vsn: usr.bin/pascal/pxref/pxref.1 6.2 SCCS-vsn: usr.bin/quota/quota.1 6.5 SCCS-vsn: old/ratfor/ratfor.1 6.2 SCCS-vsn: bin/rcp/rcp.1 6.9 SCCS-vsn: bin/rcp/rcp.1 6.10 SCCS-vsn: usr.bin/rdist/rdist.1 6.8 SCCS-vsn: bin/rm/rm.1 6.3 SCCS-vsn: bin/rmail/rmail.8 6.4 SCCS-vsn: usr.bin/rwho/rwho.1 6.3 SCCS-vsn: usr.bin/sccs/sccs.1 2.7 SCCS-vsn: old/sh/sh.1 6.4 SCCS-vsn: usr.bin/systat/systat.1 6.7 SCCS-vsn: old/tar/tar.1 6.8 SCCS-vsn: usr.bin/telnet/telnet.1 6.9 SCCS-vsn: usr.bin/tip/tip.1 6.5 SCCS-vsn: usr.bin/tn3270/tn3270/tn3270.1 4.3 SCCS-vsn: usr.bin/tset/tset.1 6.4 SCCS-vsn: usr.bin/window/window.1 6.10 --- usr/src/bin/cat/cat.1 | 106 +- usr/src/bin/chmod/chmod.1 | 299 ++- usr/src/bin/cp/cp.1 | 145 +- usr/src/bin/csh/csh.1 | 2572 ++++++++++++----------- usr/src/bin/date/date.1 | 173 +- usr/src/bin/ed/ed.1 | 1104 ++++++---- usr/src/bin/mv/mv.1 | 105 +- usr/src/bin/ps/ps.1 | 335 +-- usr/src/bin/pwd/pwd.1 | 46 +- usr/src/bin/rcp/rcp.1 | 141 +- usr/src/bin/rm/rm.1 | 120 +- usr/src/bin/rmail/rmail.8 | 55 +- usr/src/libexec/mail.local/mail.local.8 | 2 +- usr/src/old/adb/common_source/adb.1 | 1183 ++++++----- usr/src/old/as.vax/as.1 | 182 +- usr/src/old/awk/awk.1 | 334 +-- usr/src/old/cpio/cpio.1 | 201 +- usr/src/old/dbx/dbx.1 | 1012 +++++---- usr/src/old/pcc/cc/cc.1 | 335 ++- usr/src/old/pr/pr.1 | 231 +- usr/src/old/ratfor/ratfor.1 | 99 +- usr/src/old/refer/addbib/addbib.1 | 222 +- usr/src/old/roff/nroff/nroff.1 | 242 +-- usr/src/old/sh/sh.1 | 1168 +++++----- usr/src/old/tar/tar.1 | 2 +- usr/src/share/man/man1/cd.1 | 116 +- usr/src/usr.bin/apply/apply.1 | 118 +- usr/src/usr.bin/apropos/apropos.1 | 118 +- usr/src/usr.bin/ar/ar.1 | 155 +- usr/src/usr.bin/at/at/at.1 | 276 ++- usr/src/usr.bin/at/atq/atq.1 | 74 +- usr/src/usr.bin/at/atrm/atrm.1 | 99 +- usr/src/usr.bin/basename/basename.1 | 80 +- usr/src/usr.bin/bc/bc.1 | 235 +-- usr/src/usr.bin/biff/biff.1 | 87 +- usr/src/usr.bin/cal/cal.1 | 76 +- usr/src/usr.bin/calendar/calendar.1 | 138 +- usr/src/usr.bin/checknr/checknr.1 | 152 +- usr/src/usr.bin/chpass/chpass.1 | 237 ++- usr/src/usr.bin/cmp/cmp.1 | 150 +- usr/src/usr.bin/col/col.1 | 139 +- usr/src/usr.bin/colcrt/colcrt.1 | 102 +- usr/src/usr.bin/colrm/colrm.1 | 57 +- usr/src/usr.bin/column/column.1 | 93 +- usr/src/usr.bin/comm/comm.1 | 82 +- usr/src/usr.bin/compress/compress.1 | 308 +-- usr/src/usr.bin/ctags/ctags.1 | 250 ++- usr/src/usr.bin/cut/cut.1 | 103 +- usr/src/usr.bin/find/find.1 | 419 ++-- usr/src/usr.bin/fpr/fpr.1 | 2 +- usr/src/usr.bin/ftp/ftp.1 | 1197 ++++++----- usr/src/usr.bin/indent/indent.1 | 665 +++--- usr/src/usr.bin/m4/m4.1 | 458 ++-- usr/src/usr.bin/mail/mail.1 | 1311 +++++++----- usr/src/usr.bin/make/make.1 | 671 +++--- usr/src/usr.bin/more/more.1 | 327 +-- usr/src/usr.bin/msgs/msgs.1 | 220 +- usr/src/usr.bin/mt/mt.1 | 144 +- usr/src/usr.bin/netstat/netstat.1 | 255 +-- usr/src/usr.bin/nfsstat/nfsstat.1 | 90 +- usr/src/usr.bin/nice/nice.1 | 102 +- usr/src/usr.bin/nm/nm.1 | 140 +- usr/src/usr.bin/nohup/nohup.1 | 70 +- usr/src/usr.bin/pagesize/pagesize.1 | 36 +- usr/src/usr.bin/pascal/pc/pc.1 | 309 +-- usr/src/usr.bin/pascal/pdx/pdx.1 | 645 ++++-- usr/src/usr.bin/pascal/pi/pi.1 | 193 +- usr/src/usr.bin/pascal/pix/pix.1 | 89 +- usr/src/usr.bin/pascal/pmerge/pmerge.1 | 60 +- usr/src/usr.bin/pascal/px/px.1 | 111 +- usr/src/usr.bin/pascal/pxp/pxp.1 | 207 +- usr/src/usr.bin/pascal/pxref/pxref.1 | 54 +- usr/src/usr.bin/passwd/passwd.1 | 77 +- usr/src/usr.bin/paste/paste.1 | 102 +- usr/src/usr.bin/plot/plot.1 | 187 +- usr/src/usr.bin/printenv/printenv.1 | 98 +- usr/src/usr.bin/printf/printf.1 | 281 +-- usr/src/usr.bin/ptx/ptx.1 | 141 +- usr/src/usr.bin/quota/quota.1 | 157 +- usr/src/usr.bin/rdist/rdist.1 | 433 ++-- usr/src/usr.bin/rwho/rwho.1 | 68 +- usr/src/usr.bin/sccs/sccs.1 | 583 ++--- usr/src/usr.bin/systat/systat.1 | 389 ++-- usr/src/usr.bin/telnet/telnet.1 | 1065 +++++----- usr/src/usr.bin/tip/tip.1 | 457 ++-- usr/src/usr.bin/tn3270/mset/mset.1 | 167 +- usr/src/usr.bin/tn3270/tn3270/tn3270.1 | 259 ++- usr/src/usr.bin/tset/tset.1 | 609 +++--- usr/src/usr.bin/window/window.1 | 1404 +++++++++---- usr/src/usr.sbin/chown/chgrp.1 | 106 +- usr/src/usr.sbin/lpr/lpr/lpr.1 | 2 +- usr/src/usr.sbin/lpr/lprm/lprm.1 | 2 +- usr/src/usr.sbin/mtree/mtree.8 | 200 +- 93 files changed, 15869 insertions(+), 12352 deletions(-) diff --git a/usr/src/bin/cat/cat.1 b/usr/src/bin/cat/cat.1 index b529c4aa80..86a397309c 100644 --- a/usr/src/bin/cat/cat.1 +++ b/usr/src/bin/cat/cat.1 @@ -1,76 +1,90 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)cat.1 6.7 (Berkeley) %G% +.\" @(#)cat.1 6.8 (Berkeley) %G% .\" -.TH CAT 1 "" -.UC 1 -.SH NAME -cat \- concatenate and print files -.SH SYNOPSIS -\fBcat [ \fI-benstuv\fB ] [ \fI-\fB ] [ \fIfile ...\fB ] -.ft R -.SH DESCRIPTION +.Dd +.Dt CAT 1 +.Os BSD 3 +.Sh NAME +.Nm cat +.Nd concatenate and print files +.Sh SYNOPSIS +.Nm cat +.Op Fl benstuv +.Op Fl +.Ar +.Sh DESCRIPTION The -.I cat +.Nm cat utility reads files sequentially, writing them to the standard output. The -.I file +.Ar file operands are processed in command line order. A single dash represents standard input. -.PP +.Pp The options are as follows: -.TP -.I -b +.Tp Fl b Implies the -.I -n +.Fl n option but doesn't number blank lines. -.TP -.I -e +.Tp Fl e Implies the -.I -v +.Fl v option, and displays a dollar sign (``$'') at the end of each line as well. -.TP -.I -n +.Tp Fl n Number the -.I output +.Ar output lines, starting at 1. -.TP -.I -s +.Tp Fl s Squeeze multiple adjacent empty lines, causing the output to be single spaced. -.TP -.I -t +.Tp Fl t Implies the -.I -v +.Fl v option, and displays tab characters as ``^I'' as well. -.TP -.I -u +.Tp Fl u The -.I \-u -option guarantees that the output is unbuffered. -.TP -.I -v +.Fl u option guarantees that the output is unbuffered. +.Tp Fl v Displays non-printing characters so they are visible. Control characters print line ``^X'' for control-X; the delete character (octal 0177) prints as ``^?''. Non-ascii characters (with the high bit set) are printed as -``M-'' (for meta) followed by the character for the low 7 bits. -.PP -The command ``cat file1 file2 > file3'' concatenates the contents of -file1 and file2 and places the result in file3. -.PP +`.`M-'' (for meta) followed by the character for the low 7 bits. +.Tp +.Pp +.Nm cat +is useful for getting files into a pipe, for instance, to sort +two files together, +the command +.Pp +.Dl cat file1 file2 | sort > sfile +.Pp +reads the contents of +file1 and file2 sequentially, pipes it all to sort and places the +newly sorted data in file3. +.Pp Because of the shell language mechanism used to perform output redirection, the command ``cat file1 file 2 > file1'' will cause -the original data in file1 to be destroyed! -.PP -.I Cat -exits 0 on success, >0 if an error occurred. -.SH "SEE ALSO" -head(1), more(1), pr(1), tail(1) -.br -Rob Pike, ``UNIX Style, or cat -v Considered Harmful'' +.P original data in file1 to be destroyed! +.Pp +.Nm Cat +The cat utility exits 0 on success, and >0 if an error +occurs. +.Sh SEE ALSO +.Xr head 1 , +.Xr more 1 , +.Xr pr 1 , +.Xr tail 1 +.Pp +Rob Pike, +.Em UNIX Style, or cat -v Considered Harmful USENIX Summer Conference Proceedings, 1983. +.Sh HISTORY +The +.Nm +command appeared in Version 7 AT&T UNIX. diff --git a/usr/src/bin/chmod/chmod.1 b/usr/src/bin/chmod/chmod.1 index ccdc6e3f90..d8f7bcbad5 100644 --- a/usr/src/bin/chmod/chmod.1 +++ b/usr/src/bin/chmod/chmod.1 @@ -1,277 +1,228 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)chmod.1 6.6 (Berkeley) %G% +.\" @(#)chmod.1 6.7 (Berkeley) %G% .\" -.TH CHMOD 1 "" -.UC 7 -.SH NAME -chmod - change file modes -.SH SYNOPSIS -.nf -chmod [-fR] mode file ... -.fi -.SH DESCRIPTION +.Dd +.Dt CHMOD 1 +.Os BSD 4.4 +.Sh NAME +.Nm chmod +change file modes +.Sh SYNOPSIS +.Nm chmod +.Op Fl fR +.Ar mode +.Ar file ... +.Sh DESCRIPTION The -.I chmod +.Nm chmod utility modifies the file mode bits of the listed files as specified by the -.I mode +.Ar mode operand. -.PP +.Pp The options are as follows: -.TP --f -If the -f option is given, -.I chmod +.Tp Fl f +.Nm chmod will still exit 0 and not complain if it fails to change the mode on a file. -.TP --R +.Tp Fl R Traverse a file hierarchy. For each file that is of type directory, -.I chmod +.Nm chmod changes the mode of all files in the file hierarchy below it followed by the mode of the directory itself. -.PP +.Tp +.Pp Symbolic links are not indirected through, nor are their modes altered. -.PP +.Pp Only the owner of a file or the super-user is permitted to change the mode of a file. -.PP +.Pp The -.I chmod +.Nm chmod utility exits 0 on success, and >0 if an error occurs. -.SH MODES +.Sh MODES Modes may be absolute or symbolic. An absolute mode is an octal number constructed by -.IR or 'ing +.Cx Ar or +.Cx 'ing +.Cx the following values: -.RS -.TP 10 -4000 +.Dp Li 4000 set-user-ID-on-execution -.br -.ns -.TP -2000 +.Dp Li 2000 set-group-ID-on-execution -.br -.ns -.TP -1000 +.Dp Li 1000 sticky bit, see chmod(2) -.br -.ns -.TP -0400 +.Dp Li 0400 read by owner -.br -.ns -.TP -0200 +.Dp Li 0200 write by owner -.br -.ns -.TP -0100 +.Dp Li 0100 execute (or search for directories) by owner -.br -.ns -.TP -0070 +.Dp Li 0070 read, write, execute/search by group -.br -.ns -.TP -0007 +.Dp Li 0007 read, write, execute/search by others -.RE -.PP +.Dp +.Pp The read, write, and execute/search values for group and others are encoded as described for owner. -.PP +.Pp The symbolic mode is described by the following grammar: -.RS -.TP 10 -mode -::= clause [ , clause ] ... -.br -.ns -.TP -clause -::= [ who ... ] [ action ... ] last_action -.br -.ns -.TP -action -::= op perm ... -.br -.ns -.TP +.Dp Li mode +::= clause +.Op \&, clause +... +.Dp Li clause +::= +.Op who ... +.Op action ... last_action -::= op [ perm ... ] -.br -.ns -.TP -who -::= a | u | g | o -.br -.ns -.TP -op -::= + | - | = -.br -.ns -.TP -perm -::= r | s | t | w | X | x -.RE -.PP +.Dp Li action +::= op perm ... +.Dp Li last_action +::= op +.Op perm ... +.Dp Li who +.Li ::= a | u | g | o +.Dp Li op +.Li ::= + | - | = +.Dp Li perm +.Li ::= r | s | t | w | X | x +.Dp +.Pp The -.I who +.Ar who symbols ``u'', ``g'', and ``o'' specify the user, group, and other parts of the mode bits, respectively. The -.I who +.Ar who symbol ``a'' is equivalent to ``ugo''. -.PP +.Pp The -.I perm +.Ar perm symbols represent the portions of the mode bits as follows: -.RS -.TP 10 -r +.Dw Fl +.Dp r The read bits. -.br -.ns -.TP -s +.Dp s The set-user-ID-on-execution and set-group-ID-on-execution bits. -.br -.ns -.TP -t +.Dp t The sticky bit. -.br -.ns -.TP -w +.Dp w The write bits. -.br -.ns -.TP -x +.Dp x The execute/search bits. -.br -.ns -.TP -X +.Dp X The execute/search bits if the file is a directory or any of the execute/search bits are set in the original (unmodified) mode. Operations with the -.I perm +.Ar perm symbol ``X'' are only meaningful in conjunction with the -.I op +.Ar op symbol ``+'', and it is ignored in all other cases. -.RE -.PP +.Dp +.Pp The -.I op +.Ar op symbols represent the operation performed, as follows: -.TP -+ +.Tw Fl +.Tp \&+ If no value is supplied for -.IR perm , +.Ar perm , the ``+'' operation has no effect. If no value is supplied for -.IR who , +.Ar who , each permission bit specified in -.IR perm , +.Ar perm , for which the corresponding bit in the file mode creation mask is clear, is set. Otherwise, the mode bits represented by the specified -.I who +.Ar who and -.I perm +.Ar perm values are set. -.TP -- +.Tp \&- If no value is supplied for -.IR perm , +.Ar perm , the ``-'' operation has no effect. If no value is supplied for -.IR who , +.Ar who , the mode bits represented by -.I perm +.Ar perm are cleared for the owner, group and other permissions. Otherwise, the mode bits represented by the specified -.I who +.Ar who and -.I perm +.Ar perm values are cleared. -.TP -= +.Tp \&= The mode bits specified by the -.I who +.Ar who value are cleared, or, if no who value is specified, the owner, group and other mode bits are cleared. Then, if no value is supplied for -.IR who , +.Ar who , each permission bit specified in -.IR perm , +.Ar perm , for which the corresponding bit in the file mode creation mask is clear, is set. Otherwise, the mode bits represented by the specified -.I who +.Ar who and -.I perm +.Ar perm values are set. -.PP +.Tp +.Pp Each -.I clause +.Ar clause specifies one or more operations to be performed on the mode bits, and each operation is applied to the mode bits in the order specified. -.PP +.Pp Operations upon the other permissions only (specified by the symbol ``o'' by itself), in combination with the -.I perm +.Ar perm symbols ``s'' or ``t'', are ignored. -.SH EXAMPLES -.TP -``644'' +.Sh EXAMPLES +.Tw Fl +.Tp ``644'' make a file readable by anyone and writable by the owner only. -.TP -``go-w'' +.Tp ``go-w'' deny write permission to group and others. -.TP -``=rw,+X'' +.Tp ``=rw,+X'' set the read and write permissions to the usual defaults, but retain any execute permissions that are currently set. -.TP -``+X'' +.Tp ``+X'' make a directory or file searchable/executable by everyone if it is already searchable/executable by anyone. -.TP -``755'' or ``u=rwx,go=rx'' +.Tp ``755'' or ``u=rwx,go=rx'' make a file readable/executable by everyone and writeable by the owner only. -.TP -``go='' +.Tp ``go='' clear all mode bits for group and others. -.SH BUGS +.Tp +.Sh BUGS There's no -.I perm +.Ar perm option for the naughty bits. -.SH ENVIRONMENT -.SH "SEE ALSO" -install(1), chmod(2), fts(2), stat(2), umask(2), setmode(3), chown(8) -.SH STANDARDS +.Sh ENVIRONMENT +.Sh SEE ALSO +.Xr install 1 , +.Xr chmod 2 , +.Xr fts 2 , +.Xr stat 2 , +.Xr umask 2 , +.Xr setmode 3 , +.Xr chown 8 +.Sh STANDARDS The -.I chmod +.Nm chmod function is expected to be POSIX 1003.2 compatible with the exception of the -.I perm +.Ar perm symbols ``t'' and ``X'' which are not included in that standard. diff --git a/usr/src/bin/cp/cp.1 b/usr/src/bin/cp/cp.1 index 90257e5b55..fa98865eb0 100644 --- a/usr/src/bin/cp/cp.1 +++ b/usr/src/bin/cp/cp.1 @@ -1,89 +1,73 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)cp.1 6.8 (Berkeley) %G% +.\" @(#)cp.1 6.9 (Berkeley) %G% .\" -.TH CP 1 "" -.UC 4 -.SH NAME -cp - copy files -.SH SYNOPSIS -\fBcp [ \fI-fhip\fB ] source_file target_file -.sp -\fBcp [ \fI-fhipr\fB ] source_file ... target_directory -.ft R -.SH DESCRIPTION -The -.I cp -utility copies -.I source_file -to -.I target_file -or, in the second form, one or more -.IR source_file s -are copied into the target -.IR target_directory , -retaining their original filenames. +.Dd +.Dt CP 1 +.Os BSD 4 +.Sh NAME +.Nm cp +.Nd copy files +.Sh SYNOPSIS +.Nm cp +.Op Fl fhip +.Ar source_file target_file +.br +.Nm cp +.Op Fl fhipr +.Ar source_file ... target_directory +.Sh DESCRIPTION +In the first synopsis form, +.Nm cp +utility copies the contents of the +.Ar source_file +to the +.Ar target_file +or, in the second synopsis form, +the contents of each named +.Ar source_file(s) +is copied to the destination +.Ar target_directory . +The names of the files themselves are not changed. If -.I cp +.Nm cp detects an attempt to copy a file to itself, the copy will fail. -.PP -For each destination file that already exists, its contents are -overwritten if permissions allow, but its mode, user ID, and group -ID are unchanged. -.PP -If the destination file does not exist, the mode of the source file is -used as modified by the file mode creation mask (umask). -If the source file has its set user ID bit on, that bit is removed -unless both the source file and the destination file are owned by the -same user. -If the source file has its set group ID bit on, that bit is removed -unless both the source file and the destination file are in the same -group and the user is a member of that group. -If both the set user ID and set group ID bits are set, all of the above -conditions must be fulfilled or both bits are removed. -.PP -Appropriate permissions are required for file creation or overwriting. -.PP The following options are available: -.TP -.I -h +.Tp Fl h Forces -.I cp +.Nm cp to follow symbolic links. Provided for the -.I -r +.Fl r option which does not follow symbolic links by default. -.TP -.I -f +.Tp Fl f Force existing destination pathnames to be truncated before copying, without prompting for confirmation. (The -.I -i +.Fl i option is ignored if the -.I -f +.Fl f option is specified.) -.TP -.I -i +.Tp Fl i Causes -.I cp +.Nm cp to write a prompt to standard error before copying a file that would overwrite an existing file. If the response from the standard input begins with the character ``y'', the file is copied if permissions allow the copy. -.TP -.I -p +.Tp Fl p Causes -.I cp +.Nm cp to preserve in the copy as many of the modification time, access time, .\" and file mode as allowed by permissions. file mode, user ID, and group ID as allowed by permissions. -.IP +.Pp If the user ID and group ID cannot be preserved, no error message is displayed and the exit value is not altered. -.IP +.Pp If the source file has its set user ID bit on and the user ID cannot be preserved, the set user ID bit is not preserved in the copy's permissions. @@ -94,25 +78,48 @@ If the source file has both the set user ID and set group ID bits on and either the user ID or group ID cannot be preserved, neither the set user ID or set group ID bits are preserved in the copy's permissions. -.TP -.I -r +.Tp Fl r If -.I source_file +.Ar source_file designates a directory, -.I cp +.Nm cp copies the directory and the entire subtree connected at that point. This option also causes symbolic links to be copied, rather than indirected through, and for -.I cp +.Nm cp to create special files rather than copying them as normal files. Created directories have the same mode as the corresponding source directory, unmodified by the process' umask. -.PP +.Tp +.Pp +For each destination file that already exists, its contents are +overwritten if permissions allow, but its mode, user ID, and group +ID are unchanged. +.Pp +If the destination file does not exist, the mode of the source file is +used as modified by the file mode creation mask (umask). +If the source file has its set user ID bit on, that bit is removed +unless both the source file and the destination file are owned by the +same user. +If the source file has its set group ID bit on, that bit is removed +unless both the source file and the destination file are in the same +group and the user is a member of that group. +If both the set user ID and set group ID bits are set, all of the above +conditions must be fulfilled or both bits are removed. +.Pp +Appropriate permissions are required for file creation or overwriting. +.Pp Symbolic links are followed unless the -.I -r +.Fl r option is specified, in which case the link itself is copied. -.PP -.I Cp +.Pp +.Nm Cp exits 0 on success, >0 if an error occurred. -.SH "SEE ALSO" -mv(1), rcp(1), umask(2) +.Sh SEE ALSO +.Xr mv 1 , +.Xr rcp 1 , +.Xr umask 2 +.Sh HISTORY +The +.Nm cp +command appeared in Version 6 AT&T UNIX. diff --git a/usr/src/bin/csh/csh.1 b/usr/src/bin/csh/csh.1 index 4d380c666e..260f8b7467 100644 --- a/usr/src/bin/csh/csh.1 +++ b/usr/src/bin/csh/csh.1 @@ -1,90 +1,163 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)csh.1 6.12 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH CSH 1 "" -.UC 4 -.de sh -.br -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.if n .ds ua ^ -.if t .ds ua \(ua -.if n .ds aa ' -.if t .ds aa \(aa -.if n .ds ga ` -.if t .ds ga \(ga -.if t .tr *\(** -.SH NAME -csh \- a shell (command interpreter) with C-like syntax -.SH SYNOPSIS -.B csh -[ -.B \-cef\^instvVxX -] [ -arg ... -] -.SH DESCRIPTION -.I Csh -is a first implementation of a command language interpreter -incorporating a history mechanism (see \fBHistory Substitutions\fP), -job control facilities (see \fBJobs\fP), interactive file name -and user name completion (see \fBFile Name Completion\fP), -and a C-like syntax. -So as to be able to use its job control facilities, users of -.I csh -must (and automatically) use the new tty driver fully described in -.IR tty (4). -This new tty driver allows generation of interrupt characters -from the keyboard to tell jobs to stop. See -.IR stty (1) -for details on setting options in the new tty driver. -.PP -An instance of -.I csh -begins by executing commands from the file ``/etc/csh.cshrc'' and, -if this is a login shell, ``/etc/csh.login''. It then executes -commands from ``.cshrc''' in the -.I home +.\" @(#)csh.1 6.13 (Berkeley) %G% +.\" +.Dd +.Dt CSH 1 +.Os BSD 4 +.Sh NAME +.Nm csh +.Nd a shell (command interpreter) with C-like syntax +.Sh SYNOPSIS +.Nm csh +.Op Fl cef\*(uainstvVxX +.Op arg ... +.Sh DESCRIPTION +The +.Nm Csh +is a command language interpreter +incorporating a history mechanism (see +.Nm History Substitutions ) , +job control facilities (see +.Nm Jobs ) , +interactive file name +and user name completion (see +.Nm File Name Completion ) , +and a C-like syntax. It is used both as an interactive +login shell and a shell script command processor. +.Ss Argument list processing +If the first argument (argument 0) to the shell is +.Fl +then this +is a login shell. +The flag arguments are interpreted as follows: +.Tw 5n +.Tp Fl b +This flag forces a ``break'' from option processing, causing any further +shell arguments to be treated as non-option arguments. +The remaining arguments will not be interpreted as shell options. +This may be used to pass options to a shell script without confusion +or possible subterfuge. +The shell will not run a set-user ID script without this option. +.Tp Fl c +Commands are read from the (single) following argument which must +be present. +Any remaining arguments are placed in +.Ar argv . +.Tp Fl e +The shell exits if any invoked command terminates abnormally +or yields a non-zero exit status. +.Tp Fl f +The shell will start faster, because it will neither search for nor +execute commands from the file +.Pa \&.cshrc +in the invoker's home directory. +.Tp Fl i +The shell is interactive and prompts for its top-level input, +even if it appears to not be a terminal. +Shells are interactive without this option if their inputs +and outputs are terminals. +.Tp Fl n +Commands are parsed, but not executed. +This aids in syntactic checking of shell scripts. +.Tp Fl s +Command input is taken from the standard input. +.Tp Fl t +A single line of input is read and executed. +A `\e' may be used to escape the newline at the end of this +line and continue onto another line. +.Tp Fl v +Causes the +.Ar verbose +variable to be set, with the effect +that command input is echoed after history substitution. +.Tp Fl x +Causes the +.Ar echo +variable to be set, so that commands are echoed immediately before execution. +.Tp Fl V +Causes the +.Ar verbose +variable to be set even before `\&.cshrc' is executed. +.Tp Fl X +Is to +.Fl x +as +.Fl V +is to +.Fl v . +.Tp +.Pp +After processing of flag arguments, if arguments remain but none of the +.Fl c , +.Fl i , +.Fl s , +or +.Fl t +options was given, the first argument is taken as the name of a file of +commands to be executed. +The shell opens this file, and saves its name for possible resubstitution +by `$0'. +Since many systems use either the standard version 6 or version 7 shells +whose shell scripts are not compatible with this shell, the shell will +execute such a `standard' shell if the first character of a script +is not a `#', i.e. if the script does not start with a comment. +Remaining arguments initialize the variable +.Ar argv . +.Pp +.\" An instance of +.Nm csh +begins by executing commands from the file +.Pa /etc/csh.cshrc +and, +if this is a login shell, +.Pa \&/etc/csh.login . +It then executes +commands from +.Pa \&.cshrc +in the +.Ar home directory of the invoker, and, if this is a login shell, the file -``.login'' in the same location. -It is typical for users on crt's to put the command ``stty crt'' in their -.I \&.login +.Pa \&.login +in the same location. +It is typical for users on crt's to put the command ``stty crt'' +in their +.Pa \&.login file, and to also invoke -.IR tset (1) +.Xr tset 1 there. -.PP +.Pp In the normal case, the shell will then begin reading commands from the terminal, prompting with `% '. Processing of arguments and the use of the shell to process files containing command scripts will be described later. -.PP +.Pp The shell then repeatedly performs the following actions: a line of command input is read and broken into -.IR words . +.Ar words . This sequence of words is placed on the command history list and then parsed. Finally each command in the current line is executed. -.PP +.Pp When a login shell terminates it executes commands from the files -``.logout'' in the user's -.I home -directory and ``/etc/csh.logout''. -.sh "Lexical structure" +.Pa .logout +in the user's +.Ar home +directory and +.Pa /etc/csh.logout . +.Ss Lexical structure The shell splits input lines into words at blanks and tabs with the following exceptions. The characters -`&' `|' `;' `<' `>' `(' `)' +`&' `' `;' `<' `>' `(' `)' form separate words. -If doubled in `&&', `|\|\||', `<<' or `>>' these pairs form single words. +If doubled in `&&', `\\', `<<' or `>>' these pairs form single words. These parser metacharacters may be made part of other words, or prevented their special meaning, by preceding them with `\e'. A newline preceded by a `\e' is equivalent to a blank. -.PP +.Pp In addition strings enclosed in matched pairs of quotations, `\*(aa', `\*(ga' or `"', form parts of a word; metacharacters in these strings, including blanks @@ -92,66 +165,80 @@ and tabs, do not form separate words. These quotations have semantics to be described subsequently. Within pairs of `\'' or `"' characters a newline preceded by a `\e' gives a true newline character. -.PP +.Pp When the shell's input is not a terminal, the character `#' introduces a comment which continues to the end of the input line. It is prevented this special meaning when preceded by `\e' and in quotations using `\`', `\'', and `"'. -.sh "Commands" +.Ss Commands A simple command is a sequence of words, the first of which specifies the command to be executed. A simple command or -a sequence of simple commands separated by `|' characters +a sequence of simple commands separated by `' characters forms a pipeline. The output of each command in a pipeline is connected to the input of the next. Sequences of pipelines may be separated by `;', and are then executed sequentially. -A sequence of pipelines may be executed without immediately +A sequence of pipelines may be executed without immediately waiting for it to terminate by following it with an `&'. -.PP +.Pp Any of the above may be placed in `(' `)' to form a simple command (which may be a component of a pipeline, etc.) -It is also possible to separate pipelines with `|\|\||' or `&&' indicating, +It is also possible to separate pipelines with `\\' or `&&' indicating, as in the C language, that the second is to be executed only if the first fails or succeeds respectively. (See -.I Expressions.) -.sh "Jobs" -The shell associates a \fIjob\fR with each pipeline. It keeps +.Ar Expressions . ) +.Ss Jobs +The shell associates a +.Ar job +with each pipeline. It keeps a table of current jobs, printed by the -\fIjobs\fR command, and assigns them small integer numbers. When +.Ar jobs +command, and assigns them small integer numbers. When a job is started asynchronously with `&', the shell prints a line which looks like: -.PP -.DT - [1] 1234 -.PP +.Pp +.Df I +.Op 1 +1234 +.De +.Pp indicating that the job which was started asynchronously was job number 1 and had one (top-level) process, whose process id was 1234. -.PP +.Pp If you are running a job and wish to do something else you may hit the key -\fB^Z\fR (control-Z) which sends a STOP signal to the current job. +.Nm ^Z +(control-Z) which sends a STOP signal to the current job. The shell will then normally indicate that the job has been `Stopped', and print another prompt. You can then manipulate the state of this job, -putting it in the background with the \fIbg\fR command, or run some other +putting it in the background with the +.Ar bg +command, or run some other commands and then eventually bring the job back into the foreground with -the foreground command \fIfg\fR. A \fB^Z\fR takes effect immediately and +the foreground command +.Ar fg . +A +.Nm ^Z +takes effect immediately and is like an interrupt in that pending output and unread input are discarded -when it is typed. There is another special key \fB^Y\fR which does +when it is typed. There is another special key +.Nm ^Y +which does not generate a STOP signal until a program attempts to -.IR read (2) +.Xr read 2 it. This can usefully be typed ahead when you have prepared some commands for a job which you wish to stop after it has read them. -.PP +.Pp A job being run in the background will stop if it tries to read from the terminal. Background jobs are normally allowed to produce output, but this can be disabled by giving the command ``stty tostop''. If you set this tty option, then background jobs will stop when they try to produce output like they do when they try to read input. -.PP +.Pp There are several ways to refer to jobs in the shell. The character `%' introduces a job name. If you wish to refer to job number 1, you can name it as `%1'. Just naming a job brings it to the foreground; thus @@ -160,137 +247,167 @@ Similarly saying `%1 &' resumes job 1 in the background. Jobs can also be named by prefixes of the string typed in to start them, if these prefixes are unambiguous, thus `%ex' would normally restart a suspended -.IR ex (1) +.Xr ex 1 job, if there were only one suspended job whose name began with the string `ex'. It is also possible to say `%?string' which specifies a job whose text contains -.I string, +.Ar string , if there is only one such job. -.PP +.Pp The shell maintains a notion of the current and previous jobs. In output pertaining to jobs, the current job is marked with a `+' and the previous job with a `\-'. The abbreviation `%+' refers to the current job and `%\-' refers to the previous job. For close analogy with the syntax of the -.I history +.Ar history mechanism (described below), `%%' is also a synonym for the current job. -.sh "Status reporting" +.Pp +The job control mechanism requires that the +.Xr stty 1 +option +.Ic new +be set. It is an artifact from a +.Em new +implementation +of the +tty driver which allows generation of interrupt characters from +the keyboard to tell jobs to stop. See stty(1) for details +on setting options in the new tty driver. +.Ss Status reporting This shell learns immediately whenever a process changes state. It normally informs you whenever a job becomes blocked so that no further progress is possible, but only just before it prints a prompt. This is done so that it does not otherwise disturb your work. If, however, you set the shell variable -.I notify, +.Ar notify , the shell will notify you immediately of changes of status in background jobs. There is also a shell command -.I notify +.Ar notify which marks a single process so that its status changes will be immediately -reported. By default -.I notify +reported. By default +.Ar notify marks the current process; simply say `notify' after starting a background job to mark it. -.PP +.Pp When you try to leave the shell while jobs are stopped, you will -be warned that `You have stopped jobs.' You may use the \fIjobs\fR +be warned that `You have stopped jobs.' You may use the +.Ar jobs command to see what they are. If you do this or immediately try to exit again, the shell will not warn you a second time, and the suspended jobs will be terminated. -.sh "File Name Completion" +.Ss File Name Completion When the file name completion feature is enabled by setting -the shell variable \fIfilec\fP (see \fBset\fP), \fIcsh\fP will +the shell variable +.Ar filec +(see +.Ic set ) , +.Nm csh +will interactively complete file names and user names from unique prefixes, when they are input from the terminal followed by -the escape character (the escape key, or control-[). For example, +the escape character (the escape key, or control-[) +For example, if the current directory looks like -.ta 1i 2i 3i 4i 5i 6i -.nf - DSC.OLD bin cmd lib xmpl.c - DSC.NEW chaosnet cmtest mail xmpl.o - bench class dev mbox xmpl.out -.fi +.Ds I +.Cw DSC.NEW chaosnet cmtest mbox +.Cl DSC.OLD bin cmd lib xmpl.c +.Cl DSC.NEW chaosnet cmtest mail xmpl.o +.Cl bench class dev mbox xmpl.out +.Cw +.De +.Pp and the input is -.br - % vi ch -.br -\fIcsh\fP will complete the prefix ``ch'' +.Pp +.Dl \&% vi ch +.Pp +.Nm csh +will complete the prefix ``ch'' to the only matching file name ``chaosnet'', changing the input line to -.br - % vi chaosnet -.br +.Pp +.Dl \&% vi chaosnet +.Pp However, given -.br - % vi D -.br -\fIcsh\fP will only expand the input to -.br - % vi DSC. -.br +.Pp +.Dl % vi D +.Pp +.Nm csh +will only expand the input to +.Pp +.Dl \&% vi DSC. +.Pp and will sound the terminal bell to indicate that the expansion is incomplete, since there are two file names matching the prefix ``D''. -.PP +.Pp If a partial file name is followed by the end-of-file character -(usually control-D), then, instead of completing the name, \fIcsh\fP +(usually control-D), then, instead of completing the name, +.Nm csh will list all file names matching the prefix. For example, the input -.br - % vi D -.br +.Pp +.Dl \&% vi D +.Pp causes all files beginning with ``D'' to be listed: -.br - DSC.NEW DSC.OLD -.br +.Pp +.Dl \&DSC.NEW DSC.OLD +.Pp while the input line remains unchanged. -.PP +.Pp The same system of escape and end-of-file can also be used to expand partial user names, if the word to be completed (or listed) begins with the character ``~''. For example, typing -.br - cd ~ro -.br +.Pp +.Dl \&cd ~ro +.Pp may produce the expansion -.br - cd ~root -.PP +.Pp +.Dl \&cd ~root +.Pp The use of the terminal bell to signal errors or multiple matches -can be inhibited by setting the variable \fInobeep\fP. -.PP +can be inhibited by setting the variable +.Ar nobeep . +.Pp Normally, all files in the particular directory are candidates for name completion. Files with certain suffixes can be excluded -from consideration by setting the variable \fIfignore\fP to the -list of suffixes to be ignored. Thus, if \fIfignore\fP is set by +from consideration by setting the variable +.Ar fignore +to the +list of suffixes to be ignored. Thus, if +.Ar fignore +is set by the command -.br - % set fignore = (.o .out) -.br +.Pp +.Dl \&% set fignore = (.o .out) +.Pp then typing -.br - % vi x -.br +.Pp +.Dl \&% vi x +.Pp would result in the completion to -.br - % vi xmpl.c -.br +.Pp +.Dl \&% vi xmpl.c +.Pp ignoring the files "xmpl.o" and "xmpl.out". However, if the only completion possible requires not ignoring these -suffixes, then they are not ignored. In addition, \fIfignore\fP +suffixes, then they are not ignored. In addition, +.Ar fignore does not affect the listing of file names by control-D. All files are listed regardless of their suffixes. -.sh Substitutions +.Ss Substitutions We now describe the various transformations the shell performs on the input in the order in which they occur. -.sh "History substitutions" +.Ss History substitutions History substitutions place words from previous command input as portions of new commands, making it easy to repeat commands, repeat arguments of a previous command in the current command, or fix spelling mistakes in the previous command with little typing and a high degree of confidence. History substitutions begin with the character `!' and may begin -.B anywhere +.Ar anywhere in the input stream (with the proviso that they -.B "do not" +.Nm "do not" nest.) This `!' may be preceded by an `\e' to prevent its special meaning; for convenience, a `!' is passed unchanged when it is followed by a blank, @@ -299,36 +416,33 @@ tab, newline, `=' or `('. This special abbreviation will be described later.) Any input line which contains history substitution is echoed on the terminal before it is executed as it could have been typed without history substitution. -.PP +.Pp Commands input from the terminal which consist of one or more words are saved on the history list. The history substitutions reintroduce sequences of words from these saved commands into the input stream. The size of which is controlled by the -.I history +.Ar history variable; the previous command is always retained, regardless of its value. Commands are numbered sequentially from 1. -.PP +.Pp For definiteness, consider the following output from the -.I history +.Ar history command: -.PP +.Pp .DT -.br - \09 write michael -.br - 10 ex write.c -.br - 11 cat oldwrite.c -.br - 12 diff *write.c -.PP +.Pp +.Dl \&\09 write michael +.Dl 10 ex write.c +.Dl 11 cat oldwrite.c +.Dl 12 diff *write.c +.Pp The commands are shown with their event numbers. It is not usually necessary to use event numbers, but the current event number can be made part of the -.I prompt +.Ar prompt by placing an `!' in the prompt string. -.PP +.Pp With the current event 13 we can refer to previous events by event number `!11', relatively as in `!\-2' (referring to the same event), by a prefix of a command word @@ -338,114 +452,151 @@ These forms, without further modification, simply reintroduce the words of the specified events, each separated by a single blank. As a special case `!!' refers to the previous command; thus `!!' alone is essentially a -.I redo. -.PP +.Ar redo . +.Pp To select words from an event we can follow the event specification by a `:' and a designator for the desired words. The words of an input line are numbered from 0, the first (usually command) word being 0, the second word (first argument) being 1, etc. The basic word designators are: -.PP -.DT -.nf - 0 first (command) word - \fIn\fR \fIn\fR\|'th argument - \*(ua first argument, i.e. `1' - $ last argument - % word matched by (immediately preceding) ?\fIs\fR\|? search - \fIx\fR\|\-\fIy\fR range of words - \-\fIy\fR abbreviates `0\-\fIy\fR\|' - * abbreviates `\*(ua\-$', or nothing if only 1 word in event - \fIx\fR\|* abbreviates `\fIx\fR\|\-$' - \fIx\fR\|\- like `\fIx\fR\|*' but omitting word `$' -.fi -.PP +.Pp +.Dw Ds +.Dp \&0 +first (command) word +.Dp Ar n +.Cx Ar n +.Cx \'th +.Cx +argument +.Dp \*(ua +first argument, i.e. `1' +.Dp $ +last argument +.Dp % +word matched by (immediately preceding) +.Cx \&? +.Ar s +.Cx \? +.Cx +search +.Dp Ar \&x\-y +range of words +.Dp Ar \&\-y +abbreviates +.Ar `\&0\-y\' +.Dp \&* +abbreviates `\*(ua\-$', or nothing if only 1 word in event +.Dp Ar x\* +abbreviates +.Ar `x\-$\' +.Dp Ar x\- +like +.Ar `x\*\' +but omitting word `$' +.Dp +.Pp The `:' separating the event specification from the word designator can be omitted if the argument selector begins with a `\*(ua', `$', `*' `\-' or `%'. After the optional word designator can be placed a sequence of modifiers, each preceded by a `:'. The following modifiers are defined: -.ta .5i 1.2i -.PP -.nf - h Remove a trailing pathname component, leaving the head. - r Remove a trailing `.xxx' component, leaving the root name. - e Remove all but the extension `.xxx' part. - s/\fIl\fR\|/\fIr\fR\|/ Substitute \fIl\fR for \fIr\fR - t Remove all leading pathname components, leaving the tail. - & Repeat the previous substitution. - g Apply the change globally, prefixing the above, e.g. `g&'. - p Print the new command line but do not execute it. - q Quote the substituted words, preventing further substitutions. - x Like q, but break into words at blanks, tabs and newlines. -.fi -.PP +.Dw Ds +.Dp h +Remove a trailing pathname component, leaving the head. +.Dp r +Remove a trailing `.xxx' component, leaving the root name. +.Dp e +Remove all but the extension `.xxx' part. +.Cx s/ +.Ar l +.Cx \/ +.Ar r +.Cx \/ +.Cx +Substitute +.Ar l +for +.Ar r +.Dp t +Remove all leading pathname components, leaving the tail. +.Dp \&& +Repeat the previous substitution. +.Dp g +Apply the change globally, prefixing the above, e.g. `g&'. +.Dp p +Print the new command line but do not execute it. +.Dp q +Quote the substituted words, preventing further substitutions. +.Dp x +Like q, but break into words at blanks, tabs and newlines. +.Dp +.Pp Unless preceded by a `g' the modification is applied only to the first modifiable word. With substitutions, it is an error for no word to be applicable. -.PP +.Pp The left hand side of substitutions are not regular expressions in the sense of the editors, but rather strings. Any character may be used as the delimiter in place of `/'; a `\e' quotes the delimiter into the -.IR l "" +.Ar l " " and -.IR r "" +.Ar r " " strings. The character `&' in the right hand side is replaced by the text from the left. A `\e' quotes `&' also. A null -.IR l "" +.Ar l " " uses the previous string either from a -.IR l "" +.Ar l " " or from a contextual scan string -.IR s "" -in `!?\fIs\fR\|?'. +.Ar s " " +in `!? +.Ar s +\?'. The trailing delimiter in the substitution may be omitted if a newline follows immediately as may the trailing `?' in a contextual scan. -.PP +.Pp A history reference may be given without an event specification, e.g. `!$'. In this case the reference is to the previous command unless a previous history reference occurred on the same line in which case this form repeats the previous reference. Thus `!?foo?\*(ua !$' gives the first and last arguments from the command matching `?foo?'. -.PP +.Pp A special abbreviation of a history reference occurs when the first non-blank character of an input line is a `\*(ua'. This is equivalent to `!:s\*(ua' providing a convenient shorthand for substitutions on the text of the previous line. -Thus `\*(ualb\*(ualib' fixes the spelling of +Thus `\*(ualb\*(ualib' fixes the spelling of `lib' in the previous command. Finally, a history substitution may be surrounded with `{' and `}' if necessary to insulate it from the characters which follow. Thus, after `ls \-ld ~paul' we might do `!{l}a' to do `ls \-ld ~paula', while `!la' would look for a command starting `la'. -.PP -.if n .ul -\fBQuotations\ with\ \'\ and\ "\fR -.PP +.Pp +.Ss Quotations with \' and \*(Lq The quotation of strings by `\'' and `"' can be used to prevent all or some of the remaining substitutions. Strings enclosed in `\'' are prevented any further interpretation. Strings enclosed in `"' may be expanded as described below. -.PP +.Pp In both cases the resulting text becomes (all or part of) a single word; only in one special case (see -.I "Command Substitition" +.Nm "Command Substitition" below) does a `"' quoted string yield parts of more than one word; `\'' quoted strings never do. -.sh "Alias substitution" +.Ss Alias substitution The shell maintains a list of aliases which can be established, displayed and modified by the -.I alias +.Ar alias and -.I unalias +.Ar unalias commands. After a command line is scanned, it is parsed into distinct commands and the first word of each command, left-to-right, is checked to see if it @@ -457,74 +608,74 @@ The resulting words replace the command and argument list. If no reference is made to the history list, then the argument list is left unchanged. -.PP +.Pp Thus if the alias for `ls' is `ls \-l' the command `ls /usr' would map to `ls \-l /usr', the argument list here being undisturbed. Similarly if the alias for `lookup' was `grep !\*(ua /etc/passwd' then `lookup bill' would map to `grep bill /etc/passwd'. -.PP +.Pp If an alias is found, the word transformation of the input text is performed and the aliasing process begins again on the reformed input line. Looping is prevented if the first word of the new text is the same as the old by flagging it to prevent further aliasing. Other loops are detected and cause an error. -.PP +.Pp Note that the mechanism allows aliases to introduce parser metasyntax. -Thus we can `alias print \'pr \e!* \||\| lpr\'' to make a command which -.I pr's +Thus we can `alias print \'pr \e!* \\ lpr\'' to make a command which +.Ar pr 's its arguments to the line printer. -.sh "Variable substitution" +.Ss Variable substitution The shell maintains a set of variables, each of which has as value a list of zero or more words. Some of these variables are set by the shell or referred to by it. For instance, the -.I argv +.Ar argv variable is an image of the shell's argument list, and words of this variable's value are referred to in special ways. -.PP +.Pp The values of variables may be displayed and changed by using the -.I set +.Ar set and -.I unset +.Ar unset commands. Of the variables referred to by the shell a number are toggles; the shell does not care what their value is, only whether they are set or not. For instance, the -.I verbose +.Ar verbose variable is a toggle which causes command input to be echoed. The setting of this variable results from the -.B \-v +.Fl v command line option. -.PP +.Pp Other operations treat variables numerically. The `@' command permits numeric calculations to be performed and the result assigned to a variable. Variable values are, however, always represented as (zero or more) strings. For the purposes of numeric operations, the null string is considered to be zero, and the second and subsequent words of multiword values are ignored. -.PP +.Pp After the input line is aliased and parsed, and before each command is executed, variable substitution is performed keyed by `$' characters. This expansion can be prevented by preceding the `$' with a `\e' except within `"'s where it -.B always +.Ar always occurs, and within `\''s where it -.B never +.Ar never occurs. Strings quoted by `\*(ga' are interpreted later (see -.I "Command substitution" +.Nm "Command substitution" below) so `$' substitution does not occur there until later, if at all. A `$' is passed unchanged if followed by a blank, tab, or end-of-line. -.PP +.Pp Input/output redirections are recognized before variable expansion, and are variable expanded separately. Otherwise, the command name and entire argument list are expanded together. It is thus possible for the first (command) word to this point to generate more than one word, the first of which becomes the command name, and the rest of which become arguments. -.PP +.Pp Unless enclosed in `"' or given the `:q' modifier the results of variable substitution may eventually be command and filename substituted. Within `"', a variable whose value consists of multiple words expands to a @@ -533,40 +684,38 @@ separated by blanks. When the `:q' modifier is applied to a substitution the variable will expand to multiple words with each word separated by a blank and quoted to prevent later command or filename substitution. -.PP +.Pp The following metasequences are provided for introducing variable values into the shell input. Except as noted, it is an error to reference a variable which is not set. -.HP 5 -$name -.br -.ns -.HP 5 -${name} -.br +.Dw Ds +.Dp $name +.Dp ${name} Are replaced by the words of the value of variable -.I name, +.Ar name , each separated by a blank. Braces insulate -.I name +.Ar name from following characters which would otherwise be part of it. Shell variables have names consisting of up to 20 letters and digits starting with a letter. The underscore character is considered a letter. .br If -.I name +.Ar name is not a shell variable, but is set in the environment, then -that value is returned (but \fB:\fR modifiers and the other forms +that value is returned (but +.Nm : +modifiers and the other forms given below are not available in this case). -.HP 5 -$name[selector] -.br -.ns -.HP 5 -${name[selector]} -.br +.Dp Cx $name +.Op selector +.Cx +.Dp Cx ${name +.Op selector +.Cx } +.Cx May be used to select only some of the words from the value of -.I name. +.Ar name . The selector is subjected to `$' substitution and may consist of a single number or two numbers separated by a `\-'. The first word of a variables value is numbered `1'. @@ -575,63 +724,50 @@ If the last member of a range is omitted it defaults to `$#name'. The selector `*' selects all words. It is not an error for a range to be empty if the second argument is omitted or in range. -.HP 5 -$#name -.br -.ns -.HP 5 -${#name} -.br +.Dp $#name +.Dp ${#name} Gives the number of words in the variable. -This is useful for later use in a `[selector]'. -.HP 5 -$0 -.br +This is useful for later use in a +.Cx `$argv +.Op selector +.Cx \' . +.Cx +.Dp $0 Substitutes the name of the file from which command input is being read. An error occurs if the name is not known. -.HP 5 -$number -.br -.ns -.HP 5 -${number} -.br -Equivalent to `$argv[number]'. -.HP 5 -$* -.br -Equivalent to `$argv[*]'. -.PP +.Dp $number +.Dp ${number} +Equivalent to +.Cx `$argv +.Op number +.Cx \' . +.Cx +Equivalent to +.Cx `$argv +.Op * +.Cx \' . +.Cx +.Pp The modifiers `:e', `:h', `:t', `:r', `:q' and `:x' may be applied to the substitutions above as may `:gh', `:gt' and `:gr'. If braces `{' '}' appear in the command form then the modifiers must appear within the braces. -.B "The current implementation allows only one `:' modifier on each `$' expansion." -.PP +The current implementation allows only one `:' modifier on each `$' expansion. +.Pp The following substitutions may not be modified with `:' modifiers. -.HP 5 -$?name -.br -.ns -.HP 5 -${?name} -.br +.Dp $?name +.Dp ${?name} Substitutes the string `1' if name is set, `0' if it is not. -.HP 5 -$?0 -.br +.Dp $?0 Substitutes `1' if the current input filename is known, `0' if it is not. -.HP 5 -$$ -.br +.Dp $$ Substitute the (decimal) process number of the (parent) shell. -.HP 5 -$< -.br +.Dp $< Substitutes a line from the standard input, with no further interpretation thereafter. It can be used to read from the keyboard in a shell script. -.sh "Command and filename substitution" +.Dp +.Ss Command and filename substitution The remaining substitutions, command and filename substitution, are applied selectively to the arguments of builtin commands. This means that portions of expressions which are not evaluated are @@ -641,18 +777,19 @@ name is substituted separately from the argument list. This occurs very late, after input-output redirection is performed, and in a child of the main shell. -.sh "Command substitution" +.Ss Command substitution Command substitution is indicated by a command enclosed in `\*(ga'. The output from such a command is normally broken into separate words at blanks, tabs and newlines, with null words being discarded, this text then replacing the original string. Within `"'s, only newlines force new words; blanks and tabs are preserved. -.PP +.Pp In any case, the single final newline does not force a new word. Note that it is thus possible for a command substitution to yield only part of a word, even if the command outputs a complete line. -.sh "Filename substitution" -If a word contains any of the characters `*', `?', `[' or `{' +.Ss Filename substitution +If a word contains any of the characters `*', `?', ` +.Op ' or `{' or begins with the character `~', then that word is a candidate for filename substitution, also known as `globbing'. This word is then regarded as a pattern, and replaced with an alphabetically @@ -660,25 +797,30 @@ sorted list of file names which match the pattern. In a list of words specifying filename substitution it is an error for no pattern to match an existing file name, but it is not required for each pattern to match. -Only the metacharacters `*', `?' and `[' imply pattern matching, +Only the metacharacters `*', `?' and ` +.Op ' imply pattern matching, the characters `~' and `{' being more akin to abbreviations. -.PP +.Pp In matching filenames, the character `.' at the beginning of a filename or immediately following a `/', as well as the character `/' must be matched explicitly. The character `*' matches any string of characters, including the null string. The character `?' matches any single character. -The sequence `[...]' matches any one of the characters enclosed. -Within `[...]', +The sequence ` +.Op ... +' matches any one of the characters enclosed. +Within ` +.Op ... +', a pair of characters separated by `\-' matches any character lexically between the two. -.PP +.Pp The character `~' at the beginning of a filename is used to refer to home directories. Standing alone, i.e. `~' it expands to the invokers home directory as reflected in the value of the variable -.I home. +.Ar home . When followed by a name consisting of letters, digits and `\-' characters the shell searches for a user with that name and substitutes their home directory; thus `~ken' might expand to `/usr/ken' and `~ken/chmach' @@ -686,7 +828,7 @@ to `/usr/ken/chmach'. If the character `~' is followed by a character other than a letter or `/' or appears not at the beginning of a word, it is left undisturbed. -.PP +.Pp The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'. Left to right order is preserved, with results of matches being sorted separately at a low level to preserve this order. @@ -698,90 +840,66 @@ if the home directory for `source' is `/usr/source'. Similarly `../{memo,*box}' might expand to `../memo ../box ../mbox'. (Note that `memo' was not sorted with the results of matching `*box'.) As a special case `{', `}' and `{}' are passed undisturbed. -.sh Input/output +.Ss Input/output The standard input and standard output of a command may be redirected with the following syntax: -.HP 5 -< name -.br +.Dw Ds +.Dp < name Open file -.I name +.Ar name (which is first variable, command and filename expanded) as the standard input. -.HP 5 -<< word -.br +.Dp << word Read the shell input up to a line which is identical to -.I word. -.I Word +.Ar word . +.Ar Word is not subjected to variable, filename or command substitution, and each input line is compared to -.I word +.Ar word before any substitutions are done on this input line. Unless a quoting `\e', `"', `\*(aa' or `\*(ga' appears in -.I word +.Ar word variable and command substitution is performed on the intervening lines, allowing `\e' to quote `$', `\e' and `\*(ga'. Commands which are substituted have all blanks, tabs, and newlines preserved, except for the final newline which is dropped. The resultant text is placed in an anonymous temporary file which is given to the command as standard input. -.HP 5 -> name -.br -.ns -.HP 5 ->! name -.br -.ns -.HP 5 ->& name -.br -.ns -.HP 5 ->&! name -.br +.Dp > name +.Dp >! name +.Dp >& name +.Dp >&! name The file -.I name +.Ar name is used as standard output. If the file does not exist then it is created; if the file exists, its is truncated, its previous contents being lost. -.IP +.Pp If the variable -.I noclobber +.Ar noclobber is set, then the file must not exist or be a character special file (e.g. a terminal or `/dev/null') or an error results. This helps prevent accidental destruction of files. In this case the `!' forms can be used and suppress this check. -.IP +.Pp The forms involving `&' route the diagnostic output into the specified file as well as the standard output. -.I Name +.Ar Name is expanded in the same way as `<' input filenames are. -.HP 5 ->> name -.br -.ns -.HP 5 ->>& name -.br -.ns -.HP 5 ->>! name -.br -.ns -.HP 5 ->>&! name -.br +.Dp >> name +.Dp >>& name +.Dp >>! name +.Dp >>&! name Uses file -.I name +.Ar name as standard output like `>' but places output at the end of the file. If the variable -.I noclobber +.Ar noclobber is set, then it is an error for the file not to exist unless one of the `!' forms is given. Otherwise similar to `>'. -.PP +.Dp +.Pp A command receives the environment in which the shell was invoked as modified by the input-output parameters and the presence of the command in a pipeline. @@ -792,32 +910,36 @@ The `<<' mechanism should be used to present inline data. This permits shell command scripts to function as components of pipelines and allows the shell to block read its input. Note that the default standard input for a command run detached is -.B not -modified to be the empty file `/dev/null'; rather the standard input +.Ar not +modified to be the empty file +.Pa /dev/null ; +rather the standard input remains as the original standard input of the shell. If this is a terminal and if the process attempts to read from the terminal, then the process will block and the user will be notified (see -.B Jobs +.Ar Jobs above). -.PP +.Pp Diagnostic output may be directed through a pipe with the standard output. -Simply use the form `|\|&' rather than just `|'. -.sh Expressions +Simply use the form `\&' rather than just `'. +.Ss Expressions A number of the builtin commands (to be described subsequently) take expressions, in which the operators are similar to those of C, with the same precedence. These expressions appear in the -.I @, -.I exit, -.I if, +.Nm @, +.Ar exit , +.Ar if , and -.I while +.Ar while commands. The following operators are available: -.DT -.PP - |\|\|| && | \*(ua & == != =~ !~ <= >= < > << >> + \- * / % ! ~ ( ) -.PP +.Pp +.Ds I +\\ && \*(ua & == != =~ !~ <= >= < > +<< >> + \- * / % ! ~ ( ) +.De +.Pp Here the precedence increases to the right, `==' `!=' `=~' and `!~', `<=' `>=' `<' and `>', `<<' and `>>', `+' and `\-', `*' `/' and `%' being, in groups, at the same level. @@ -825,40 +947,46 @@ The `==' `!=' `=~' and `!~' operators compare their arguments as strings; all others operate on numbers. The operators `=~' and `!~' are like `!=' and `==' except that the right hand side is a -.I pattern -(containing, e.g. `*'s, `?'s and instances of `[...]') +.Ar pattern +(containing, e.g. `*'s, `?'s and instances of +.Cx ` +.Op ... +.Cx \' ) +.Cx against which the left hand operand is matched. This reduces the need for use of the -.I switch +.Ar switch statement in shell scripts when all that is really needed is pattern matching. -.PP +.Pp Strings which begin with `0' are considered octal numbers. Null or missing arguments are considered `0'. The result of all expressions are strings, which represent decimal numbers. It is important to note that no two components of an expression can appear in the same word; except when adjacent to components of expressions which -are syntactically significant to the parser (`&' `|' `<' `>' `(' `)') +are syntactically significant to the parser (`&' `' `<' `>' `(' `)') they should be surrounded by spaces. -.PP +.Pp Also available in expressions as primitive operands are command executions enclosed in `{' and `}' -and file enquiries of the form `\-\fIl\fR name' where -.I l +and file enquiries of the form +.Fl l +.Ar name +where +.Ic l is one of: -.PP -.DT -.nf - r read access - w write access - x execute access - e existence - o ownership - z zero size - f plain file - d directory -.fi -.PP +.Pp +.Ds I +r read access +w write access +x execute access +e existence +o ownership +z zero size +f plain file +d directory +.De +.Pp The specified name is command and filename expanded and then tested to see if it has the specified relationship to the real user. If the file does not exist or is inaccessible then all enquiries return @@ -868,514 +996,495 @@ if the command exits with status 0, otherwise they fail, returning false, i.e. `0'. If more detailed status information is required then the command should be executed outside of an expression and the variable -.I status +.Ar status examined. -.sh "Control flow" +.Ss Control flow The shell contains a number of commands which can be used to regulate the flow of control in command files (shell scripts) and (in limited but useful ways) from terminal input. These commands all operate by forcing the shell to reread or skip in its input and, due to the implementation, restrict the placement of some of the commands. -.PP +.Pp The -.I foreach, -.I switch, +.Ic foreach , +.Ic switch , and -.I while +.Ic while statements, as well as the -.I if\-then\-else +.Ic if\-then\-else form of the -.I if +.Ic if statement require that the major keywords appear in a single simple command on an input line as shown below. -.PP +.Pp If the shell's input is not seekable, the shell buffers up input whenever a loop is being read and performs seeks in this internal buffer to accomplish the rereading implied by the loop. (To the extent that this allows, backward goto's will succeed on non-seekable inputs.) -.sh "Builtin commands" +.Ss Builtin commands Builtin commands are executed within the shell. If a builtin command occurs as any component of a pipeline except the last then it is executed in a subshell. -.HP 5 -.B alias -.br -.ns -.HP 5 -.BR alias " name" -.br -.ns -.HP 5 -.BR alias " name wordlist" -.br +.Dw Ds +.Ds L +.Dp Ic alias +.Dp Cx Ic alias +.Cx \&\ \& +.Cx Ar name +.Cx +.Dp Cx Ic alias +.Cx \&\ \& +.Ar name wordlist +.Cx The first form prints all aliases. The second form prints the alias for name. The final form assigns the specified -.I wordlist -as the alias of -.I name; -.I wordlist +.Ar wordlist +as the alias of +.Ar name ; +.Ar wordlist is command and filename substituted. -.I Name +.Ar Name is not allowed to be -.I alias +.Ar alias or -.I unalias. -.HP 5 -.B alloc -.br +.Ar unalias . +.Dp Ic alloc Shows the amount of dynamic memory acquired, broken down into used and free memory. With an argument shows the number of free and used blocks in each size category. The categories start at size 8 and double at each step. This command's output may vary across system types, since systems other than the VAX may use a different memory allocator. -.HP 5 -.B bg -.br -.ns -.HP 5 -\fBbg\ %\fRjob\ ... -.br +.Dp Ic bg +.Dp Cx Ic bg \&% +.Ar job ... +.Cx Puts the current or specified jobs into the background, continuing them if they were stopped. -.HP 5 -.B break -.br +.Dp Ic break Causes execution to resume after the -.I end +.Ic end of the nearest enclosing -.I foreach +.Ic foreach or -.I while. +.Ic while . The remaining commands on the current line are executed. Multi-level breaks are thus possible by writing them all on one line. -.HP 5 -.B breaksw -.br +.Dp Ic breaksw Causes a break from a -.I switch, +.Ic switch , resuming after the -.I endsw. -.HP 5 -.BR case " label:" -.br +.Ic endsw . +.Dp Cx Ic case +.Cx \&\ \& +.Ar label : +.Cx A label in a -.I switch +.Ic switch statement as discussed below. -.HP 5 -.B cd -.br -.ns -.HP 5 -.BR cd " name" -.br -.ns -.HP 5 -.B chdir -.br -.ns -.HP 5 -.BR chdir " name" -.br +.Dp Ic cd +.Dp Cx Ic cd +.Cx \&\ \& +.Ar name +.Cx +.Dp Ic chdir +.Dp Cx Ic chdir +.Cx \&\ \& +.Ar name +.Cx Change the shell's working directory to directory -.I name. +.Ar name . If no argument is given then change to the home directory of the user. -.br If -.I name +.Ar name is not found as a subdirectory of the current directory (and does not begin with `/', `./' or `../'), then each component of the variable -.I cdpath +.Ic cdpath is checked to see if it has a subdirectory -.I name. +.Ar name . Finally, if all else fails but -.I name +.Ar name is a shell variable whose value begins with `/', then this is tried to see if it is a directory. -.HP 5 -.B continue -.br +.Dp Ic continue Continue execution of the nearest enclosing -.I while +.Ic while or -.I foreach. +.Ic foreach . The rest of the commands on the current line are executed. -.HP 5 -.B default: -.br +.Dp Ic default : Labels the default case in a -.I switch +.Ic switch statement. The default should come after all -.I case +.Ic case labels. -.HP 5 -.BR "dirs" -.br +.Dp Ic dirs Prints the directory stack; the top of the stack is at the left, the first directory in the stack being the current directory. -.HP 5 -.BR echo " wordlist" -.br -.ns -.HP 5 -.BR "echo \-n" " wordlist" -.br +.Dp Cx Ic echo +.Cx \&\ \& +.Ar wordlist +.Cx +.Dp Cx Ic echo +.Cx \&\ \& +.Fl n +.Cx \&\ \& +.Ar wordlist +.Cx The specified words are written to the shells standard output, separated by spaces, and terminated with a newline unless the -.B \-n +.Fl n option is specified. -.HP 5 -.B else -.br -.ns -.HP 5 -.B end -.br -.ns -.HP 5 -.B endif -.br -.ns -.HP 5 -.B endsw -.br +.Dp Ic else +.Dp Ic end +.Dp Ic endif +.Dp Ic endsw See the description of the -.I foreach, -.I if, -.I switch, +.Ic foreach , +.Ic if , +.Ic switch , and -.I while +.Ic while statements below. -.HP 5 -.BR eval " arg ..." -.br +.Dp Cx Ic eval +.Cx \&\ \& +.Ar arg ... +.Cx (As in -.IR sh (1).) +.Xr sh 1 . ) The arguments are read as input to the shell and the resulting command(s) executed in the context of the current shell. This is usually used to execute commands generated as the result of command or variable substitution, since parsing occurs before these substitutions. See -.IR tset (1) +.Xr tset 1 for an example of using -.IR eval . -.HP 5 -.BR exec " command" -.br +.Ic eval . +.Dp Cx Ic exec +.Cx \&\ \& +.Ar command +.Cx The specified command is executed in place of the current shell. -.HP 5 -.B exit -.br -.ns -.HP 5 -.BR exit (expr) -.br +.Dp Ic exit +.Dp Cx Ic exit +.Cx \&\ \& +.Ar (expr ) +.Cx The shell exits either with the value of the -.I status +.Ic status variable (first form) or with the value of the specified -.I expr +.Ic expr (second form). -.HP 5 -.B fg -.br -.ns -.HP 5 -\fBfg\ %\fRjob\ ... -.br +.Dp Ic fg +.Dp Cx Ic fg \&% +.Ar job ... +.Cx Brings the current or specified jobs into the foreground, continuing them if they were stopped. -.HP 5 -.BR foreach " name (wordlist)" -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -.B end -.br +.Dp Cx Ic foreach +.Cx \&\ \& +.Ar name (wordlist) +.Cx +.Dp ... +.Dp Ic end The variable -.I name +.Ic name is successively set to each member of -.I wordlist +.Ic wordlist and the sequence of commands between this command and the matching -.I end +.Ic end are executed. (Both -.I foreach +.Ic foreach and -.I end +.Ic end must appear alone on separate lines.) -.IP The builtin command -.I continue +.Ic continue may be used to continue the loop prematurely and the builtin command -.I break +.Ic break to terminate it prematurely. When this command is read from the terminal, the loop is read up once prompting with `?' before any statements in the loop are executed. If you make a mistake typing in a loop at the terminal you can rub it out. -.HP 5 -.BR glob " wordlist" -.br +.Dp Cx Ic glob +.Cx \&\ \& +.Ar wordlist +.Cx Like -.I echo +.Ic echo but no `\e' escapes are recognized and words are delimited by null characters in the output. Useful for programs which wish to use the shell to filename expand a list of words. -.HP 5 -.BR goto " word" -.br +.Dp Cx Ic goto +.Cx \&\ \& +.Ar word +.Cx The specified -.I word +.Ic word is filename and command expanded to yield a string of the form `label'. The shell rewinds its input as much as possible and searches for a line of the form `label:' possibly preceded by blanks or tabs. Execution continues after the specified line. -.HP 5 -.BR hashstat -.br +.Dp Ic hashstat Print a statistics line indicating how effective the internal hash table has been at locating commands (and avoiding -.IR exec 's). +.Cx Ic exec +.Cx 's ) . +.Cx An -.I exec +.Ic exec is attempted for each component of the -.I path +.Em path where the hash function indicates a possible hit, and in each component which does not begin with a `/'. -.HP 5 -.B history -.br -.ns -.HP 5 -.BI history " n" -.br -.ns -.HP 5 -.BI "history \-r" " n" -.br -.ns -.HP 5 -.BI "history \-h" " n" -.br -Displays the history event list; if \fIn\fR is given only the -.I n +.Dp Ic history +.Dp Cx Ic history +.Cx \&\ \& +.Ar n +.Cx +.Dp Cx Ic history +.Cx \&\ \& +.Fl r +.Cx \&\ \& +.Ar n +.Cx +.Dp Cx Ic history +.Cx \&\ \& +.Fl h +.Cx \&\ \& +.Ar n +.Cx +Displays the history event list; if +.Ar n +is given only the +.Ar n most recent events are printed. The -.B \-r +.Fl r option reverses the order of printout to be most recent first rather than oldest first. The -.B \-h +.Fl h option causes the history list to be printed without leading numbers. This is used to produce files suitable for sourceing using the \-h option to -.IR source . -.HP 5 -.BR if " (expr) command" -.br +.Ic source . +.Dp Cx Ic if +.Cx \&\ \& +.Cx \&( +.Ar expr +.Cx \&) +.Cx +.Ar command If the specified expression evaluates true, then the single -.I command +.Ar command with arguments is executed. Variable substitution on -.IR command "" +.Ar command happens early, at the same time it does for the rest of the -.I if -command. -.I Command +.Ic if +.Ar command . +.Ar Command must be a simple command, not a pipeline, a command list, or a parenthesized command list. Input/output redirection occurs even if -.I expr +.Ar expr is false, when command is -.B not +.Sy not executed (this is a bug). -.HP 5 -.BR if " (expr) " "then" -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -.BR else " " "if\fR (expr2) \fBthen" -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -.B else -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -.B endif -.br +.Dp Cx Ic if +.Cx \&\ \& +.Cx \&( +.Ar expr +.Cx \&) +.Cx \&\ \& +.Ar then +.Cx +.Dp ... +.Dp Cx Ic else if +.Cx \&\ \& +.Cx \&( +.Ar expr2 +.Cx \&) +.Cx \&\ \& +.Ic then +.Cx +.Dp ... +.Dp Ic else +.Dp ... +.Dp Ic endif If the specified -.IR expr "" +.Ar expr is true then the commands to the first -.I else +.Ic else are executed; otherwise if -.IR expr2 "" +.Ar expr2 is true then the commands to the -second \fIelse\fR are executed, etc. +second +.Ic else +are executed, etc. Any number of -.I else-if +.Ic else-if pairs are possible; only one -.I endif +.Ic endif is needed. The -.I else +.Ic else part is likewise optional. (The words -.I else +.Ic else and -.I endif +.Ic endif must appear at the beginning of input lines; the -.I if +.Ic if must appear alone on its input line or after an -.I else.) -.HP 5 -.B jobs -.br -.ns -.HP 5 -.B "jobs \-l" -.br +.Ic else . ) +.Dp Ic jobs +.Dp Cx Ic jobs +.Cx \&\ \& +.Fl l +.Cx Lists the active jobs; given the -.B \-l +.Fl l options lists process id's in addition to the normal information. -.HP 5 -\fBkill %\fRjob -.br -.ns -.HP 5 -\fBkill\ \-\fRsig\ \fB%\fRjob\ ... -.br -.ns -.HP 5 -\fBkill\fR\ pid -.br -.ns -.HP 5 -\fBkill\ \-\fRsig\ pid\ ... -.br -.ns -.HP 5 -\fBkill\ \-l\fR -.br +.Dp Cx Ic kill % +.Ar job +.Cx +.Dp Cx Ic kill +.Cx \&\ \& +.Ar pid +.Cx +.Dp Cx Ic kill +.Cx \&\ \& +.Fl sig +.Ar pid ... +.Cx +.Dp Cx Ic kill +.Cx \&\ \& +.Fl l +.Cx Sends either the TERM (terminate) signal or the specified signal to the specified jobs or processes. Signals are either given by number or by names (as given in -.I /usr/include/signal.h, +.Pa /usr/include/signal.h, stripped of the prefix ``SIG''). The signal names are listed by ``kill \-l''. There is no default, saying just `kill' does not send a signal to the current job. If the signal being sent is TERM (terminate) or HUP (hangup), then the job or process will be sent a CONT (continue) signal as well. -.HP -\fBlimit\fR -.br -.ns -.HP 5 -\fBlimit\fR \fIresource\fR -.br -.ns -.HP 5 -\fBlimit\fR \fIresource\fR \fImaximum-use\fR -.br -.ns -.HP 5 -\fBlimit\ \-h\fR -.br -.ns -.HP 5 -\fBlimit\ \-h\fR \fIresource\fR -.br -.ns -.HP 5 -\fBlimit\ \-h\fR \fIresource\fR \fImaximum-use\fR -.br +.Dp Ic limit +.Dp Cx Ic limit +.Cx \&\ \& +.Ar resource +.Cx +.Dp Cx Ic limit +.Cx \&\ \& +.Ar resource maximum-use +.Cx +.Dp Cx Ic limit +.Cx \&\ \& +.Fl h +.Cx +.Dp Cx Ic limit +.Cx \&\ \& +.Fl h +.Cx \&\ \& +.Ar resource +.Cx +.Dp Cx Ic limit +.Cx \&\ \& +.Fl h +.Cx \&\ \& +.Ar resource maximum-use +.Cx Limits the consumption by the current process and each process -it creates to not individually exceed \fImaximum-use\fR on the -specified \fIresource\fR. If no \fImaximum-use\fR is given, then -the current limit is printed; if no \fIresource\fR is given, then -all limitations are given. If the \fB\-h\fR +it creates to not individually exceed +.Ar maximum-use +on the +specified +.Ar resource . +If no +.Ar maximum-use +is given, then +the current limit is printed; if no +.Ar resource +is given, then +all limitations are given. If the +.Fl h flag is given, the hard limits are used instead of the current limits. The hard limits impose a ceiling on the values of the current limits. Only the super-user may raise the hard limits, but a user may lower or raise the current limits within the legal range. -.IP -Resources controllable currently include \fIcputime\fR (the maximum -number of cpu-seconds to be used by each process), \fIfilesize\fR -(the largest single file which can be created), \fIdatasize\fR +.Pp +Resources controllable currently include +.Ar cputime +(the maximum +number of cpu-seconds to be used by each process), +.Ar filesize +(the largest single file which can be created), +.Ar datasize (the maximum growth of the data+stack region via -.IR sbrk (2) -beyond the end of the program text), \fIstacksize\fR (the maximum -size of the automatically-extended stack region), and \fIcoredumpsize\fR +.Xr sbrk 2 +beyond the end of the program text), +.Ar stacksize +(the maximum +size of the automatically-extended stack region), and +.Ar coredumpsize (the size of the largest core dump that will be created). -.IP -The \fImaximum-use\fR may be given as a (floating point or integer) -number followed by a scale factor. For all limits other than \fIcputime\fR +.Pp +The +.Ar maximum-use +may be given as a (floating point or integer) +number followed by a scale factor. For all limits other than +.Ar cputime the default scale is `k' or `kilobytes' (1024 bytes); a scale factor of `m' or `megabytes' may also be used. For -.I cputime +.Ar cputime the default scaling is `seconds', while `m' for minutes or `h' for hours, or a time of the form `mm:ss' giving minutes and seconds may be used. -.IP -For both \fIresource\fR names and scale factors, unambiguous prefixes +.Pp +For both +.Ar resource +names and scale factors, unambiguous prefixes of the names suffice. -.HP 5 -.B login -.br +.Dp Ic login Terminate a login shell, replacing it with an instance of -.B /bin/login. +.Pa /bin/login. This is one way to log off, included for compatibility with -.IR sh (1). -.HP 5 -.B logout -.br +.Xr sh 1 . +.Dp Ic logout Terminate a login shell. Especially useful if -.I ignoreeof +.Ic ignoreeof is set. -.HP 5 -.B nice -.br -.ns -.HP 5 -.BR nice " +number" -.br -.ns -.HP 5 -.BR nice " command" -.br -.ns -.HP 5 -.BR nice " +number command" -.br +.Dp Ic nice +.Dp Cx Ic nice +.Cx \&\ \& +.Ar +number +.Cx +.Dp Cx Ic nice +.Cx \&\ \& +.Ar command +.Cx +.Dp Cx Ic nice +.Cx \&\ \& +.Ar +number command +.Cx The first form sets the scheduling priority for this shell to 4. @@ -1383,50 +1492,46 @@ The second form sets the priority to the given number. The final two forms run command at priority 4 and -.I number +.Ar number respectively. The greater the number, the less cpu the process will get. The super-user may specify negative priority by using `nice \-number ...'. Command is always executed in a sub-shell, and the restrictions placed on commands in simple -.I if +.Ic if statements apply. -.HP 5 -.B nohup -.br -.ns -.HP 5 -.BR "nohup" " command" -.br +.Dp Ic nohup +.Dp Cx Ic nohup +.Cx \&\ \& +.Ar command +.Cx The first form can be used in shell scripts to cause hangups to be ignored for the remainder of the script. The second form causes the specified command to be run with hangups ignored. All processes detached with `&' are effectively -.I nohup'ed. -.HP 5 -.B notify -.br -.ns -.HP 5 -\fBnotify\ %\fRjob\ ... -.br +.Cx Ic nohup +.Cx \'ed . +.Cx +.Dp Ic notify +.Dp Cx Ic notify % +.Cx \&\ \& +.Ar job ... +.Cx Causes the shell to notify the user asynchronously when the status of the current or specified jobs changes; normally notification is presented before a prompt. This is automatic if the shell variable -.I notify +.Ic notify is set. -.HP 5 -.B onintr -.br -.ns -.HP 5 -.BR onintr " \-" -.br -.ns -.HP 5 -.BR onintr " label" -.br +.Dp Ic onintr +.Dp Cx Ic onintr +.Cx \&\ \& +.Fl +.Cx +.Dp Cx Ic onintr +.Cx \&\ \& +.Ar label +.Cx Control the action of the shell on interrupts. The first form restores the default action of the shell on interrupts which is to terminate shell scripts or to return to the terminal command @@ -1435,823 +1540,704 @@ The second form `onintr \-' causes all interrupts to be ignored. The final form causes the shell to execute a `goto label' when an interrupt is received or a child process terminates because it was interrupted. -.IP +.Pp In any case, if the shell is running detached and interrupts are being ignored, all forms of -.I onintr +.Ic onintr have no meaning and interrupts continue to be ignored by the shell and all invoked commands. -.HP 5 -.BR "popd" -.br -.ns -.HP 5 -.BR "popd" " +n" -.br +.Dp Ic popd +.Dp Cx Ic popd +.Cx \&\ \& +.Ar +n +.Cx Pops the directory stack, returning to the new top directory. -With an argument `+\fIn\fR' discards the \fIn\fR\|th +With an argument +.Cx `+ +.Ar n +.Cx \' +.Cx +discards the +.Cx Ar n +.Cx \' +.Cx th +.Cx entry in the stack. The elements of the directory stack are numbered from 0 starting at the top. -.HP 5 -.BR "pushd" -.br -.ns -.HP 5 -.BR "pushd" " name" -.br -.ns -.HP 5 -.BR "pushd" " +n" -.br +.Dp Ic pushd +.Dp Cx Ic pushd +.Cx \&\ \& +.Ar name +.Cx +.Dp Cx Ic pushd +.Cx \&\ \& +.Ar n +.Cx With no arguments, -.I pushd +.Ic pushd exchanges the top two elements of the directory stack. Given a -.I name +.Ar name argument, -.I pushd +.Ic pushd changes to the new directory (ala -.I cd) +.Ic cd ) and pushes the old current working directory (as in -.I csw) +.Ic csw ) onto the directory stack. -With a numeric argument, rotates the \fIn\fR\|th argument of the directory +With a numeric argument, rotates the +.Cx Ar n +.Cx \' +.Cx th +.Cx +argument of the directory stack around to be the top element and changes to it. The members of the directory stack are numbered from the top starting at 0. -.HP 5 -.BR rehash -.br +.Dp Ic rehash Causes the internal hash table of the contents of the directories in the -.I path +.Ic path variable to be recomputed. This is needed if new commands are added to directories in the -.I path +.Ic path while you are logged in. This should only be necessary if you add commands to one of your own directories, or if a systems programmer changes the contents of one of the system directories. -.HP 5 -.BR repeat " count command" -.br -The specified -.I command +.Dp Cx Ic repeat +.Cx \&\ \& +.Ar count command +.Cx +The specified +.Ar command which is subject to the same restrictions as the -.I command +.Ar command in the one line -.I if +.Ic if statement above, is executed -.I count +.Ar count times. I/O redirections occur exactly once, even if -.I count +.Ar count is 0. -.HP 5 -.B set -.br -.ns -.HP 5 -.BR set " name" -.br -.ns -.HP 5 -.BR set " name=word" -.br -.ns -.HP 5 -.BR set " name[index]=word" -.br -.ns -.HP 5 -.BR set " name=(wordlist)" -.br +.Dp Ic set +.Dp Cx Ic set +.Cx \&\ \& +.Ar name +.Cx +.Dp Cx Ic set +.Cx \&\ \& +.Ar name=word +.Cx +.Dp Cx Ic set +.Cx \&\ \& +.Ar name +.Op index +.Ar =word +.Cx +.Dp Cx Ic set +.Cx \&\ \& +.Ar name=(wordlist) +.Cx The first form of the command shows the value of all shell variables. Variables which have other than a single word as value print as a parenthesized word list. The second form sets -.I name +.Ic name to the null string. The third form sets -.I name +.Ic name to the single -.I word. +.Ic word . The fourth form sets the -.I index'th +.Cx Ar index +.Cx \'th +.Cx component of name to word; this component must already exist. The final form sets -.I name +.Ar name to the list of words in -.I wordlist. +.Ar wordlist . In all cases the value is command and filename expanded. -.IP +.Pp These arguments may be repeated to set multiple values in a single set command. Note however, that variable expansion happens for all arguments before any setting occurs. -.HP 5 -.BR setenv -.br -.ns -.HP 5 -.BR setenv " name value" -.br -.ns -.HP 5 -.BR setenv " name" -.br +.Dp Ic setenv +.Dp Cx Ic setenv +.Cx \&\ \& +.Ar name value +.Cx +.Dp Cx Ic setenv +.Cx \&\ \& +.Ar name +.Cx The first form lists all current environment variables. The last form sets the value of environment variable -.I name +.Ar name to be -.I value, +.Ar value , a single string. The second form sets -.I name +.Ar name to an empty string. The most commonly used environment variable USER, TERM, and PATH are automatically imported to and exported from the -.I csh +.Nm csh variables -.I user, -.I term, +.Ar user , +.Op Ar term , and -.I path; +.Ar path ; there is no need to use -.I setenv +.Ic setenv for these. -.HP 5 -.B shift -.br -.ns -.HP 5 -.BR shift " variable" -.br +.Dp Ic shift +.Dp Cx Ic shift +.Cx \&\ \& +.Ar variable +.Cx The members of -.I argv +.Ic argv are shifted to the left, discarding -.I argv[1]. +.Cx Ic argv +.Op 1 . +.Cx It is an error for -.I argv +.Ic argv not to be set or to have less than one word as value. The second form performs the same function on the specified variable. -.HP 5 -.BR source " name" -.br -.ns -.HP 5 -.BR "source \-h" " name" -.br +.Dp Cx Ic source +.Cx \&\ \& +.Ar name +.Cx +.Dp Cx Ic source +.Cx \&\ \& +.Fl h +.Cx \&\ \& +.Ar name +.Cx The shell reads commands from -.I name. -.I Source +.Ic name . +.Ic Source commands may be nested; if they are nested too deeply the shell may run out of file descriptors. An error in a -.I source +.Ic source at any level terminates all nested -.I source +.Ic source commands. -Normally input during -.I source +Normally input during +.Ic source commands is not placed on the history list; the \-h option causes the commands to be placed in the history list without being executed. -.HP 5 -.B stop -.br -.ns -.HP 5 -\fBstop\ %\fRjob\ ... -.br +.Dp Ic stop +.Dp Cx Ic stop % +.Ar job ... +.Cx Stops the current or specified job which is executing in the background. -.HP 5 -.B suspend -.br -.ns +.Dp Ic suspend Causes the shell to stop in its tracks, much as if it had been sent a stop -signal with \fB^Z\fR. This is most often used to stop shells started by -.IR su (1). -.HP 5 -.BR switch " (string)" -.br -.ns -.HP 5 -.BR case " str1:" -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -\ -.B breaksw -.br -.ns -.HP 5 -\&... -.br -.ns -.HP 5 -.B default: -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -\ -.B breaksw -.br -.ns -.HP 5 -.B endsw -.br +signal with +.Ic ^Z . +This is most often used to stop shells started by +.Xr su 1 . +.Dp Cx Ic switch +.Cx \&\ \& +.Ar (string) +.Cx +.Dp Cx Ic case +.Cx \&\ \& +.Ar str1 : +.Cx +.Dp \&... +.Dp Ic breaksw +.Dp \&... +.Dp Ic default : +.Dp \&... +.Dp Ic breaksw +.Dp Ic endsw Each case label is successively matched, against the specified -.I string +.Ar string which is first command and filename expanded. -The file metacharacters `*', `?' and `[...]' may be used in the case labels, +The file metacharacters `*', `?' and +.Cx \&\ \& +.Op \&... +.Cx \' +.Cx +may be used in the case labels, which are variable expanded. If none of the labels match before a `default' label is found, then the execution begins after the default label. Each case label and the default label must appear at the beginning of a line. -The command -.I breaksw +The command +.Ic breaksw causes execution to continue after the -.I endsw. +.Ic endsw . Otherwise control may fall through case labels and default labels as in C. If no label matches and there is no default, execution continues after the -.I endsw. -.HP 5 -.B time -.br -.ns -.HP 5 -.BR time " command" -.br +.Ic endsw . +.Dp Ic time +.Dp Cx Ic time +.Cx \&\ \& +.Ar command +.Cx With no argument, a summary of time used by this shell and its children is printed. If arguments are given the specified simple command is timed and a time summary as described under the -.I time +.Ic time variable is printed. If necessary, an extra shell is created to print the time statistic when the command completes. -.HP 5 -.B umask -.br -.ns -.HP 5 -.BR umask " value" -.br +.Dp Ic umask +.Dp Cx Ic umask +.Cx \&\ \& +.Ar value +.Cx The file creation mask is displayed (first form) or set to the specified value (second form). The mask is given in octal. Common values for the mask are 002 giving all access to the group and read and execute access to others or 022 giving all access except no write access for users in the group or others. -.HP 5 -.BR unalias " pattern" -.br +.Dp Cx Ic unalias +.Cx \&\ \& +.Ar pattern +.Cx All aliases whose names match the specified pattern are discarded. Thus all aliases are removed by `unalias *'. It is not an error for nothing to be -.I unaliased. -.HP 5 -.BR unhash -.br +.Ic unaliased . +.Dp Ic unhash Use of the internal hash table to speed location of executed programs is disabled. -.HP 5 -\fBunlimit\fR -.br -.ns -.HP 5 -\fBunlimit\fR \fIresource\fR -.br -.ns -.HP 5 -\fBunlimit\ \-h\fR -.br -.ns -.HP 5 -\fBunlimit\ \-h\fR \fIresource\fR -.br -Removes the limitation on \fIresource\fR. If no \fIresource\fR -is specified, then all \fIresource\fR limitations are removed. If -\fB\-h\fR is given, the corresponding hard limits are removed. Only the +.Dp Ic unlimit +.Dp Cx Ic unlimit +.Cx \&\ \& +.Ar resource +.Cx +.Dp Cx Ic unlimit +.Cx \&\ \& +.Fl h +.Cx +.Dp Cx Ic unlimit +.Cx \&\ \& +.Fl h +.Cx \&\ \& +.Ar resource +.Cx +Removes the limitation on +.Ar resource . +If no +.Ar resource +is specified, then all +.Ar resource +limitations are removed. If +.Fl h +is given, the corresponding hard limits are removed. Only the super-user may do this. -.HP 5 -.BR unset " pattern" -.br +.Dp Cx Ic unset +.Cx \&\ \& +.Ar pattern +.Cx All variables whose names match the specified pattern are removed. Thus all variables are removed by `unset *'; this has noticeably distasteful side-effects. It is not an error for nothing to be -.I unset. -.HP 5 -.BR unsetenv " pattern" -.br +.Ic unset . +.Dp Cx Ic unsetenv +.Cx \&\ \& +.Ar pattern +.Cx Removes all variables whose name match the specified pattern from the environment. See also the -.I setenv +.Ic setenv command above and -.IR printenv (1). -.HP 5 -.B wait -.br +.Xr printenv 1 . +.Dp Ic wait All background jobs are waited for. It the shell is interactive, then an interrupt can disrupt the wait, at which time the shell prints names and job numbers of all jobs known to be outstanding. -.HP 5 -.BR while " (expr)" -.br -.ns -.HP 5 -\ ... -.br -.ns -.HP 5 -.B end -.br +.Dp Cx Ic while +.Cx \&\ \& +.Ar (expr) +.Cx +.Dp \&... +.Dp Ic end While the specified expression evaluates non-zero, the commands between the -.I while +.Ic while and the matching end are evaluated. -.I Break +.Ic Break and -.I continue +.Ic continue may be used to terminate or continue the loop prematurely. (The -.I while +.Ic while and -.I end +.Ic end must appear alone on their input lines.) Prompting occurs here the first time through the loop as for the -.I foreach +.Ic foreach statement if the input is a terminal. -.HP 5 -\fB%\fRjob -.br +.Dp Cx Ic % +.Cx \&\ \& +.Ar job +.Cx Brings the specified job into the foreground. -.HP 5 -\fB%\fRjob \fB&\fR -.br +.Dp Cx Ic % +.Cx \&\ \& +.Ar job +.Cx \&\ \& +.Ic & +.Cx Continues the specified job in the background. -.HP 5 -.B "@" -.br -.ns -.HP 5 -.BR "@" " name = expr" -.br -.ns -.HP 5 -.BR "@" " name[index] = expr" -.br +.Dp Ic @ +.Dp Cx Ic @ +.Cx \&\ \& +.Ar name = expr +.Cx +.Dp Cx Ic @ +.Cx \&\ \& +.Ar name +.Op index +.Cx\&\ = expr +.Cx The first form prints the values of all the shell variables. The second form sets the specified -.I name +.Ar name to the value of -.I expr. -If the expression contains `<', `>', `&' or `|' then at least +.Ar expr . +If the expression contains `<', `>', `&' or `' then at least this part of the expression must be placed within `(' `)'. The third form assigns the value of -.I expr +.Ar expr to the -.I index'th +.Cx Ar index +.Cx \'th +.Cx argument of -.I name. -Both -.I name +.Ar name . +Both +.Ar name and its -.I index'th +.Cx Ar index +.Cx \'th +.Cx component must already exist. -.IP +.Cx \&\ \& +.Dp +.Pp The operators `*=', `+=', etc are available as in C. The space separating the name from the assignment operator is optional. Spaces are, however, mandatory in separating components of -.I expr +.Ar expr which would otherwise be single words. -.IP -Special postfix `++' and `\-\|\-' operators increment and decrement -.I name +.Pp +Special postfix `++' and `\-\\-' operators increment and decrement +.Ar name respectively, i.e. `@ i++'. -.sh "Pre-defined and environment variables" +.Ss Pre-defined and environment variables The following variables have special meaning to the shell. Of these, -.I argv, -.I cwd, -.I home, -.I path, -.I prompt, -.I shell +.Ar argv , +.Ar cwd, +.Ar home , +.Ar path, +.Ar prompt , +.Ar shell and -.I status +.Ar status are always set by the shell. Except for -.I cwd +.Ar cwd and -.I status +.Ar status this setting occurs only at initialization; these variables will not then be modified unless this is done explicitly by the user. -.PP +.Pp This shell copies the environment variable USER into the variable -.I user, +.Ar user , TERM into -.I term, +.Ar term , and HOME into -.I home, +.Ar home , and copies these back into the environment whenever the normal shell variables are reset. The environment variable PATH is likewise handled; it is not necessary to worry about its setting other than in the file -.I \&.cshrc +.Ar \& .cshrc as inferior -.I csh +.Nm csh processes will import the definition of -.I path +.Ar path from the environment, and re-export it if you then change it. -.TP 15 -.B argv -\c +.Tp Ic argv Set to the arguments to the shell, it is from this variable that positional parameters are substituted, i.e. `$1' is replaced by -`$argv[1]', etc. -.TP 15 -.B cdpath -\c +.Cx $argv +.Op 1 +.Cx \' , +.Cx +etc. +.Tp Ic cdpath Gives a list of alternate directories searched to find subdirectories in -.I chdir +.Ar chdir commands. -.TP 15 -.B cwd +.Tp Ic cwd The full pathname of the current directory. -.TP 15 -.B echo -\c +.Tp Ic echo Set when the -.B \-x +.Fl x command line option is given. Causes each command and its arguments to be echoed just before it is executed. For non-builtin commands all expansions occur before echoing. Builtin commands are echoed before command and filename substitution, since these substitutions are then done selectively. -.TP 15 -.B filec +.Tp Ic filec Enable file name completion. -\c -.TP 15 -.B histchars -\c +.Tp Ic histchars Can be given a string value to change the characters used in history substitution. The first character of its value is used as the history substitution character, replacing the default character !. The second character of its value replaces the character \(ua in quick substitutions. -.TP 15 -.B history -\c +.Tp Ic history Can be given a numeric value to control the size of the history list. Any command which has been referenced in this many events will not be discarded. Too large values of -.I history +.Ar history may run the shell out of memory. The last executed command is always saved on the history list. -.TP 15 -.B home -\c +.Tp Ic home The home directory of the invoker, initialized from the environment. -The filename expansion of `\fB~\fR' refers to this variable. -.TP 15 -.B ignoreeof -\c +The filename expansion of +.Cx ` +.Pa ~ +.Cx \' +.Cx +refers to this variable. +.Tp Ic ignoreeof If set the shell ignores end-of-file from input devices which are terminals. This prevents shells from accidentally being killed by control-D's. -.TP 15 -.B mail -\c +.Tp Ic mail The files where the shell checks for mail. This is done after each command completion which will result in a prompt, if a specified interval has elapsed. The shell says `You have new mail.' if the file exists with an access time not greater than its modify time. -.IP +.Pp If the first word of the value of -.I mail +.Ar mail is numeric it specifies a different mail checking interval, in seconds, than the default, which is 10 minutes. -.IP +.Pp If multiple mail files are specified, then the shell says `New mail in -.IR name ' +.Cx Ar name +.Cx \' +.Cx when there is mail in the file -.I name. -.TP 15 -.B noclobber -\c +.Ar name . +.Tp Ic noclobber As described in the section on -.I Input/output, +.Ar Input/output , restrictions are placed on output redirection to insure that files are not accidentally destroyed, and that `>>' redirections refer to existing files. -.TP 15 -.B noglob -\c +.Tp Ic noglob If set, filename expansion is inhibited. This is most useful in shell scripts which are not dealing with filenames, or after a list of filenames has been obtained and further expansions are not desirable. -.TP 15 -.B nonomatch -\c +.Tp Ic nonomatch If set, it is not an error for a filename expansion to not match any existing files; rather the primitive pattern is returned. It is still an error for the primitive pattern to be malformed, i.e. -`echo [' still gives an error. -.TP 15 -.B notify -\c +`echo [' +still gives an error. +.Tp Ic notify If set, the shell notifies asynchronously of job completions. The default is to rather present job completions just before printing a prompt. -.TP 15 -.B path -\c +.Tp Ic path Each word of the path variable specifies a directory in which commands are to be sought for execution. A null word specifies the current directory. If there is no -.I path +.Ar path variable then only full path names will execute. The usual search path is `.', `/bin' and `/usr/bin', but this may vary from system to system. For the super-user the default search path is `/etc', `/bin' and `/usr/bin'. A shell which is given neither the -.B \-c +.Fl c nor the -.B \-t +.Fl t option will normally hash the contents of the directories in the -.I path +.Ar path variable after reading -.I \&.cshrc, +.Ar \& .cshrc , and each time the -.I path +.Ar path variable is reset. If new commands are added to these directories while the shell is active, it may be necessary to give the -.I rehash +.Ar rehash or the commands may not be found. -.TP 15 -.B prompt -\c +.Tp Ic prompt The string which is printed before each command is read from an interactive terminal input. If a `!' appears in the string it will be replaced by the current event number unless a preceding `\e' is given. Default is `% ', or `# ' for the super-user. -.TP 15 -.B savehist -\c +.Tp Ic savehist is given a numeric value to control the number of entries of the history list that are saved in ~/.history when the user logs out. Any command which has been referenced in this many events will be saved. During start up the shell sources ~/.history into the history list enabling history to be saved across logins. Too large values of -.I savehist +.Ar savehist will slow down the shell during start up. -.TP 15 -.B shell -\c +.Tp Ic shell The file in which the shell resides. This is used in forking shells to interpret files which have execute bits set, but which are not executable by the system. (See the description of -.I "Non-builtin Command Execution" +.Em Non-builtin Command Execution below.) Initialized to the (system-dependent) home of the shell. -.TP 15 -.B status -\c +.Tp Ic status The status returned by the last command. If it terminated abnormally, then 0200 is added to the status. Builtin commands which fail return exit status `1', all other builtin commands set status `0'. -.TP 15 -.B time -\c +.Tp Ic time Controls automatic timing of commands. If set, then any command which takes more than this many cpu seconds will cause a line giving user, system, and real times and a utilization percentage which is the ratio of user plus system times to real time to be printed when it terminates. -.TP 15 -.B verbose -\c +.Tp Ic verbose Set by the -.B \-v +.Fl v command line option, causes the words of each command to be printed after history substitution. -.sh "Non-builtin command execution" +.Tp +.Ss Non-builtin command execution When a command to be executed is found to not be a builtin command the shell attempts to execute the command via -.IR execve (2). +.Xr execve 2 . Each word in the variable -.I path +.Ar path names a directory from which the shell will attempt to execute the command. If it is given neither a -.B \-c +.Fl c nor a -.B \-t +.Fl t option, the shell will hash the names in these directories into an internal table so that it will only try an -.I exec +.Ic exec in a directory if there is a possibility that the command resides there. This greatly speeds command location when a large number of directories are present in the search path. If this mechanism has been turned off (via -.IR unhash ), +.Ic unhash ) , or if the shell was given a -.B \-c +.Fl c or -.B \-t +.Fl t argument, and in any case for each directory component of -.I path +.Ar path which does not begin with a `/', the shell concatenates with the given command name to form a path name of a file which it then attempts to execute. -.PP +.Pp Parenthesized commands are always executed in a subshell. Thus `(cd ; pwd) ; pwd' prints the -.I home +.Ar home directory; leaving you where you were (printing this after the home directory), while `cd ; pwd' leaves you in the -.I home +.Ar home directory. Parenthesized commands are most often used to prevent -.I chdir +.Ic chdir from affecting the current shell. -.PP +.Pp If the file has execute permissions but is not an executable binary to the system, then it is assumed to be a file containing shell commands and a new shell is spawned to read it. -.PP +.Pp If there is an -.I alias +.Ic alias for -.I shell +.Ic shell then the words of the alias will be prepended to the argument list to form the shell command. The first word of the -.I alias +.Ic alias should be the full path name of the shell (e.g. `$shell'). Note that this is a special, late occurring, case of -.I alias +.Ic alias substitution, and only allows words to be prepended to the argument list without modification. -.sh "Argument list processing" -If argument 0 to the shell is `\-' then this -is a login shell. -The flag arguments are interpreted as follows: -.TP 5 -.B \-b -\c -This flag forces a ``break'' from option processing, causing any further -shell arguments to be treated as non-option arguments. -The remaining arguments will not be interpreted as shell options. -This may be used to pass options to a shell script without confusion -or possible subterfuge. -The shell will not run a set-user ID script without this option. -.TP 5 -.B \-c -\c -Commands are read from the (single) following argument which must -be present. -Any remaining arguments are placed in -.I argv. -.TP 5 -.B \-e -\c -The shell exits if any invoked command terminates abnormally -or yields a non-zero exit status. -.TP 5 -.B \-f -\c -The shell will start faster, because it will neither search for nor -execute commands from the file -`\&.cshrc' in the invoker's home directory. -.TP 5 -.B \-i -\c -The shell is interactive and prompts for its top-level input, -even if it appears to not be a terminal. -Shells are interactive without this option if their inputs -and outputs are terminals. -.TP 5 -.B \-n -\c -Commands are parsed, but not executed. -This aids in syntactic checking of shell scripts. -.TP 5 -.B \-s -\c -Command input is taken from the standard input. -.TP 5 -.B \-t -\c -A single line of input is read and executed. -A `\e' may be used to escape the newline at the end of this -line and continue onto another line. -.TP 5 -.B \-v -\c -Causes the -.I verbose -variable to be set, with the effect -that command input is echoed after history substitution. -.TP 5 -.B \-x -\c -Causes the -.I echo -variable to be set, so that commands are echoed immediately before execution. -.TP 5 -.B \-V -\c -Causes the -.I verbose -variable to be set even before `\&.cshrc' is executed. -.TP 5 -.B \-X -\c -Is to -.B \-x -as -.B \-V -is to -.B \-v. -.PP -After processing of flag arguments, if arguments remain but none of the -.B \-c, -.B \-i, -.B \-s, -or -.B \-t -options was given, the first argument is taken as the name of a file of -commands to be executed. -The shell opens this file, and saves its name for possible resubstitution -by `$0'. -Since many systems use either the standard version 6 or version 7 shells -whose shell scripts are not compatible with this shell, the shell will -execute such a `standard' shell if the first character of a script -is not a `#', i.e. if the script does not start with a comment. -Remaining arguments initialize the variable -.I argv. -.sh "Signal handling" +.Ss Signal handling The shell normally ignores -.I quit +.Ar quit signals. -Jobs running detached (either by `&' or the \fIbg\fR or \fB%... &\fR +Jobs running detached (either by `&' or the +.Ic bg +or +.Ic %... & commands) are immune to signals generated from the keyboard, including hangups. Other signals have the values which the shell inherited from its parent. The shells handling of interrupts and terminate signals in shell scripts can be controlled by -.I onintr. +.Ic onintr . Login shells catch the -.I terminate +.Ar terminate signal; otherwise this signal is passed on to children from the state in the shell's parent. In no case are interrupts allowed when a login shell is reading the file -`\&.logout'. -.SH AUTHOR +.Pa \&.logout . +.Sh AUTHOR William Joy. Job control and directory stack features first implemented by J.E. Kulp of I.I.A.S.A, Laxenburg, Austria, with different syntax than that used now. File name completion code written by Ken Greer, HP Labs. -.SH FILES -.ta 1.75i -.nf -~/.cshrc Read at beginning of execution by each shell. -~/.login Read by login shell, after `.cshrc' at login. -~/.logout Read by login shell, at logout. -/bin/sh Standard shell, for shell scripts not starting with a `#'. -/tmp/sh* Temporary file for `<<'. -/etc/passwd Source of home directories for `~name'. -.fi -.SH LIMITATIONS +.Sh FILES +.Dw /etc/passwd +.Di L +.Dp Pa ~/.cshrc +Read at beginning of execution by each shell. +.Dp Pa ~/.login +Read by login shell, after `.cshrc' at login. +.Dp Pa ~/.logout +Read by login shell, at logout. +.Dp Pa /bin/sh +Standard shell, for shell scripts not starting with a `#'. +.Dp Pa /tmp/sh* +Temporary file for `<<'. +.Dp Pa /etc/passwd +Source of home directories for `~name'. +.Dp +.Sh LIMITATIONS +Word lengths \- Words can be no longer than 1024 characters. The system limits argument lists to 10240 characters. The number of arguments to a command which involves filename expansion @@ -2259,46 +2245,74 @@ is limited to 1/6'th the number of characters allowed in an argument list. Command substitutions may substitute no more characters than are allowed in an argument list. To detect looping, the shell restricts the number of -.I alias +.Ic alias substitutions on a single line to 20. -.SH "SEE ALSO" -sh(1), access(2), execve(2), fork(2), killpg(2), pipe(2), sigvec(2), -umask(2), setrlimit(2), wait(2), tty(4), a.out(5), environ(7), -`An introduction to the C shell' -.SH BUGS +.Sh SEE ALSO +.Xr sh 1 , +.Xr access 2 , +.Xr execve 2 , +.Xr fork 2 , +.Xr killpg 2 , +.Xr pipe 2 , +.Xr sigvec 2 , +.Xr umask 2 , +.Xr setrlimit 2 , +.Xr wait 2 , +.Xr tty 4 , +.Xr a.out 5 , +.Xr environ 7 , +.br +.Em An introduction to the C shell +.Sh HISTORY +.Nm Csh +Appeared in 3 BSD. It +was a first implementation of a command language interpreter +incorporating a history mechanism (see +.Nm History Substitutions ) , +job control facilities (see +.Nm Jobs ) , +interactive file name +and user name completion (see +.Nm File Name Completion ) , +and a C-like syntax. +There are now many shells which also have these mechanisms, plus +a few more (and maybe some bugs too), which are available thru +the internet, or as contributed software such as the +.Xr ksh (korn\ shell) . +.Sh BUGS When a command is restarted from a stop, the shell prints the directory it started in if this is different from the current directory; this can be misleading (i.e. wrong) as the job may have changed directories internally. -.PP +.Pp Shell builtin functions are not stoppable/restartable. Command sequences of the form `a ; b ; c' are also not handled gracefully when stopping is attempted. If you suspend `b', the shell will then immediately execute `c'. This is especially noticeable if this expansion results from an -.I alias. +.Ar alias . It suffices to place the sequence of commands in ()'s to force it to a subshell, i.e. `( a ; b ; c )'. -.PP +.Pp Control over tty output after processes are started is primitive; perhaps this will inspire someone to work on a good virtual terminal interface. In a virtual terminal interface much more interesting things could be done with output control. -.PP +.Pp Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be provided rather than aliases. -.PP +.Pp Commands within loops, prompted for by `?', are not placed in the -.I history +.Ic history list. Control structure should be parsed rather than being recognized as built-in commands. This would allow control commands to be placed anywhere, -to be combined with `|', and to be used with `&' and `;' metasyntax. -.PP +to be combined with `', and to be used with `&' and `;' metasyntax. +.Pp It should be possible to use the `:' modifiers on the output of command substitutions. All and more than one `:' modifier should be allowed on `$' substitutions. -.PP +.Pp The way the -.B filec +.Ic filec facility is implemented is ugly and expensive. diff --git a/usr/src/bin/date/date.1 b/usr/src/bin/date/date.1 index 21ac14e667..23fc16c754 100644 --- a/usr/src/bin/date/date.1 +++ b/usr/src/bin/date/date.1 @@ -1,75 +1,132 @@ +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %sccs.include.redist.man% +.\" +.\" @(#)date.1 6.7 (Berkeley) %G% +.\" +.Dd +.\" .Os BSD 4.4 .\" Copyright (c) 1980 Regents of the University of California. .\" All rights reserved. The Berkeley software License Agreement .\" specifies the terms and conditions for redistribution. .\" -.\" @(#)date.1 6.6 (Berkeley) %G% +.\" @(#)date.1 6.6 (Berkeley) 4/1/87 .\" -.TH DATE 1 "" -.UC 4 -.SH NAME -date \- print and set the date -.SH SYNOPSIS -.B date -.RB "[-nu] [-d dst] [-t minutes_west] [yymmddhhmm [" . "ss] ]" -.SH DESCRIPTION -If no arguments are given, the current date and time are -printed. Providing an argument will set the desired date; -only the superuser can set the date. The \fI-d\fP and \fI-t\fP -flags set the kernel's values for daylight savings time and -minutes west of GMT. If \fIdst\fP is non-zero, future calls -to \fIgettimeofday\fP(2) will return a non-zero \fItz_dsttime\fP. -\fIMinutes_west\fP provides the number of minutes returned -by future calls to \fIgettimeofday\fP(2) in \fItz_minuteswest\fP. The -\fI-u\fP flag is used to display or set the date in GMT (universal) time. -.I yy -represents the last two digits of the year; -the first -.I mm -is the month number; -.I dd -is the day number; -.I hh -is the hour number (24 hour system); -the second -.I mm -is the minute number; -.BI . ss -is optional and represents the seconds. -For example: -.IP -date 8506131627 -.PP -sets the date to June 13 1985, 4:27 PM. The year, month and day may -be omitted; the default values will be the current ones. The system -operates in GMT. \fIDate\fP takes care of the conversion to and from -local standard and daylight-saving time. -.PP -If -.I timed(8) +.Dt DATE 1 +.Os BSD 4 +.Sh NAME +.Nm date +.Nd display or set date and time +.Sh SYNOPSIS +.Nm date +.Op Fl nu +.Op Fl d Ar dst +.Op Fl t Ar minutes_west +.Op yymmddhhmm Op ss +.Sh DESCRIPTION +.Nm Date +displays today's date and time when invoked without +arguments. Providing an argument will set the desired date; +only the superuser can set the date. The +.Tp Fl d +Set the kernel's values for daylight savings time. +If +.Ar dst +is non-zero, future calls +to +.Ar gettimeofday +2 will return a non-zero +.Ar tz_dsttime . +.Tp Fl t +Set the kernel's values for minutes west of GMT. +.Ar Minutes_west +provides the number of minutes returned by future calls to +.Ar gettimeofday +2 in +.Ar tz_minuteswest . +.Tp Fl u +Display or set the date in GMT (universal) time. +.Tp +.Pp +The canonical representation for setting the date and time: +.Dp Ar yy +Year in abbreviated form (.e.g 89 for 1989). +.Dp Ar mm +Numeric month. +A number from 01 to 12. +.Dp Ar dd +Day, a number from 01 to 31. +.Dp Ar hh +Hour, a number from 00 to 24. +.Dp Ar mm +Minutes, a number from 00 to 60. +.Dp Ar .ss +Seconds, a number from 00 to 60. +.Dp +The command: +.Pp +.Dl date 8506131627 +.Pp +sets the date to June 13 1985, 4:27 PM. +.Pp +To reset today's time, the incantation can be shortened +to just the hours and minutes: +.Pp +.Dl date 1432 +.Pp +sets the time to 2:32 PM, unaffecting the date. +.Pp +Providing a system stays running, date will handle +time changes for daylight/standards savings time and leap times. +.Pp +If +.Ar timed 8 is running to synchronize the clocks of machines in a local -area network, \fIdate\fP sets the time globally on all those +area network, +.Nm date +sets the time globally on all those machines unless the -.B \-n +.Fl n option is given. -.SH FILES -/usr/adm/wtmp to record time-setting. -In /usr/adm/messages, \fIdate\fP records the name of the user +.Sh FILES +.Dw Pa /usr/adm/messages +.Di L +.Dp Pa /usr/adm/wtmp +A record of date resets and time changes. +.Dp Pa /usr/adm/messages, +A record of the name of the user setting the time. -.SH SEE ALSO -gettimeofday(2), utmp(5), timed(8), +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr utmp 5 , +.Xr timed 8 , .br -\fITSP: The Time Synchronization Protocol for UNIX 4.3BSD\fP, -R. Gusella and S. Zatti -.SH DIAGNOSTICS +.Em TSP:\ The\ Time\ Synchronization Protocol +.Em for UNIX 4.3BSD , +R. Gusella +and\ S.\ Zatti +.Sh HISTORY +.Nm +appeared in Version 6 AT&T UNIX. +.Sh DIAGNOSTICS Exit status is 0 on success, 1 on complete failure to set the date, and 2 on successfully setting the local date but failing globally. -.PP -Occasionally, when \fItimed\fP synchronizes the time on many hosts, +.Pp +Occasionally, when +.Ar timed +synchronizes the time on many hosts, the setting of a new time value may require more than a few seconds. -On these occasions, \fIdate\fP prints: `Network time being set'. +On these occasions, +.Nm date +prints: `Network time being set'. The message `Communication error with timed' occurs when the communication -between \fIdate\fP and \fItimed\fP fails. -.SH BUGS +between +.Nm date +and +.Ar timed +fails. +.Sh BUGS The system attempts to keep the date in a format closely compatible with VMS. VMS, however, uses local time (rather than GMT) and does not understand daylight-saving time. Thus, if you use both UNIX diff --git a/usr/src/bin/ed/ed.1 b/usr/src/bin/ed/ed.1 index a9a3d6733f..96b44fad18 100644 --- a/usr/src/bin/ed/ed.1 +++ b/usr/src/bin/ed/ed.1 @@ -1,277 +1,416 @@ -.\" @(#)ed.1 6.2 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH ED 1 "" -.AT 3 +.\" %sccs.include.redist.man% +.\" +.\" @(#)ed.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt ED 1 +.Os ATT 7th .if t .ds q \(aa .if n .ds q ' -.SH NAME -ed \- text editor -.SH SYNOPSIS -.B ed -[ -.B \- -] [ name ] -.SH DESCRIPTION -.I Ed +.Sh NAME +.Nm ed +.Nd text editor +.Sh SYNOPSIS +.Nm ed +.Op Fl +.Op Fl x +.Op Ar file +.Sh DESCRIPTION +.Nm Ed is the standard text editor. -.PP +.Pp If a -.I name +.Ar file argument is given, -.I ed +.Nm ed simulates an -.I e -command (see below)\| on the named file; that is to say, +.Ic e +command (see below) on the named file; that is to say, the file is read into -.I ed's +.Nm ed 's buffer so that it can be edited. -The optional -.B \- -suppresses the printing +.Tp Fl +Suppresses the printing of explanatory output and should be used when the standard input is an editor script. -.PP -.I Ed +.Tp +.Pp +.Nm Ed operates on a copy of any file it is editing; changes made in the copy have no effect on the file until a -.IR w "" -(write)\| -command is given. +.Ic w +(write) command is given. The copy of the text being edited resides -in a temporary file called the -.IR buffer . -.PP +in a temporary file called the +.Ar buffer . +.Pp Commands to -.I ed +.Nm ed have a simple and regular structure: zero or more -.I addresses +.Ar addresses followed by a single character -.I command, +.Ar command , possibly followed by parameters to the command. These addresses specify one or more lines in the buffer. Missing addresses are supplied by default. -.PP +.Pp In general, only one command may appear on a line. -Certain commands allow the +Certain commands allow the addition of text to the buffer. While -.I ed +.Nm ed is accepting text, it is said to be in -.I "input mode." +.Ar input mode . In this mode, no commands are recognized; all input is merely collected. -Input mode is left by typing a period `\fB.\fR' alone at the +Input mode is left by typing a period +.Sq Ic \&. +alone at the beginning of a line. -.PP -.I Ed +.Pp +.Nm Ed supports a limited form of -.I "regular expression" +.Ar regular expression notation. A regular expression specifies a set of strings of characters. A member of this set of strings is said to be -.I matched +.Ar matched by the regular expression. In the following specification for regular expressions the word `character' means any character but newline. -.IP 1. +.Tw Ds +.Tp 1. Any character except a special character matches itself. Special characters are the regular expression delimiter plus -.RB \e\|[\| . -and sometimes ^\|*\|$. -.IP 2. +.Sq Li \e\[ +and sometimes +.Sq Li ^*$ . +.Tp 2. A -.B . +.Sq Ic \&. matches any character. -.IP 3. -A \e followed by any character except a digit or (\|) matches that character. -.IP 4. +.Tp 3. +A +.Sq Li \e +followed by any character except a digit or +.Li (\) +matches that character. +.Tp 4. A nonempty string -.I s -bracketed -.RI [ \|s\| ] -(or -.RI [^ s\| ]) +.Op Ar s +or +.Cx \&( +.Op \&^ Ar s +.Cx \&) +.Cx matches any character in (or not in) -.I s. -In -.I s, -\e has no special meaning, and ] may only appear as +.Ar s . +In +.Ar s , +.Sq Li \e +has no special meaning, and +may only appear as the first letter. -A substring -.I a\-b, +A substring +.Ar a\-b , with -.I a +.Ar a and -.I b +.Ar b in ascending ASCII order, stands for the inclusive range of ASCII characters. -.IP 5. -A regular expression of form 1-4 followed by * matches a sequence of +.Tp 5. +A regular expression of form 1\-4 followed by * matches a sequence of 0 or more matches of the regular expression. -.IP 6. +.Tp 6. A regular expression, -.I x, -of form 1-8, bracketed -.RI \e( \|x\| \e) +.Ar x , +of form 1\-8, bracketed +.Cx Li \e( +.Ar x +.Li \e) +.Cx matches what -.I x +.Ar x matches. -.IP 7. -A \e followed by a digit -.I n +.Tp 7. +A \e followed by a digit +.Ar n matches a copy of the string that the bracketed regular expression beginning with the -.IR n th -\e( matched. -.IP 8. -A regular expression of form 1-8, -.I x, -followed by a regular expression of form 1-7, -.I y +.Cx Ar n +.Cx \'th +.Cx +.Li \e( +matched. +.Tp 8. +A regular expression of form 1\-8, +.Ar x , +followed by a regular expression of form 1\-7, +.Ar y matches a match for -.I x +.Ar x followed by a match for -.I y, +.Ar y , with the -.I x +.Ar x match being as long as possible while still permitting a -.I y +.Ar y match. -.IP 9. -A regular expression of form 1-8 preceded by ^ -(or followed by $), is constrained to matches that +.Tp 9. +A regular expression of form 1\-8 preceded by +.Sq Li ^ +(or followed by +.Sq Li $ ) , +is constrained to matches that begin at the left (or end at the right) end of a line. -.IP 10. -A regular expression of form 1-9 picks out the +.Tp 10. +A regular expression of form 1\-9 picks out the longest among the leftmost matches in a line. -.IP 11. +.Tp 11. An empty regular expression stands for a copy of the last regular expression encountered. -.PP +.Tp +.Pp Regular expressions are used in addresses to specify lines and in one command (see -.I s -below)\| +.Ar s +below) to specify a portion of a line which is to be replaced. If it is desired to use one of the regular expression metacharacters as an ordinary -character, that character may be preceded by `\e'. +character, that character may be preceded by +.Sq Li \e . This also applies to the character bounding the regular -expression (often `/')\| and to `\e' itself. -.PP +expression (often +.Sq Li \&/ ) +and to +.Sq Li \e +itself. +.Pp To understand addressing in -.I ed +.Nm ed it is necessary to know that at any time there is a -.I "current line." +.Ar current line. Generally speaking, the current line is the last line affected by a command; however, the exact effect on the current line is discussed under the description of the command. Addresses are constructed as follows. -.TP -1. -The character `\fB.\fR' addresses the current line. -.TP -2. -The character `$' addresses the last line of the buffer. -.TP -3. +.Tw Ds +.Tp 1. +The character +.Sq Ic \&. +addresses the current line. +.Tp 2. +The character +.Cx ` +.Ic $ +.Cx \' +.Cx +addresses the last line of the buffer. +.Tp 3. A decimal number -.I n +.Ar n addresses the -.IR n -th +.Cx Ar n +.Cx \'th +.Cx line of the buffer. -.TP -4. -`\(fm\fIx\fR' addresses the line marked with the name -.IR x , +.Tp 4. +.Cx `\(fm +.Ar x +.Cx \' +.Cx +addresses the line marked with the name +.Ar x , which must be a lower-case letter. Lines are marked with the -.I k +.Ar k command described below. -.TP -5. -A regular expression enclosed in slashes `/' addresses +.Tp 5. +A regular expression enclosed in slashes +.Cx ` +.Li / +.Cx \' +.Cx +addresses the line found by searching forward from the current line and stopping at the first line containing a string that matches the regular expression. If necessary the search wraps around to the beginning of the buffer. -.TP -6. -A regular expression enclosed in queries `?' addresses +.Tp 6. +A regular expression enclosed in queries +.Cx ` +.Li ? +.Cx \' +.Cx +addresses the line found by searching backward from the current line and stopping at the first line containing a string that matches the regular expression. If necessary the search wraps around to the end of the buffer. -.TP -7. -An address followed by a plus sign `+' -or a minus sign `\-' followed by a decimal number specifies that address plus -(resp. minus)\| the indicated number of lines. +.Tp 7. +An address followed by a plus sign +.Cx ` +.Li + +.Cx \' +.Cx +or a minus sign +.Cx ` +.Li \- +.Cx \' +.Cx +followed by a decimal number specifies that address plus +(resp. minus) the indicated number of lines. The plus sign may be omitted. -.TP -8. -If an address begins with `+' or `\-' +.Tp 8. +If an address begins with +.Cx ` +.Li + +.Cx \' +.Cx +or +.Cx ` +.Li \- +.Cx \' +.Cx the addition or subtraction is taken with respect to the current line; -e.g. `\-5' is understood to mean `\fB.\fR\-5'. -.TP -9. -If an address ends with `+' or `\-', +e.g. +.Cx ` +.Li \-5 +.Cx \' +.Cx +is understood to mean +.Cx ` +.Li .\-5 +.Cx \' +.Cx +.Nm . +.Tp 9. +If an address ends with +.Cx ` +.Li + +.Cx \' +.Cx +.Cx ` +.Li \- +.Cx \', +.Cx then 1 is added (resp. subtracted). As a consequence of this rule and rule 8, -the address `\-' refers to the line before the current line. +the address +.Cx ` +.Li \- +.Cx \' +.Cx +refers to the line before the current line. Moreover, trailing -`+' and `\-' characters -have cumulative effect, so `\-\-' refers to the current +.Cx ` +.Li + +.Cx \' +.Cx +and +.Cx ` +.Li \- +.Cx \' +.Cx +characters +have cumulative effect, so +.Cx ` +.Li \-\- +.Cx \' +.Cx +refers to the current line less 2. -.TP -10. +.Tp 10. To maintain compatibility with earlier versions of the editor, -the character `^' in addresses is -equivalent to `\-'. -.PP +the character +.Cx ` +.Li ^ +.Cx \' +.Cx +in addresses is +equivalent to +.Cx ` +.Li \- +.Cx \'. +.Cx +.Tp +.Pp Commands may require zero, one, or two addresses. Commands which require no addresses regard the presence of an address as an error. Commands which accept one or two addresses assume default addresses when insufficient are given. If more addresses are given than such a command requires, -the last one or two (depending on what is accepted)\| are used. -.PP +the last one or two (depending on what is accepted) are used. +.Pp Addresses are separated from each other typically by a comma -`\fB,\fR'. +.Cx ` +.Li , +.Cx \' +.Cx They may also be separated by a semicolon -`\fB;\fR'. -In this case the current line `\fB.\fR' is set to +.Cx ` +.Li ; +.Cx \' +.Cx +In this case the current line +.Cx ` +.Li . +.Cx \' +.Cx +.Nm . +is set to the previous address before the next address is interpreted. This feature can be used to determine the starting -line for forward and backward searches (`/', `?')\|. +line for forward and backward searches +.Cx \&(` +.Li / +.Cx \' +.Cx +.Cx ` +.Li ? +.Cx \'). +.Cx The second address of any two-address sequence must correspond to a line following the line corresponding to the first address. -The special form `%' -is an abbreviation for the address pair `1,$'. -.PP +The special form +.Cx ` +.Li \&% +.Cx \' +.Cx +is an abbreviation for the address pair +.Cx ` +.Li 1,$ +.Cx \'. +.Cx +.Pp In the following list of -.I ed +.Nm ed commands, the default addresses are shown in parentheses. The parentheses are not part of the address, but are used to show that the given addresses are the default. -.PP +.Pp As mentioned, it is generally illegal for more than one command to appear on a line. However, most commands may be suffixed by `p' @@ -283,383 +422,608 @@ Commands may also be suffixed by `n', meaning the output of the command is to be line numbered. These suffixes may be combined in any order. -.TP 5 -.RB (\| .\| )\|a -.br -.ns -.TP 5 - -.br -.ns -.TP 5 -.B . -.br +.Tw Ds +.Tp Cx \&( +.Ic . +.Cx \&) +.Ic a +.Cx +.Tp +.Tp Ic \&. The append command reads the given text and appends it after the addressed line. -`\fB.\fR' is left +.Sq Ic \&. +is left on the last line input, if there were any, otherwise at the addressed line. Address `0' is legal for this command; text is placed at the beginning of the buffer. -.TP 5 -.RB (\| .\| ,\ .\| )\|c -.br -.ns -.TP 5 - -.br -.ns -.TP 5 -.B . -.br +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&c +.Cx +.Tp +.Tp Ic \&. The change command deletes the addressed lines, then accepts input text which replaces these lines. -`\fB.\fR' is left at the last line input; if there were none, +.Sq Ic \&. +is left at the last line input; if there were none, it is left at the line preceding the deleted lines. -.TP 5 -.RB (\| .\| ,\ .\| )\|d +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&d +.Cx The delete command deletes the addressed lines from the buffer. The line originally after the last line deleted becomes the current line; if the lines deleted were originally at the end, the new last line becomes the current line. -.TP 5 -e filename +.Tp Cx Ic \&e +.Cx \&\ \& +.Ar filename +.Cx The edit command causes the entire contents of the buffer to be deleted, and then the named file to be read in. -`\fB.\fR' is set to the last line of the buffer. +.Sq Ic \&. +is set to the last line of the buffer. The number of characters read is typed. -`filename' is remembered for possible use as a default file name +.Ar filename +is remembered for possible use as a default file name in a subsequent -.I r +.Ic r or -.I w +.Ic w command. -If `filename' is missing, the remembered name is used. -.TP 5 -E filename +If +.Ar filename +is missing, the remembered name is used. +.Tp Cx Ic E +.Cx \&\ \& +.Ar filename +.Cx This command is the same as -.I e, +.Ic e , except that no diagnostic results when no -.I w +.Ic w has been given since the last buffer alteration. -.TP 5 -f filename +.Tp Cx Ic f +.Cx \&\ \& +.Ar filename +.Cx The filename command prints the currently remembered file name. -If `filename' is given, -the currently remembered file name is changed to `filename'. -.TP 5 -(1,$)\|g/regular expression/command list +If +.Ar filename +is given, +the currently remembered file name is changed to +.Ar filename . +.Tp Cx \&( +.Ic \&1 +.Cx \&, +.Ic \&$ +.Cx \&) +.Ic \&g +.Ar/regular expression/command list +.Cx In the global command, the first step is to mark every line which matches the given regular expression. Then for every such line, the -given command list is executed with `\fB.\fR' initially set to that line. +given command list is executed with +.Cx ` +.Ic \&. +.Cx \' +.Cx +initially set to that line. A single command or the first of multiple commands appears on the same line with the global command. -All lines of a multi-line list except the last line must be ended with `\e'. -.I A, -.I i, +All lines of a multi-line list except the last line must be ended with +.Cx ` +.Ic \&\e +.Cx \'. +.Cx +.Ic A , +.Ic i, and -.I c +.Ic c commands and associated input are permitted; -the `\fB.\fR' terminating input mode may be omitted if it would be on the +the +.Cx ` +.Ic \&. +.Cx \' +.Cx +terminating input mode may be omitted if it would be on the last line of the command list. The commands -.I g +.Ic g and -.I v +.Ic v are not permitted in the command list. -.TP 5 -.RB (\| .\| )\|i -.ns -.TP 5 - -.br -.ns -.TP 5 -.B . -.br +.Tp Cx \&( +.Ic . +.Cx \&) +.Ic i +.Cx +.Tp +.Tp Ic \&. This command inserts the given text before the addressed line. -`\fB.\fR' is left at the last line input, or, if there were none, +.Cx ` +.Ic \&. +.Cx \' +.Cx +is left at the last line input, or, if there were none, at the line before the addressed line. This command differs from the -.I a +.Ic a command only in the placement of the text. -.TP 5 -.RB (\| .\| ,\ . +1)\|j +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&.+1 +.Cx \&) +.Ic \&j +.Cx This command joins the addressed lines into a single line; intermediate newlines simply disappear. -`\fB.\fR' is left at the resulting line. -.TP 5 -( \fB. \fR)\|k\fIx\fR +.Cx ` +.Ic \&. +.Cx \' +.Cx +is left at the resulting line. +.Tp Cx \&( +.Ic . +.Cx \&) +.Ic k +.Ar x +.Cx The mark command marks the addressed line with name -.I x, +.Ar x , which must be a lower-case letter. -The address form `\(fm\fIx\fR' then addresses this line. -.ne 2.5 -.TP 5 -.RB (\| .\| ,\ .\| )\|l +The address form +.Cx `\(fm +.Ar x +.Cx \' +.Cx +then addresses this line. +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&l +.Cx The list command prints the addressed lines in an unambiguous way: non-graphic characters are printed in two-digit octal, and long lines are folded. The -.I l +.Ar l command may be placed on the same line after any non-i/o command. -.TP 5 -.RB (\| .\| ,\ .\| )\|m\fIa +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&m +.Ar a +.Cx The move command repositions the addressed lines after the line addressed by -.IR a . +.Ar a . The last of the moved lines becomes the current line. -.TP 5 -.RB (\| .\| ,\ .\| )\|p +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&p +.Cx The print command prints the addressed lines. -`\fB.\fR' +.Cx ` +.Ic \&. +.Cx \' +.Cx is left at the last line printed. The -.I p +.Ic p command may be placed on the same line after any non-i/o command. -.TP -.RB (\| .\| ,\ .\| )\|P +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&P +.Cx This command is a synonym for -.I p. -.TP 5 -q +.Ic p . +.Tp Ic q The quit command causes -.I ed +.Nm ed to exit. No automatic write of a file is done. -.TP 5 -Q +.Tp Ic Q This command is the same as -.I q, +.Ic q , except that no diagnostic results when no -.I w +.Ic w has been given since the last buffer alteration. -.TP 5 -($)\|r filename +.Tp Cx \&( +.Ic $ +.Cx \&) +.Ic r +.Cx \&\ \& +.Ar filename +.Cx The read command reads in the given file after the addressed line. If no file name is given, the remembered file name, if any, is used (see -.I e +.Ic e and -.I f -commands)\|. +.Ic f +commands). The file name is remembered if there was no remembered file name already. Address `0' is legal for -.I r +.Ic r and causes the file to be read at the beginning of the buffer. If the read is successful, the number of characters read is typed. -`\fB.\fR' is left at the last line read in from the file. -.TP 5 -(\| \fB.\fR\|, \fB.\fR\|)\|s/regular expression/replacement/ or, -.br -.ns -.TP 5 -(\| \fB.\fR\|, \fB.\fR\|)\|s/regular expression/replacement/g +.Cx ` +.Ic \&. +.Cx \' +.Cx +is left at the last line read in from the file. +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&s +.Ar/regular expression/replacement/ +.Cx \&\tor +.Cx +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&s +.Ar/regular expression/replacement/ +.Ic \&g +.Cx The substitute command searches each addressed line for an occurrence of the specified regular expression. On each line in which a match is found, all matched strings are replaced by the replacement specified, -if the global replacement indicator `g' appears after the command. +if the global replacement indicator +.Ic \&g +appears after the command. If the global indicator does not appear, only the first occurrence of the matched string is replaced. It is an error for the substitution to fail on all addressed lines. Any punctuation character -may be used instead of `/' to delimit the regular expression +may be used instead of +.Cx ` +.Ic \&/ +.Cx \' +.Cx +to delimit the regular expression and the replacement. -`\fB.\fR' is left at the last line substituted. -.IP -An ampersand `&' appearing in the replacement +.Cx ` +.Ic \&. +.Cx \' +.Cx +is left at the last line substituted. +An ampersand +.Cx ` +.Ic \&& +.Cx \' +.Cx +appearing in the replacement is replaced by the string matching the regular expression. -The special meaning of `&' in this context may be -suppressed by preceding it by `\e'. +The special meaning of +.Cx ` +.Ic \&& +.Cx \' +.Cx +in this context may be +suppressed by preceding it by +.Cx ` +.Ic \&\e +.Cx \'. +.Cx The characters -.I `\|\en' +.Cx ` +.Ic \&\e +.Ar n +.Cx \' +.Cx where -.I n +.Ar n is a digit, are replaced by the text matched by the -.IR n -th +.Cx Ar n +.Cx \'th +.Cx regular subexpression -enclosed between `\e(' and `\e)'. +enclosed between +.Cx ` +.Ic \&\e\&( +.Cx \'. +.Cx +and +.Cx ` +.Ic \&\e\&) +.Cx \'. +.Cx When nested, parenthesized subexpressions are present, -.I n -is determined by counting occurrences of `\e(' starting from the left. -.IP +.Ar n +is determined by counting occurrences of +.Cx ` +.Ic \&\e\&( +.Cx \'. +.Cx +starting from the left. Lines may be split by substituting new-line characters into them. The new-line in the replacement string -must be escaped by preceding it by `\e'. -.IP +must be escaped by preceding it by +.Cx ` +.Ic \&\e +.Cx \'. +.Cx One or two trailing delimiters may be omitted, -implying the `p' suffix. -The special form `s' followed by -.I no +implying the +.Ic p +suffix. +The special form +.Ic s +followed by +.Ar no delimiters repeats the most recent substitute command on the addressed lines. -The `s' may be followed by the letters -.B r +The +.Ic s +may be followed by the letters +.Ic r (use the most recent regular expression for the left hand side, instead of the most recent left hand side of a substitute command), -.B p +.Ic p (complement the setting of the -.I p +.Ic p suffix from the previous substitution), or -.B g +.Ic g (complement the setting of the -.I g +.Ic g suffix). These letters may be combined in any order. -.TP 5 -.RB (\| .\| ,\ .\| )\|t\|\fIa +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&t +.Ar a +.Cx This command acts just like the -.I m +.Ic m command, except that a copy of the addressed lines is placed after address -.I a +.Ad a (which may be 0). -`\fB.\fR' is left on the last line of the copy. -.TP 5 -.RB (\| .\| ,\ .\| )\|u +.Cx ` +.Ic \&. +.Cx \' +.Cx +is left on the last line of the copy. +.Tp Cx \&( +.Ic \&. +.Cx \&, +.Ic \&. +.Cx \&) +.Ic \&u +.Cx The undo command restores the buffer to it's state before the most recent buffer modifying command. The current line is also restored. Buffer modifying commands are -.I a, c, d, g, i, k, m, r, s, t, +.Ic a , c , d , g , i , k , m , r , s , t , and -.I v. +.Ic v . For purposes of undo, -.I g +.Ic g and -.I v +.Ic v are considered to be a single buffer modifying command. Undo is its own inverse. -.IP When -.I ed +.Nm ed runs out of memory (at about 8000 lines on any 16 bit mini-computer such as the PDP-11) This full undo is not possible, and -.I u +.Ic u can only undo the effect of the most recent substitute on the current line. This restricted undo also applies to editor scripts when -.I ed +.Nm ed is invoked with the -.B - +.Fl option. -.TP 5 -(1, $)\|v/regular expression/command list +.Tp Cx \&( +.Ic \&1 +.Cx \&, +.Ic \&$ +.Cx \&) +.Ic \&v +.Ar/regular expression/command list +.Cx This command is the same as the global command -.I g +.Ic g except that the command list is executed -.I g -with `\fB.\fR' initially set to every line -.I except +.Ic g +with +.Cx ` +.Ic \&. +.Cx \' +.Cx +initially set to every line +.Em except those matching the regular expression. -.TP 5 -(1, $)\|w filename -.br +(1, $)\w filename +.Tp Cx \&( +.Ic \&1 +.Cx \&, +.Ic \&$ +.Cx \&) +.Ic \&w +.Cx \&\ \& +.Ar filename +.Cx The write command writes the addressed lines onto the given file. If the file does not exist, it is created. -The file name is remembered if there was no +The file name is remembered if there was no remembered file name already. If no file name is given, the remembered file name, if any, is used (see -.I e +.Ic e and -.I f -commands)\|. -`\fB.\fR' is unchanged. +.Ic f +commands). +.Cx ` +.Ic \&. +.Cx \' +.Cx +is unchanged. If the command is successful, the number of characters written is printed. -.TP -(1, $)\|W filename +.Tp Cx \&( +.Ic \&1 +.Cx \&, +.Ic \&$ +.Cx \&) +.Ic \&W +.Cx \&\ \& +.Ar filename +.Cx This command is the same as -.I w, +.Ic w , except that the addressed lines are appended to the file. -.TP 5 -(1, $)\|wq filename +.Tp Cx \&( +.Ic \&1 +.Cx \&, +.Ic \&$ +.Cx \&) +.Ic \&wq +.Cx \&\ \& +.Ar filename +.Cx This command is the same as -.I w +.Ic w except that afterwards a -.I q +.Ic q command is done, exiting the editor after the file is written. -.TP 5 -.RB (\| .\| +1)\|z or, -.br -.ns -.TP 5 -.RB (\| .\| +1)\|z\fIn +.Ic \&1 +.Ic \&+1 +.Cx \&) +.Ic \&z +.Cx \&\ \ \&or, +.Cx +.Tp Cx \&( +.Ic \&1 +.Ic \&+1 +.Cx \&) +.Ic \&z +.Ar n +.Cx This command scrolls through the buffer starting at the addressed line. 22 (or -.I n, +.Ar n , if given) lines are printed. The last line printed becomes the current line. The value -.I n +.Ar n is sticky, in that it becomes the default for future -.I z +.Ic z commands. -.TP 5 -($)\|= +.Tp Cx \&( +.Ic \&$ +.Cx \&) +.Ic \&= +.Cx The line number of the addressed line is typed. -`\fB.\fR' is unchanged by this command. -.TP 5 -! +.Cx ` +.Ic \&. +.Cx \' +.Cx +is unchanged by this command. +.Tp Cx Ic \&! +.Cx +.Cx The remainder of the line after the `!' is sent to -.IR sh (1) +.Xr sh 1 to be interpreted as a command. -.RB ` . ' +.Cx ` +.Ic \&. +.Cx \' +.Cx is unchanged. -.TP 5 -.RB (\| . +1,\| . +1)\| +.Tp Cx \&( +.Ic \&.+1 +.Cx \&, +.Ic \&.+1 +.Cx \&) +.Cx +.Cx An address alone on a line causes the addressed line to be printed. -A blank line alone is equivalent to `.+1p'; it is useful +A blank line alone is equivalent to +.Ic .+1 +it is useful for stepping through text. If two addresses are present with no intervening semicolon, -.I ed +.Nm ed prints the range of lines. If they are separated by a semicolon, the second line is printed. -.PP -If an interrupt signal (ASCII DEL)\| is sent, -.I ed -prints `?interrupted' +.Tp +.Pp +If an interrupt signal (ASCII DEL) is sent, +.Nm ed +prints +.Sq Li ?interrupted and returns to its command level. -.PP +.Pp Some size limitations: 512 characters per line, 256 characters per global command list, @@ -668,48 +1032,58 @@ and, on mini computers, 128K characters in the temporary file. The limit on the number of lines depends on the amount of core: each line takes 2 words. -.PP +.Pp When reading a file, -.I ed +.Nm ed discards ASCII NUL characters and all characters after the last newline. It refuses to read files containing non-ASCII characters. -.SH FILES -/tmp/e* +.Sh FILES +.Dw edhup +.Di L +.Dp Pa /tmp/e* +.Dp Pa edhup +work is saved here if terminal hangs up +.Dp +.Sh SEE ALSO +.Xr ex 1 , +.Xr sed 1 , +.Xr crypt 1 .br -edhup: work is saved here if terminal hangs up -.SH "SEE ALSO" B. W. Kernighan, -.I -A Tutorial Introduction to the ED Text Editor +.Em A Tutorial Introduction to the ED Text Editor .br B. W. Kernighan, -.I Advanced editing on UNIX -.br -ex(1), sed(1), crypt(1) -.SH DIAGNOSTICS -`?name' for inaccessible file; -`?self-explanatory message' +.Em Ar Advanced editing on UNIX +.Sh HISTORY +The +.Nm ed +command appeared in Version 6 AT&T UNIX. +.Sh DIAGNOSTICS +.Sq Li name +for inaccessible file; +.Sq Li ?self-explanatory message for other errors. -.PP +.Pp To protect against throwing away valuable work, a -.I q +.Ic q or -.I e +.Ic e command is considered to be in error, unless a -.I w +.Ic w has occurred since the last buffer change. A second -.I q +.Ic q or -.I e +.Ic e will be obeyed regardless. -.SH BUGS -The -.I l -command mishandles DEL. +.Sh BUGS +The +.Ic l +command mishandles +.Li DEL . .br The -.I undo +.Ic undo command causes marks to be lost on affected lines. diff --git a/usr/src/bin/mv/mv.1 b/usr/src/bin/mv/mv.1 index 98c4ccec2d..20b11520d5 100644 --- a/usr/src/bin/mv/mv.1 +++ b/usr/src/bin/mv/mv.1 @@ -1,97 +1,98 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)mv.1 6.3 (Berkeley) %G% +.\" @(#)mv.1 6.4 (Berkeley) %G% .\" -.TH MV 1 "" -.UC 7 -.SH NAME -mv \- move files -.SH SYNOPSIS -.nf -mv [ \-f | \-i ] source target -mv [ \-f | \-i ] source ... source directory -.fi -.SH DESCRIPTION -.PP +.Dd +.Dt MV 1 +.Os BSD 4.4 +.Sh NAME +.Nm mv +.Nd move files +.Sh SYNOPSIS +.Nm mv +.Op Fl f Li \&| Fl i +.Ar source target +.Nm mv +.Op Fl f Li \&| Fl i +.Ar source ... source directory +.De +.Sh DESCRIPTION +.Pp In its first form, the -.I mv +.Nm mv utility renames the file named by the -.I source +.Ar source operand to the destination path named by the -.I target +.Ar target operand. This form is assumed when the last operand does not name an already existing directory. -.PP +.Pp In its second form, -.I mv +.Nm mv moves each file named by a -.I source +.Ar source operand to a destination file in the existing directory named by the -.I directory +.Ar directory operand. The destination path for each operand is the pathname produced by the concatenation of the last operand, a slash, and the final pathname component of the named file. -.PP +.Pp The following options are available: -.TP -\-f +.Tw Ds +.Tp Fl f Do not prompt for confirmation before overwriting the destination path. (The -.I \-i +.Fl i option is ignored if the -.I \-f +.Fl f option is specified.) -.TP -\-i +.Tp Fl i Causes -.I mv +.Nm mv to write a prompt to standard error before moving a file that would overwrite an existing file. If the response from the standard input begins with the character ``y'', the move is attempted. -.PP +.Tp +.Pp It is an error for either the -.I source +.Ar source operand or the destination path to specify a directory unless both do. -.PP +.Pp If the destination path does not have a mode which permits writing, -.I mv +.Nm mv prompts the user for confirmation as specified for the -.I \-i +.Fl i option. -.PP +.Pp As the -.IR rename (2) +.Xr rename 2 call does not work across file systems, -.I mv +.Nm mv uses -.IR cp (1) +.Xr cp 1 and -.IR rm (1) +.Xr rm 1 to accomplish the move. The effect is equivalent to: -.sp -.nf -.ti +5 +.Pp +.Ds I rm -f destination_path && \e -.ti +8 -cp -pr source_file destination && \e -.ti +8 -rm -rf source_file -.fi -.PP +\tcp -pr source_file destination && \e +\trm -rf source_file +.De +.Pp The -.I mv +.Nm mv utility exits 0 on success, and >0 if an error occurs. -.SH ENVIRONMENT -.SH "SEE ALSO" -.SH STANDARDS +.Sh SEE ALSO +.Sh STANDARDS The -.I mv +.Nm mv function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/bin/ps/ps.1 b/usr/src/bin/ps/ps.1 index c4952affb9..13a1d56cec 100644 --- a/usr/src/bin/ps/ps.1 +++ b/usr/src/bin/ps/ps.1 @@ -1,30 +1,43 @@ +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %sccs.include.redist.man% +.\" +.\" @(#)ps.1 6.6 (Berkeley) %G% +.\" +.Dd .\" Copyright (c) 1980 Regents of the University of California. .\" All rights reserved. The Berkeley software License Agreement .\" specifies the terms and conditions for redistribution. .\" -.\" @(#)ps.1 6.5 (Berkeley) %G% +.\" @(#)ps.1 6.5 (Berkeley) 3/10/88 .\" -.TH PS 1 "" -.UC 4 -.SH NAME -ps \- process status -.SH SYNOPSIS -.B ps -[ -.B acegklnstuvwxU# -] -.SH DESCRIPTION -.I Ps -prints information about processes. +.Dt PS 1 +.Os BSD 4 +.Sh NAME +.Nm ps +.Nd display current process status +.Sh SYNOPSIS +.Nm ps +.Op Fl acegklnstuvwxU\&\#\& +.Sh DESCRIPTION +.Nm Ps +displays the current process status. Normally, only your processes are candidates to be printed by -.I ps; +.Nm ps ; specifying -.B a +.Fl a causes other users' processes to be candidates to be printed; specifying -.B x +.Fl x includes processes without control terminals in the candidate pool. -.PP +While +.Nm ps +is a fairly accurate snapshot of the system, +.Nm Ps +cannot begin and finish a snapshot of the system as fast as some processes +themselves change state. At times there may be minor discrepancies. +.Pp All output formats include, for each process, the process id PID, control terminal of the process TT, cpu time used by the process TIME (this includes both user and system time), the state STAT of the process, @@ -52,231 +65,239 @@ a `<' is shown. The final optional letter indicates any special treatment of the process for virtual memory replacement; the letters correspond to options to the -.IR vadvise (2) -call; currently the possibilities are A standing for VA_ANOM and +.Xr vadvise 2 +call; currently the possibilities are A standing for VA_ANOM and S for VA_SEQL. An A typically represents a -.IR lisp (1) +.Xr lisp 1 in garbage collection, and S is typical of large image processing programs which are using virtual memory to sequentially address voluminous data. -.PP +.Pp Here are the options: -.TP 5 -.B a -asks for information about all processes with terminals (ordinarily +.Tp Fl a +asks for information regarding processes associated with terminals (ordinarily only one's own processes are displayed). -.TP 5 -.B c +.Tp Fl c prints the command name, as stored internally in the system for purposes of accounting, rather than the command arguments, which are kept in the process' address space. This is more reliable, if less informative, since the process is free to destroy the latter information. -.TP 5 -.B e +.Tp Fl e Asks for the environment to be printed as well as the arguments to the command. -.TP 5 -.B g +.Tp Fl g Asks for all processes. Without this option, -.I ps +.Nm ps only prints ``interesting'' processes. Processes are deemed to be uninteresting if they are process group leaders. This normally eliminates top-level command interpreters and processes waiting for users to login on free terminals. -.TP 5 -.B k +.Tp Fl k causes the file -.I /vmcore -is used in place of -.IR /dev/kmem " and " /dev/mem. -This is used for -postmortem system debugging. -.TP 5 -.B l -asks for a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and +.Pa /vmcore +to be used instead of +.Pa /dev/kmem +and +.Ar /dev/mem +for non-interactive (after the fact) +debugging. +.Tp Fl l +asks for a detailed list, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as described below. -.TP 5 -.B n +.Tp Fl n Asks for numerical output. In a long listing, the WCHAN field is printed numerically rather than symbolically, or, in a user listing, the USER field is replaced by a UID field. -.TP 5 -.B s +.Tp Fl s Adds the size SSIZ of the kernel stack of each process (for use by system maintainers) to the basic output format. -.TP 5 -\fBt\fIx\fR -restricts output to processes whose controlling tty is \fIx\fR +.Ct Fl t +.Ar x +.Cx +Only output information on processes whose controlling tty is +.Ar x (which should be specified as printed by -.I ps, +.Nm ps , e.g. -.I t3 +.Ar t3 for tty3, -.I tco +.Ar tco for console, -.I td0 +.Ar td0 for ttyd0, -.I t? +.Ar t ? for processes with no tty, -.I t +.Ar t for processes at the current tty, etc). This option must be the last one given. -.TP 5 -.B u +.Tp Fl u A user oriented output is produced. This includes fields USER, %CPU, NICE, SIZE, and RSS as described below. -.TP 5 -.B v +.Tp Fl v A version of the output containing virtual memory statistics is output. This includes fields RE, SL, PAGEIN, SIZE, RSS, LIM, TSIZ, TRS, %CPU and %MEM, described below. -.TP 5 -.B w +.Tp Fl w Use a wide output format (132 columns rather than 80); if repeated, e.g. ww, use arbitrarily wide output. This information is used to decide how much of long commands to print. -.TP 5 -.B x +.Tp Fl x asks even about processes with no terminal. -.TP -.B U +.Tp Fl U causes ps to update a private database where it keeps system -information. Thus ``ps U'' should be included in the /etc/rc file. -.TP 5 -.B # +information. Thus ``ps U'' should be included in the +.Pa /etc/rc +file. +.Tp Fl # A process number may be given, (indicated here by #), in which case the output is restricted to that process. This option must also be last. -.PP -A second argument is taken +.Tp +.Pp +A second argument is taken to be the file containing the system's namelist. Otherwise, /vmunix is used. A third argument tells -.I ps +.Nm ps where to look for -.I core +.Pa core if the -.B k -option is given, instead of /vmcore. +.Fl k +option is given, instead of +.Pa /vmcore . If a fourth argument is given, it is taken to be the name of a swap file to use instead of -the default /dev/drum. -.PP +the default +.Pa /dev/drum . +.Pp Fields which are not common to all output formats: -.PD 0 -.IP USER 10 +.Pp +.Dw PAGEIN +.Dp Li USER name of the owner of the process -.IP %CPU 10 +.Dp Li %CPU cpu utilization of the process; this is a decaying average over up to a minute of previous (real) time. Since the time base over which this is computed varies (since processes may be very young) it is possible for the sum of all %CPU fields to exceed 100%. -.IP NICE 10 +.Dp Li NICE (or NI) process scheduling increment (see -.IR setpriority (2)) -.IP SIZE 10 +.Xr setpriority 2 ) +.Dp Li SIZE virtual size of the process (in 1024 byte units) -.IP RSS 10 +.Dp Li RSS real memory (resident set) size of the process (in 1024 byte units) -.IP LIM 10 +.Dp Li LIM soft limit on memory used, specified via a call to -.IR setrlimit (2); -if no limit has been specified then shown as \fIxx\fR -.IP TSIZ 10 +.Xr setrlimit 2 ; +if no limit has been specified then shown as +.Ar xx +.Dp Li TSIZ size of text (shared program) image -.IP TRS 10 +.Dp Li TRS size of resident (real memory) set of text -.IP %MEM 10 +.Dp Li %MEM percentage of real memory used by this process. -.IP RE 10 +.Dp Li RE residency time of the process (seconds in core) -.IP SL 10 +.Dp Li SL sleep time of the process (seconds blocked) -.IP PAGEIN 10 +.Dp Li PAGEIN number of disk i/o's resulting from references by the process to pages not loaded in core. -.IP UID 10 -numerical user-id of process owner -.IP PPID 10 -numerical id of parent of process -.IP CP 10 +.Dp Li UID +process owner's user-id (numerical) +.Dp Li PPID +parent process id (numerical) +.Dp Li CP short-term cpu utilization factor (used in scheduling) -.IP PRI 10 +.Dp Li PRI process priority (non-positive when in non-interruptible wait) -.IP ADDR 10 +.Dp Li ADDR swap address of the process -.IP WCHAN 10 -event on which process is waiting (an address in the system). +.Dp Li WCHAN +address of event on which a process is waiting (an address in the system). A symbol is chosen that classifies the address, unless numerical -output is requested (see the -.B n +output is requested (see the +.Fl n flag). In this case, the initial part of the address is trimmed off and is printed hexadecimally, e.g., 0x80004000 prints as 4000. -.sp -.IP F 10 +.Pp +.Dp Li F flags associated with process as in -.RI < sys/proc.h >: -.br -.PP -.sp -.nf -.ta 6n 18n 26n - SLOAD 000001 in core - SSYS 000002 swapper or pager process - SLOCK 000004 process being swapped out - SSWAP 000008 save area flag - STRC 000010 process is being traced - SWTED 000020 another tracing flag - SULOCK 000040 user settable lock in core - SPAGE 000080 process in page wait state - SKEEP 000100 another flag to prevent swap out - SDLYU 000200 delayed unlock of pages - SWEXIT 000400 working on exiting - SPHYSIO 000800 doing physical i/o (bio.c) - SVFORK 001000 process resulted from vfork() - SVFDONE 002000 another vfork flag - SNOVM 004000 no vm, parent in a vfork() - SPAGI 008000 init data space on demand from inode - SANOM 010000 system detected anomalous vm behavior - SUANOM 020000 user warned of anomalous vm behavior - STIMO 040000 timing out during sleep - SDETACH 080000 detached inherited by init - SOUSIG 100000 using old signal mechanism -.fi -.PD -.PP +.Aq Pa sys/proc.h : +.Pp +.Cw SDETACH 080000 +.Cl SLOAD 000001 in core +.Cl SSYS 000002 swapper or pager process +.Cl SLOCK 000004 swapping out process +.Cl SSWAP 000008 save area flag +.Cl STRC 000010 tracing the process +.Cl SWTED 000020 trace flag +.Cl SULOCK 000040 user settable lock in core +.Cl SPAGE 000080 process in page wait state +.Cl SKEEP 000100 another flag to prevent swap out +.Cl SDLYU 000200 delayed unlock of pages +.Cl SWEXIT 000400 working on exiting +.Cl SPHYSIO 000800 doing physical i/o (bio.c) +.Cl SVFORK 001000 process resulted from vfork() +.Cl SVFDONE 002000 another vfork flag +.Cl SNOVM 004000 no vm, parent in a vfork() +.Cl SPAGI 008000 init data space on demand from inode +.Cl SANOM 010000 system detected anomalous vm behavior +.Cl SUANOM 020000 user warned of anomalous vm behavior +.Cl STIMO 040000 timing out during sleep +.Cl SDETACH 080000 detached inherited by init +.Cl SOUSIG 100000 using old signal mechanism +.Cw +.Dp +.Pp +.Tp Aq Li defunct +A +.Aq defunct +process is one that has exited, but whose parent process has +not waited for it. A process that has exited and has a parent that has not -yet waited for the process is marked ; a process -which is blocked trying to exit is marked ; -.I Ps +yet waited for the process is marked +.Aq Li defunct . +.Tp Aq Li exiting +A process +which is blocked trying to exit is marked +.Aq Li exiting +.Tp +.Pp +.Nm Ps makes an educated guess as to the file name and arguments given when the process was created by examining memory or the swap area. The method is inherently somewhat unreliable and in any event a process is entitled to destroy this information, so the names cannot be counted on too much. -.SH FILES -.ta \w'/etc/psdatabase 'u -/vmunix system namelist -.br -/dev/kmem kernel memory -.br -/dev/drum swap device -.br -/vmcore core file -.br -/dev searched to find swap device and tty names -.br -/etc/psdatabase system namelist, device, and wait channel information -.SH "SEE ALSO" -kill(1), w(1) -.SH BUGS -Things can change while -.I ps -is running; the picture it gives is only a close -approximation to reality. +.Sh FILES +.Dw /etc/pasdatabase +.Di L +.Dp Pa /vmunix +system namelist +.Dp Pa /dev/kmem +kernel memory +.Dp Pa /dev/drum +swap device +.Dp Pa /vmcore +core file +.Dp Pa /dev +searched to find swap device and tty names +.\" .Dp Pa /etc/psdatabase +.\" system namelist, device, and wait channel information +.Dp +.Sh SEE ALSO +.Xr kill 1 , +.Xr w 1 +.Sh HISTORY +A +.Nm Ps +command appeared in VERSION 6 AT&T UNIX. diff --git a/usr/src/bin/pwd/pwd.1 b/usr/src/bin/pwd/pwd.1 index 1ac14ff624..0cda4afc73 100644 --- a/usr/src/bin/pwd/pwd.1 +++ b/usr/src/bin/pwd/pwd.1 @@ -1,25 +1,35 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pwd.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PWD 1 "" -.UC 4 -.SH NAME -pwd \- working directory name -.SH SYNOPSIS -.B pwd -.SH DESCRIPTION -.I Pwd -prints the pathname of the working (current) directory. -.SH "SEE ALSO" -cd(1), csh(1), getwd(3) -.SH BUGS +.\" @(#)pwd.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PWD 1 +.Os BSD 4 +.Sh NAME +.Nm pwd +.Nd return working directory name +.Sh SYNOPSIS +.Nm pwd +.Sh DESCRIPTION +.Nm Pwd +writes the absolute pathname of the current working directory to +the standard output. +.Pp +The pwd utility exits 0 on success, and >0 if an error occurs. +.Sh STANDARDS +The pwd function is expected to be POSIX 1003.2 compatible +.Sh SEE ALSO +.Xr cd 1 , +.Xr csh 1 , +.Xr getwd 3 +.Sh BUGS In -.IR csh (1) +.Xr csh 1 the command -.I dirs +.Ic dirs is always faster (although it can give a different answer in the rare case that the current directory or a containing directory was moved after the shell descended into it). diff --git a/usr/src/bin/rcp/rcp.1 b/usr/src/bin/rcp/rcp.1 index 0fc0628b72..4f885eaa12 100644 --- a/usr/src/bin/rcp/rcp.1 +++ b/usr/src/bin/rcp/rcp.1 @@ -1,104 +1,111 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)rcp.1 6.8 (Berkeley) %G% +.\" @(#)rcp.1 6.10 (Berkeley) %G% .\" -.TH RCP 1 "" -.UC 5 -.SH NAME -rcp \- remote file copy -.SH SYNOPSIS -.B rcp -[ -.B \-p -] [ -.B \-k realm -] file1 file2 -.br -.B rcp -[ -.B \-p -] [ -.B \-r -] [ -.B \-k realm -] file ... directory -.SH DESCRIPTION -.I Rcp +.Dd +.Dt RCP 1 +.Os BSD 4.2 +.Sh NAME +.Nm rcp +.Nd remote file copy +.Sh SYNOPSIS +.Nm rcp +.Op Fl p +.Op Fl k Ar realm +.Ar file1 file2 +.Nm rcp +.Op Fl p +.Op Fl r +.Op Fl k Ar realm +.Ar file ... +.Ar directory +.Sh DESCRIPTION +.Nm Rcp copies files between machines. Each -.I file +.Ar file or -.I directory +.Ar directory argument is either a remote file name of the form ``rname@rhost:path'', or a local file name (containing no `:' characters, or a `/' before any `:'s). -.PP -If the -.B \-r -option -is specified and any of the source files are directories, -.I rcp +.Pp +.Tp Fl r +If any of the source files are directories, +.Nm rcp copies each subtree rooted at that name; in this case the destination must be a directory. -.PP -By default, the mode and owner of -.I file2 -are preserved if it already existed; otherwise the mode of the source file -modified by the -.IR umask (2) -on the destination host is used. +.Tp Fl p The -.B \-p +.Fl p option causes -.I rcp +.Nm rcp to attempt to preserve (duplicate) in its copies the modification times and modes of the source files, ignoring the -.IR umask . -.PP +.Ar umask . +By default, the mode and owner of +.Ar file2 +are preserved if it already existed; otherwise the mode of the source file +modified by the +.Xr umask 2 +on the destination host is used. +.Tp Fl k The -.B \-k +.Fl k option requests -.I rcp +.Nm rcp to obtain tickets for the remote host in realm -.I realm +.Ar realm instead of the remote host's realm as determined by -.IR krb_realmofhost (3). -.PP +.Xr krb_realmofhost 3 . +.Tp +.Pp If -.I path +.Ar path is not a full path name, it is interpreted relative to the login directory of the specified user -.I ruser -on -.IR rhost , +.Ar ruser +on +.Ar rhost , or your current user name if no other remote user name is specified. -A -.I path +A +.Ar path on a remote host may be quoted (using \e, ", or \(aa) so that the metacharacters are interpreted remotely. -.PP -.I Rcp +.Pp +.Nm Rcp does not prompt for passwords; it performs remote execution via -.IR rsh (1), +.Xr rsh 1 , and requires the same authorization. -.PP -.I Rcp +.Pp +.Nm Rcp handles third party copies, where neither source nor target files are on the current machine. -.SH SEE ALSO -cp(1), ftp(1), rsh(1), rlogin(1) -.SH BUGS +.Sh SEE ALSO +.Xr cp 1 , +.Xr ftp 1 , +.Xr rsh 1 , +.Xr rlogin 1 +.Sh HISTORY +.Nm Rcp +appeared in 4.2 BSD. The version of rcp described here +is new with 4.4BSD and is part of Kerberos. +.Sh BUGS Doesn't detect all cases where the target of a copy might be a file in cases where only a directory should be legal. -.PP +.Pp Is confused by any output generated by commands in a -\&.login, \&.profile, or \&.cshrc file on the remote host. -.PP +.Pa \&.login , +.Pa \&.profile , +or +.Pa \&.cshrc +file on the remote host. +.Pp The destination user and hostname may have to be specified as ``rhost.rname'' when the destination machine is running the 4.2BSD -version of \fIrcp\fP. - +version of +.Nm rcp . diff --git a/usr/src/bin/rm/rm.1 b/usr/src/bin/rm/rm.1 index eaa291c5c0..0d29891fa3 100644 --- a/usr/src/bin/rm/rm.1 +++ b/usr/src/bin/rm/rm.1 @@ -1,61 +1,63 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)rm.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH RM 1 "" -.UC 4 -.SH NAME -rm, rmdir \- remove (unlink) files or directories -.SH SYNOPSIS -.B rm -[ -.B \-f -] [ -.B \-r -] [ -.B \-i -] file ... -.PP -.B rmdir -dir ... -.PP -.SH DESCRIPTION -.I Rm -removes the entries for one or more files from a directory. -If an entry was the last link to the file, the file is destroyed. -Removal of a file requires write permission in its directory, -but neither read nor write permission on the file itself. -.PP -If a file has no write permission and the standard input is a terminal, -its permissions are printed and a line is read from the standard input. -If that line begins with `y' the file is deleted, otherwise the file remains. -No questions are asked and no errors are reported when the -.B \-f -(force) option is given. -.PP -If a designated file is a directory, -an error comment is printed unless the optional argument -.B \-r -has been used. In that case, -.I rm -recursively deletes the entire contents of the specified directory, -and the directory itself. -.PP -If the -.B \-i -(interactive) option is in effect, -.I rm -asks whether to delete each file, and, under -.BR \-r , -whether to examine each directory. -.PP -Since getopt recognizes the string ``--'' as terminating the set -of options, it can be used to allow the removal of file names -starting with a dash. -.PP -.I Rmdir -removes entries for the named directories, which must be empty. -.SH "SEE ALSO" -rm(1), unlink(2), rmdir(2) +.\" @(#)rm.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt RM 1 +.Os BSD 4.4 +.Sh NAME +.Nm rm +.Nd remove directory entries +.Sh SYNOPSIS +.Nm rm +.Op Fl f Li \&| Fl i +.Op Fl Rr +.Ar file ... +.Sh DESCRIPTION +The rm utility removes the directory entry specified by each +file argument. +.Pp +The following options are available: +.Tp Fl f +Force each specified directory entry to be removed +without prompting for confirmation, regardless of +the permissions of the file to which it refers. +Suppress diagnostic messages regarding non-existent +operands. +.Tp Fl i +Write a prompt to the standard error output +requesting confirmation before removing each existing +directory entry, regardless of the permissions +of the file to which it refers. +.Tp Fl R +Permit directories to be removed. +.Pp +.Tp Fl r +Equivalent to +.FL R. +.Tp +.Pp +The following operands are available: +.Tw Fl +.Tp Ar file +A pathname of a directory entry to be removed. +.Tp +.Pp +The +.Nm rm +utility exits with one of the following values: +.Tw Ds +.Tp Li 0 +All the named directory entries were removed. +.Tp Li >0 +An error occurred. +.Tp +.Sh ENVIRONMENT +.Sh SEE ALSO +.Sh STANDARDS +The +.Nm rm +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/bin/rmail/rmail.8 b/usr/src/bin/rmail/rmail.8 index 43b9de217b..1b8b7598f7 100644 --- a/usr/src/bin/rmail/rmail.8 +++ b/usr/src/bin/rmail/rmail.8 @@ -1,35 +1,42 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)rmail.8 6.3 (Berkeley) %G% +.\" @(#)rmail.8 6.4 (Berkeley) %G% .\" -.TH RMAIL 1 "" -.UC 5 -.SH NAME -rmail \- handle remote mail received via uucp -.SH SYNOPSIS -.B rmail -user ... -.SH DESCRIPTION -.I Rmail +.Dd +.Dt RMAIL 1 +.Os BSD 4.2 +.Sh NAME +.Nm rmail +.Nd handle remote mail received via uucp +.Sh SYNOPSIS +.Nm rmail +.Ar user ... +.Sh DESCRIPTION +.Nm Rmail interprets incoming mail received via -.IR uucp (1C), +.Xr uucp 1 , collapsing ``From'' lines in the form generated -by -.IR binmail (1) +by +.Xr binmail 1 into a single line of the form ``return-path!sender'', and passing the processed mail on to -.IR sendmail (8). -.PP -.I Rmail -is explicitly designed for use with -.I uucp +.Xr sendmail 8 . +.Pp +.Nm Rmail +is explicitly designed for use with +.Xr uucp and -.IR sendmail . -.SH "SEE ALSO" -binmail(1), uucp(1), sendmail(8) -.SH BUGS -.I Rmail +.Xr sendmail . +.Sh SEE ALSO +.Xr binmail 1 , +.Xr uucp 1 , +.Xr sendmail 8 +.Sh HISTORY +.Nm Rmail +aapeared in 4.2 BSD. +.Sh BUGS +.Nm Rmail should not reside in /bin. diff --git a/usr/src/libexec/mail.local/mail.local.8 b/usr/src/libexec/mail.local/mail.local.8 index 097fa90858..dd3b3e351e 100644 --- a/usr/src/libexec/mail.local/mail.local.8 +++ b/usr/src/libexec/mail.local/mail.local.8 @@ -1,4 +1,4 @@ -.\" @(#)mail.local.8 6.2 (Berkeley) %G% +.\" @(#)mail.local.8 6.3 (Berkeley) %G% .\" .TH DELIVERMAIL 1 "" .AT 3 diff --git a/usr/src/old/adb/common_source/adb.1 b/usr/src/old/adb/common_source/adb.1 index f042c48bd4..3321b17ba1 100644 --- a/usr/src/old/adb/common_source/adb.1 +++ b/usr/src/old/adb/common_source/adb.1 @@ -1,802 +1,1013 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)adb.1 5.6 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH ADB 1 "" -.UC 4 -.SH NAME -adb \- debugger -.SH SYNOPSIS -.B adb -[ \fB\-w\fR ] [ \fB\-k\fR ] [ \fB-I\fRdir ] [ objfil [ corfil ] ] -.ds TW \v'.25m'\s+2~\s-2\v'-.25m' -.ds ST * -.ds IM \v'.1m'=\v'-.1m'\s-2\h'-.1m'>\h'.1m'\s+2 -.ds LE \(<= -.ds LT \s-2<\s+2 -.ds GT \s-2>\s+2 -.SH DESCRIPTION -.I Adb +.\" @(#)adb.1 5.7 (Berkeley) %G% +.\" +.Dd +.Dt ADB 1 +.Os BSD 4 +.Sh NAME +.Nm adb +.Nd debugger +.Sh SYNOPSIS +.Nm adb +.Op Fl w +.Op Fl k +.Oo +.Op Fl I Ar dir +.Oo +.Op Ar objfil Op Ar corfil +.Sh DESCRIPTION +.Nm Adb is a general purpose debugging program. It may be used to examine files and to provide a controlled environment for the execution of UNIX programs. -.PP -.I Objfil +.Pp +.Ar Objfil is normally an executable program file, preferably containing a symbol table; if not then the symbolic features of -.I adb +.Nm adb cannot be used although the file can still be examined. The default for -.I objfil +.Ar objfil is -.B a.out. -.I Corfil +.Pa a.out . +.Ar Corfil is assumed to be a core image file produced after executing -.IR objfil ; +.Ar objfil ; the default for -.I corfil +.Ar corfil is -.B core. -.PP +.Pa core +.Pp Requests to -.I adb +.Nm adb are read from the standard input and responses are to the standard output. If the -.B \-w +.Fl w flag is present then both -.I objfil +.Ar objfil and -.I corfil +.Ar corfil are created if necessary and opened for reading and writing so that files can be modified using -.IR adb . -.PP -The \fB\-k\fP option makes \fIadb\fP do UNIX kernel memory -mapping; it should be used when \fIcore\fP is a UNIX crash dump -or \fI/dev/mem\fP. -.PP -The \fB\-I\fP option specifies a directory where files to be read -with $< or $<< (see below) will be sought; the default is -.IR /usr/lib/adb . -.PP -.I Adb -ignores QUIT; INTERRUPT causes return to the next -.I adb +.Nm adb . +.Pp +The +.Fl k +option makes +.Nm adb +do UNIX kernel memory +mapping; it should be used when +.Pa core +is a UNIX crash dump +or +.Pa /dev/mem . +.Pp +The +.Fl I +option specifies a directory where files to be read +with +.Li $< +or +.Li $<< +(see below) will be sought; the default is +.Pa /usr/lib/adb . +.Pp +.Nm Adb +ignores +.Li QUIT ; +.Li INTERRUPT +causes return to the next +.Nm adb command. -.PP +.Pp In general requests to -.I adb +.Nm adb are of the form -.PP -.if n .ti 16 -.if t .ti 1.6i -[\|\fIaddress\fR\|] [\|, -.IR count \|] -[\|\fIcommand\fR\|] [\|;\|] -.PP +.Pp +.ti +\n(Dsu +.Op Ad address +.Op \&, Va count +.Op Ic command +.Op \&; +.Pp If -.I address +.Ad address is present then -.I dot +.Ad dot is set to -.IR address . +.Ad address . Initially -.I dot +.Ad dot is set to 0. For most commands -.I count +.Va count specifies how many times the command will be executed. The default -.I count +.Va count is 1. -.I Address +.Ad Address and -.I count +.Va count are expressions. -.PP +.Pp The interpretation of an address depends on the context it is used in. If a subprocess is being debugged then addresses are interpreted in the usual way in the address space of the subprocess. If the operating system is being debugged either post-mortem or using the special file -.I /dev/mem +.Pa /dev/mem to interactively examine and/or modify memory, the maps are set to map -the kernel virtual addresses which start at 0x80000000 (on the VAX); see -.SM ADDRESSES. -.SH EXPRESSIONS -.TP 7.2n -.B . +the kernel virtual addresses which start at +.Li \&0x80000000 +(on the VAX); see ADDRESSES below. +.Sh EXPRESSIONS +.Tw Li +.Tp Sy \&\. The value of -.IR dot . -.TP 7.2n -+ +.Ad dot . +.Tp Sy \&\+ The value of -.I dot +.Ad dot incremented by the current increment. -.TP 7.2n -^ +.Tp Sy \&^ The value of -.I dot +.Ad dot decremented by the current increment. -.TP 7.2n -" +.Tp Sy \&" The last -.I address +.Ad address typed. -.TP 7.2n -.I integer -A number. The prefixes 0o and 0O (\*(lqzero oh\*(rq) force interpretation -in octal radix; the prefixes 0t and 0T force interpretation in -decimal radix; the prefixes 0x and 0X force interpretation in -hexadecimal radix. Thus 0o20 = 0t16 = 0x10 = sixteen. +.Tp Va integer +A number. The prefixes +.Li \&0o +and +.Li \&0O +(\*(lqzero oh\*(rq) +force interpretation +in octal radix; the prefixes +.Li 0t +and +.Li 0T +force interpretation in +decimal radix; the prefixes +.Li 0x +and +.Li 0X +force interpretation in +hexadecimal radix. Thus +.Li 0o20 += +.Li 0t16 += +.Li 0x10 += sixteen. If no prefix appears, then the -.I default\ radix -is used; see the $d command. The default radix is initially hexadecimal. -The hexadecimal digits are 0123456789abcdefABCDEF with the obvious +.Em default radix +is used; see the +.Li $d +command. The default radix is initially hexadecimal. +The hexadecimal digits are +.Li 0123456789abcdefABCDEF +with the obvious values. Note that a hexadecimal number whose most significant -digit would otherwise be an alphabetic character must have a 0x -(or 0X) prefix (or a leading zero if the default radix is hexadecimal). -.TP 7.2n -.IB integer . fraction +digit would otherwise be an alphabetic character must have a +.Li 0x +(or +.Li 0X ) +prefix (or a leading zero if the default radix is hexadecimal). +.Tp Va integer.fraction A 32 bit floating point number. -.TP 7.2n -.I \'cccc\|\' +.Tp Li \'cccc\' The ASCII value of up to 4 characters. -\e may be used to escape a \'. -.TP 7.2n -.I \*(LT name +.Li \e +may be used to escape a +.Li \' . +.Tp Va < name The value of -.IR name , +.Va name , which is either a variable name or a register name. -.I Adb +.Nm Adb maintains a number of variables (see -.SM VARIABLES\*S) +VARIABLES below) named by single letters or digits. If -.I name +.Va name is a register name then the value of the register is obtained from the system header in -.IR corfil . -The register names are those printed by the $r command. -.TP 7.2n -.I symbol +.Ar corfil . +The register names are those printed by the +.Li $r +command. +.Tp Va symbol A -.I symbol +.Va symbol is a sequence of upper or lower case letters, underscores or digits, not starting with a digit. The backslash character -.B \e +.Li \e may be used to escape other characters. The value of the -.I symbol +.Va symbol is taken from the symbol table in -.IR objfil . -An initial \_ will be prepended to -.I symbol +.Ar objfil . +An initial +.Li \_ +will be prepended to +.Va symbol if needed. -.TP -.I _ symbol -In C, the `true name' of an external symbol begins with _. +.Tp Va _symbol +In C, the `true name' of an external symbol begins with +.Li \_ . It may be necessary to utter this name to distinguish it from internal or hidden variables of a program. -.TP 7.2n -.IB routine . name +.Tp Va routine.name The address of the variable -.I name +.Va name in the specified C routine. Both -.I routine +.Va routine and -.I name +.Va name are -.IR symbols . +.Va symbols . If -.I routine +.Va routine is omitted, the currently active frame is used. (This form is currently broken; local variables can be examined only with -.IR dbx (1).) +.Xr dbx 1 ) . If -.I name +.Va name is omitted the value is the address of the most recently activated C stack frame corresponding to -.I routine +.Va routine (this much works). -.TP 7.2n -.RI ( exp \|) +.Tp (exp) +.\" .Tp Cx \&(\& +.\" .Va exp +.\" .Cx \&)\& The value of the expression -.IR exp . -.LP -.SM -.B "Monadic\ operators" -.TP 7.2n -.RI \*(ST exp +.Va exp . +.Tp +.Pp +.Ss Monadic Operators +.Pp +.Dp Cx Li \&* +.Va exp +.Cx The contents of the location addressed by -.I exp +.Va exp in -.IR corfil . -.TP 7.2n -.RI @ exp +.Ar corfil . +.Dp Cx Li \&@ +.Va exp +.Cx The contents of the location addressed by -.I exp +.Va exp in -.IR objfil . -.TP 7.2n -.RI \- exp +.Ar objfil . +.Dp Cx Li \&\- +.Va exp +.Cx Integer negation. -.TP 7.2n -.RI \*(TW exp +.Dp Cx Li \&~ +.Va exp +.Cx Bitwise complement. -.TP 7.2n -.RI # exp +.Dp Cx Li \&# +.Va exp +.Cx Logical negation. -.LP -.tr '' -.B "Dyadic\ operators" +.Dp +.Ss Dyadic operators are left associative and are less binding than monadic operators. -.TP 7.2n -.IR e1 + e2 +.Dp Cx Va e1 +.Li \&\+ +.Va e2 +.Cx Integer addition. -.TP 7.2n -.IR e1 \- e2 +.Dp Cx Va e1 +.Li \&\- +.Va e2 +.Cx Integer subtraction. -.TP 7.2n -.IR e1 \*(ST e2 +.Dp Cx Va e1 +.Li \&* +.Va e2 +.Cx Integer multiplication. -.TP 7.2n -.IR e1 % e2 +.Dp Cx Va e1 +.Li \&% +.Va e2 +.Cx Integer division. -.TP 7.2n -.IR e1 & e2 +.Dp Cx Va e1 +.Li & +.Va e2 +.Cx Bitwise conjunction. -.TP 7.2n -.IR e1 \(bv e2 +.Dp Cx Va e1 +.Li \&| +.Va e2 +.Cx Bitwise disjunction. -.TP 7.2n -.IR e1 # e2 -.I E1 +.Dp Cx Va e1 +.Li # +.Va e2 +.Cx +.Va E1 rounded up to the next multiple of -.IR e2 . -.DT -.SH COMMANDS +.Va e2 . +.Dp +.Sh COMMANDS Most commands consist of a verb followed by a modifier or list of modifiers. The following verbs are available. -(The commands `?' and `/' may be followed by `\*(ST'; see -.SM ADDRESSES +(The commands +.Ic ? +and +.Li / +may be followed by +.Li * ; +see the +ADDRESSES section for further details.) -.TP .5i -.RI ? f +.Tw XXX +.Tp Cx Ic ? +.Va f +.Cx Locations starting at -.I address +.Ad address in -.I objfil +.Ar objfil are printed according to the format -.IR f . -.I dot +.Va f . +.Ad dot is incremented by the sum of the increments for each format letter (q.v.). -.TP -.RI / f +.Tp Cx Ic / +.Va f +.Cx Locations starting at -.I address +.Ad address in -.I corfil +.Ar corfil are printed according to the format -.I f +.Va f and -.I dot -is incremented as for `?'. -.TP -.RI = f +.Ad dot +is incremented as for +.Ic ? . +.Tp Cx Ic = +.Va f +.Cx The value of -.I address +.Ad address itself is printed in the styles indicated by the format -.IR f . +.Va f . (For -.B i +.Va i format zero values are assumed for the parts of the instruction that reference subsequent words.) -.PP +.Tp +.Pp A -.I format +.Va format consists of one or more characters that specify a style of printing. Each format character may be preceded by a decimal integer that is a repeat count for the format character. While stepping through a format -.I dot +.Ad dot is incremented by the amount given for each format letter. If no format is given then the last format is used. The format characters available are as follows. -Note that a backslash (\e) must be used +Note that a backslash +.Cx ( +.Li \e +.Cx ) +.Cx +must be used to quote the three numeric formats. -.de f1 -.TP -.BR "\\$1" " \\$2" -.. -.de fR -.br -.ns -.TP -.BR "\\$1" " \\$2" -.. -.de fI -.br -.ns -.TP -.BI "\\$1" " \\$2" -.. -.de f -.br -.ns -.TP -\\$1 -.. -.ta 2.5n .5i -.RS -.f1 1 1 +.Dw \&M_____\&M +.Dp Cx Ic 1 +.Cx \&\ \ \& +.Va 1 +.Cx Print 1 byte in the current radix -(which may be either signed or unsigned; see the $d command). -.fR 2 2 +(which may be either signed or unsigned; see the +.Li $d +command). +.Dp Cx Ic 2 +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in the current radix. -.fR 4 4 +.Dp Cx Ic 4 +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in the current radix. -.fR v 2 +.Dp Cx Ic v +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in the signed variant of the current radix. -.fR V 4 +.Dp Cx Ic V +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in the signed variant of the current radix. -.fR o 2 +.Dp Cx Ic o +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in unsigned octal. All octal numbers output by -.I adb +.Nm adb are preceded by 0. -.fR O 4 +.Dp Cx Ic O +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in unsigned octal. -.fR q 2 +.Dp Cx Ic q +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in signed octal. -.fR Q 4 +.Dp Cx Ic Q +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in signed octal. -.fR u 2 +.Dp Cx Ic u +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in unsigned decimal. -.fR U 4 +.Dp Cx Ic U +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in long unsigned decimal. -.fR d 2 +.Dp Cx Ic d +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in signed decimal. -.fR D 4 +.Dp Cx Ic D +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in long signed decimal. -.fR x 2 +.Dp Cx Ic x +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in unsigned hexadecimal. -.fR X 4 +.Dp Cx Ic X +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in unsigned hexadecimal. -.fR z 2 +.Dp Cx Ic z +.Cx \&\ \ \& +.Va 2 +.Cx Print 2 bytes in signed hexadecimal. -.fR Z 4 +.Dp Cx Ic Z +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in signed hexadecimal. -.fR f 4 +.Dp Cx Ic f +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes as a floating point number. -.fR F 8 +.Dp Cx Ic F +.Cx \&\ \ \& +.Va 8 +.Cx Print 8 bytes as a double floating point number. -.fR b 1 +.Dp Cx Ic b +.Cx \&\ \ \& +.Va 1 +.Cx Print 1 byte in unsigned octal. -.fR c 1 +.Dp Cx Ic c +.Cx \&\ \ \& +.Va 1 +.Cx Print 1 byte as a character. -.fR C 1 +.Dp Cx Ic C +.Cx \&\ \ \& +.Va 1 +.Cx Print 1 byte as a character, using the standard escape convention where control characters are printed as ^X and the delete character is printed as ^?. -.fI s n +.Dp Cx Ic s +.Cx \&\ \ \& +.Va n +.Cx Print the addressed characters until a zero character is reached. -.fI S n -Print a string using the ^\fIX\fR escape convention (see \fBC\fR above). -.I n +.Dp Cx Ic S +.Cx \&\ \ \& +.Va n +.Cx +Print a string using the ^ +.Ar X +escape convention (see +.Ar C +above). +.Ar n is the length of the string including its zero terminator. -.fR Y 4 +.Dp Cx Ic Y +.Cx \&\ \ \& +.Va 4 +.Cx Print 4 bytes in date format (see -.IR ctime (3)). -.fR i n +.Xr ctime 3 ) . +.Dp Cx Ic i +.Cx \&\ \ \& +.Va n +.Cx Print as machine instructions. -.I n +.Ar n is the number of bytes occupied by the instruction. This style of printing causes the numeric variables 1, 2, ... to be set according to the offset parts of the arguments, if any, of the instruction (up to 6 on the VAX). -.fR a 0 +.Dp Cx Ic a +.Cx \&\ \ \& +.Va 0 +.Cx Print the value of -.I dot +.Ad dot in symbolic form. Symbols are checked to ensure that they have an appropriate type as indicated below. -.LP - / local or global data symbol -.br - ? local or global text symbol -.br - = local or global absolute symbol -.f1 p 4 +.Dw AAAA +.Dp Va / +local or global data symbol +.Dp Va \&? +.Cx +local or global text symbol +.Dp Va \&= +.Cx +local or global absolute symbol +.Dp +.Dp Cx Ic p +.Cx \&\ \ \& +.Va 4 +.Cx Print the addressed value in symbolic form using the same rules for symbol lookup as -.BR a . -.fR t 0 +.Ic a . +.Dp Cx Ic t +.Cx \&\ \ \& +.Va 0 +.Cx When preceded by an integer tabs to the next appropriate tab stop. For example, -.B 8t +.Li 8t moves to the next 8-space tab stop. -.fR r 0 +.Dp Cx Ic r +.Cx \&\ \ \& +.Va 0 +.Cx Print a space. -.fR n 0 +.Dp Cx Ic n +.Cx \&\ \ \& +.Va 0 +.Cx Print a newline. -.tr '" -.fR '...' 0 +.Dp Ic \*(Rq...\*(Lq +.Va 0 +\&\ \ \& Print the enclosed string. -.tr '' -.f ^ -.I Dot +.Dp ^ +.Ad Dot is decremented by the current increment. Nothing is printed. -.f + -.I Dot +.Dp + +.Ad Dot is incremented by 1. Nothing is printed. -.f \- -.I Dot +.Dp \- +.Ad Dot is decremented by 1. Nothing is printed. -.RE -.TP -newline +.Dp newline Repeat the previous command with a -.I count +.Va count of 1. -.rm f -.rm fI -.rm fB -.rm f1 -.TP -.RB [ ?/ ] l "\fI value mask\fR" +.Dp +.Pp +.Tw $modifier +.Tp Cx Op Ic ?/ +.Ic l\ \& +.Va value mask +.Cx Words starting at -.I dot +.Ad dot are masked with -.I mask -and compared with -.I value +.Va mask +and +compared with +.Va value until a match is found. If -.B L +.Cm L is used then the match is for 4 bytes at a time instead of 2. If no match is found then -.I dot +.Ad dot is unchanged; otherwise -.I dot +.Ad dot is set to the matched location. If -.I mask +.Va mask is omitted then all bits are compared. -.TP -.RB [ ?/ ] w "\fI value ...\fR" +.Tp Cx Op Ic ?/ +.Ic w\ \& +.Va value ... +.Cx Write the 2-byte -.I value +.Va value into the addressed location. If the command is -.BR W , +.Ic W , write 4 bytes. -Odd addresses \fIare\fP allowed +Odd addresses +.Em are +allowed when writing to the subprocess address space. -.TP -[\fB?/\fR]\fBm\fI b1 e1 f1\fR[\fB?/\fR] -.br +.Tp Cx Op Ic ?/ +.Ic m\ \& +.Ad b1 e1 f1 +.Op Ic ?/ +.Cx New values for -.RI ( b1,\ e1,\ f1 ) +.Ad ( b1 , e1 , f1 ) are recorded. If less than three expressions are given then the remaining map parameters are left unchanged. -If the `?' or `/' is followed by `\*(ST' then -the second segment (\fIb2\fR\|,\|\fIe2\fR\|,\|\fIf2\fR) +If the +.Ic ? +or +.Ic / +is followed by +.Li * +then +the second segment ( +.Ad ( b2 , e2 , f2 ) of the mapping is changed. -If the list is terminated by `?' or `/' then the file (\fIobjfil\fR or -.I corfil +If the list is terminated by +.Ic ? +or +.Ic / +then the file +.Ar ( objfil +or +.Ar corfil respectively) is used for subsequent requests. -For example, `/m?' will cause `/' to refer to -.IR objfil . -.TP -.BI \*(GT name -.I Dot +For example, +.Li /m? +will cause +.Ic / +to refer to +.Ar objfil . +.Tp Cx Ic > +.Va name +.Cx +.Ad Dot is assigned to the variable or register named. -.TP -.B ! -A shell (/bin/sh) is called to read the rest of the line following `!'. -.TP -.RI $ modifier -Miscellaneous commands. The available -.I modifiers +.Tp Ic \&! +A shell +.Cx \&( +.Pa /bin/sh ) +.Cx +is called to read the rest of the line following +.Ic \&! . +.Tp Cx Cm $ +.Va modifier +.Cx +Miscellaneous commands. The available +.Va modifiers are: -.de f -.br -.ns -.TP -.. -.RS -.TP -.BI < f -Read commands from the file -.IR f . +.Tw fil +.Tp Cx Cm < +.Va file +.Cx +Read commands from +.Va file If this command is executed in a file, further commands in the file are not seen. If -.I f +.Va file is omitted, the current input stream is terminated. If a -.I count +.Va count is given, and is zero, the command will be ignored. The value of the count will be placed in variable -.I 9 +.Va 9 before the first command in -.I f +.Va file is executed. -.f -.BI << f +.Tp Cx Cm << +.Va file +.Cx Similar to -.B < +.Cm < except it can be used in a file of commands without causing the file to be closed. Variable -.I 9 +.Va 9 is saved during the execution of this command, and restored when it completes. There is a (small) finite limit to the number of -.B << +.Cm << files that can be open at once. -.f -.BI > f +.Tp Cx Cm > +.Va file +.Cx Append output to the file -.IR f , +.Va file , which is created if it does not exist. If -.I f +.Va file is omitted, output is returned to the terminal. -.f -.B ? +.Tp Cx Cm ? +.Va file +.Cx Print process id, the signal which caused stoppage or termination, -as well as the registers as \fB$r\fR. This is the default if -\fImodifier\fR is omitted. -.f -.B r +as well as the registers as +.Ic $r . +This is the default if +.Va modifier +is omitted. +.Tp Cm r Print the general registers and the instruction addressed by -.BR pc . -.I Dot -is set to \fBpc\fR. -.f -.B b +.Nm pc . +.Ad Dot +is set to +.Nm pc . +.Tp Cm b Print all breakpoints and their associated counts and commands. -.f -.B c +.Tp Cm c C stack backtrace. If -.I address -is given then it is taken as the address of the current frame +.Ad address +is given then it is taken as the address of the current frame instead of the contents of the frame\-pointer register. If -.B C +.Cm C is used then the names and (32 bit) values of all automatic and static variables are printed for each active function (this is partially broken; the names are not now available). If -.I count +.Va count is given then only the first -.I count +.Va count frames are printed. -.f -.B d +.Tp Cm d Set the default radix to -.I address +.Ad address and report the new value. If no -.I address +.Ad address is given, the default radix is not changed. The new radix must be between -16 (decimal) and 16 (decimal) and must not be 0, 1, or -1. A negative radix implies that numbers printed in that radix will be treated as signed; otherwise they are treated as unsigned. Note that -.I address +.Ad address is interpreted in the (old) current radix. Thus \*(lq10$d\*(rq simply changes the default radix to unsigned. To make signed decimal the default radix, use \*(lq-0t10$d\*(rq. -.f -.B e +.Tp Cm e The names and values of external variables are printed. -.f -.B w +.Tp Cm w Set the page width for output to -.I address +.Ad address (default 80). -.f -.B s +.Tp Cm s Set the limit for symbol matches to -.I address +.Ad address (default 1024). -.f -.B q +.Tp Cm q Exit from -.IR adb . -.f -.B v +.Nm adb . +.Tp Cm v Print all non zero variables in octal. -.f -.B m +.Tp Cm m Print the address map. -.f -.B p -.RI ( "Kernel debugging" ) -Change the current kernel memory mapping to map the designated -.B "user structure" +.Tp Cm p +.Em ( Kernel debugging ) +Change the current kernel memory mapping to map the designated +.Sy user structure to the address given by the symbol -.I "_u." +.Sy _u . The -.I address +.Ad address argument is the address of the user's user page table entries. -.RE -.TP -.BI : modifier +.Tp +.Tp Cx Cm : +.Va modifier +.Cx Manage a subprocess. Available modifiers are: -.RS -.TP -.BI b c +.Tw Ds +.Tp Cx Cm b +.Va c +.Cx Set breakpoint at -.IR address . +.Ad address . The breakpoint is executed -.IR count \-1 +.Va count\-1 times before causing a stop, after which it stops unconditionally. Each time the breakpoint is encountered the command -.I c +.Va c is executed. If this command is omitted or sets -.I dot +.Ad dot to zero, the breakpoint causes a stop immediately, regardless of any remaining count. -.TP -.B d +.Tp Cm d Delete breakpoint at -.IR address . -.TP -.B D +.Ad address . +.Tp Cm D Delete all breakpoints. -.TP -.B r +.Tp Cm r Run -.I objfil +.Ar objfil as a subprocess. If -.I address +.Ad address is given explicitly then the program is entered at this point; otherwise the program is entered at its standard entry point. -.I count +.Va count specifies how many breakpoints are to be ignored before stopping. Arguments to the subprocess may be supplied on the same line as the command. An argument starting with < or > causes the standard input or output to be established for the command. -.TP -.BI c s +.Tp Cx Cm c +.Va s +.Cx The subprocess is continued with signal -.I s, +.Va s see -.IR sigvec (2). +.Xr sigvec 2 . If -.I address +.Ad address is given then the subprocess is continued at this address. If no signal is specified then the signal that caused the subprocess to stop is sent. Breakpoint skipping is the same as for -.BR r . -.TP -.BI s s +.Cm r . +.Tp Cx Cm s +.Va s +.Cx As for -.B c +.Cm c except that the subprocess is single stepped -.I count +.Va count times. If there is no current subprocess then -.I objfil +.Ar objfil is run as a subprocess as for -.BR r . +.Cm r . In this case no signal can be sent; the remainder of the line is treated as arguments to the subprocess. -.TP -.B k +.Tp Cm k The current subprocess, if any, is terminated. -.RE -.SH VARIABLES -.I Adb +.Tp +.Tp +.Sh VARIABLES +.Nm Adb provides a number of variables. Named variables are set initially by -.I adb +.Nm adb but are not used subsequently. Numbered variables are reserved for communication as follows. -.TP -0 +.Dw Ds +.Di L +.Dp \&0 The last value printed. -.f -1 +.Dp \&1 The last offset part of an instruction source. This continues up through at most 6 on the VAX. For a three-operand instruction, variable 2 is the second source offset and variable 3 the destination offset part. -.f -9 +.Dp \&9 The count on the last $< or $<< command. -.PP +.Dp On entry the following are set from the system header in the -.IR corfil . +.Ar corfil . If -.I corfil +.Ar corfil does not appear to be a -.B core +.Pa core file then these values are set from -.IR objfil . -.TP -b +.Ar objfil . +.Dw Ds +.Di L +.Dp b The base address of the data segment. -.f -d +.Dp d The data segment size. -.f -e +.Dp e The entry point. -.f -m +.Dp m The `magic' number (0407, 0410 or 0413). -.f -s +.Dp s The stack segment size. -.f -t +.Dp t The text segment size. -.SH ADDRESSES +.Sh ADDRESSES The address in a file associated with a written address is determined by a mapping associated with that file. Each mapping is represented by two triples -.RI ( "b1, e1, f1" ) +.Ad ( b1 , e1 , f1 ) and -.RI ( "b2, e2, f2" ) +.Ad ( b2 , e2 , f2 ) and the -.I file address +.Ad file +.Ad address corresponding to a written -.I address +.Ad address is calculated as follows. -.PP -.if t .ti 1.5i -.if n .ti 8 -.IR b1 \*(LE address < e1 -\*(IM -.IR "file address" = address + f1\-b1, -otherwise, -.PP -.if t .ti 1.5i -.if n .ti 8 -.IR b2 \*(LE address < e2 -\*(IM -.IR "file address" = address + f2\-b2, -.PP +.Pp +.Ds I +.Cx Ad b1 +.Sy \&\*(<= +.Ad address +.Sy < +.Ad e1 +.Sy \ \&\(->\ \& +.Ad file address +.Sy = +.Ad address +.Sy + +.Ad f1 +.Sy \- +.Ad b1 , +.Cx \ \& +.Cx otherwise, +.Cx +.De +.Pp +.Ds I +.Cx Ad b2 +.Sy \&\*(<= +.Ad address +.Sy < +.Ad e2 +.Sy \ \&\(->\ \& +.Ad file address +.Sy = +.Ad address +.Sy + +.Ad f2 +.Sy \- +.Ad b2 , +.Cx +.De +.Pp otherwise, the requested -.I address +.Ar address is not legal. In some cases (e.g. for programs with separated I and D space) the two segments for a file may overlap. If a -.B ? +.Ic ? or -.B / +.Ic / is followed by an -.B \*(ST +.Ic * then only the second triple is used. -.PP +.Pp The initial setting of both mappings is suitable for normal -.B a.out +.Pa a.out and -.B core +.Pa core files. If either file is not of the kind expected then, for that file, -.I b1 -is set to 0, -.I e1 +.Ad b1 +is set to +.Li 0 , +.Ad e1 is set to the maximum file size and -.I f1 +.Ad f1 is set to 0; in this way the whole file can be examined with no address translation. -.PP -.SH FILES -a.out -.br -core -.SH SEE\ ALSO -cc(1), -dbx(1), -ptrace(2), -a.out(5), -core(5) -.SH DIAGNOSTICS -`Adb' when there is no current command or format. +.Pp +.Sh FILES +.Dw a.out +.Dp Pa a.out +.Dp Pa core +.Dp +.Sh SEE ALSO +.Xr cc 1 , +.Xr dbx 1 , +.Xr ptrace 2 , +.Xr a.out 5 , +.Xr core 5 +.Sh HISTORY +.Nm Adb +was first released with Version 7 AT&T UNIX. The version +of +.Nm adb +this man page describes +is descended from the orignial. +.Sh DIAGNOSTICS +.Li `adb' +when there is no current command or format. Comments about inaccessible files, syntax errors, abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned nonzero status. -.SH BUGS +.Sh BUGS Since no shell is invoked to interpret the arguments of the -.B :r +.Ic :r command, the customary wild-card and variable expansions cannot occur. diff --git a/usr/src/old/as.vax/as.1 b/usr/src/old/as.vax/as.1 index 643697fca6..96f79432b4 100644 --- a/usr/src/old/as.vax/as.1 +++ b/usr/src/old/as.vax/as.1 @@ -1,109 +1,123 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)as.1 6.3 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH AS 1 "" -.UC 4 -.SH NAME -as \- VAX-11 assembler -.SH SYNOPSIS -.B as -[ -.B \-a1-16 -] [ -[ -.B \-d124 -] [ -.B \-L -] [ -.B \-W -] [ -.B \-V -] [ -.B \-J -] [ -.B \-R -] [ -.B \-t -directory -] [ -.B \-o -objfile ] [ name ... ] -.SH DESCRIPTION -.I As -assembles the named files, or the standard input if no file name is specified. -The available flags are: -.TP -.B \-a -Specifies the alignment of procedures and data blocks. +.\" @(#)as.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt AS 1 +.Os BSD 4 +.Sh NAME +.Nm as +.Nd VAX-11 assembler +.Sh SYNOPSIS +.Nm as +.Op Fl \&a Ar val +.Op Fl \&d Ar bytes +.Op Fl \&L +.Op Fl \&W +.Op Fl \&V +.Op Fl \&J +.Op Fl \&R +.Op Fl \&t Ar directory +.Op Fl \&o Ar outfile +.Op Ar source_file(s) +.Sh DESCRIPTION +The +.Nm as +assembler produces an object file from the given source files +or from the standard input. +.Tp Fl a +Specifies the alignment +.Ar value +of procedures and data blocks. It is given as a power of two; thus an alignment of 3 causes alignment on an eight byte boundary. The default is -.B \-a2. -.TP -.B \-d -Specifies the number of bytes to be assembled for offsets -which involve forward or external references, and which have sizes unspecified -in the assembly language. -The default is -.B \-d4. -.TP -.B \-L -Save defined labels beginning with a `L', which are normally discarded +.Cx Fl a +.Li 2 +.Cx , +.Cx +the minumum value is +.Li 1 , +the maximum value +.Li 16 . +.Tp Fl d +Displacement offset in bytes for displacement values +not defined in the first pass or unspecified in the assembly language. +Possible values are +.Li 1 , 2 , +or +.Li 4 . +The default is +.Cx Fl d +.Li 4 +.Cx , +.Cx +if +.Fl d +is not given. +.Tp Fl L +Save defined labels beginning with a +\*(LqL\*(Rq, which are normally discarded to save space in the resultant symbol table. The compilers generate such temporary labels. -.TP -.B \-V +.Tp Fl V Use virtual memory for some intermediate storage, rather than a temporary file. -.TP -.B \-W +.Tp Fl W Do not complain about errors. -.TP -.B \-J +.Tp Fl J Use long branches to resolve jumps when byte-displacement branches are insufficient. This must be used when a compiler-generated assembly contains branches of more than 32k bytes. -.TP -.B \-R +.Tp Fl R Make initialized data segments read-only, by concatenating them to the text segments. This obviates the need to run editor scripts on assembly code to make initialized data read-only and shared. -.TP -.B \-t +.Tp Fl t Specifies a directory to receive the temporary file, other than the default /tmp. -.PP -All undefined symbols in the assembly -are treated as global. -.PP -The output of the assembly is left on the file -.I objfile; -if that is omitted, -.I a.out -is used. -.SH FILES -.ta 1.5i -/tmp/as\(** default temporary files -.br -a.out default resultant object file -.SH "SEE ALSO" -ld(1), -nm(1), -adb(1), -dbx(1), -a.out(5) -.br +.Tp +.Pp +Symbols remaining undefined upon completion are assumed global +.Pp +Output is either placed in +.Ar outfile, +if given, or sent +placed in +.Pa a.out . +.Sh FILES +.Dw /tmp/as* +.Di L +.Dp Pa tmp/as\(** +default temporary files +.Dp Pa a.out +default resultant object file +.Dp +.Sh SEE ALSO +.Xr a.out 5 , +.Xr adb 1 , +.Xr dbx 1 , +.Xr ld 1 , +.Xr nm 1 +.Pp Auxiliary documentation -.I Assembler Reference Manual. -.SH AUTHORS +.Em Assembler Reference Manual . +.Sh AUTHORS John F. Reiser .br Robert R. Henry -.SH BUGS -.B \-J +.Sh HISTORY +The +.Nm As +appeared as a PDP11 +assembler in Version 6 AT&T UNIX. It has been hacked a bit +at various times to accomodate different DEC hardware, including this +VAX version. +.Sh BUGS +.Fl J should be eliminated; the assembler should automatically choose among byte, word and long branches. diff --git a/usr/src/old/awk/awk.1 b/usr/src/old/awk/awk.1 index bd9d9e0788..9da319d023 100644 --- a/usr/src/old/awk/awk.1 +++ b/usr/src/old/awk/awk.1 @@ -1,73 +1,101 @@ -.\" @(#)awk.1 6.1 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH AWK 1 "" -.AT 3 -.SH NAME -awk \- pattern scanning and processing language -.SH SYNOPSIS -.B awk -[ -.BI \-F c -] -[ prog ] [ file ] ... -.SH DESCRIPTION -.I Awk +.\" %sccs.include.redist.man% +.\" +.\" @(#)awk.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt AWK 1 +.Os ATT 7 +.Sh NAME +.Nm awk +.Nd pattern scanning and processing language +.Sh SYNOPSIS +.Nm awk +.Oo +.Op Fl \&F Ar \&c +.Oo +.\".Op Op Fl \&f Ar file Op Ar prog +.Cx \&[ +.Op Fl f Ar file +.Op Ar prog +.Cx \&] +.Cx +.Ar +.Sh DESCRIPTION +.Nm Awk scans each input -.I file +.Ar file for lines that match any of a set of patterns specified in -.IR prog . +.Ar prog . With each pattern in -.I prog +.Ar prog there can be an associated action that will be performed when a line of a -.I file +.Ar file matches the pattern. The set of patterns may appear literally as -.I prog, +.Ar prog or in a file specified as -.B \-f -.IR file . -.PP +.Fl f +.Ar file . +.Pp +.Tw Fl +.Tp Cx Fl F +.Ar c +.Cx +Specify a field separator of +.Ar c . +.Tp Fl f +Use +.Ar file +as an input +.Ar prog +(an awk script). +.Tp +.Pp Files are read in order; if there are no files, the standard input is read. -The file name `\-' +The file name +.Fl means the standard input. Each line is matched against the pattern portion of every pattern-action statement; the associated action is performed for each matched pattern. -.PP +.Pp An input line is made up of fields separated by white space. -(This default can be changed by using FS, -.IR "vide infra" ".)" +(This default can be changed by using +.Li FS , +.Em vide infra . ) The fields are denoted $1, $2, ... ; $0 refers to the entire line. -.PP -.PP +.Pp A pattern-action statement has the form -.PP - pattern { action } -.PP +.Pp +.Dl pattern {action} +.Pp A missing { action } means print the line; a missing pattern always matches. -.PP +.Pp An action is a sequence of statements. A statement can be one of the following: -.PP -.nf - if ( conditional ) statement [ else statement ] - while ( conditional ) statement - for ( expression ; conditional ; expression ) statement - break - continue - { [ statement ] ... } - variable = expression - print [ expression-list ] [ >expression ] - printf format [ , expression-list ] [ >expression ] - next # skip remaining patterns on this input line - exit # skip the rest of the input -.fi -.PP +.Pp +.Ds I +if ( conditional ) statement [ else statement ] +while ( conditional ) statement +for ( expression ; conditional ; expression ) statement +break +continue +{ [ statement ] ... } +variable = expression +print [ expression-list ] [ >expression ] +printf format [, expression-list ] [ >expression ] +next # skip remaining patterns on this input line +exit # skip the rest of the input +.De +.Pp Statements are terminated by semicolons, newlines or right braces. An empty expression-list stands for the whole line. @@ -78,80 +106,96 @@ The C operators ++, \-\-, +=, \-=, *=, /=, and %= are also available in expressions. Variables may be scalars, array elements (denoted -x[i]) +.Cx x +.Op i +.Cx ) +.Cx or fields. Variables are initialized to the null string. Array subscripts may be any string, not necessarily numeric; this allows for a form of associative memory. String constants are quoted "...". -.PP -The -.I print +.Pp +The +.Ic print statement prints its arguments on the standard output -(or on a file if -.I >file +(or on a file if +.Ar \&>file is present), separated by the current output field separator, and terminated by the output record separator. The -.I printf +.Ic printf statement formats its expression list according to the format (see -.IR printf (3S)). -.PP +.Xr printf 3 ) . +.Pp The built-in function -.I length +.Ic length returns the length of its argument taken as a string, or of the whole line if no argument. There are also built-in functions -.I exp, -.I log, -.I sqrt, +.Ic exp , +.Ic log , +.Ic sqrt and -.IR int . +.Ic int . The last truncates its argument to an integer. -.IR substr(s,\ m,\ n) -returns the -.IR n -character +The function +.Cx Ic substr +.Cx ( +.Ar s , +.Ar \& m , +.Ar \& n ) +.Cx +returns the +.Cx Ar n +.Cx \- +.Cx character +.Cx substring of -.I s +.Ar s that begins at position -.IR m . +.Ar m . The function -.IR sprintf(fmt,\ expr,\ expr,\ ...) +.Cx Ic sprintf +.Cx ( +.Ar fmt , +.Ar \& expr , +.Ar \& expr , +.Ar \& ... ) +.Cx formats the expressions according to the -.IR printf (3S) +.Xr printf 3 format given by -.I fmt +.Ar fmt and returns the resulting string. -.PP +.Pp Patterns are arbitrary Boolean combinations -(!, \(or\(or, &&, and parentheses) of +(!, \(or\(or, &&, and parentheses) of regular expressions and relational expressions. Regular expressions must be surrounded by slashes and are as in -.IR egrep . +.Xr egrep 1 . Isolated regular expressions in a pattern apply to the entire line. Regular expressions may also occur in relational expressions. -.PP +.Pp A pattern may consist of two patterns separated by a comma; in this case, the action is performed for all lines between an occurrence of the first pattern and the next occurrence of the second. -.PP -.nf +.Pp A relational expression is one of the following: -.PP -.nf - expression matchop regular-expression - expression relop expression -.PP -.fi +.Ds +expression matchop regular-expression +expression relop expression +.De +.Pp where a relop is any of the six relational operators in C, and a matchop is either ~ (for contains) or !~ (for does not contain). @@ -159,82 +203,94 @@ A conditional is an arithmetic expression, a relational expression, or a Boolean combination of these. -.PP +.Pp The special patterns -BEGIN +.Li BEGIN and -END +.Li END may be used to capture control before the first input line is read and after the last. -BEGIN must be the first pattern, END the last. -.PP +.Li BEGIN +must be the first pattern, +.Li END +the last. +.Pp A single character -.I c +.Ar c may be used to separate the fields by starting the program with -.PP - BEGIN { FS = "c" } -.PP +.Pp +.Dl BEGIN { FS = "c" } +.Pp or by using the -.BI \-F c +.Cx Fl F +.Ar c +.Cx option. -.PP +.Pp Other variable names with special meanings -include NF, the number of fields in the current record; -NR, the ordinal number of the current record; -FILENAME, the name of the current input file; -OFS, the output field separator (default blank); -ORS, the output record separator (default newline); -and -OFMT, the output format for numbers (default "%.6g"). -.PP -.SH EXAMPLES -.PP +include +.Dp Li NF +the number of fields in the current record; +.Dp Li NR +the ordinal number of the current record; +.Dp Li FILENAME +the name of the current input file; +.Dp Li OFS +the output field separator (default blank); +.Dp Li ORS +the output record separator (default newline); +.Dp Li OFMT +the output format for numbers (default "%.6g"). +.Dp +.Pp +.Sh EXAMPLES +.Pp Print lines longer than 72 characters: -.PP -.nf - length > 72 -.fi -.PP +.Pp +.Dl length > 72 +.Pp Print first two fields in opposite order: -.PP -.nf - { print $2, $1 } -.fi -.PP +.Pp +.Dl { print $2, $1 } +.Pp Add up first column, print sum and average: -.PP -.nf - { s += $1 } - END { print "sum is", s, " average is", s/NR } -.fi -.PP +.Pp +.Ds I + { s += $1 } +END { print "sum is", s, " average is", s/NR } +.De +.Pp Print fields in reverse order: -.PP -.nf - { for (i = NF; i > 0; \-\-i) print $i } -.fi -.PP +.Pp +.Dl { for (i = NF; i > 0; \-\-i) print $i } +.Pp Print all lines between start/stop pairs: -.PP -.nf - /start/, /stop/ -.fi -.PP +.Pp +.Dl /start/, /stop/ +.Pp Print all lines whose first field is different from previous one: -.PP -.nf - $1 != prev { print; prev = $1 } -.fi -.SH SEE ALSO -.PP -lex(1), sed(1) -.br +.Pp +.Dl $1 != prev { print; prev = $1 } +.Sh SEE ALSO +.Xr lex 1 , +.Xr sed 1 +.Pp A. V. Aho, B. W. Kernighan, P. J. Weinberger, -.I -Awk \- a pattern scanning and processing language -.SH BUGS +.Em Awk \- a pattern scanning and processing language +.Sh HISTORY +.Nm Awk +appeared in Version 7 AT&T UNIX. A much improved +and true to the book version of +.Nm awk +appeared in the AT&T Toolchest in the late 1980's. +The version of +.Nm awk +this manual page describes +is a derivative of the original and not the Toolchest version. +.Sh BUGS There are no explicit conversions between numbers and strings. To force an expression to be treated as a number add 0 to it; -to force it to be treated as a string concatenate "" +to force it to be treated as a string concatenate +.Dq to it. diff --git a/usr/src/old/cpio/cpio.1 b/usr/src/old/cpio/cpio.1 index 471e211b25..e1296846d2 100644 --- a/usr/src/old/cpio/cpio.1 +++ b/usr/src/old/cpio/cpio.1 @@ -1,118 +1,169 @@ -.\" @(#)cpio.1 5.3 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH CPIO 1 "" -.UC 7 -.SH NAME -cpio - copy file archives in and out -.SH SYNOPSIS -cpio -o [ acBv ] +.\" %sccs.include.redist.man% +.\" +.\" @(#)cpio.1 5.4 (Berkeley) %G% +.\" +.Dd +.\" @(#)cpio.1 5.3 (Berkeley) 3/29/88 +.\" +.Dt CPIO 1 +.Os BSD 4.4 +.Sh NAME +.Nm cpio +.Nd copy file archives in and out +.Sh SYNOPSIS +.Nm cpio +.Fl o +.Op Fl acBv .br -cpio -i [ BcdmrtuvfsSb6 ] [ patterns ] +.Nm cpio +.Fl i +.Op Fl BcdmrtuvfsSb6 +.Op Ar patterns .br -cpio -p [ adlmruv ] directory -.SH DESCRIPTION -Cpio -o (copy out) reads the standard input to obtain a list +.Nm cpio +.Fl p +.Op Fl adlmruv +.Ar directory +.Sh DESCRIPTION +.Nm Cpio +has three functional modes; copy out, copy in and pass. +.Pp +Functional Options: +.Tp Fl o +Copy out \- reads the standard input to obtain a list of path names and copies those files onto the standard output together with path name and status information. Output is padded to a 512-byte boundary. -.sp -Cpio -i (copy in) extracts files from the standard input, -which is assumed to be the product of a previous cpio -o. +.Pp +.Tp Fl i +Copy in \- extracts files from the standard input, +which is assumed to be the product of a previous +.Nm cpio +.Fl o . Only files with names that match patterns are selected. -Patterns are given in the name-generating notation of sh(1). -In patterns, meta-characters ?, *, and [...] match the +Patterns are given in the name-generating notation of +.Xr sh 1 . +In patterns, meta-characters ?, *, and +.Op ... +match the slash / character. Multiple patterns may be specified and if no patterns are specified, the default for patterns is * (i.e., select all files). The extracted files are conditionally created and copied into the current directory tree based upon the options described below. The -permissions of the files will be those of the previous cpio --o. The owner and group of the files will be that of the +permissions of the files will be those of the previous +.Nm cpio +.Fl o . +The owner and group of the files will be that of the current user unless the user is super-user, which causes -cpio to retain the owner and group of the files of the -previous cpio -o. -.sp -Cpio -p (pass) reads the standard input to obtain a list of +.Nm cpio +to retain the owner and group of the files of the +previous +.Nm cpio +.Fl o . +.Pp +.Tp Fl p +Pass \- reads the standard input to obtain a list of path names of files that are conditionally created and copied into the destination directory tree based upon the options described below. -.sp -The meanings of the available options are: -.IP a +.Tp +.Pp +Options for the above functional options: +.Tp Fl a Reset access times of input files after they have been copied. -.IP B -Input/output is to be blocked 5,120 bytes to the record -(does not apply to the pass options; meaningful only -with data directed to or from /dev/rmt/??). -.IP d +.Tp Fl B +Input/output is to be blocked 5,120 bytes to the record +(does not apply to the pass options; meaningful only +with data directed to or from +.Pa /dev/rmt/??). +.Tp Fl d Directories are to be created as needed. -.IP c +.Tp Fl c Write header information in ASCII character form for portability. -.IP r +.Tp Fl r Interactively rename files. If the user types a null line, the files is skipped. -.IP t +.Tp Fl t Print a table of contents of the input. No files are created. -.IP u +.Tp Fl u Copy unconditionally (normally, an older file will not replace a newer file with the same name). -.IP v -Verbose: causes a list of file names to be printed. +.Tp Fl v +Verbose: causes a list of file names to be printed. When used with the t option, the table of contents -looks like the output of an ls -l command (see ls(1)). -.IP l +looks like the output of an +.Li ls -l +command (see +.Xr ls 1 ) . +.Tp Fl l Whenever possible, link files rather than copying them. -Usable only with the -p option. -.IP m +Usable only with the +.Fl p +option. +.Tp Fl m Retain previous file modification time. This option is ineffective on directories that are being copied. -.IP f +.Tp Fl f Copy in all files except those in patterns. -.IP s -Swap bytes. Use only with the -i option. -.IP S -Swap halfwords. Use only with the -i option. -.IP b -Swap both bytes and halfwords. Use only with the -i +.Tp Fl s +Swap bytes. Use only with the +.Fl i +option. +.Tp Fl S +Swap halfwords. Use only with the +.Fl i option. -.IP 6 +.Tp Fl b +halfwords. Use only with the +.Fl i +option. +.Tp Fl 6 Process an old (i.e., UNIX System Sixth Edition format) -file. Only useful with -i (copy in). -.SH EXAMPLES +file. Only useful with +.FL i +(copy in). +.Tp +.Sh EXAMPLES The first example below copies the contents of a directory into an archive; the second duplicates a directory hierarchy: -.sp -.in +5 -ls | cpio -o >/dev/rmt/0m -.sp -cd olddir -.br -find . -depth -print | cpio -pdl newdir -.br -.sp -.in -5 +.Pp +.Dl ls cpio -o >/dev/rmt/0m +.Pp +.Dl cd olddir +.Dl find . -depth -print cpio -pdl newdir +.Pp The trivial case -.nf -.in +5 -``find . -depth -print | cpio -oB >/dev/fmt/0m'' -.in -5 -.fi +.Pp +.Dl find . -depth -print cpio -oB >/dev/fmt/0m +.Pp can be handled more efficiently by: -.in +5 -find . -cpio /dev/rmt/0m -.in -5 -.sp -.SH SEE ALSO -ar(1), find(1), ls(1). -.br -cpio(4) in the UNIX System User Reference Manual. -.SH BUGS +.Pp +.Dl find . -cpio /dev/rmt/0m +.Pp +.Sh SEE ALSO +.Xr ar 1 , +.Xr find 1 , +.Xr ls 1 . +.Xr cpio 4 +in the UNIX System User Reference Manual. +.Sh HISTORY +The +.Nm cpio +command appeared in System V AT&T UNIX. This program is derived +from the System V AT&T sources which were contributed to the public +domain by AT&T. +.Sh BUGS Path names are restricted to 128 characters. If there are too many unique linked files, the program runs out of memory to keep track of them and, thereafter, linking information is lost. Only the super-user can copy special files. The --B option does not work with certain magnetic tape drives. +.Fl B +option does not work with certain magnetic tape drives. diff --git a/usr/src/old/dbx/dbx.1 b/usr/src/old/dbx/dbx.1 index 8feb47eba4..411cb1b181 100644 --- a/usr/src/old/dbx/dbx.1 +++ b/usr/src/old/dbx/dbx.1 @@ -1,200 +1,307 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)dbx.1 6.3 (Berkeley) %G% +.\" @(#)dbx.1 6.4 (Berkeley) %G% .\" -.TH DBX 1 "" -.UC 5 -.ds dB dbx -.ds DB Dbx -.SH NAME -dbx \- debugger -.SH SYNOPSIS -.B dbx -[ -.B \-r -] [ -.B \-i -] [ -.B \-k -] [ -.B \-I -.I dir -] [ -.B \-c -.I file -] [ -.I objfile -[ -.I coredump -]] -.SH DESCRIPTION -\fI\*(DB\fP is a tool for source level debugging and execution of +.Dd +.Dt DBX 1 +.Os BSD 4.2 +.Sh NAME +.Nm dbx +.Nd debugger +.Sh SYNOPSIS +.Nm Dbx +.Op Fl r +.Op Fl i +.Op Fl k +.Op Fl I Ar dir +.Op Fl c Ar file +.Op Ar objfile Op Ar coredump +.Sh DESCRIPTION +.Nm dbx +is a tool for source level debugging and execution of programs under UNIX. -The \fIobjfile\fP is an object file produced by a compiler -with the appropriate flag (usually ``\-g'') +The +.Ar objfile +is an object file produced by a compiler +with the appropriate flag (usually +.Fl g ) specified to produce symbol information in the object file. -Currently, \fIcc\fP(1), \fIf77\fP(1), \fIpc\fP(1), and the DEC Western -Research Laboratory Modula-2 compiler, \fImod\fP(l), +Currently, +.Xr cc 1 , +.Xr f77 1 , +.Xr pc 1 , +and the DEC Western +Research Laboratory Modula-2 compiler, +.Xr mod l , produce the appropriate source information. -The machine level facilities of \fI\*(dB\fP +The machine level facilities of +.Nm dbx can be used on any program. -.PP +.Pp The object file contains a symbol table that includes the name of the all the source files translated by the compiler to create it. These files are available for perusal while using the debugger. -.PP -If a file named ``core'' exists in the current directory -or a \fIcoredump\fP file is specified, \fI\*(dB\fP can be used +.Pp +If a file named ``core'' +exists in the current directory +or a +.Ar coredump +file is specified, +.Nm dbx +can be used to examine the state of the program when it faulted. -.PP -If the file ``.\*(dBinit'' exists in the current directory then the +.Pp +If the file ``.dbxinit'' exists in the current directory then the debugger commands in it are executed. -\fI\*(DB\fP also checks for a ``.\*(dBinit'' in the user's home directory +.Nm Dbx +also checks for a ``.dbxinit'' in the user's home directory if there isn't one in the current directory. -.PP +.Pp The command line options and their meanings are: -.nr In 8 -.in +\n(Inn -.ta \n(Inn -.sp 1 -.ti -\n(Inn -\&\fB\-r\fP \c -Execute \fIobjfile\fP immediately. -If it terminates successfully \fI\*(dB\fP exits. +.Tw Fl +.Tp Fl r +Execute +.Ar objfile +immediately. +If it terminates successfully +.Nm dbx +exits. Otherwise the reason for termination will be reported and the user offered the option of entering the debugger or letting the program fault. -\fI\*(DB\fP will read from ``/dev/tty'' when \fB\-r\fP is specified +.Nm Dbx +will read from ``/dev/tty'' when +.Fl r +is specified and standard input is not a terminal. -.sp 1 -.ti -\n(Inn -\&\fB\-i\fP \c -Force \fI\*(dB\fP to act as though standard input is a terminal. -.sp 1 -.ti -\n(Inn -\&\fB\-k\fP \c +.Tp Fl i +Force +.Nm dbx +to act as though standard input is a terminal. +.Tp Fl k Map memory addresses, useful for kernel debugging. -.sp 1 -.ti -\n(Inn -\&\fB\-I\fP \fIdir\fP \c -Add \fIdir\fP to the list of directories +.Tp Cx Fl I +.Cx \&\ \& +.Ar dir +.Cx +Add +.Ar dir +to the list of directories that are searched when looking for a source file. -Normally \fI\*(dB\fP looks for source files in the current directory -and in the directory where \fIobjfile\fP is located. -The directory search path can also be set with the \fBuse\fP command. -.sp 1 -.ti -\n(Inn -\&\fB\-c\fP \fIfile\fP \c -Execute the \fI\*(dB\fP commands in the \fIfile\fP before +Normally +.Nm dbx +looks for source files in the current directory +and in the directory where +.Ar objfile +is located. +The directory search path can also be set with the +.Ar use +command. +.Tp Cx Fl c +.Cx \&\ \& +.Ar file +.Cx +Execute the +.Nm dbx +commands in the +.Ar file +before reading from standard input. -.in -\n(Inn -.sp 1 -.PP -Unless \fB\-r\fP is specified, \fI\*(dB\fP just prompts and waits for a command. -.sp 1 -.ne 8 -.B Execution and Tracing Commands -.sp 1 -.TP -\fBrun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP] -.ns -.TP -\fBrerun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP] -Start executing \fIobjfile\fP, passing \fIargs\fP as command line arguments; -\fB<\fP or \fB>\fP can be used to redirect input or output in the usual manner. -When \fBrerun\fP is used without any arguments the previous +.Tp +.Pp +Unless +.Fl r +is specified, +.Nm dbx +just prompts and waits for a command. +.Ss Execution and Tracing Commands +.Dw Fl +.Di L +.Dp Cx Ic run +.Cx \&\ \& +.Op Ar args +.Cx \&\ \& +.Op Sy < Ar filename +.Cx \&\ \& +.Op Sy > Ar filename +.Cx +.Dp Cx Ic rerun +.Cx \&\ \& +.Op Ar args +.Cx \&\ \& +.Op Sy < Ar filename +.Cx \&\ \& +.Op Sy > Ar filename +.Cx +Start executing +.Ar objfile , +passing +.Ar args +as command line arguments; +.Sy < +or +.Sy > +can be used to redirect input or output in the usual manner. +When +.Ic rerun +is used without any arguments the previous argument list is passed to the program; -otherwise it is identical to \fBrun\fP. -If \fIobjfile\fP has been written since the last time the symbolic information -was read in, \fI\*(dB\fP will read in the new information. -.TP -\fBtrace\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIprocedure/function\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIexpression\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIvariable\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] +otherwise it is identical to +.Ic run . +If +.Ar objfile +has been written since the last time the symbolic information +was read in, +.Nm dbx +will read in the new information. +.Dp Cx Ic trace +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar procedure/function +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Ic at +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx Have tracing information printed when the program is executed. A number is associated with the command that is used -to turn the tracing off (see the \fBdelete\fP command). -.sp 1 +to turn the tracing off (see the +.Ic delete +command). +.Pp The first argument describes what is to be traced. -If it is a \fIsource-line-number\fP, then the line is printed +If it is a +.Ar source-line-number , +then the line is printed immediately prior to being executed. Source line numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon, e.g. "mumble.p":17. -.sp 1 +.Pp If the argument is a procedure or function name then every time it is called, information is printed telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it's a function then the value it is returning is also printed. -.sp 1 -If the argument is an \fIexpression\fP with an \fBat\fP clause +.Pp +If the argument is an +.Ar expression +with an +.Ic at +clause then the value of the expression is printed whenever the identified source line is reached. -.sp 1 +.Pp If the argument is a variable then the name and value of the variable is printed whenever it changes. Execution is substantially slower during this form of tracing. -.sp 1 +.Pp If no argument is specified then all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. -.sp 1 -The clause ``\fBin\fP \fIprocedure/function\fP'' restricts tracing information +.Pp +The clause +.Ic in +.Ar procedure/function +restricts tracing information to be printed only while executing inside the given procedure or function. -.sp 1 -\fICondition\fP is a boolean expression and is +.Pp +.Ar Condition +is a boolean expression and is evaluated prior to printing the tracing information; if it is false then the information is not printed. -.br -.ne 10 -.IP "\fBstop\fP \fBif\fP \fIcondition\fP" -.ns -.IP "\fBstop\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]" -.ns -.IP "\fBstop\fP \fBin\fP \fIprocedure/function\fP [\fBif\fP \fIcondition\fP]" -.ns -.IP "\fBstop\fP \fIvariable\fP [\fBif\fP \fIcondition\fP]" +.Dp Cx Ic stop if +.Cx \&\ \& +.Ar condition +.Cx +.Dp Cx Ic stop at +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic stop in +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic stop +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ic if Ar condition +.Cx Stop execution when the given line is reached, procedure or function called, variable changed, or condition true. -.IP "\fBstatus\fP [\fB>\fP \fIfilename\fP]" -Print out the currently active \fBtrace\fP and \fBstop\fP commands. -.IP "\fBdelete\fP \fIcommand-number\fP ..." +.Dp Cx Ic status +.Cx \&\ \& +.Op Ic \&> Ar filename +.Cx +Print out the currently active +.Ic trace +and +.Ic stop +commands. +.Dp Cx Ic delete +.Cx \&\ \& +.Ar command-number ... +.Cx The traces or stops corresponding to the given numbers are removed. The numbers associated with traces and stops are printed by -the \fBstatus\fP command. -.IP "\fBcatch\fP \fInumber\fP" -.ns -.IP "\fBcatch\fP \fIsignal-name\fP" -.ns -.IP "\fBignore\fP \fInumber\fP" -.ns -.IP "\fBignore\fP \fIsignal-name\fP" +the +.Ic status +command. +.Dp Cx Ic catch +.Cx \&\ \& +.Ar number +.Cx +.Dp Cx Ic catch +.Cx \&\ \& +.Ar signal-name +.Cx +.Dp Cx Ic ignore +.Cx \&\ \& +.Ar number +.Cx +.Dp Cx Ic ignore +.Cx \&\ \& +.Ar signal-name +.Cx Start or stop trapping a signal before it is sent to the program. This is useful when a program being debugged @@ -204,371 +311,524 @@ A signal may be specified by number or by a name Signal names are case insensitive and the ``SIG'' prefix is optional. By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM and SIGKILL. -.IP "\fBcont\fP \fIinteger\fP" -.ns -.IP "\fBcont\fP \fIsignal-name\fP" +.Dp Cx Ic cont +.Cx \&\ \& +.Ar integer +.Cx +.Dp Cx Ic cont +.Cx \&\ \& +.Ar signal-name +.Cx Continue execution from where it stopped. If a signal is specified, the process continues as though it received the signal. Otherwise, the process is continued as though it had not been stopped. -.PP +.Pp Execution cannot be continued if the process has ``finished'', that is, called the standard procedure ``exit''. -\fI\*(DB\fP does not allow the process to exit, thereby +.Nm Dbx +does not allow the process to exit, thereby letting the user to examine the program state. -.IP \fBstep\fP +.Dp Ic step Execute one source line. -.IP \fBnext\fP +.Dp Ic next Execute up to the next source line. -The difference between this and \fBstep\fP is that +The difference between this and +.Ic step +is that if the line contains a call to a procedure or function -the \fBstep\fP command will stop at the beginning of that -block, while the \fBnext\fP command will not. -.IP "\fBreturn\fP [\fIprocedure\fP]" -Continue until a return to \fIprocedure\fP is executed, or +the +.Ic step +command will stop at the beginning of that +block, while the +.Ic next +command will not. +.Dp Cx Ic return +.Cx \&\ \& +.Op Ar procedure +.Cx +Continue until a return to +.Ar procedure +is executed, or until the current procedure returns if none is specified. -.IP "\fBcall\fP \fIprocedure(parameters)\fP" +.Dp Cx Ic call +.Cx \&\ \& +.Ar procedure (parameters ) +.Cx Execute the object code associated with the named procedure or function. -.sp 1 -.br -.ne 8v -.PP -.B Printing Variables and Expressions -.sp 1 -.PP +.Dp +.Ss Printing Variables and Expressions Names are resolved first using the static scope of the current function, then using the dynamic scope if the name is not defined in the static scope. If static and dynamic searches do not yield a result, an arbitrary symbol is chosen and -the message ``[using\ \fIqualified\ name\fP]'' is printed. +the message +.Cx `` +.Op using Ar qualified name +.Cx \'\' +.Cx +is printed. The name resolution procedure may be overridden by qualifying an identifier -with a block name, e.g., ``\fImodule\fP.\fIvariable\fP''. +with a block name, e.g., +.Cx `` +Ar module.variable +.Cx \'\'. +.Cx For C, source files are treated as modules named by the file name without ``.c''. -.PP +.Pp Expressions are specified with an approximately common subset of C and Pascal (or equivalently Modula-2) syntax. Indirection can be denoted using either a prefix ``*'' or a postfix ``^'' and -array expressions are subscripted by brackets (``[ ]''). +array expressions are subscripted by brackets +.Cx (`` +.Op +.Cx \'\'). +.Cx The field reference operator (``.'') can be used with pointers -as well as records, making the C operator ``->'' unnecessary +as well as records, making the C operator ``\->'' unnecessary (although it is supported). -.PP +.Pp Types of expressions are checked; the type of an expression may be overridden -by using ``\fItype-name\fP(\fIexpression\fP)''. +by using +.Cx `` +.Ar type-name (expression) +.Cx \'\'. +.Cx When there is no corresponding named type -the special constructs ``&\fItype-name\fP'' and ``$$\fItag-name\fP'' +the special constructs +.Cx ``& +.Ar type-name +.Cx \'\' +.Cx +and +.Cx ``$$ +.Ar tag-name +.Cx \'\' +.Cx can be used to represent a pointer to a named type or C structure tag. -.sp 1 -.IP "\fBassign\fP \fIvariable\fP \fB=\fP \fIexpression\fP" +.Dw Fl +.Di L +.Dp Cx Ic assign +.Cx \&\ \& +.Ar variable +.Ic = +.Ar expression +.Cx Assign the value of the expression to the variable. -.IP "\fBdump\fP [\fIprocedure\fR] [\fB>\fP \fIfilename\fP]" +.Dp Cx Ic dump +.Cx \&\ \& +.Op Ar procedure +.Cx \&\ \& +.Op Ic > Ar filename +.Cx Print the names and values of variables in the given procedure, or the current one if none is specified. If the procedure given is ``.'', then the all active variables are dumped. -.IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]" +.Dp Cx Ic print +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Op Ic \&, Ar expression ... +.Cx Print out the values of the expressions. -.IP "\fBwhatis\fP \fIname\fP" +.Dp Cx Ic whatis +.Cx \&\ \& +.Ar name +.Cx Print the declaration of the given name, which may be qualified with block names as above. -.IP "\fBwhich\fP \fIidentifier\fP" +.Dp Cx Ic which +.Cx \&\ \& +.Ar identifier +.Cx Print the full qualification of the given identifer, i.e. the outer blocks that the identifier is associated with. -.IP "\fBup\fP [\fIcount\fP]" -.ns -.IP "\fBdown\fP [\fIcount\fP]" +.Dp Cx Ic up +.Cx \&\ \& +.Op Ar count +.Cx +.Dp Cx Ic down +.Cx \&\ \& +.Op Ar count +.Cx Move the current function, which is used for resolving names, -up or down the stack \fIcount\fP levels. -The default \fIcount\fP is 1. -.IP \fBwhere\fP +up or down the stack +.Ar count +levels. +The default +.Ar count +is 1. +.Dp Ic where Print out a list of the active procedures and function. -.IP "\fBwhereis\fP \fIidentifier\fP" +.Dp Cx Ic whereis +.Cx \&\ \& +.Ar identifier +.Cx Print the full qualification of all the symbols whose name matches the given identifier. The order in which the symbols are printed is not meaningful. -.sp 1 -.br -.ne 8v -.PP -.B Accessing Source Files -.sp 1 -.IP "/\fIregular\ expression\fP[/]" -.ns -.IP "?\fIregular\ expression\fP[?]" +.Ss Accessing Source Files +.Pp +.Dp Cx Ar /regular expression +.Op / +.Cx +.Dp Cx Ar ?regular expression +.Op ? +.Cx Search forward or backward in the current source file for the given pattern. -.IP "\fBedit\fP [\fIfilename\fP]" -.ns -.IP "\fBedit\fP \fIprocedure/function-name\fP" -Invoke an editor on \fIfilename\fP or the current source file if none +.Dp Cx Ic edit +.Cx \&\ \& +.Op Ar filename +.Cx +.Dp Cx Ic edit +.Cx \&\ \& +.Ar procedure/function-name +.Cx +Invoke an editor on +.Ar filename +or the current source file if none is specified. -If a \fIprocedure\fP or \fIfunction\fP name is specified, +If a +.Ar procedure +or +.Ar function +name is specified, the editor is invoked on the file that contains it. Which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable -EDITOR to the name of the desired editor. -.IP "\fBfile\fP [\fIfilename\fP]" -Change the current source file name to \fIfilename\fP. +.Ev EDITOR +to the name of the desired editor. +.Dp Cx Ic file +.Cx \&\ \& +.Op Ar filename +.Cx +Change the current source file name to +.Ar filename . If none is specified then the current source file name is printed. -.IP "\fBfunc\fP [\fIprocedure/function\fP]" +.Dp Cx Ic func +.Cx \&\ \& +.Op Ar procedure/function +.Cx Change the current function. If none is specified then print the current function. Changing the current function implicitly changes the current source file to the one that contains the function; it also changes the current scope used for name resolution. -.IP "\fBlist\fP [\fIsource-line-number\fP [\fB,\fP \fIsource-line-number\fP]]" -.ns -.IP "\fBlist\fP \fIprocedure/function\fP" +.Dp Cx Ic list +.Cx \&\ \& +.Op Ar source-line-number Op Ic \&, Ar source-line-number +.Cx +.Dp Cx Ic list +.Cx \&\ \& +.Ar procedure/function +.Cx List the lines in the current source file from the first line number to the second inclusive. If no lines are specified, the next 10 lines are listed. If the name of a procedure or function is given -lines \fIn-k\fP to \fIn+k\fP are listed where \fIn\fP is the first statement -in the procedure or function and \fIk\fP is small. -.IP "\fBuse\fP \fIdirectory-list\fP" +lines +.Ar n-k +to +.Ar n +k +are listed where +.Ar n +is the first statement +in the procedure or function and +.Ar k +is small. +.Dp Cx Ic use +.Cx \&\ \& +.Ar directory-list +.Cx Set the list of directories to be searched when looking for source files. -.sp 1 -.br -.ne 8v -.PP -.B Command Aliases and Variables -.sp 1 -.TP -\fBalias\fP \fIname\fP \fIname\fP -.ns -.TP -\fBalias\fP \fIname\fP ``\fIstring\fP'' -.ns -.TP -\fBalias\fP \fIname\fP (\fIparameters\fP) ``\fIstring\fP'' +.Dp +.Ss Command Aliases and Variables +.Dw Fl +.Di L +.Dp Cx Ic alias +.Cx \&\ \& +.Ar name +.Cx \&\ \& +.Ar name +.Cx +.Dp Cx Ic alias +.Cx \&\ \& +.Ar name +.Cx \&\ \& +.Ar string +.Cx +.Dp Cx Ic alias +.Cx \&\ \& +.Ar name (parameters) +.Cx \&\ \& +.Cx `` +.Ar string +.Cx \'\' +.Cx When commands are processed, -\*(dB first checks to see if the word +dbx first checks to see if the word is an alias for either a command or a string. -If it is an alias, then \*(dB treats the input as though +If it is an alias, then dbx treats the input as though the corresponding string (with values substituted for any parameters) had been entered. For example, to define an alias ``rr'' for the command ``rerun'', one can say -.sp 1 -.in +8n -alias rr rerun -.in -8n -.sp 1 +.Pp +.Dl alias rr rerun +.Pp To define an alias called ``b'' that sets a stop at a particular line one can say -.sp 1 -.in +8n -alias b(x) ``stop at x'' -.in -8n -.sp 1 +.Pp +.Dl alias b(x) ``stop at x'' +.Pp Subsequently, the command ``b(12)'' will expand to ``stop at 12''. -.need 5 -.TP -\fBset\fP \fIname\fP [= \fIexpression\fP] -The \fBset\fP command defines values for debugger variables. +.Pp +.Dp Cx Ic set +.Ar name +.Op \&= Ar expression +.Cx +The +.Ic set +command defines values for debugger variables. The names of these variables cannot conflict with names in the program being debugged, and are expanded to the corresponding expression within other commands. The following variables have a special meaning: -.sp 1 -.in +8n -.ti -5n -$frame -.br -Setting this variable to an address causes \*(dB to use the stack frame +.Dw Ds +.Di L +.Dp Li $frame +Setting this variable to an address causes dbx to use the stack frame pointed to by the address for doing stack traces and accessing local variables. This facility is of particular use for kernel debugging. -.sp 1 -.ti -5n -$hexchars -.ti -5n -$hexints -.ti -5n -$hexoffsets -.ti -5n -$hexstrings -.br -When set, \*(dB prints out +.Dp Li $hexchars +.Dp Li $hexints +.Dp Li $hexoffsets +.Dp Li $hexstrings +When set, dbx prints out out characters, integers, offsets from registers, or character pointers respectively in hexadecimal. -.sp 1 -.ti -5n -$listwindow -.br +.Dp Li $listwindow The value of this variable specifies the number -of lines to list around a function or when the \fBlist\fP command +of lines to list around a function or when the +.Ic list +command is given without any parameters. Its default value is 10. -.sp 1 -.ti -5n -$mapaddrs -.br -Setting (unsetting) this variable causes \*(dB to start (stop) +.Dp Li $mapaddrs +Setting (unsetting) this variable causes dbx to start (stop) mapping addresses. As with ``$frame'', this is useful for kernel debugging. -.sp 1 -.ti -5n -$unsafecall -.ti -5n -$unsafeassign -.br +.Dp Li $unsafecall +.Dp Li $unsafeassign When ``$unsafecall'' is set, strict type checking is turned off for arguments to -subroutine or function calls (\fIe.g.\fP in the \fBcall\fP statement). +subroutine or function calls ( +.Ar e .g . +in the +.Ic call +statement). When ``$unsafeassign'' is set, strict type checking between the two sides -of an \fBassign\fP statement is turned off. +of an +.Ic assign +statement is turned off. These variables should be used only with great care, -because they severely limit \*(dB's usefulness +because they severely limit dbx's usefulness for detecting errors. -.in -8n -.TP -\fBunalias\fP \fIname\fP +.Dp +.Dp Cx Ic unalias +.Cx \&\ \& +.Ar name +.Cx Remove the alias with the given name. -.TP -\fBunset\fP \fIname\fP -Delete the debugger variable associated with \fIname\fP. -.sp 1 -.br -.ne 8v -.PP -.B Machine Level Commands -.sp 1 -.TP -\fBtracei\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBtracei\fP [\fIvariable\fP] [\fBat\fP \fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBstopi\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBstopi\fP [\fBat\fP] [\fIaddress\fP] [\fBif\fP \fIcond\fP] +.Dp Cx Ic unset +.Cx \&\ \& +.Ar name +.Cx +Delete the debugger variable associated with +.Ar name . +.Dp +.Ss Machine Level Commands +.Dw Fl +.Di L +.Dp Cx Ic tracei +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op .Ic if Ar cond +.Cx +.Dp Cx Ic tracei +.Cx \&\ \& +.Op Ar variable +.Cx \&\ \& +.Op Ic at Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +.Dp Cx Ic stopi +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +.Dp Cx Ic stopi +.Cx \&\ \& +.Op Ic at +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx Turn on tracing or set a stop using a machine instruction address. -.TP -\fBstepi\fP -.ns -.TP -\fBnexti\fP -Single step as in \fBstep\fP or \fBnext\fP, but do a single instruction +.Dp Ic stepi +.Dp Ic nexti +Single step as in +.Ic step +or +.Ic next , +but do a single instruction rather than source line. -.TP -\fIaddress\fP \fB,\fP\fIaddress\fP\fB/\fP [\fImode\fP] -.ns -.TP -\fIaddress\fP \fB/\fP [\fIcount\fP] [\fImode\fP] -Print the contents of memory starting at the first \fIaddress\fP -and continuing up to the second \fIaddress\fP or until \fIcount\fP items are printed. +.Dp Cx Ar address +.Cx \&, +.Ar address +.Cx \&/ +.Op Ar mode +.Cx +.Dp Cx Ar address +.Cx \&/ +.Op Ar count +.Op Ar mode +.Cx +Print the contents of memory starting at the first +.Ar address +and continuing up to the second +.Ar address +or until +.Ar count +items are printed. If the address is ``.'', the address following the one printed most recently is used. -The \fImode\fP specifies how memory is to be printed; +The +.Ar mode +specifies how memory is to be printed; if it is omitted the previous mode specified is used. The initial mode is ``X''. The following modes are supported: -.nr In 5 -.in +\n(Inn -.ta \n(Inn -.sp 1 -.ti -\n(Inn -\&\fBi\fP \c +.Dw Cm +.Dp Cm i print the machine instruction -.ti -\n(Inn -\&\fBd\fP \c +.Dp Cm d print a short word in decimal -.ti -\n(Inn -\&\fBD\fP \c +.Dp Cm D print a long word in decimal -.ti -\n(Inn -\&\fBo\fP \c +.Dp Cm o print a short word in octal -.ti -\n(Inn -\&\fBO\fP \c +.Dp Cm O print a long word in octal -.ti -\n(Inn -\&\fBx\fP \c +.Dp Cm x print a short word in hexadecimal -.ti -\n(Inn -\&\fBX\fP \c +.Dp Cm X print a long word in hexadecimal -.ti -\n(Inn -\&\fBb\fP \c +.Dp Cm b print a byte in octal -.ti -\n(Inn -\&\fBc\fP \c +.Dp Cm c print a byte as a character -.ti -\n(Inn -\&\fBs\fP \c +.Dp Cm s print a string of characters terminated by a null byte -.ti -\n(Inn -\&\fBf\fP \c +.Dp Cm f print a single precision real number -.ti -\n(Inn -\&\fBg\fP \c +.Dp Cm g print a double precision real number -.in -\n(Inn -.sp 1 -.PP +.Dp +.Pp Symbolic addresses are specified by preceding the name with an ``&''. Registers are denoted by ``$rN'' where N is the number of the register. Addresses may be expressions made up of other addresses and the operators ``+'', ``-'', and indirection (unary ``*''). -.sp 1 -.br -.ne 8v -.PP -.B Miscellaneous Commands -.sp 1 -.IP \fBgripe\fP -Invoke a mail program to send a message to the person in charge of \fI\*(dB\fP. -.IP \fBhelp\fP -Print out a synopsis of \fI\*(dB\fP commands. -.IP "\fBquit\fP" -Exit \fI\*(dB\fP. -.IP "\fBsh\fP \fIcommand-line\fP" +.Dp +.Ss Miscellaneous Commands +.Tw Ic +.Tp Ic gripe +Invoke a mail program to send a message to the person in charge of +.Nm dbx . +.Tp Ic help +Print out a synopsis of +.Nm dbx +commands. +.Tp Ic quit +Exit +.Nm dbx . +.Tp Cx Ic sh +.Cx \&\ \& +.Ar command-line +.Cx Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used. -.TP -\fBsource\fP \fIfilename\fP -Read \fI\*(dB\fP commands from the given \fIfilename\fP. -.SH FILES -.nr In 20 -.in +\n(Inn -.ta \n(Inn -.sp 1 -.ti -\n(Inn -\&a.out \c +.Tp Cx Ic source +.Cx \&\ \& +.Ar filename +.Cx +Read +.Nm dbx +commands from the given +.Ar filename . +.Tp +.Sh ENVIRONMENT +.Nm Dbx +checks these environment variables: +.Ds I +EDITOR +HOME +PATH +SHELL +.De +.Sh FILES +.Dw .dbxinit +.Di L +.Dp Pa a.out object file -.ti -\n(Inn -\&\&.\*(dBinit \c +.Dp Pa .dbxinit initial commands -.SH SEE ALSO -cc(1), f77(1), pc(1), mod(l) -.SH COMMENTS -\fI\*(DB\fP suffers from the same ``multiple include'' malady as did \fIsdb\fP. +.Dp +.Sh SEE ALSO +.Xr cc 1 , +.Xr mod l , +.Xr f77 1 , +.Xr pc 1 +.Sh HISTORY +.Nm Dbx +appeared in 4.2 BSD. +.Sh BUGS +.Nm Dbx +suffers from the same ``multiple include'' malady as did +.Nm sdb . If you have a program consisting of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file. Since about one debugger start-up is done for each link, -having the linker (ld) re-organize the symbol information +having the linker +.Xr ld 1 +re-organize the symbol information would not save much time, though it would reduce some of the disk space used. -.PP +.Pp This problem is an artifact of the unrestricted semantics of #include's in C; for example an include file can contain static declarations that are separate entities for each file in which they are included. However, even with Modula-2 there is a substantial amount of duplication of symbol information necessary for inter-module type checking. -.PP +.Pp Some problems remain with the support for individual languages. Fortran problems include: inability to assign to logical, logical*2, complex diff --git a/usr/src/old/pcc/cc/cc.1 b/usr/src/old/pcc/cc/cc.1 index 6defeaec3a..c3f79d1492 100644 --- a/usr/src/old/pcc/cc/cc.1 +++ b/usr/src/old/pcc/cc/cc.1 @@ -1,22 +1,27 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)cc.1 6.3 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH CC 1 "" -.UC 4 -.SH NAME -cc \- C compiler -.SH SYNOPSIS -.B cc -[ option ] ... file ... -.SH DESCRIPTION -.I Cc +.\" @(#)cc.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt CC 1 +.Os BSD 4 +.Sh NAME +.Nm cc +.Nd C compiler +.Sh SYNOPSIS +.Nm cc +.Op option +... +.Ar file ... +.Sh DESCRIPTION +.Nm Cc is the UNIX C compiler. -.I Cc +.Nm Cc accepts several types of arguments: -.PP +.Pp Arguments whose names end with `.c' are taken to be C source programs; they are compiled, and each object program is left on the file @@ -24,245 +29,235 @@ whose name is that of the source with `.o' substituted for `.c'. The `.o' file is normally deleted, however, if a single C program is compiled and loaded all at one go. -.PP +.Pp In the same way, arguments whose names end with `.s' are taken to be assembly source programs and are assembled, producing a `.o' file. -.PP +.Pp The following options are interpreted by -.IR cc . +.Nm cc . See -.IR ld (1) +.Xr ld 1 for load-time options. -.TP 8 -.B \-c +.Tw Fl +.Tp Fl c Suppress the loading phase of the compilation, and force an object file to be produced even if only one program is compiled. -.TP -.B \-g +.Tp Fl g Have the compiler produce additional symbol table information -for -.IR dbx (1). +for +.Xr dbx 1 Also pass the -.B \-lg +.Fl lg flag to -.IR ld (1). -.TP -.B \-go +.Xr ld 1 . +.Tp Fl go Have the compiler produce additional symbol table information for the obsolete debugger -.IR sdb (1). +.Xr sdb 1 . Also pass the -.B \-lg +.Fl lg flag to -.IR ld (1). -.TP -.B \-w +.Xr ld 1 . +.Tp Fl w Suppress warning diagnostics. -.TP -.B \-p +.Tp Fl p Arrange for the compiler to produce code which counts the number of times each routine is called. If loading takes place, replace the standard startup routine by one which automatically calls -.IR monitor (3) +.Xr monitor 3 at the start and arranges to write out a -.I mon.out +.Pa mon.out file at normal termination of execution of the object program. An execution profile can then be generated by use of -.IR prof (1). -.TP -.B \-pg +.Xr prof 1 . +.Tp Fl pg Causes the compiler to produce counting code in the manner of -.B \-p, +.Fl p but invokes a run-time recording mechanism that keeps more -extensive statistics and produces a -.I gmon.out +extensive statistics and produces a +.Pa gmon.out file at normal termination. Also, a profiling library is searched, in lieu of the standard C library. An execution profile can then be generated by use of -.IR gprof (1). -.TP -.SM -.B \-O +.Xr gprof 1 . +.Tp Fl O Invoke an object-code improver. -.TP -.SM -.B \-R +.Tp Fl R Passed on to -.I as, +.Xr as 1 making initialized variables shared and read-only. -.TP -.SM -.B \-S +.Tp Fl S Compile the named C programs, and leave the assembler-language output on corresponding files suffixed `.s'. -.TP -.SM -.B \-M +.Tp Fl M Run only the macro preprocessor on the named C programs, requesting it to generate Makefile dependencies and send the result to the standard output. -.TP -.SM -.B \-E +.Tp Fl E Run only the macro preprocessor on the named C programs, and send the result to the standard output. -.TP -.SM -.B \-C +.Tp Fl C prevent the macro preprocessor from eliding comments. -.TP -.BI \-o " output" +.Tp Cx Fl o +.Cx \& \& +.Ar output +.Cx Name the final output file -.IR output . +.Ar output . If this option is used the file `a.out' will be left undisturbed. -.TP -.SM -.BI \-D name=def -.br -.ns -.TP -.SM -.BI \-D \*Sname +.Tp Cx Fl D +.Ar name=def +.Cx +.Tp Cx Fl D +.Ar name +.Cx Define the -.I name +.Ar name to the preprocessor, -as if by -`#define'. +as if by `#define'. If no definition is given, the name is defined as "1". -.TP -.SM -.BI \-U \*Sname +.Tp Cx Fl U +.Ar name +.Cx Remove any initial definition of -.IR name . -.TP -.SM -.BI \-I \*Sdir -`#include' files -whose names do not begin with `/' are always -sought first in the directory +.Ar name . +.Tp Cx Fl I +.Ar dir +.Cx +`#include files' +whose names do not begin with `/' +are always +sought first in the directory of the -.I file +.Ar file argument, -then in directories named in -.B \-I +then in directories named in +.Fl I options, then in directories on a standard list. -.TP -.SM -.BI \-L \*Sdir +.Tp Cx Fl L +.Ar dir +.Cx Library archives are sought first in directories named in -.B \-L +.Fl L options, then in directories on a standard list. -.TP -.B \-f +.Tp Fl f Use an alternate compiler which does not convert expressions involving only floats to double. This does not conform to the standard which states that all intermediate results should be converted to double but does provide a speed improvement for programs which don't require full double precision. This option also makes -.B "register float" +.Sy register float variables work appropriately. -.TP -.SM -.BI \-B \*Spath +.Tp Cx Fl B +.Ar path +.Cx Find substitute compiler passes in the named path with the suffixes cpp, ccom and c2. -.TP -.BR \-t [ p012 ] +.Tp Cx Fl t +.Op p012 +.Cx Find only the designated compiler passes in the files whose names are constructed by a -.B \-B +.Fl B option. -In the absence of a -.B \-B -option, the -.I string -is taken to be `/usr/c/'. -.PP +.Pp Other arguments are taken to be either loader option arguments, or C-compatible object programs, typically produced by an earlier -.I cc +.Nm cc run, or perhaps libraries of C-compatible routines. These programs, together with the results of any compilations specified, are loaded (in the order given) to produce an executable program with name -.B a.out. -.SH FILES -.ta \w'/usr/c/occom 'u -file.c input file -.br -file.o object file -.br -a.out loaded output -.br -/tmp/ctm? temporary -.br -/lib/cpp preprocessor -.br -/lib/ccom compiler -.br -/lib/sccom compiler for single precision floats -.br -/usr/c/occom backup compiler -.br -/usr/c/ocpp backup preprocessor -.br -/lib/c2 optional optimizer -.br -/lib/crt0.o runtime startoff -.br -/lib/mcrt0.o startoff for profiling -.br -/usr/lib/gcrt0.o startoff for gprof-profiling -.br -/lib/libc.a standard library, see -.IR intro (3) -.br -/usr/lib/libc_p.a profiling library, see -.IR intro (3) -.br -/usr/include standard directory for `#include' files -.br -mon.out file produced for analysis by -.IR prof (1) -.br -gmon.out file produced for analysis by -.IR gprof (1) -.SH "SEE ALSO" +.Pa a.out . +.Sh FILES +.Dw /usr/libexec/sccom +.Ds L +.Dp Pa file.c +input file +.Dp Pa file.o +object file +.Dp Pa a.out +loaded output +.Dp Pa ctm? +temporary +.Dp Pa /usr/bin/cpp +preprocessor +.Dp Pa /usr/libexec/ccom +compiler +.Dp Pa /usr/libexec/ccom +compiler for single precision floats +.Dp Pa /usr/libexec/c2 +optional optimizer +.Dp Pa /usr/lib/crt0.o +runtime startoff +.Dp Pa /usr/lib/mcrt0.o +startoff for profiling +.Dp Pa /usr/lib/gcrt0.o +startoff for gprof-profiling +.Dp Pa /usr/lib/libc.a +standard library, see +.Ar intro 3 +.Dp Pa /usr/lib/libc_p.a +profiling library, see +.Ar intro 3 +.Dp Pa /usr/include +standard directory for `#include' files +.Dp Pa mon.out +file produced for analysis by +.Xr prof 1 +.Dp Pa gmon.out +file produced for analysis by +.Xr gprof 1 +.Dp +.Sh SEE ALSO B. W. Kernighan and D. M. Ritchie, -.I The C Programming Language, -Prentice-Hall, +.Em The Programming Language , +Prentice-.Xr Hall, 1978 -.br +.Pp B. W. Kernighan, -.I -Programming in C\(ema tutorial -.br +.Em Programming in C\-em a tutorial +.Pp D. M. Ritchie, -.I -C Reference Manual -.br -monitor(3), prof(1), gprof(1), adb(1), ld(1), dbx(1), as(1) -.SH DIAGNOSTICS +.Em C Reference Manual +.Pp +.Xr monitor 3 , +.Xr prof 1 , +.Xr gprof 1 , +.Xr adb 1 , +.Xr ld 1 , +.Xr dbx 1 , +.Xr as 1 +.Sh DIAGNOSTICS The diagnostics produced by C itself are intended to be self-explanatory. Occasional messages may be produced by the assembler or loader. -.SH BUGS -The compiler currently ignores advice to put -\fBchar\fR, \fBunsigned char\fR, -\fBshort\fR, \fBunsigned short\fR, -\fBfloat\fR, or \fBdouble\fR +.Sh HISTORY +The +.Nm +compiler was distributed with Version 6 AT&T UNIX. +The current version was derived from the original. +.Sh BUGS +The compiler currently ignores advice to put +.Ic char , +.Ic unsigned char , +.Ic short , +.Ic unsigned short , +.Ic float , +or +.Ic double variables in registers, except as noted above. It previously produced poor, and in some cases incorrect, code for such declarations. diff --git a/usr/src/old/pr/pr.1 b/usr/src/old/pr/pr.1 index ac5398086d..d3d9ca31d2 100644 --- a/usr/src/old/pr/pr.1 +++ b/usr/src/old/pr/pr.1 @@ -1,87 +1,148 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pr.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PR 1 "" -.UC 4 -.SH NAME -pr \- print file -.SH SYNOPSIS -.B pr -[ option ] ... -[ file ] ... -.SH DESCRIPTION -.I Pr -produces a printed listing of one or more -.I files. -The output is separated into pages headed by a date, -the name of the file or a specified header, and the page number. -If there are no file arguments, -.I pr -prints its standard input. -.PP -Options apply to all following files but may be reset -between files: -.TP -.BI \- n -Produce -.IR n -column -output. -.TP -.BI + n -Begin printing with page -.I n. -.TP -.B \-h -Take the next argument as a page header. -.TP -.BI \-w n -For purposes of multi-column output, -take the width of the page to be -.I n -characters instead of the default 72. -.TP -.BI \-f -Use formfeeds instead of newlines to separate pages. -A formfeed is assumed to use up two blank lines at the top of a page. -(Thus this option does not affect the effective page length.) -.TP -.BI \-l n -Take the length of the page to be -.I n -lines instead of the default 66. -.TP -.B \-t -Do not print the 5-line header or the -5-line trailer normally supplied for each page. -.TP -.BI \-s c -Separate columns by the single character -.I c -instead of by the appropriate amount of white space. -A missing -.I c -is taken to be a tab. -.TP -.B \-m -Print all -.I files -simultaneously, -each in one column, -.PP -Inter-terminal messages via -.IR write (1) -are -forbidden during a -.IR pr . -.SH FILES -/dev/tty? -to suspend messages. -.SH "SEE ALSO" -cat(1) -.SH DIAGNOSTICS -There are no diagnostics when -.I pr -is printing on a terminal. +.\" @(#)pr.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PR 1 +.Os BSD 4.4 +.Sh NAME +.Nm pr +.Nd Print files. +.Sh SYNOPSIS +.Ar pr +.Op +page +.Oo +.Op Fl Ar column +.Op Fl f +.Op Fl hheader +.Op Fl llines +.Op Fl m +.Op Fl s Ar char +.Op Fl t +.Op Fl w Ar width +.Ar +.Oo +.Sh DESCRIPTION +The +.Nm pr +utility is a printing and pagination filter. +If multiple +input files are specified, each is read, formatted, +and written to standard output. +By default, the input is +separated into pages, each with a header that includes the +page number, date, time, and the file's pathname. +Text +columns are of equal width, with at least one +separation between text columns. +Lines that do not fit into +a text column are truncated. +If standard output is associated +with a terminal, diagnostic messages are suppressed +until the pr utility has completed processing. +.Pp +The following options are available: +.Tw Fl +.Tp Ar +page +Begin output at page number page of the +formatted input. +.Tp Ar \-column +Produce output that is columns wide (default +is 1) and is in text column rank order. +This +option should not be used with \-m. +When +used with \-t, use the minimum number of lines +to display the output. +.Tp Fl f +Use character for new pages, +instead of the default behavior that uses a +sequence of characters. +Prior to +displaying the first page of output an + character is written to standard output. +.Tp Cx Fl h +.Ar header +.Cx +Use the string header as the header to be +printed instead of file. +.Tp Cx Fl l +.Ar lines +.Cx +Override the 66 line default and reset the +page length to lines. +If lines is smaller +than the sum of both the header and trailer +depths (in lines), the pr utility suppresses +both the header and trailer, as if the \-t +option were in effect. +.Tp Fl m +Merge files. +Standard output is formatted so +the +.Nm pr +utility writes one line from each file +specified by a file operand, side by side +into text columns of equal fixed widths, in +terms of the number of column positions. +.Tp Cx Fl s +.Ar char +.Cx +Separate text columns by the single character +char instead of by the appropriate number of +s (default for char is the character). +.Tp Fl t +Print neither the five-line identifying +header nor the five-line trailer usually +supplied for each page. +Quit printing after the +last line of each file without spacing to the +end of the page. +.Tp Cx Fl w +.Ar width +.Cx +Set the width of the line to width column +positions for multiple text-column output +only (default is 72). +.Tp +.Pp +The following operands are available: +.Tw Fl +.Tp Ar file +A pathname of a file to be printed. +.Tp +.Pp +If no file +operands are specified, or if a file operand is \-, +the standard input is used. +.Pp +The standard input is used only if no file operands are +specified, or if a file operand is \-. +.Pp +If pr receives an interrupt while printing to a terminal, it +flushes all accumulated error messages to the screen before +terminating. +.Pp +The pr utility output is a paginated version of the original +file (or files). +This pagination is optionally done using +s or a sequence of s. +Page headers are +generated unless the \-t option is specified. +.Pp +The +.Nm pr +utility exits 0 on success, and >0 if an error occurs. +.Pp +Error +messages are written to standard error during the printing +process (if output is redirected) or after all successful +file printing is complete (when printing to a terminal). +.Sh FILES +.Sh STANDARDS +The +.Nm pr +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/old/ratfor/ratfor.1 b/usr/src/old/ratfor/ratfor.1 index ab24f96b7b..ebb20ee1dc 100644 --- a/usr/src/old/ratfor/ratfor.1 +++ b/usr/src/old/ratfor/ratfor.1 @@ -1,67 +1,74 @@ -.\" @(#)ratfor.1 6.1 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH RATFOR 1 "" -.AT 3 -.SH NAME -ratfor \- rational Fortran dialect -.SH SYNOPSIS -.B ratfor -[ option ... ] -[ filename ... ] -.SH DESCRIPTION -.I Ratfor +.\" %sccs.include.redist.man% +.\" +.\" @(#)ratfor.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt RATFOR 1 +.Os ATT 7th +.Sh NAME +.Nm ratfor +.Nd rational Fortran dialect +.Sh SYNOPSIS +.Nm ratfor +.Op Ar option ... +.Op Ar filename ... +.Sh DESCRIPTION +.Nm Ratfor converts a rational dialect of Fortran into ordinary irrational Fortran. -.I Ratfor +.Nm Ratfor provides control flow constructs essentially identical to those in C: -.TP -statement grouping: -.nf +.Tw Fl +.Tp statement grouping: { statement; statement; statement } -.TP -decision-making: -if (condition) statement [ else statement ] -.br +.Tp decision-making: +.Ds I +if (condition) statement { else statement } switch (integer value) { - case integer: statement - ... - [ default: ] statement +\tcase integer: statement +\t... +\t[default]: statement } -.TP -loops: +.De +.Tp loops: +.Ds L while (condition) statement for (expression; condition; expression) statement do limits statement -repeat statement [ until (condition) ] +repeat statement [until (condition)] break next -.LP +.De +.Tp +.Pp and some syntactic sugar to make programs easier to read and write: -.TP -free form input: +.Tw Fl +.Tp free form input: multiple statements/line; automatic continuation -.TP -comments: +.Tp comments: # this is a comment -.TP -translation of relationals: +.Tp translation of relationals: >, >=, etc., become .GT., .GE., etc. -.TP -return (expression) +.Tp return (expression) returns expression to caller from function -.TP -define: +.Tp define: define name replacement -.TP -include: +.Tp include: include filename -.PP -.fi -.I Ratfor +.Tp +.Pp +.Nm Ratfor is best used with -.IR f77 (1). -.SH "SEE ALSO" -f77(1) +.Xr f77 1 . +.Sh SEE ALSO +.Xr f77 1 .br B. W. Kernighan and P. J. Plauger, -.IR "Software Tools" , -Addison-Wesley, 1976. +.Em Software Tools , +Addison-Wesley, +1976. +.Sh HISTORY +.Nm Ratfor +appeared in Version 7 AT&T UNIX. diff --git a/usr/src/old/refer/addbib/addbib.1 b/usr/src/old/refer/addbib/addbib.1 index 01ea5c1836..dec361065e 100644 --- a/usr/src/old/refer/addbib/addbib.1 +++ b/usr/src/old/refer/addbib/addbib.1 @@ -1,99 +1,169 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)addbib.1 6.1 (Berkeley) %G% .\" -.TH ADDBIB 1 "" -.UC 5 -.SH NAME -addbib \- create or extend bibliographic database -.SH SYNOPSIS -\fBaddbib\fP [ \fB\-p\fP promptfile ] [ \fB\-a\fP ] database -.SH DESCRIPTION -When this program starts up, answering ``y'' -to the initial ``Instructions?'' prompt yields directions; -typing ``n'' or \s-2RETURN\s0 skips them. -.I Addbib +.\" @(#)addbib.1 6.2 (Berkeley) %G% +.\" +.Dd +.Os BSD 4.2 +.Dt ADDBIB 1 +.Sh NAME +.Nm addbib +.Nd create or extend bibliographic database +.Sh SYNOPSIS +.Nm addbib +.Op Fl p Ar promptfile +.Op Fl a +.Ar database +.Sh DESCRIPTION +When this program starts up, answering +.Li y +to the initial +.Li Instructions? +prompt yields directions; +typing +.Li n +or +.Li RETURN +skips them. +.Nm Addbib then prompts for various bibliographic fields, reads responses from the terminal, and sends output records to a -.I database. -A null response (just \s-2RETURN\s0) means to leave out that field. -A minus sign (\-) means to go back to the previous field. +.Ar database . +A null response (just +.Li RETURN ) +means to leave out that field. +A minus sign +.Li (\-) +means to go back to the previous field. A trailing backslash allows a field to be continued on the next line. -The repeating ``Continue?'' prompt allows the user -either to resume by typing ``y'' or \s-2RETURN\s0, -to quit the current session by typing ``n'' or ``q'', +The repeating +.Li Continue? +prompt allows the user +either to resume by typing +.Li y +or +.Li RETURN , +to quit the current session by typing +.Li n +or +.Li q , or to edit the -.I database -with any system editor \fI(vi, ex, edit, ed).\fP -.PP +.Ar database +with any system editor (.e.g. +.Xr vi , +.Xr ex , +.Xr edit , +.Xr ed ) . +.Pp The -.B \-a +.Fl a option suppresses prompting for an abstract; asking for an abstract is the default. -Abstracts are ended with a \s-2CTRL\s0-d. +Abstracts are ended with a +.Li CTRL-d . The -.B \-p +.Fl p option causes -.I addbib +.Nm addbib to use a new prompting skeleton, defined in -.I promptfile. +.Ar promptfile . This file should contain prompt strings, a tab, and the key-letters to be written to the -.I database. -.PP +.Ar database . +.Pp The most common key-letters and their meanings are given below. -.I Addbib +.Nm Addbib insulates you from these key-letters, since it gives you prompts in English, but if you edit the bibliography file later on, you will need to know this information. -.sp -.nf - %A Author's name - %B Book containing article referenced - %C City (place of publication) - %D Date of publication - %E Editor of book containing article referenced - %F Footnote number or label (supplied by \fIrefer\fP\|) - %G Government order number - %H Header commentary, printed before reference - %I Issuer (publisher) - %J Journal containing article - %K Keywords to use in locating reference - %L Label field used by \fB\-k\fP option of \fIrefer\fP - %M Bell Labs Memorandum (undefined) - %N Number within volume - %O Other commentary, printed at end of reference - %P Page number(s) - %Q Corporate or Foreign Author (unreversed) - %R Report, paper, or thesis (unpublished) - %S Series title - %T Title of article or book - %V Volume number - %X Abstract \(em used by \fIroffbib\fP, not by \fIrefer\fP - %Y,Z ignored by \fIrefer\fP -.fi -.sp +.Dw \&%Y,Z +.Dp \&%A +Author's name +.Dp \&%B +Book containing article referenced +.Dp \&%C +City (place of publication) +.Dp \&%D +Date of publication +.Dp \&%E +Editor of book containing article referenced +.Dp \&%F +Footnote number or label (supplied by +.Xr refer ) +.Dp \&%G +Government order number +.Dp \&%H +Header commentary, printed before reference +.Dp \&%I +Issuer (publisher) +.Dp \&%J +Journal containing article +.Dp \&%K +Keywords to use in locating reference +.Dp \&%L +Label field used by +.Fl k +option of +.Xr refer +.Dp \&%M +Memorandum label +.Dp \&%N +Number within volume +.Dp \&%O +Other commentary, printed at end of reference +.Dp \&%P +Page number(s) +.Dp \&%Q +Corporate or Foreign Author (unreversed) +.Dp \&%R +Report, paper, or thesis (unpublished) +.Dp \&%S +Series title +.Dp \&%T +Title of article or book +.Dp \&%V +Volume number +.Dp \&%X +Abstract \(em used by +.Xr roffbib , +not by +.Xr refer +.Dp \&%Y,Z +ignored by +.Xr refer +.Dp +.Pp Except for `A', each field should be given just once. Only relevant fields should be supplied. -An example is: -.sp -.nf - %A Bill Tuthill - %T Refer \(em A Bibliography System - %I Computing Services - %C Berkeley - %D 1982 - %O \s-1UNX\s0 4.3.5. -.fi -.sp -.SH FILES -.DT -promptfile optional file to define prompting -.SH SEE ALSO -refer(1), sortbib(1), roffbib(1), indxbib(1), lookbib(1) -.SH AUTHORS +.Sh EXAMPLES +.Dw \&%Y,Z +.Dp %A +Bill Tuthill +.Dp %T +Refer \(em A Bibliography System +.Dp %I +Computing Services +.Dp %C +Berkeley +.Dp %D +1982 +.Dp %O +\s-1UNX\s0 4.3.5. +.Dp +.Sh FILES +.Dw promptfile +.Dp Pa promptfile +optional file to define prompting +.Sh SEE ALSO +.Xr refer 1 , +.Xr sortbib 1 , +.Xr roffbib 1 , +.Xr indxbib 1 , +.Xr lookbib 1 +.Sh HISTORY +appeared in 4.2 BSD. +.Sh AUTHORS Al Stangenberger, Bill Tuthill diff --git a/usr/src/old/roff/nroff/nroff.1 b/usr/src/old/roff/nroff/nroff.1 index d707c1414f..35367924bb 100644 --- a/usr/src/old/roff/nroff/nroff.1 +++ b/usr/src/old/roff/nroff/nroff.1 @@ -1,179 +1,185 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)nroff.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH NROFF 1 "" -.UC 5 -.SH NAME -nroff \- text formatting -.SH SYNOPSIS -.B nroff -[ option ] ... -[ file ] ... -.SH DESCRIPTION -.I Nroff +.\" @(#)nroff.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt NROFF 1 +.Os BSD 4.2 +.Sh NAME +.Nm nroff +.Nd text formatting +.Sh SYNOPSIS +.Nm nroff +.Op option +\&... +.Op file +\&... +.Sh DESCRIPTION +.Nm Nroff formats text in the named -.I files -for typewriter-like devices. See also -.I troff(1). +.Ar files +for typewriter-like devices. See also +.Xr troff 1 . The full capabilities of -.I nroff +.Nm nroff are described in the -.I Nroff/Troff User's Manual. -.PP +.Em Nroff/Troff User's Manual . +.Pp If no -.I file +.Ar file argument is present, the standard input is read. An argument consisting of a single minus -.RB ( \- ) +.Fl is taken to be a file name corresponding to the standard input. -.PP +.Pp The options, which may appear in any order so long as they appear -.I before +.Ar before the files, are: -.TP "\w'\f3\-m\f1name 'u" -.BI \-o list +.Tw Fl +.Tp Cx Fl o +.Ar list +.Cx Print only pages whose page numbers appear in the comma-separated -.I list +.Ar list of numbers and ranges. A range -.IB N \- M +.Ar N\-M means pages -.I N +.Ar N through -.IR M ; +.Ar M ; an initial -.I \-N +.Ar \-N means from the beginning to page -.IR N ; +.Ar N ; and a final -.IR N \- +.Ar N\- means from -.I N +.Ar N to the end. -.TP -.BI \-n N +.Tp Cx Fl n +.Ar N +.Cx Number first generated page -.IR N . -.TP -.BI \-s N +.Ar N . +.Tp Cx Fl s +.Ar N +.Cx Stop every -.I N +.Ar N pages. -.I Nroff +.Nm Nroff will halt prior to every -.I N +.Ar N pages (default -.IR N =1) +.Cx Ar N +.Cx =1) +.Cx to allow paper loading or changing, and will resume upon receipt of a newline. -.TP -.BI \-m name +.Tp Cx Fl m +.Ar name +.Cx Prepend the macro file -.BI /usr/lib/tmac/tmac. name +.Pa /usr/share/tmac/tmac.name to the input -.IR files . -.TP -.BI \-r aN +.Ar files . +.Tp Cx Fl r +.Ar aN +.Cx Set register -.I a +.Ar a (one-character) to -.IR N . -.TP -.B \-i +.Ar N . +.Tp Fl i Read standard input after the input files are exhausted. -.TP -.B \-q +.Tp Fl q Invoke the simultaneous input-output mode of the -.B rd +.Ar rd request. -.TP -.BI \-T name -Prepare output for specified terminal. Known \fInames\fP are: -.PP -.RS -.TP -.BR 37 +.Tp Cx Fl T +.Ar name +.Cx +Prepare output for specified terminal. Known +.Ar names +are: +.Pp +.Tw Cm +.Tp Cm 37 for the Teletype Corporation Model 37 terminal, -.TP -.BR crt +.Tp Cm crt the default; linked to lpr and tn300, for the GE TermiNet 300 (or any terminal without reverse-line or half-line capability), -.TP -.BR 300 +.Tp Cm 300 for the DTC 300, -.TP -.BR 302 +.Tp Cm 302 for the DTC 302S and the DTC 300S, -.TP -.BR 382 +.Tp Cm 382 for the DTC 382, -.TP -.BR 450 +.Tp Cm 450 for the DTC 450 and the IPSI 1622, -.TP -.BR 833 +.Tp Cm 833 for the AJ 832/833, -.TP -.BR epson +.Tp Cm epson for the Epson FX80, -.TP -.BR itoh +.Tp Cm itoh for the C:ITOH Prowriter -.TP -.BR nec +.Tp Cm nec for the NEC-55?0/77?0 Spinwriter, with the Courier-72/Manifold thimble, -.TP -.BR nec-t +.Tp Cm nec-t for the NEC-55?0/77?0 Spinwriter, with the Tech-Math/Times-Roman thimble, -.TP -.BR nec25-t +.Tp Cm nec25-t for the NEC-5525/7725 Spinwriter, with the Tech-Math/Times-Roman thimble, -.TP -.BR qume +.Tp Cm qume for the Qume Sprint 5 or 9, -.TP -.BR x-ecs +.Tp Cm x-ecs for the Xerox/Diablo 1730/630, extended character set, -.TP -.BR xerox +.Tp Cm xerox for the Xerox 17?0 or the Diablo 16?0. - -Most of these also have versions for 12 pitch; see -\fI/usr/lib/term/README\fP for more information. -.RE -.PP -.TP -.B \-e +Most of these also have versions for 12 pitch. +where did this file go? see +.Pa /usr/libdata/term/README +for more information. +.Tp Fl e Produce equally-spaced words in adjusted lines, using full terminal resolution. -.TP -.B \-h +.Tp Fl h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every 8 nominal character widths. -.SH FILES -.ta \w'/usr/lib/tmac/tmac.* 'u -/tmp/ta* temporary file -.br -/usr/lib/tmac/tmac.* standard macro files +.Tp +.Sh FILES +.Dw /usr/share/tmac/tmac.* +.Di L +.Dp Pa /tmp/ta* +temporary file +.Dp Pa /usr/share/tmac/tmac.* +standard macro files +.Dp Pa /usr/libdata/term/* +terminal driving tables for +.Nm nroff .br -/usr/lib/term/* terminal driving tables for -.I nroff -.br -.SH "SEE ALSO" +.Dp +.Sh SEE ALSO J. F. Ossanna, -.I Nroff/Troff user's manual +.Em Nroff/ Troff user's manual .br B. W. Kernighan, -.I A TROFF Tutorial +.Em A TROFF Tutorial .br -troff(1), -eqn(1), -tbl(1), -ms(7), -me(7), -man(7), -col(1) +.Xr troff 1 , +.Xr eqn 1 , +.Xr tbl 1 , +.Xr ms 7 , +.Xr me 7 , +.Xr man 7 , +.Xr col 1 +.Sh HISTORY +.Nm Nroff +appeared in Version 6 AT&T UNIX. +The version described here is +Version 7. + diff --git a/usr/src/old/sh/sh.1 b/usr/src/old/sh/sh.1 index b57bfa7f02..70c7fc3c70 100644 --- a/usr/src/old/sh/sh.1 +++ b/usr/src/old/sh/sh.1 @@ -1,866 +1,962 @@ -.\" @(#)sh.1 6.3 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH SH 1 "" -.AT 3 -.SH NAME -sh, for, case, if, while, \fB:\fP, \fB.\fP, break, continue, cd, eval, exec, exit, export, login, read, readonly, set, shift, times, trap, umask, wait \- command language -.SH SYNOPSIS -.B sh -[ -.B \-ceiknrstuvx -] [ arg ] ... -.ds OK [\| -.ds CK \|] -.ds LT \s-2<\s0 -.ds GT \s-2>\s0 -.ds LE \s-2<\s0 -.ds ST * -.SH DESCRIPTION -.I Sh +.\" %sccs.include.redist.man% +.\" +.\" @(#)sh.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt SH 1 +.Os ATT 7th +.Sh NAME +.Nm sh +.Nd shell command interpreter +.Sh SYNOPSIS +.Nm sh +.Op Fl ceiknrstuvx +.Op arg +.Ar ... +.Sh DESCRIPTION +.Nm Sh is a command programming language that executes commands read from a terminal -or a file. See -.B invocation -for the meaning of arguments to the shell. -.PP -.B Commands. -.br +or a file. The shell this page describes is called the +.Em Bourne +shell. +.Pp +Command line options: +.Pp +If the first character of argument 0 if +.Fl , +commands are read from +.Pa $HOME/.profile , +if such a file exists. +The following flags are interpreted by the shell when it is invoked. +.Tw Fl +.Tp Cx Fl c +.Cx \&\ \& +.Ar string +.Cx +Commands are read from +.Ar string. +.Tp Fl s +If the +.Fl s +flag is present or if no arguments remain +then commands are read from the standard input. +Shell output is written to file descriptor 2. +.Tp Fl i +If the +.Fl i +flag is present or +if the shell input and output are attached to a terminal (as told by +.Xr getty ) +then this shell is +.Em interactive . +In this case the terminate signal SIGTERM (see +.Xr sigvec 2 ) +is ignored (so that 'kill 0' +does not kill an interactive shell) and the interrupt signal +SIGINT is caught and ignored (so that +.Xr wait +is interruptible). +In all cases SIGQUIT is ignored by the shell. +.Tp +.Pp +This next set of options can be used on the command line invoking +the +.Nm sh +or set with the interactive command +.Ic set . +.Tp Fl e +If non interactive, exit immediately if a command fails. +.Tp Fl k +All keyword arguments are placed in the environment for a command, +not just those that precede the command name. +.Tp Fl n +Read commands but do not execute them. +.Tp Fl t +Exit after reading and executing one command. +.Tp Fl u +Treat unset variables as an error when substituting. +.Tp Fl v +Print shell input lines as they are read. +.Tp Fl x +Print commands and their arguments as they are executed. +.Tp Fl +Turn off the +.Fl x +and +.Fl v +options. +.Tp +.Ss Commands . A -.I simple-command +.Em simple-command is a sequence of non blank -.I words +.Em words separated by blanks (a blank is a -.B tab +.Em tab or a -.BR space ). +.Em space ) . The first word specifies the name of the command to be executed. Except as specified below the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see -.IR execve (2)). +.Xr execve 2 ) . The -.I value +.Em value of a simple-command is its exit status -if it terminates normally or 200+\fIstatus\fP if it terminates abnormally (see -.IR sigvec (2) +if it terminates normally or +.Cx Li 200+ +.Em status +.Cx +if it terminates abnormally (see +.Ar sigvec 2 for a list of status values). -.LP +.Pp A -.I pipeline +.Em pipeline is a sequence of one or more -.I commands +.Em commands separated by -.B \(or. +.Sq Nm \&| . The standard output of each command but the last is connected by a -.IR pipe (2) +.Xr pipe 2 to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. -.LP +.Pp A -.I list +.Em list is a sequence of one or more -.I pipelines +.Em pipelines separated by -.BR ; , -.BR & , -.B && +.Nm \&; , +.Nm \&& , +.Nm \&&& or -.B \(or\|\(or +.Nm \&| +or +.Nm \&|\&| and optionally terminated by -.B ; +.Nm \&; or -.BR & . -.B ; +.Nm \&& . +.Nm \&; and -.B & +.Nm \&& have equal precedence which is lower than that of -.B && +.Nm \&&& and -.BR \(or\|\(or , -.B && +.Nm \&|\&| , +.Nm && and -.B \(or\|\(or +.Nm \&|\&| , also have equal precedence. A semicolon causes sequential execution; an ampersand causes the preceding -.I pipeline +.Em pipeline to be executed without waiting for it to finish. The symbol -.B && -.RB ( \(or\|\(or ) +.Nm \&&& +.Pq Nm \&|\&| causes the -.I list +.Em list following to be executed only if the preceding -.I pipeline +.Em pipeline returns a zero (non zero) value. Newlines may appear in a -.I list, +.Em list , instead of semicolons, to delimit commands. -.LP +.Pp A -.I command +.Em command is either a simple-command or one of the following. The value returned by a command is that of the last simple-command executed in the command. -.TP -\fBfor \fIname\fR \*(OK\fBin \fIword\fR ...\*(CK \fBdo \fIlist \fBdone\fR +.Tw Fl +.Tp Cx Ic for +.Cx \&\ \& +.Ar name +.Cx \&\ \& +.Op Ic in Ar word ... +.Cx \&\ \& +.Ic do +.Cx \&\ \& +.Ar list +.Cx \&\ \& +.Ic done +.Cx Each time a -.B for +.Ic for command is executed -.I name +.Ar name is set to the next word in the -.B for +.Ic for word list. If -.BI in \ word -\&... +.Ic in +.Ar word \&... is omitted, -.B -in "$@" +.Ic in +.Dq Ic \&$@ is assumed. Execution ends when there are no more words in the list. -.TP -\fBcase \fIword \fBin\fR \*(OK\fIpattern \fR\*(OK \fB\(or \fIpattern \fR\*(CK ... \fB) \fIlist \fB;;\fR\*(CK ... \fBesac\fR +.Tp Cx Ic case +.Cx \&\ \& +.Ar word +.Cx \&\ \& +.Ic in +.Cx \&\ \&[ +.Ar pattern +.Cx \&\ \& +.Op Ar \&| pattern ... +.Cx \&\ \& +.Ic \&) +.Cx \&\ \& +.Ar list +.Cx \&\ \& +.Ic \&;; +.Cx \&]\ \& ... +.Ar esac +.Cx A -.B case +.Ic case command executes the -.I list +.Ar list associated with the first pattern that matches -.I word. +.Ar word . The form of the patterns is the same as that used for file name generation. -.TP -\fBif \fIlist \fBthen \fIlist\fR \*(OK\fBelif \fIlist \fBthen \fIlist\fR\*(CK ... \*(OK\fBelse \fIlist\fR\*(CK \fBfi\fR +.Tp Cx Ic if +.Cx \&\ \& +.Ar list +.Cx \&\ \& +.Ic then +.Cx \&\ \& +.Ar list +.Cx \&\ \& +.Op Ic elif Ar list Ic then Ar list +.Cx \&\ \& +.Cx \&... +.Cx \&\ \& +.Op Ic else Ar list +.Cx \&\ \& +.Ic fi +.Cx The -.I list +.Ar list following -.B if +.Ic if is executed and if it returns zero the -.I list +.Ar list following -.B then +.Ic then is executed. Otherwise, the -.I list +.Ar list following -.B elif +.Ic elif is executed and if its value is zero the -.I list +.Ar list following -.B then +.Ic then is executed. Failing that the -.B else -.I list +.Ic else +.Ar list is executed. -.TP -\fBwhile \fIlist\fR \*(OK\fBdo \fIlist\fR\*(CK \fBdone\fR +.Tp Cx Ic while +.Cx \&\ \& +.Ar list +.Cx \&\ \& +.Op Ic do Ar list +.Cx \&\ \& +.Ic done +.Cx A -.B while +.Ic while command repeatedly executes the -.B while -.I list +.Ic while +.Ar list and if its value is zero executes the -.B do -.I list; +.Ic do +.Ar list ; otherwise the loop terminates. The value returned by a -.B while +.Ic while command is that of the last executed command in the -.B do -.I list. -.B until +.Ic do +.Ar list . +.Ic until may be used in place of -.B while +.Ic while to negate the loop termination test. -.TP -.BI ( " list " ) +.Tp Pq Ar list Execute -.I list +.Ar list in a subshell. -.TP -.BI { " list " } -.I list +.Tp Cx \&{ +.Ar list +.Cx \&} +.Cx +.Ar list is simply executed. -.LP +.Tp +.Pp The following words are only recognized as the first word of a command and when not quoted. -.IP -.B -if then else elif fi case in esac for while until do done { } -.PP -.B Command substitution. -.br -The standard output from a command enclosed in a pair of back quotes -.RB ( \`\|\` ) +.Df I +.Nm if then else elif fi case in esac +.Nm for while until do done \&{ \&} +.De +.Pp +.Ss Command substitution +The standard output from a command enclosed in a pair of back quotes +.Pq Ic \&`` may be used as part or all of a word; trailing newlines are removed. -.PP -.B Parameter substitution. -.br +.Pp +.Ss Parameter substitution . The character -.B $ +.Ic \&$ is used to introduce substitutable parameters. Positional parameters may be assigned values by -.BR set . +.Ic set . Variables may be set by writing -.IP -.IB name = value -[ -.IB name = value -] ... -.TP -$\fB\|{\fIparameter\fB\|}\fR +.Pp +.Df I +.Ar name=value +.Op Ar name=value +\&... +.De +.Pp +.Tp Cx Ic \&$ +.Cx \&\ \& +.Sy \&{ +.Ar parameter +.Sy \&} +.Cx A -.I parameter +.Ar parameter is a sequence of letters, digits or underscores (a -.IR name ), +.Ar name ) , a digit, or any of the characters -.B -* @ # ? \- $ !\|. +.Nm \&* \&@ \&# \&? \&\- \&$ \&!\ The value, if any, of the parameter is substituted. The braces are required only when -.I parameter +.Ar parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If -.I parameter +.Ar parameter is a digit, it is a positional parameter. If -.I parameter +.Ar parameter is -.BR * " or" " @" +.Ic \&* +or +.Ic \&@ then all the positional parameters, starting with -.SM -.BR $1 , +.Ic $1 , are substituted separated by spaces. -.SM -.B $0 +.Ic $0 is set from argument zero when the shell is invoked. -.TP -$\fB\|{\fIparameter\|\-word\|\fB}\fR +.Tp Cx Ic \&$ +.Cx \&\ \& +.Sy \&{ +.Ar parameter +.Fl +.Ar word +.Sy \&} +.Cx If -.I parameter +.Ar parameter is set, substitute its value; otherwise substitute -.I word. -.TP -$\fB\|{\fIparameter\|\(eq\|word\|\fB}\fR +.Ar word . +.Tp Cx Ic \&$ +.Cx \&\ \& +.Sy \&{ +.Ar parameter +.Ic \&= +.Ar word +.Cx \&\ \& +.Sy \&} +.Cx If -.I parameter +.Ar parameter is not set, set it to -.I word; +.Ar word ; the value of the parameter is then substituted. Positional parameters may not be assigned to in this way. -.TP -$\fB\|{\fIparameter\|?\|word\|\fB}\fR +.Tp Cx Ic \&$ +.Cx \&\ \& +.Sy \&{ +.Ar parameter +.Ic \&? +.Ar word +.Sy \&} +.Cx If -.I parameter +.Ar parameter is set, substitute its value; otherwise, print -.I word +.Ar word and exit from the shell. If -.I word +.Ar word is omitted, a standard message is printed. -.TP -$\fB\|{\fIparameter\|\(plword\|\fB}\fR +.Tp Cx Ic \&$ +.Cx \&\ \& +.Sy \&{ +.Ar parameter +.Ic \&+ +.Ar word +.Sy \&} +.Cx If -.I parameter +.Ar parameter is set, substitute -.I word; +.Ar word ; otherwise substitute nothing. -.LP +.Tp +.Pp In the above -.I word +.Ar word is not evaluated unless it is to be used as the substituted string. (So that, for example, echo ${d\-\'pwd\'} will only execute -.I pwd +.Ar pwd if -.I d +.Ar d is unset.) -.LP +.Pp The following -.I parameters +.Ar parameters are automatically set by the shell. -.RS -.TP -.B # +.Pp +.Dw Ds +.Dp Ic \&# The number of positional parameters in decimal. -.PD 0 -.TP -.B \- +.Dp Fl Options supplied to the shell on invocation or by -.BR set . -.TP -.B ? +.Ar set . +.Dp Ic \&? The value returned by the last executed command in decimal. -.TP -.B $ +.Dp Ic \&$ The process number of this shell. -.TP -.B ! +.Dp Ic \&! The process number of the last background command invoked. -.PD -.RE -.LP +.Dp +.De +.Pp The following -.I parameters +.Ar parameters are used but not set by the shell. -.RS -.TP -.B -.SM HOME +.Pp +.Ds I +.Tp Ev HOME The default argument (home directory) for the -.B cd +.Ic cd command. -.PD 0 -.TP -.B -.SM PATH +.Tp Ev PATH The search path for commands (see -.BR execution ). -.TP -.B -.SM MAIL +.Ar execution ) . +.Tp Ev MAIL If this variable is set to the name of a mail file, the shell informs the user of the arrival of mail in the specified file. -.SM -.TP -.B PS1 +.Tp Ev PS1 Primary prompt string, by default '$ '. -.TP -.SM -.B PS2 +.Tp Ev PS2 Secondary prompt string, by default '> '. -.TP -.SM -.B IFS +.Tp Ev IFS Internal field separators, normally -.BR space , -.BR tab , +.Em space , +.Em tab , and -.BR newline . -.B IFS -is ignored if -.I sh +.Em newline . +.Ev IFS +is ignored if +.Nm sh is running as root or if the effective user id differs from the real user id. -.PD -.RE -.PP -.B Blank interpretation. -.br +.Tp +.De +.Ss Blank interpretation . After parameter and command substitution, any results of substitution are scanned for internal field separator characters (those found in -.SM -.BR $IFS \*S) +.Cx Ic $ +.Ev IFS ) +.Cx and split into distinct arguments where such characters are found. Explicit null arguments ("" or \'\') are retained. Implicit null arguments (those resulting from -.I parameters +.Em parameters that have no values) are removed. -.PP -.B File name generation. -.br +.Pp +.Ss File name generation . Following substitution, each command word is scanned for the characters -.BR * , -.B ? +.Ic \&* , +.Ic \&? and -.B \*(OK. +.Ic \&[ . If one of these characters appears, the word is regarded as a pattern. The word is replaced with alphabetically sorted file names that match the pattern. If no file name is found that matches the pattern, the word is left unchanged. The character -.B . +.Ic \&. at the start of a file name or immediately following a -.BR / , +.Ic \&/ , and the character -.BR / , +.Ic \&/ , must be matched explicitly. -.TP -.B \*(ST +.Dp Ic \&*\& Matches any string, including the null string. -.PD 0 -.TP -.B ? +.Dp Ic \&? Matches any single character. -.TP -.B \*(OK...\*(CK +.Dp Ic \&[...] Matches any one of the characters enclosed. A pair of characters separated by -.B \- +.Fl matches any character lexically between the pair. -.PD -.PP -.B Quoting. -.br +.Dp +.Pp +.Ss Quoting . The following characters have a special meaning to the shell and cause termination of a word unless quoted. -.LP - \fB; & ( ) \(or \*(LT \*(GT newline space tab\fP -.LP +.Pp +.Df I +.Sy \&; \&& \&( \&) \&| \&< \&> +.Sy newline space tab +.De +.Pp A character may be -.I quoted +.Ar quoted by preceding it with a -.B -\\\|. -.B \\\\newline +.Sq Sy \e . +.Sy \enewline is ignored. -All characters enclosed between a pair of quote marks (\fB\'\|\'\fP), -except a single quote, are quoted. Inside double quotes (\fB"\|"\fP) +All characters enclosed between a pair of quote marks +.Pq Sq , +except a single quote, are quoted. Inside double quotes +.Pq Dq parameter and command substitution occurs and -.B -\\ +.Sy \e quotes the characters -.B -\\ \' " +.Sy \e\' " and -.BR $ \|. -.LP -.B -"$*" +.Sy \&$ . +.Pp +.Dq \&$* is equivalent to -.SM -.B -"$1 $2 ..." +.Dq Sy $1 $2 \&... whereas .br -.B -"$@" +.Dq Sy $@ is equivalent to -.SM -.B -"$1" "$2" ... . -.PP -.B Prompting. -.br +.Dq Sy $1 +.Dq Sy $2 +\&...\ . +.Pp +.Ss Prompting . When used interactively, the shell prompts with the value of -.SM -PS1 +.Ev PS1 before reading a command. If at any time a newline is typed and further input is needed to complete a command, the secondary prompt -.RB ( \s-2$PS2\s0 ) +.Cx Sy $ +.Ev PS2 +.Cx is issued. -.PP -.B Input output. -.br +.Pp +.Ss Input/Output . Before a command is executed its input and output may be redirected using a special notation interpreted by the shell. The following may appear anywhere in a simple-command or may precede or follow a -.I command +.Ar command and are not passed on to the invoked command. Substitution occurs before -.I word +.Ar word or -.I digit +.Ar digit is used. -.TP -\*(LT\fI\|word\fP +.Tw Ic +.Tp Cx Ic \&< +.Cx \&\ \& +.Ar word +.Cx Use file -.I word +.Ar word as standard input (file descriptor 0). -.PD -.TP -\*(GT\fI\|word\fP +.Tp Cx Ic \&> +.Cx \&\ \& +.Ar word +.Cx Use file -.I word +.Ar word as standard output (file descriptor 1). If the file does not exist, it is created; otherwise it is truncated to zero length. -.TP -\*(GT\*(GT\fI\|word\fP +.Tp Cx Ic \&>\&> +.Cx \&\ \& +.Ar word +.Cx Use file -.I word +.Ar word as standard output. If the file exists, output is appended (by seeking to the end); otherwise the file is created. -.TP -\*(LT\*(LT\fI\|word\fP +.Tp Cx Ic \&<\&< +.Cx \&\ \& +.Ar word +.Cx The shell input is read up to a line the same as -.IR word , +.Ar word , or end of file. The resulting document becomes the standard input. If any character of -.I word +.Ar word is quoted, no interpretation is placed upon the characters of the document; otherwise, parameter and command substitution occurs, -.B -\\newline +.Sy \enewline is ignored, and -.B -\\ +.Sy \e is used to quote the characters -.B -\\ $ \' +.Sy \&$ \&\' and the first character of -.I word. -.TP -\*(LT\|&\|\fIdigit\fP +.Ar word . +.Tp Cx Ic \&<\&& +.Cx \&\ \& +.Ar digit +.Cx The standard input is duplicated from file descriptor -.I digit; +.Ar digit ; see -.IR dup (2). -Similarly for the standard output using \*(GT\|. -.TP -\*(LT\|&\|\- +.Xr dup 2 . +Similarly for the standard output using +.Ic \&> . +.Tp Ic \&<\&&\- The standard input is closed. -Similarly for the standard output using \*(GT\|. -.PD -.LP +Similarly for the standard output using +.Ic \&> . +.Tp +.Pp If one of the above is preceded by a digit, the file descriptor created is that specified by the digit (instead of the default 0 or 1). For example, -.LP - \&... 2\*(GT&1 -.LP +.Pp +.Dl \&... 2>&1 +.Pp creates file descriptor 2 to be a duplicate of file descriptor 1. -.LP +.Pp If a command is followed by -.B & +.Ic \&& then the default standard input for the command is the empty file -(/dev/null). +.Pq Pa dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input output specifications. -.PP -.B Environment. -.br +.Pp +.Ss Environment The environment is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list; see -.IR execve (2) +.Xr execve 2 and -.IR environ (7). +.Xr environ 7 . The shell interacts with the environment in several ways. On invocation, the shell scans the environment and creates a -.I parameter +.Ar parameter for each name found, giving it the corresponding value. Executed commands inherit the same environment. If the user modifies the values of these -.I parameters +.Ar parameters or creates new ones, none of these affects the environment unless the -.B export +.Ic export command is used to bind the shell's -.I parameter +.Ar parameter to the environment. The environment seen by any executed command is thus composed of any unmodified name-value pairs originally inherited by the shell, plus any modifications or additions, all of which must be noted in -.B export +.Ic export commands. -.LP +.Pp The environment for any -.I simple-command +.Ar simple-command may be augmented by prefixing it with one or more assignments to -.I parameters. +.Ar parameters . Thus these two lines are equivalent -.IP -TERM=450 cmd args -.br -(export TERM; TERM=450; cmd args) -.LP +.Pp +.Dl TERM=450 cmd args +.Dl (export TERM; TERM=450; cmd args) +.Pp If the -.B \-k +.Fl k flag is set, -.I all +.Ar all keyword arguments are placed in the environment, -even if the occur after the command name. +even if they occur after the command name. The following prints 'a=b c' and 'c': -.nf +.Pp +.Ds I echo a=b c set \-k echo a=b c -.fi -.PP -.B Signals. -.br +.De +.Pp +.Ss Signals . The INTERRUPT and QUIT signals for an invoked command are ignored if the command is followed by -.BR & ; +.Ic \&& ; otherwise signals have the values inherited by the shell from its parent. (But see also -.BR trap. ) -.PP -.B Execution. -.br +.Ic trap . ) +.Pp +.Ss Execution . Each time a command is executed the above substitutions are carried out. Except for the 'special commands' listed below a new process is created and an attempt is made to execute the command via an -.IR execve (2). -.LP +.Xr execve 2 . +.Pp The shell parameter -.B -.SM $PATH +.Cx Ic \&$ +.Ev $PATH +.Cx defines the search path for the directory containing the command. Each alternative directory name is separated by a colon -.RB ( : ). +.Pq Sy \&: . The default path is -.BR :/bin:/usr/bin . -If the command name contains a /, the search path is not used. +.Pa :/bin:/usr/bin . +If the command name contains a +.Sy / , +the search path is not used. Otherwise, each directory in the path is searched for an executable file. If the file has execute permission but is not an -.I a.out +.Pa a.out file, it is assumed to be a file containing shell commands. A subshell (i.e., a separate process) is spawned to read it. A parenthesized command is also executed in a subshell. -.PP -.B Special commands. -.br +.Pp +.Ss Special commands . The following commands are executed in the shell process and except where specified no input output redirection is permitted for such commands. -.TP -.B # +.Tw Fl +.Tp Ic \&# For non-interactive shells, everything following the -.B # +.Ic \&# is treated as a comment, i.e. the rest of the line is ignored. For interactive shells, the -.B # +.Ic \&# has no special effect. -.TP -.B : +.Tp Ic \&:\& No effect; the command does nothing. -.PD 0 -.TP -.BI . \ file +.Tp Cx Ic \&.\& +.Ar file +.Cx Read and execute commands from -.I file +.Ar file and return. The search path -.B -.SM $PATH +.Cx Ic \&$ +.Ev PATH +.Cx is used to find the directory containing -.IR file . -.TP -\fBbreak\fR \*(OK\fIn\fR\*(CK +.Ar file . +.Tp Cx Ic break +.Cx \&\ \& +.Op Ar n +.Cx Exit from the enclosing -.B for +.Ic for or -.B while +.Ic while loop, if any. If -.I n +.Ar n is specified, break -.I n +.Ar n levels. -.TP -\fBcontinue\fR \*(OK\fIn\fR\*(CK +.Tp Cx Ic continue +.Cx \&\ \& +.Op Ar n +.Cx Resume the next iteration of the enclosing -.B for +.Ic for or -.B while +.Ic while loop. If -.I n +.Ar n is specified, resume at the -.IR n -th +.Cx Ar n +.Cx \'th +.Cx enclosing loop. -.TP -\fBcd\fR \*(OK\fIarg\fR\*(CK +.Tp Cx Ic cd +.Cx \&\ \& +.Op Ar arg +.Cx Change the current directory to -.I arg. +.Ar arg . The shell parameter -.B -.SM $HOME +.Cx Sy \&$ +.Ev $HOME +.Cx is the default -.IR arg . -.TP -\fBeval\fR \*(OK\fIarg \fR...\*(CK +.Ar arg . +.Tp Cx Ic eval +.Cx \&\ \& +.Op Ar arg \&... +.Cx The arguments are read as input to the shell and the resulting command(s) executed. -.TP -\fBexec\fR \*(OK\fIarg \fR...\*(CK +.Tp Cx Ic exec +.Cx \&\ \& +.Op Ar arg \&... +.Cx The command specified by the arguments is executed in place of this shell without creating a new process. Input output arguments may appear and if no other arguments are given cause the shell input output to be modified. -.TP -\fBexit\fR \*(OK\fIn\fR\*(CK +.Tp Cx Ic exit +.Cx \&\ \& +.Op Ar n +.Cx Causes a non interactive shell to exit with the exit status specified by -.I n. +.Ar n . If -.I n +.Ar n is omitted, the exit status is that of the last command executed. (An end of file will also exit from the shell.) -.TP -\fBexport\fR \*(OK\fIname\fR ...\*(CK +.Tp Cx Ic export +.Cx \&\ \& +.Op Ar name ... +.Cx The given names are marked for automatic export to the -.I environment +.Ar environment of subsequently-executed commands. If no arguments are given, a list of exportable names is printed. -.TP -\fBlogin\fR \*(OK\fIarg\fR ...\*(CK +.Tp Cx Ic login +.Cx \&\ \& +.Op Ar arg ... +.Cx Equivalent to 'exec login arg ...'. -.TP -.BI read \ name\ ... +.Tp Cx Ic read +.Cx \&\ \& +.Ar name \&... +.Cx One line is read from the standard input; successive words of the input are assigned to the variables -.I name +.Ar name in order, with leftover words to the last variable. The return code is 0 unless the end-of-file is encountered. -.TP -\fBreadonly\fR \*(OK\fIname \fR...\*(CK +.Tp Cx Ic readonly +.Cx \&\ \& +.Op Ar name \&... +.Cx The given names are marked readonly and the values of the these names may not be changed by subsequent assignment. If no arguments are given, a list of all readonly names is printed. -.TP -\fBset\fR \*(OK\fB\-eknptuvx\fR \*(OK\fIarg \fR...\*(CK\*(CK -.RS -.PD 0 -.TP 3m -.B \-e -If non interactive, exit immediately if a command fails. -.TP -.B \-k -All keyword arguments are placed in the environment for a command, -not just those that precede the command name. -.TP -.B \-n -Read commands but do not execute them. -.TP -.B \-t -Exit after reading and executing one command. -.TP -.B \-u -Treat unset variables as an error when substituting. -.TP -.B \-v -Print shell input lines as they are read. -.TP -.B \-x -Print commands and their arguments as they are executed. -.TP -.B \- -Turn off the -.B \-x -and -.B \-v -options. -.PD -.LP -These flags can also be used upon invocation of the shell. +.Tp Cx Ic set +.Cx \&\ \& +.Op Fl eknptuvx +.Cx \&\ \& +.Op Ar arg ... +.Cx +The set flags are described in the options section at the beginning +of this man page. The current set of flags may be found in -.BR $\- . -.LP -Remaining arguments are positional +.Ic \&$\- . +.Pp +Remaining arguments after the flag are positional parameters and are assigned, in order, to -.SM -.BR $1 , -.SM -.BR $2 , +.Ic \&$1 , +.Ic \&$2 , etc. If no arguments are given, the values of all names are printed. -.RE -.TP -.B shift +.Tp Ic shift The positional parameters from -.SM -.BR $2 ... +.Ic \&$2 ... are renamed -.SM -.BR $1 ... -.TP -.B times +.Ic $1 ... +.Tp Ic times Print the accumulated user and system times for processes run from the shell. -.TP -\fBtrap\fR \*(OK\fIarg\fR\*(CK \*(OK\fIn\fR\*(CK ... -.I Arg +.Tp Cx Ic trap +.Cx \&\ \& +.Op Ar arg +.Cx \&\ \& +.Op Ar n +.Cx \&\ \& \&... +.Cx +.Ar Arg is a command to be read and executed when the shell receives signal(s) -.I n. +.Ar n . (Note that -.I arg +.Ar arg is scanned once when the trap is set and once when the trap is taken.) Trap commands are executed in order of signal number. If -.I arg +.Ar arg is absent, all trap(s) -.I n +.Ar n are reset to their original values. If -.I arg +.Ar arg is the null string, this signal is ignored by the shell and by invoked commands. If -.I n +.Ar n is 0, the command -.I arg +.Ar arg is executed on exit from the shell, otherwise upon receipt of signal -.I n +.Ar n as numbered in -.IR sigvec (2). -.I Trap +.Xr sigvec 2 . +.Ic Trap with no arguments prints a list of commands associated with each signal number. -.TP -\fBumask \fR[ \fInnn\fR ] +.Tp Cx Ic umask +.Cx \&\ \& +.Op Ar nnn +.Cx The user file creation mask is set to the octal value -.I nnn +.Ar nnn (see -.IR umask (2)). +.Xr umask 2 ) . If -.I nnn +.Ar nnn is omitted, the current value of the mask is printed. -.TP -\fBwait\fP \*(OK\fIn\fP\*(CK +.Tp Cx Ic wait +.Cx \&\ \& +.Op Ar n +.Cx Wait for the specified process and report its termination status. If -.I n +.Ar n is not given, all currently active child processes are waited for. The return code from this command is that of the process waited for. -.PD -.LP -.PP -.B Invocation. -.br -If the first character of argument zero is -.BR \- , -commands are read from -.BR \s-2$HOME\s0/.\|profile , -if such a file exists. -Commands are then read as described below. -The following flags are interpreted by the shell when it is invoked. -.PD 0 -.TP 11n -.BI \-c \ string -If the -.B \-c -flag is present, commands are read from -.I string\|. -.TP 11n -.B \-s -If the -.B \-s -flag is present or if no arguments remain -then commands are read from the standard input. -Shell output is written to file descriptor 2. -.TP 11n -.B \-i -If the -.B \-i -flag is present or -if the shell input and output are attached to a terminal (as told by -.IR gtty ) -then this shell is -.I interactive. -In this case the terminate signal SIGTERM (see -.IR sigvec (2)) -is ignored (so that 'kill 0' -does not kill an interactive shell) and the interrupt signal -SIGINT is caught and ignored (so that -.B wait -is interruptible). -In all cases SIGQUIT is ignored by the shell. -.PD -.LP -The remaining flags and arguments are described under the -.B set -command. -.SH FILES -.RB $HOME/ . \^profile -.br -/tmp/sh* -.br -/dev/null -.SH SEE ALSO -csh(1), -test(1), -execve(2), -environ(7) -.SH DIAGNOSTICS +.Tp +.Sh FILES +.Dw (longest file name here) +.Di L +.Dp Pa $HOME/.profile +.Dp Pa /tmp/sh* +.Dp Pa /dev/null +.Dp +.Sh SEE ALSO +.Xr csh 1 , +.Xr test 1 , +.Xr execve 2 , +.Xr environ 7 +.Sh DIAGNOSTICS Errors detected by the shell, such as syntax errors cause the shell to return a non zero exit status. If the shell is being used non interactively then execution of the shell file is abandoned. Otherwise, the shell returns the exit status of the last command executed (see also -.BR exit ). +.Ic exit ) . +.Sh HISTORY +The +.Nm Sh +shell appeared in Version 6 AT&Y UNIX. .SH BUGS -If \*(LT\*(LT is used to provide standard input to an asynchronous -process invoked by &, the shell gets mixed up about naming the input document. -A garbage file /tmp/sh* is created, and the shell complains about +If +.Ic \&<\&< +is used to provide standard input to an asynchronous +process invoked by +.Ic \&& , +the shell gets mixed up about naming the input document. +A garbage file +.Pa /tmp/sh* +is created, and the shell complains about not being able to find the file by another name. +.\" .Sh ENVIRONMENT +.\" /usr/src/bin/sh/defs.h:STRING *setenv(); +.\" /usr/src/bin/sh/name.c:STRING *setenv() +.\" /usr/src/bin/sh/service.c: xecenv=setenv(); diff --git a/usr/src/old/tar/tar.1 b/usr/src/old/tar/tar.1 index 303a6fe82d..0798ff72c1 100644 --- a/usr/src/old/tar/tar.1 +++ b/usr/src/old/tar/tar.1 @@ -1,4 +1,4 @@ -.\" @(#)tar.1 6.7 (Berkeley) %G% +.\" @(#)tar.1 6.8 (Berkeley) %G% .\" .TH TAR 1 "" .AT 3 diff --git a/usr/src/share/man/man1/cd.1 b/usr/src/share/man/man1/cd.1 index a422f1652f..fb5c5839d3 100644 --- a/usr/src/share/man/man1/cd.1 +++ b/usr/src/share/man/man1/cd.1 @@ -1,37 +1,83 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)cd.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH CD 1 "" -.UC 4 -.SH NAME -cd \- change working directory -.SH SYNOPSIS -.B cd -directory -.SH DESCRIPTION -.I Directory -becomes the new working directory. -The process must have execute (search) -permission in -.IR directory . -.PP -Because a new process is created to execute each command, -.I cd -would be ineffective if it were written as a -normal command. It is therefore recognized and executed -by the shells. -In -.IR csh (1) -you may specify a list of directories in which -.I directory -is to be sought as a subdirectory if it is not -a subdirectory of the current directory; -see the description of the -.I cdpath -variable in -.IR csh (1). -.SH "SEE ALSO" -csh(1), sh(1), pwd(1), chdir(2) +.\" @(#)cd.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt CD 1 +.Os BSD 4 +.Sh NAME +.Nm cd +.Nd change working directory +.Sh SYNOPSIS +.Nm cd +.Ar directory +.Sh DESCRIPTION +The cd utility changes the working directory +to +.Ar directory . +.Pp +.The +.Ar directory +is an absolute or relative pathname +which becomes the new working directory. +The +interpretation of a relative pathname by cd depends +on the CDPATH environment variable (see below). +.Pp +.Sh ENVIRONMENT +The following environment variables affect the execution of +cd: +.Pp +.Tw Ar +.Tp Ev HOME +If +.Nm cd +is +invoked without arguments, the +.Ev HOME +environment variable is checked for a default +directory name. If +.Ev HOME +exists and contains +a directory name, +that directory becomes the new working directory. +.Tp Ev CDPATH +If the +.Ar directory +operand does not +begin with a slash (/) character, and the first +component is not dot (.) or dot-dot (..), +.Nm cd +searches for +the directory relative to each directory named in the +.Ev CDPATH +variable, in the order listed. +The new +working directory is set to the first matching +directory found. +An empty string in place of a +directory pathname represents the current directory. +.Nm Cd +will print the pathname of the new working directory if it +was an element of +.Ev CDPATH . +See +.Xr csh 1 +for info on environment variables. +.Tp +.Pp +The +.Nm cd +utility exits 0 on success, and >0 if an error occurs. +.Sh SEE ALSO +.Xr csh 1 , +.Xr sh 1 , +.Xr pwd 1 , +.Xr chdir 2 +.Sh STANDARDS +The +.Nm cd +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/apply/apply.1 b/usr/src/usr.bin/apply/apply.1 index 02563f690d..8ef1dc5a17 100644 --- a/usr/src/usr.bin/apply/apply.1 +++ b/usr/src/usr.bin/apply/apply.1 @@ -1,86 +1,94 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)apply.1 6.1 (Berkeley) %G% .\" -.TH APPLY 1 "" -.UC 5 -.SH NAME -apply \- apply a command to a set of arguments -.SH SYNOPSIS -.B apply -[ -.B \-a\fIc\fP -] [ -.B \-\fIn\fP -] command args ... -.SH DESCRIPTION -.I Apply +.\" @(#)apply.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt APPLY 1 +.Os BSD 4.2 +.Sh NAME +.Nm apply +.Nd apply a command to a set of arguments +.Sh SYNOPSIS +.Nm apply +.Op Fl ac +.Op Fl n +.Ar command args ... +.Sh DESCRIPTION +.Nm Apply runs the named -.I command +.Ar command on each argument -.I arg +.Ar arg in turn. Normally arguments are chosen singly; the optional number -.I n +.Fl n specifies the number of arguments to be passed to -.I command. +.Ar command . If -.I n +.Fl n is zero, -.I command +.Ar command is run without arguments once for each -.I arg. -Character sequences of the form %\fId\fP +.Ar arg +Character sequences of the form +Cx % +.Ar d +.Cx in -.I command, +.Ar command , where -.I d +.Ar d is a digit from 1 to 9, are replaced by the -\fId\fP'th following unused -.I arg. +.Ar d\'th +following unused +.Ar arg . If any such sequences occur, -.I n +.Fl n is ignored, and the number of arguments passed to -.I command +.Ar command is the maximum value of -.I d +.Ar d in -.I command. +.Ar command . The character `%' may be changed by the -.B \-a +.Fl a option. -.PP -Examples: -.RS -apply echo * -.RE +.SH ENVIRONMENT +.Nm apply +checks the environment variable +.Ev SHELL +to find out which shell to use. +.Sh EXAMPLES +.Ds +.Tw apply \-2 cmp a1 b1 a2 b2 ... +.Tp Li apply echo a* is similar to ls(1); -.RS -apply \-2 cmp a1 b1 a2 b2 ... -.RE +.Tp Li apply \-2 cmp a1 b1 a2 b2 ... compares the `a' files to the `b' files; -.RS -apply \-0 who 1 2 3 4 5 -.RE +.Tp Li apply \-0 who 1 2 3 4 5 runs who(1) 5 times; and -.RS -apply \(aaln %1 /usr/joe\(aa * -.RE -links all files in the current directory to the directory /usr/joe. -.SH "SEE ALSO" -sh(1) -.SH AUTHOR +.Tp Li apply \(aaln %1 /usr/joe\(aa * +links all files in the current directory to the directory +.Pa /usr/joe . +.Tp +.De +.Sh SEE ALSO +.Xr sh 1 +.Sh HISTORY +.Nm Apply +appeared in 4.2BSD. +.Sh AUTHOR Rob Pike -.SH BUGS +.Sh BUGS Shell metacharacters in -.I command +.Ar command may have bizarre effects; it is best to enclose complicated commands in single quotes \(aa\ \(aa. -.sp +.Pp There is no way to pass a literal `%2' if `%' is the argument expansion character. diff --git a/usr/src/usr.bin/apropos/apropos.1 b/usr/src/usr.bin/apropos/apropos.1 index 62567378e2..1f792f5a72 100644 --- a/usr/src/usr.bin/apropos/apropos.1 +++ b/usr/src/usr.bin/apropos/apropos.1 @@ -1,81 +1,83 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)apropos.1 6.7 (Berkeley) %G% +.\" @(#)apropos.1 6.8 (Berkeley) %G% .\" -.TH APROPOS 1 "" -.AT 3 -.SH NAME -apropos \- locate commands by keyword lookup -.SH SYNOPSIS -.nf -.ft B -apropos [-M path] [-m path] keyword ... -.ft R -.fi -.SH DESCRIPTION -.I Apropos +.Dd +.Dt APROPOS 1 +.Sh NAME +.Nm apropos +.Nd locate commands by keyword lookup +.Sh SYNOPSIS +.Nm apropos +.Op Fl M Ar path +.Op Fl m Ar path +.Ar keyword ... +.Sh DESCRIPTION +.Nm Apropos shows which manual pages contain instances of any of the given -.I keyword(s) +.Ar keyword(s) in their title line. Each word is considered separately and case of letters is ignored. Words which are part of other words are considered; when looking for -``compile'', -.I apropos -will also list all instances of ``compiler''. -.PP +\*(Lqcompile\*(Rq, +.Nm apropos +will also list all instances of \*(Lqcompiler\*(Rq. +.Pp If the line output by -.I apropos -starts ``name(section) ...'' you can enter ``man section name'' to get +.Nm apropos +starts +.Li \*(Lqname(section) ...\*(Rq +you can enter +.Li \*(Lqman section name\*(Rq +to get its documentation. -.PP +.Pp The options are as follows: -.TP -.I M +.Tp Fl M Override the list of standard directories where -.I apropos -searches for a database named ``whatis.db''. +.Nm apropos +searches for a database named +.Pa whatis.db . The supplied -.I path -must be a colon (``:'') separated list of directories. +.Ar path +must be a colon (\*(Lq:\*(Rq) separated list of directories. This search path may also be set using the environmental variable -.IR MANPATH . -.TP -.I m +.Ev MANPATH . +.Tp Fl m Augment the list of standard directories where -.I apropos -searches for a database named ``whatis.db''. +.Nm apropos +searches for its database. The supplied -.I path -must be a colon (``:'') separated list of directories. +.Ar path +must be a colon (\*(Lq:\*(Rq) separated list of directories. These directories will be searched before the standard directories or the directories supplied with the -.I M +.Fl M option or the -.I MANPATH +.Ev MANPATH environmental variable are searched. -.SH "ENVIRONMENTAL VARIABLES" -.TP -.I MANPATH +.Sh ENVIRONMENT +.Tw MANPATH +.Tp Ev MANPATH The standard search path used by -.I man +.Xr man 1 may be overridden by specifying a path in the -.I MANPATH +.Ev MANPATH environmental variable. -The format of the path is a colon (``:'') separated list of directories. -.SH FILES -whatis.db name of the apropos database -.SH "SEE ALSO" -man(1), whatis(1), whereis(1) +The format of the path is a colon (\*(Lq:\*(Rq) separated list of directories. +.Tp +.Sh FILES +.Tw whatis.db +.Tp Pa whatis.db +name of the apropos database +.Tp +.Sh SEE ALSO +.Xr man 1 , +.Xr whatis 1 , +.Xr whereis 1 +.Sh HISTORY +.Nm apropos +appeared in 3 BSD. diff --git a/usr/src/usr.bin/ar/ar.1 b/usr/src/usr.bin/ar/ar.1 index cb849b285c..056895c64e 100644 --- a/usr/src/usr.bin/ar/ar.1 +++ b/usr/src/usr.bin/ar/ar.1 @@ -1,147 +1,164 @@ -.\" @(#)ar.1 6.1 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH AR 1 "" -.AT 3 -.SH NAME -ar \- archive and library maintainer -.SH SYNOPSIS -.B ar -key [ posname ] afile name ... -.SH DESCRIPTION -.I Ar +.\" %sccs.include.redist.man% +.\" +.\" @(#)ar.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt AR 1 +.Os ATT 7th +.Sh NAME +.Nm ar +.Nd archive and library maintainer +.Sh SYNOPSIS +.Nm ar +.Cm key +.Op Ar posname +.Ar afile name ... +.Sh DESCRIPTION +.Nm Ar maintains groups of files combined into a single archive file. Its main use is to create and update library files as used by the loader. It can be used, though, for any similar purpose. -.B N.B: +.Sy N.B.: This version of -.I ar +.Nm ar uses a ASCII-format archive which is portable among the various -machines running \s-2UNIX\s0. +machines running UNIX. Programs for dealing with older formats are available: see -.IR arcv (8). -.PP -.I Key +.Xr arcv 8 . +.Pp +.Cm Key is one character from the set -.B drqtpmx, +.Fl drqtpmx optionally concatenated with one or more of -.B vuaibclo. -.I Afile +.Fl vuaibclo . +.Ar Afile is the archive file. The -.I names +.Ar names are constituent files in the archive file. The meanings of the -.I key +.Fl key characters are: -.TP -.B d +.Tp Fl d Delete the named files from the archive file. -.TP -.B r +.Tp Fl r Replace the named files in the archive file. If the optional character -.B u +.Fl u is used with -.B r, -then only those files with `last-modified' dates later than +.Fl r +then only those files with +.Li last-modified +dates later than the archive files are replaced. If an optional positioning character from the set -.B abi +.Fl abi is used, then the -.I posname +.Ar posname argument must be present and specifies that new files are to be placed after -.RB ( a ) +.Fl a or before -.RB ( b +.Fl b or -.BR i ) -.IR posname . +.Fl i +.Ar posname . Otherwise new files are placed at the end. -.TP -.B q +.Tp Fl q Quickly append the named files to the end of the archive file. Optional positioning characters are invalid. The command does not check whether the added members are already in the archive. Useful only to avoid quadratic behavior when creating a large archive piece-by-piece. -.TP -.B t +.Tp Fl t Print a table of contents of the archive file. If no names are given, all files in the archive are tabled. If names are given, only those files are tabled. -.TP -.B p +.Tp Fl p Print the named files in the archive. -.TP -.B m +.Tp Fl m Move the named files to the end of the archive. If a positioning character is present, then the -.I posname +.Ar posname argument must be present and, as in -.B r, +.Fl r specifies where the files are to be moved. -.TP -.B x +.Tp Fl x Extract the named files. If no names are given, all files in the archive are extracted. In neither case does -.B x +.Fl x alter the archive file. Normally the `last-modified' date of each extracted file is the date when it is extracted. However, if -.B o +.Fl o is used, the `last-modified' date is reset to the date recorded in the archive. -.TP -.B v +.Tp Fl v Verbose. Under the verbose option, -.I ar +.Nm ar gives a file-by-file description of the making of a new archive file from the old archive and the constituent files. When used with -.B t, +.Fl t it gives a long listing of all information about the files. When used with -.BR p , +.Fl p , it precedes each file with a name. -.TP -.B c +.Tp Fl c Create. Normally -.I ar +.Nm ar will create -.I afile +.Ar afile when it needs to. The create option suppresses the normal message that is produced when -.I afile +.Ar afile is created. -.TP -.B l +.Tp Fl l Local. Normally -.I ar +.Nm ar places its temporary files in the directory /tmp. This option causes them to be placed in the local directory. -.SH FILES -/tmp/v* temporaries -.SH "SEE ALSO" -lorder(1), ld(1), ranlib(1), ar(5), arcv(8) -.SH BUGS +.Tp +.Sh FILES +.Tw /tmp/v* +.Tp Pa tmp/v* +temporaries +.Tp +.Sh SEE ALSO +.Xr lorder 1 , +.Xr ld 1 , +.Xr ranlib 1 , +.Xr ar 5 , +.Xr arcv 8 +.Sh HISTORY +.Nm Ar +appeared in vanilla Version 6 AT&T UNIX. The Version 7 +.Nm ar +appeared +in 2.0 BSD. +.Sh BUGS If the same file is mentioned twice in an argument list, it may be put in the archive twice. -.LP -The `last-modified' date of a file will not be altered by the -.B o +.Pp +The +.Li last-modified +date of a file will not be altered by the +.Fl o option if the user is not the owner of the extracted file, or the super-user. diff --git a/usr/src/usr.bin/at/at/at.1 b/usr/src/usr.bin/at/at/at.1 index 07e3426a50..7be505252f 100644 --- a/usr/src/usr.bin/at/at/at.1 +++ b/usr/src/usr.bin/at/at/at.1 @@ -1,130 +1,186 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)at.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH AT 1 "" -.UC 4 -.SH NAME -at \- execute commands at a later time -.SH SYNOPSIS -.B "at [ -c ] [ -s ] [ -m ]" -time -[ day ] -[ file ] -.SH DESCRIPTION -.I At -spools away a copy of the named -.I file -to be used as input to -.IR sh (1) -or -.IR csh (1). -If the -.B \-c -flag (for -.IR (csh (1))) -or the -.B \-s -flag (for -.IR (sh (1))) -is specified, then that shell will be used to execute the job; -if no shell is specified, -the current environment shell is used. -If no file name is specified, -.I at -prompts for commands from standard input until a ^D is typed. -.PP -If the -.B \-m -flag is specified, mail will be sent to the user after the job +.\" @(#)at.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt AT 1 +.Dd +.Os BSD 4 +.Sh NAME +.Nm at +.Sd run command(s) at a specific time +.Sh SYNOPSIS +.Nm at +.Op Fl c +.Op Fl s +.Op Fl m +.Ar time +.Op Ar day +.Op Ar command_file +.Sh DESCRIPTION +.Nm At +allows commands to be run at a user specified time. +The commands can be given to +.Nm +via the +.Ar command_file +or accepted from the standard input. +.Nm At +will pass these commands to the appropriate +shell at the requested time. +.Tp Fl c +.Ar Command_file +contains +.Xr csh 1 +commands. +.Tp Fl s +.Ar Command_file +contains +.Xr sh 1 +commands. +.Tp Fl m +Mail will be sent to the user after the job has been run. If errors occur during execution of the job, then a copy of the error diagnostics will be sent to the user. If no errors occur, then a short message is sent informing the user that no errors occurred. -.PP +.Tp +.Pp +If no file name is specified, +.Nm at +prompts for commands from standard input until a +.Li \&^D is typed. +.Pp The format of the spool file is as follows: A four line header that includes the owner of the job, the name of the job, the shell used to run the job, and whether mail will be set after the job is executed. The header is followed by a -.I cd -command to the current directory and a -.I umask +.Ic cd +command to the current directory and a +.Ic umask command to set the modes on any files created by the job. -Then -.I at +Then +.Nm at copies all relevant environment variables to the spool file. When the script is run, it uses the user and group ID of the creator of the spool file. -.PP +.Pp The -.I time -is 1 to 4 digits, with an optional following -`A', `P', `N' or `M' for -AM, PM, noon or midnight. -One and two digit numbers are taken to be hours, three and four digits -to be hours and minutes. -If no letters follow the digits, a 24 hour clock time is understood. -.PP -The optional -.I day -is either -(1) a month name followed by a day number, -or -(2) a day of the week; -if the word `week' follows, invocation is moved -seven days further off. -Names of months and days may be recognizably truncated. -Examples of legitimate commands are -.IP -at 8am jan 24 -.br -at -c -m 1530 fr week -.br -at -s -m 1200n week -.PP -.I At -programs are executed by periodic execution -of the command -.IR -/usr/lib/atrun -from -.IR cron (8). -The granularity of -.I at -depends upon the how often atrun is executed. -.PP -Error output is lost unless redirected or the -.I \-m -flag is requested, in which case a copy of the errors is sent to -the user via -.IR mail (1). -.SH FILES -.nf -/usr/spool/at spooling area -/usr/spool/at/yy.ddd.hhhh.* job file -/usr/spool/at/past directory where jobs are executed from -/usr/spool/at/lasttimedone last time atrun was run -/usr/lib/atrun executor (run by cron(8)) -.fi -.SH "SEE ALSO" -atq(1), -atrm(1), -calendar(1), -sleep(1), -cron(8) -.SH DIAGNOSTICS +.Ar time +is either a 24 hour military time +.Em hhmm, +where +.Em hh +is hour and +.Em mm +is minutes, or the traditional 12 hour time +with qualifying options: +.Df I +.Dp Li am +am +.Dp Li a +am +.Dp Li pm +pm +.Dp Li p +pm +.Dp Li n +noon +.Dp Li m +midnight +.Dp +.De +The time can be abbreviated as shown below in the EXAMPLES. +.Pp +A +.Ar day +of the week may be specified by the first two +letters of its name. A week (7 days) may be specified by +the argument +.Em week . +If a month name is given, the following argument is expected to +be the day. +.Sh ENVIRONMENT +If no shell is specified, +the current environment variable +.Ev SHELL +is used. +Examples +.Pp +.Dp Li at 10p +Execute at 10pm today, or tomorrow +if 10pm has past. Use the shell +found in the environment variable +.Ev SHELL. +.Dp Li at -c -m 1705 mo +Execute at 5:05pm on Monday using +.Xr csh 1 +and send mail upon completion or +termination of the job. +.Dp Li at -s -m 1200n week +Use +.Xr sh 1 , +send mail upon completetion, start at noon o'clock, +one week from today. +.Dp Li at -s 8a apr 1 +Try it for fun. +.Dp +.Pp +.Sh ERRORS +Errors must be collected via the +.Fl m +option or by redirecting the standard output +from inside the +.Ar command_file. +.Sh FILES +.Dw /var/spool/at/yy.ddd.hhhh.* +.Ds L +.Dp Pa /var/spool/at +spooling area +.Dp Pa /var/spool/at/yy.ddd.hhhh.* +job file +.Dp Pa /var/spool/at/past +directory where jobs are executed from +.Dp Pa /var/spool/at/lasttimedone +last time atrun was run +.Dp Pa /var/libexec/atrun +executor (run by +.Xr cron 8 ) +.Dp +.Sh SEE ALSO +.Xr atq 1 , +.Xr atrm 1 , +.Xr calendar 1 , +.Xr cron 8 +.Xr sleep 1 , +.Sh DIAGNOSTICS Complains about various syntax errors and times out of range. -.SH BUGS -Due to the granularity of the execution of -.IR /usr/lib/atrun, -there may be bugs in scheduling things almost -exactly 24 hours into the future. - +.Sh HISTORY +.Nm +appeared in Version 7 AT&T UNIX. +.Sh BUGS +The queueing mechanism +.Pa /usr/libexec/atrun , +is scheduled by +.Xr cron 8 . +Frequency with which +.Xr cron 8 +runs +.Pa /usr/libexec/atrun +is site dependent. +If it is run infrequently, a job may +fall thru the cracks. +.Pp +There are known problems attempting to specify +a time of 2400 hours to +.Nm at . +.Pp If the system crashes, mail is not sent to the user informing them that the job was not completed. - +.Pp Sometimes old spool files are not removed from the directory -/usr/spool/at/past. This is usually due to a system crash, +/var/spool/at/past. This is usually due to a system crash, and requires that they be removed by hand. diff --git a/usr/src/usr.bin/at/atq/atq.1 b/usr/src/usr.bin/at/atq/atq.1 index 01547137f7..6a9598cdb7 100644 --- a/usr/src/usr.bin/at/atq/atq.1 +++ b/usr/src/usr.bin/at/atq/atq.1 @@ -1,41 +1,49 @@ -.\" Copyright (c) 1985 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)atq.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH ATQ 1 "" -.UC 6 -.SH NAME -atq \- print the queue of jobs waiting to be run -.SH SYNOPSIS -.B atq -[ -c ] [ -n ] [ name ... ] -.SH DESCRIPTION -.I Atq +.\" @(#)atq.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt ATQ 1 +.Os BSD 4.3 +.Sh NAME +.Nm atq +.Nd print the queue of jobs waiting to be run +.Sh SYNOPSIS +.Nm atq +.Op Fl c +.Op Fl n +.Op Ar name ... +.Sh DESCRIPTION +.Nm Atq prints the queue of jobs that are waiting to be run at a later date. These jobs were created with the -.IR at (1) +.Xr at 1 command. With no flags, the queue is sorted in the order that the jobs will be executed. -.PP -If the -.B \-c -flag is used, the queue is sorted by the time that the -.I at -command was given. -.PP -The -.B \-n -flag prints only the total number of files that are currently -in the queue. -.PP -If a name(s) is provided, only those files belonging to that user(s) are +.Tp Fl c +the queue is sorted by the time that the +.Li at +command was given. +.Tp Fl n +only the total number of files that are currently +in the queue are printed. +.Tp +.Pp +If a name(s) is provided, only those files belonging to that user(s) are displayed. -.SH FILES -/usr/spool/at spool area -.SH "SEE ALSO" -at(1), -atrm(1), -cron(8) +.Sh FILES +.Tw /var/spool/at +.Tp /var/spool/at +spool area +.Tp +.Sh SEE ALSO +.Xr at 1 , +.Xr atrm 1 , +.Xr cron 8 +.Sh HISTORY +.Nm Atq +appeared in the 4.3 BSD release. diff --git a/usr/src/usr.bin/at/atrm/atrm.1 b/usr/src/usr.bin/at/atrm/atrm.1 index faeb03f74e..532753154e 100644 --- a/usr/src/usr.bin/at/atrm/atrm.1 +++ b/usr/src/usr.bin/at/atrm/atrm.1 @@ -1,48 +1,67 @@ -.\" Copyright (c) 1985 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)atrm.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH ATRM 1 "" -.UC 6 -.SH NAME -atrm \- remove jobs spooled by at -.SH SYNOPSIS -.B atrm -[ -f ] [ -i ] [-] [[ job #] [ name ]... ] -.SH DESCRIPTION -.I Atrm +.\" @(#)atrm.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt ATRM 1 +.Os BSD 4.3 +.Sh NAME +.Nm atrm +.Nd remove jobs spooled by at +.Sh SYNOPSIS +.Nm atrm +.Op Fl f +.Op Fl i +.Op Fl +.Cx [ +.Op Ar job # +.Op Ar name +.Cx ... +.Cx ] +.Cx +.Sh DESCRIPTION +.Nm Atrm removes jobs that were created with the -.IR at (1) +.Xr at 1 command. -With the -.B \- -flag, all jobs belonging to the person invoking -.I atrm -are removed. -If a job number(s) is specified, -.I atrm -attempts to remove only that job number(s). -.PP -If the -.B \-f -flag is used, all information regarding the +.Pp +.Tp Fl f +all information regarding the removal of the specified jobs is suppressed. -If the -.B \-i -flag is used, -.I atrm +.Tp Fl i +.Nm atrm asks if a job should be removed; a response of 'y' causes the job to be removed. -.PP -If a user(s) name is specified, all +.Tp Fl +all jobs belonging to the person invoking +.Nm atrm +are removed. +.Tp +.Pp +If a +.Ar job +number(s) is specified, +.Nm atrm +attempts to remove only that +.Ar job +number(s). +.Pp +If a user(s) name is specified, all jobs belonging to that user(s) are removed. -This form of invoking -.I atrm +This form of invoking +.Nm atrm is useful only to the super-user. -.SH FILES -/usr/spool/at spool area -.SH "SEE ALSO" -at(1), -atq(1), -cron(8) +.Sh FILES +.Tw /usr/spool/at +.Tp /usr/spool/at +spool area +.Tp +.Sh SEE ALSO +.Xr at 1 , +.Xr atq 1 , +.Xr cron 8 +.Sh HISTORY +.Nm Atrm +appeared in the 4.3 BSD release. diff --git a/usr/src/usr.bin/basename/basename.1 b/usr/src/usr.bin/basename/basename.1 index 8019c4ccba..11c31df6f6 100644 --- a/usr/src/usr.bin/basename/basename.1 +++ b/usr/src/usr.bin/basename/basename.1 @@ -1,32 +1,50 @@ -.\" @(#)basename.1 6.2 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH BASENAME 1 "" -.AT 3 -.SH NAME -basename, dirname \- strip filename affixes -.SH SYNOPSIS -\fBbasename\fP \fBstring\fP [ \fBsuffix\fP ] -.br -\fBdirname\fP \fBstring\fP -.SH DESCRIPTION -\fIBasename\fP deletes any prefix ending in `/' and the \fIsuffix\fP, -if present in \fIstring\fP, from \fIstring\fP, and prints the result -to the standard output. It is normally used inside substitution marks -(\`\`) in shell procedures. -.PP -\fIDirname\fP deletes from the last slash (``/'') to the end of -\fIstring\fP, and prints to result to the standard output. -.SH EXAMPLES -This shell procedure invoked with the argument \fI/usr/src/bin/cat.c\fP -compiles the named file and moves the output to \fIcat\fP in the current -directory: -.IP "" 15n -cc $1 -.br -mv a.out \`basename $1 .c\` -.PP -The following line sets the shell variable \fIFOO\fP to \fI/usr/bin\fP. -.IP "" 15n -FOO=`dirname /usr/bin/trail` -.SH "SEE ALSO" -sh(1) +.\" %sccs.include.redist.man% +.\" +.\" @(#)basename.1 6.3 (Berkeley) %G% +.\" +.Dt BASENAME 1 +.Dd +.Os BSD 4.4 +.Sh NAME +.Nm basename +.Nd Extract filename from pathname +.Sh SYNOPSIS +.Nm basename +.Ar string +.Op suffix +.Sh DESCRIPTION +.Nm Basename +strips +.Ar string +of its pathname prefix +and a +.Ar suffix , +if given, to the standard output. +If +.Ar string +ends in the slash character, +.Li / , +or is the same as the +.Ar suffix +argument, +a newline is output. +A non-existant suffix is ignored. +.Pp +The following line sets the shell variable +.Ev FOO +to +.Pa /usr/bin . +.Pp +.Dl FOO=`dirname /usr/bin/trail` +.Pp +.Ar baseline +utility exits 0 on success, and >0 if an error occurs. +.Sh SEE ALSO +.Xr sh 1 +.Sh STANDARDS +The +.Nm baseline +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/bc/bc.1 b/usr/src/usr.bin/bc/bc.1 index f88b2dd967..3c12e5d56d 100644 --- a/usr/src/usr.bin/bc/bc.1 +++ b/usr/src/usr.bin/bc/bc.1 @@ -1,133 +1,132 @@ -.\" @(#)bc.1 6.2 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH BC 1 "" -.AT 3 -.SH NAME -bc \- arbitrary-precision arithmetic language and calculator -.SH SYNOPSIS -.B bc -[ -.B \-c -] [ -.B \-l -] [ file ... ] -.SH DESCRIPTION -.I Bc +.\" %sccs.include.redist.man% +.\" +.\" @(#)bc.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt BC 1 +.Os ATT 7th +.Sh NAME +.Nm bc +.Nd arbitrary-precision arithmetic language and calculator +.Sh SYNOPSIS +.Nm bc +.Op Fl c +.Op Fl l +.Ar +.Sh DESCRIPTION +.Nm Bc is an interactive processor for a language which resembles C but provides unlimited precision arithmetic. It takes input from any files given, then reads the standard input. The -.B \-l +.Tp Fl l argument stands for the name of an arbitrary precision math library. -The syntax for -.I bc +.Tp Fl c +.Nm Bc +is actually a preprocessor for +.Ar dc 1 , +which it invokes automatically, unless the +.Fl c +compile only. +option is present. +In this case the +.Ar dc +input is sent to the standard output instead. +.Tp +.Pp +The syntax for +.Nm bc programs is as follows; L means letter a-z, E means expression, S means statement. -.HP 6 +.Pp Comments -.br -are enclosed in /* and */. -.HP 6 +.Dl are enclosed in /* and */. +.Pp Names -.br -simple variables: L -.br -array elements: L [ E ] -.br +.Dl simple variables: L +.Df I +array elements: L +.Op E +.De +.Df I The words `ibase', `obase', and `scale' -.HP 6 +.De +.Pp Other operands -.br -arbitrarily long numbers with optional sign and decimal point. -.br -( E ) -.br -sqrt ( E ) -.br -length ( E ) number of significant decimal digits -.br -scale ( E ) number of digits right of decimal point -.br -L ( E , ... , E ) -.HP 6 +.Dl arbitrarily long numbers with optional sign and decimal point. +.Dl \&( E \&) +.Dl sqrt ( E ) +.Dl length ( E ) number of significant decimal digits +.Dl scale ( E ) number of digits right of decimal point +.Dl L ( E , ... , E ) +.Pp Operators -.br -+ \- * / % ^ -(% is remainder; ^ is power) -.br -++ \-\- (prefix and postfix; apply to names) -.br -== <= >= != < > -.br -= += \-= *= /= %= ^= -.br -.HP 6 +.Dl \&+ \- * / % ^ (% is remainder; ^ is power) +.Dl \&++ \-\- (prefix and postfix; apply to names) +.Dl \&== <= >= != < > +.Dl \&= += \-= *= /= %= ^= +.Pp Statements -.br +.Ds I E -.br { S ; ... ; S } -.br if ( E ) S -.br while ( E ) S -.br for ( E ; E ; E ) S -.br null statement -.br break -.br quit -.HP 6 +.De +.Pp Function definitions -.br +.Ds I define L ( L ,..., L ) { -.br auto L, ... , L -.br S; ... S -.br return ( E ) -.br } -.HP 6 -Functions in -.B \-l +.De +.Pp +Functions in +.Fl l math library -.br -s(x) sine -.br -c(x) cosine -.br -e(x) exponential -.br -l(x) log -.br -a(x) arctangent -.br -j(n,x) Bessel function -.PP -.DT +.Dw ss(x) +.Dp s(x) +sine +.Dp c(x) +cosine +.Dp e(x) +exponential +.Dp l(x) +log +.Dp a(x) +arctangent +.Dp j(n,x) +Bessel function +.Dp +.Pp All function arguments are passed by value. -.PP +.Pp The value of a statement that is an expression is printed unless the main operator is an assignment. Either semicolons or newlines may separate statements. Assignment to -.I scale +.Ar scale influences the number of digits to be retained on arithmetic operations in the manner of -.IR dc (1). +.Xr dc 1 . Assignments to -.I ibase +.Ar ibase or -.I obase +.Ar obase set the input and output number radix respectively. -.PP +.Pp The same letter may be used as an array, a function, and a simple variable simultaneously. All variables are global to the program. @@ -135,10 +134,10 @@ All variables are global to the program. When using arrays as function arguments or defining them as automatic variables empty square brackets must follow the array name. -.PP +.Pp For example -.PP -.nf +.Pp +.Ds I scale = 20 define e(x){ auto a, b, c, i, s @@ -153,44 +152,34 @@ define e(x){ s = s+c } } -.PP +.De +.Pp .fi defines a function to compute an approximate value of the exponential function and -.PP -.nf - for(i=1; i<=10; i++) e(i) -.fi -.PP +.Pp +.Dl for(i=1; i<=10; i++) e(i) +.Pp prints approximate values of the exponential function of the first ten integers. -.PP -.I Bc -is actually a preprocessor for -.IR dc (1), -which it invokes automatically, unless the -.B \-c -(compile only) -option is present. -In this case the -.I dc -input is sent to the standard output instead. -.SH FILES -.ta \w'/usr/lib/lib.b 'u -/usr/lib/lib.b mathematical library -.br -dc(1) desk calculator proper -.SH "SEE ALSO" -dc(1) -.br -L. L. Cherry and R. Morris, -.I -BC \- An arbitrary precision desk-calculator language -.SH BUGS -No &&, \(or\|\(or, or ! operators. +.Sh FILES +.\" /usr/lib/lib.b mathematical library +.Ds L +.Dw Dc(1) +.Dp Pa dc(1) desk calculator proper +.Sh SEE ALSO +.Xr dc 1 +.L. .L. .Cherry and R. Morris, +.Em BC \- An arbitrary precision desk-calculator language +.Sh HISTORY +The +.Nm bc +command appeared in Version 7 AT&T UNIX. +.Sh BUGS +No &&, \(or\\(or, or ! operators. .br -.I For +.Li For statement must have all three E's. .br -.I Quit +.Li Quit is interpreted when read, not when executed. diff --git a/usr/src/usr.bin/biff/biff.1 b/usr/src/usr.bin/biff/biff.1 index d894bb1e66..e84eb84a62 100644 --- a/usr/src/usr.bin/biff/biff.1 +++ b/usr/src/usr.bin/biff/biff.1 @@ -1,60 +1,59 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)biff.1 6.2 (Berkeley) %G% +.\" @(#)biff.1 6.3 (Berkeley) %G% .\" -.TH BIFF 1 "" -.UC 4 -.SH NAME -biff \- be notified if mail arrives and who it is from -.SH SYNOPSIS -.B biff -[ -.B yn -] -.SH DESCRIPTION -.I Biff +.Dd +.Dt BIFF 1 +.Os BSD 4 +.Sh NAME +.Nm biff +.Nd be notified if mail arrives and who it is from +.Sh SYNOPSIS +.Nm biff +.Op Cm yn +.Sh DESCRIPTION +.Nm Biff informs the system whether you want to be notified when mail arrives during the current terminal session. The command -.IP -.B "biff y" -.LP +.Pp +.Dl biff y +.Pp enables notification; the command -.IP -.B "biff n" -.LP +.Pp +.Dl biff n +.Pp disables it. When mail notification is enabled, the header and first few lines of the message will be printed on your screen whenever mail arrives. -A ``biff y'' command is often included in the file -.I \&.login +A +.Li ``biff y'' +command is often included in the file +.Pa \& +login or -.I \&.profile +.Pa \& +profile to be executed at each login. -.PP -.I Biff +.Pp +.Nm Biff operates asynchronously. -For synchronous notification use the MAIL variable of -.IR sh (1) +For synchronous notification use the +.Ar MAIL +variable of +.Xr sh 1 or the -.I mail +.Ar mail variable of -.IR csh (1). -.SH SEE ALSO -csh(1), -sh(1), -mail(1), -comsat(8C) +.Xr csh 1 . +.Sh SEE ALSO +.Xr csh 1 , +.Xr mail 1 , +.Xr sh 1 , +.Xr comsat 8 +.Sh HISTORY +.Nm biff +appeared in the 4.0 BSD release. diff --git a/usr/src/usr.bin/cal/cal.1 b/usr/src/usr.bin/cal/cal.1 index e72f0cbcfc..2de126788b 100644 --- a/usr/src/usr.bin/cal/cal.1 +++ b/usr/src/usr.bin/cal/cal.1 @@ -1,58 +1,56 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Kim Letkeman. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)cal.1 6.5 (Berkeley) %G% +.\" @(#)cal.1 6.6 (Berkeley) %G% .\" -.TH CAL 1 "" -.UC 7 -.SH NAME -cal \- displays a calendar -.SH SYNOPSIS -.B cal -[ -jy ] [[ -.I month -] -.I year -] -.SH DESCRIPTION -.I Cal -displays a calendar for a specified month and/or year. +.Dd +.Dt CAL 1 +.Os BSD 4.4 +.Sh NAME +.Nm cal +.Nd displays a calendar +.Sh SYNOPSIS +.Nm cal +.Op Fl jy +.Op Ar month Op Ar year +.Sh DESCRIPTION +.Nm Cal +displays a simple calendar. +If no options or arguments are given, +.Nm cal +displays the current month. The options are as follows: -.TP -\-j +.Tp Fl j Display julian dates (days one-based, numbered from January 1). -.TP -\-y +.Tp Fl y Display a calendar for the current year. -.PP +.Tp +.Pp A single parameter specifies the year (1 - 9999) to be displayed; note the year must be fully specified: ``cal 89'' will -.B not +.Em not display a calendar for 1989. Two parameters denote the month (1 - 12) and year. If no parameters are specified, the current month's calendar is -displayed. -.PP +displayed. +.Pp A year starts on Jan 1. -.PP -The Gregorian Reformation is assumed to have occurred on 3 September -1752. +.Pp +The Gregorian Reformation is assumed to have occurred on 3rd of September +in 1752. By this time, most countries had recognized the reformation (although a few did not recognize it until the early 1900's.) -From 3 September 1752 through 13 September 1752 was eliminated by +Ten days following that date were eliminated by the reformation, so the calendar for that month is a bit unusual. +.Sh HISTORY +A +.Nm +command appeared in Version 6 AT&T UNIX. The +.Nm +command this man page describes is +derived from code contributed by Kim Letkeman. diff --git a/usr/src/usr.bin/calendar/calendar.1 b/usr/src/usr.bin/calendar/calendar.1 index 0d685670a9..effc6123f4 100644 --- a/usr/src/usr.bin/calendar/calendar.1 +++ b/usr/src/usr.bin/calendar/calendar.1 @@ -1,40 +1,35 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)calendar.1 6.7 (Berkeley) %G% +.\" @(#)calendar.1 6.8 (Berkeley) %G% .\" -.TH CALENDAR 1 "" -.UC 7 -.SH NAME -calendar \- reminder service -.SH SYNOPSIS -.B calendar -[ \-a ] -.SH DESCRIPTION -.I Calendar -reads the file ``calendar'' in the current directory and displays lines -that begin with either today's or tomorrow's date. +.Dd +.\" +.Dt CALENDAR 1 +.Os BSD 4.4 +.Sh NAME +.Nm calendar +.Nd reminder service +.Sh SYNOPSIS +.Nm calendar +.Op \-a +.Sh DESCRIPTION +.Nm Calendar +checks the current directory for a file named named +.Li calendar +and displays lines that begin with either today's date +or tomorrow's. On Fridays, events on Friday through Monday are displayed. -.PP +.Pp The following options are available: -.TP -\-a +.Tp Fl a Process the ``calendar'' files of all users and mail the results to them. This requires super-user privileges. -.PP +.Tp +.Pp A month and day should begin lines. They may be entered in almost any format, either numeric or as character strings. @@ -46,79 +41,86 @@ Lines with leading tabs default to the last entered date, allowing multiple line specifications for a single date. By convention, dates followed by an asterisk are not fixed, i.e. change from year to year. -.PP +.Pp The ``calendar'' file is preprocessed by -.IR cpp (1), +.Xr cpp 1 , allowing the inclusion of shared files such as company holidays or meetings. If the shared file is not referenced by a full pathname, -.I cpp +.Xr cpp 1 searches in the current (or home) directory first, and then in the directory -.IR /usr/share/calendar . +.Pa /usr/share/calendar . Empty lines and lines protected by the C commenting syntax (/* ... */) are ignored. -.PP +.Pp Some possible calendar entries: -.in +5 -.sp -.nf +.Pp +.Ds I #include #include -.sp + 6/15 ... June 15 (if ambiguous, will default to month/day). Jun. 15 ... June 15. 15 June ... June 15. Thursday ... Every Thursday. June ... Every June 1st. 15 * ... 15th of every month. -.fi -.PP -.SH FILES +.De +.Pp +.Sh FILES The following default calendar files are provided: -.TP -calendar.birthday -Births and deaths of famous (and not-so-famous) people. -.TP -calendar.christian +.Dw calendar.christian +.Ds L +.Dp Pa calendar.birthday +Births and deaths of famous ( and not- so- famous) people. +.Dp Pa calendar.christian Christian holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. -.TP -calendar.computer +.Dp Pa calendar.computer Days of special significance to computer people. -.TP -calendar.history -Everything else, mostly U.S. historical events. -.TP -calendar.holiday -Other holidays, including the not-well-known, obscure, and -.B really +.Dp Pa calendar.history +Everything else, mostly U. S. historical events. +.Dp Pa calendar.holiday +Other holidays, including the not-well-known, obscure, and +.Em really obscure. -.TP -calendar.judaic +.Dp Pa calendar.judaic Jewish holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. -.TP -calendar.music -Musical events, births, and deaths. -Strongly oriented toward rock 'n' roll. -.TP -calendar.usholiday +.Dp Pa calendar.music +Musical events, births, and deaths. +Strongly oriented toward rock ' n' roll. +.Dp Pa calendar.usholiday U.S. holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. -.SH "SEE ALSO" -at(1), cpp(1), mail(1), cron(8) -.SH COMPATIBILITY +.Dp +.Sh SEE ALSO +.Xr at 1 , +.Xr cpp 1 , +.Xr cron 8 +.Xr mail 1 , +.Sh COMPATIBILITY The -.I calendar +.Nm calendar program previously selected lines which had the correct date anywhere in the line. This is no longer true, the date is only recognized when it occurs first on the line. -.SH BUGS -.I Calendar +.Sh HISTORY +A +.Nm +command appeared in Version 7 AT&T UNIX. +The version of +.Nm calendar +released with this man page +is not derived from the AT&T version. +.\" what is status of code?? are phrases like today's date a problem? +.\" todays's and tomorrow' are only AT&T similarities +.Sh BUGS +.Nm Calendar doesn't handle events that move around from year to year, i.e. ``the last Monday in April''. diff --git a/usr/src/usr.bin/checknr/checknr.1 b/usr/src/usr.bin/checknr/checknr.1 index 6672d48679..c28bf5eeae 100644 --- a/usr/src/usr.bin/checknr/checknr.1 +++ b/usr/src/usr.bin/checknr/checknr.1 @@ -1,68 +1,49 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)checknr.1 6.3 (Berkeley) %G% +.\" @(#)checknr.1 6.4 (Berkeley) %G% .\" -.TH CHECKNR 1 "" -.UC 4 -.SH NAME -checknr \- check nroff/troff files -.SH SYNOPSIS -.B checknr -[ -.B \-s -] [ -.B \-f -] [ -.BR \-a ".x1.y1.x2.y2. ... .xn.yn" -] [ -.BR \-c ".x1.x2.x3 ... .xn" -] [ -\fIfile\fP ... -] -.SH DESCRIPTION -.I Checknr +.Dd +.Dt CHECKNR 1 +.Os BSD 4 +.Sh NAME +.Nm checknr +.Nd check nroff/troff files +.Sh SYNOPSIS +.Nm checknr +.Op Fl s +.Op Fl f +.Op Fl \&a Ar \&.x1.y1.x2.y2. ... \&.xn.yn +.Op Fl \&c Ar \&.x1.x2.x3 ... \&.xn +.Ar file +.Sh DESCRIPTION +.Nm Checknr checks a list of -.IR nroff (1) +.Xr nroff 1 or -.IR troff (1) +.Xr troff 1 input files for certain kinds of errors involving mismatched opening and closing delimiters and unknown commands. If no files are specified, -.I checknr +.Nm checknr checks the standard input. Delimiters checked are: -.IP (1) -Font changes using \efx ... \efP. -.IP (2) -Size changes using \esx ... \es0. -.IP (3) +.Pp +.Dl Font changes using \efx ... \efP. +.Pp +.Dl Size changes using \esx ... \es0. +.Pp +.Df I Macros that come in open ... close forms, for example, the .TS and .TE macros which must always come in pairs. -.PP -.I Checknr -knows about the -.IR ms (7) -and -.IR me (7) -macro packages. -.PP -Additional pairs of macros can be added to the list using the -.B \-a -option. +.De +.Pp +Options: +.Tp Fl a +Add additional pairs of macros to the list of known macros. This must be followed by groups of six characters, each group defining a pair of macros. The six characters are @@ -70,30 +51,27 @@ a period, the first macro name, another period, and the second macro name. -For example, to define a pair .BS and .ES, use \-\fBa\fP.BS.ES -.PP -The -.B \-c -option defines commands which would otherwise be complained about +For example, to define a pair .BS and .ES, use +.Cx Ar a +.Li \&.BS.ES +.Cx +.Pp +.Tp Fl c +Define commands which would otherwise be complained about as undefined. -.PP -The -.B \-f -option requests -.I checknr +.Tp Fl f +Request +.Nm checknr to ignore \ef font changes. -.PP -The -.B \-s -option requests -.I checknr -to ignore \es size changes. -.PP -.I Checknr +.Tp Fl s +Ignore \es size changes. +.Tp +.Pp +.Nm Checknr is intended to be used on documents that are prepared with -.I checknr +.Nm checknr in mind, much the same as -.I lint. +.Xr lint 1 . It expects a certain document writing style for \ef and \es commands, in that each \efx must be terminated with \efP and each \esx must be terminated with \es0. @@ -101,21 +79,35 @@ While it will work to directly go into the next font or explicitly specify the original font or point size, and many existing documents actually do this, such a practice will produce complaints from -.I checknr. +.Nm checknr Since it is probably better to use the \efP and \es0 forms anyway, you should think of this as a contribution to your document preparation style. -.SH SEE\ ALSO -nroff(1), troff(1), checkeq(1), ms(7), me(7) -.SH DIAGNOSTICS +.Pp +.Nm Checknr +knows about the +.Xr ms 7 +and +.Xr me 7 +macro packages. +.Sh SEE ALSO +.Xr nroff 1 , +.Xr troff 1 , +.Xr checkeq 1 , +.Xr ms 7 , +.Xr me 7 +.Sh DIAGNOSTICS +.Ds L Complaints about unmatched delimiters. -.br Complaints about unrecognized commands. -.br Various complaints about the syntax of commands. -.SH BUGS +.De +.Sh BUGS There is no way to define a 1 character macro name using -.BR \-a . -.br +.Fl a . +.Pp Does not correctly recognize certain reasonable constructs, such as conditionals. +.Sh HISTORY +.Nm +appeared in 4.0 BSD. diff --git a/usr/src/usr.bin/chpass/chpass.1 b/usr/src/usr.bin/chpass/chpass.1 index 9288237744..69b56a5e31 100644 --- a/usr/src/usr.bin/chpass/chpass.1 +++ b/usr/src/usr.bin/chpass/chpass.1 @@ -1,169 +1,188 @@ -.\" Copyright (c) 1988 The Regents of the University of California. +.\" Copyright (c) 1988, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)chpass.1 5.7 (Berkeley) %G% +.\" @(#)chpass.1 5.8 (Berkeley) %G% .\" -.TH CHPASS 1 "" -.UC 4 -.SH NAME -chpass \- add or change user database information -.SH SYNOPSIS -chpass [ -a list ] [ -s shell ] [ user ] -.SH DESCRIPTION -.I Chpass +.Dd +.Dt CHPASS 1 +.Os BSD 4.4 +.Sh NAME +.Nm chpass +.Nd add or change user database information +.Sh SYNOPSIS +chpass +.Op Fl a Ar list +.Op Fl s Ar shell +.Op user +.Sh DESCRIPTION +.Nm Chpass allows editing of the user database information associated with -.I user +.Ar user or, by default, the current user. The information is formatted and supplied to an editor for changes. -The -.I vi -editor will be used unless the environmental variable EDITOR selects -an alternate editor. -When the editor terminates, the information is re-read and used to -update the user database itself. -Only the user, or the super-user, may edit the information associated -with the user. -.PP +.Pp Only the information that the user is allowed to change is displayed. -.PP +.Pp +The options are as follows: +.Tp Fl a +The super-user is allowed to directly supply a user database +entry, in the format specified by +.Xr passwd 5 , +as an argument. +This argument must be a colon (``:'') separated list of all the +user database fields, although they may be empty. +.Tp Fl s +The +.Fl s +option attempts to change the user's shell to +.Ar newsh . +.Tp +.Pp Possible display items are as follows: -.PP -.RS - Login: user's login name - Password: user's encrypted password - Uid: user's id - Gid: user's login group id - Change: password change time - Expire: account expiration time - Class: user's general classification - Home Directory: user's home directory - Shell: user's login shell - Full Name: user's real name - Location: user's normal location - Home Phone: user's home phone - Office Phone: user's office phone -.RE -.PP -.PP +.Pp +.Dw Home\ Directory: +.Dp Login: +user's login name +.Dp Password: +user's encrypted password +.Dp Uid: +user's id +.Dp Gid: +user's login group id +.Dp Change: +password change time +.Dp Expire: +account expiration time +.Dp Class: +user's general classification +.Dp Home Directory: +user's home directory +.Dp Shell: +user's login shell +.Dp Full Name: +user's real name +.Dp Location: +user's normal location +.Dp Home Phone: +user's home phone +.Dp Office Phone: +user's office phone +.Dp +.Pp The -.I login +.Ar login field is the user name used to access the computer account. -.PP +.Pp The -.I password +.Ar password field contains the encrypted form of the user's password. -.PP +.Pp The -.I uid +.Ar uid field is the number associated with the -.I login +.Ar login field. Both of these fields should be unique across the system (and often across a group of systems) as they control file access. -.PP +.Pp While it is possible to have multiple entries with identical login names and/or identical user id's, it is usually a mistake to do so. Routines that manipulate these files will often return only one of the multiple entries, and that one by random selection. -.PP +.Pp The -.I group +.Ar group field is the group that the user will be placed in at login. Since this system supports multiple groups (see -.IR groups (1)) +.Xr groups 1 ) this field currently has little special meaning. This field may be filled in with either a number or a group name (see -.IR group (5)). -.PP +.Xr group 5 ) . +.Pp The -.I change +.Ar change field is the date by which the password must be changed. -.PP +.Pp The -.I expire +.Ar expire field is the date on which the account expires. -.PP +.Pp Both the -.I change +.Ar change and -.I expire +.Ar expire fields should be entered in the form ``month day year'' where -.I month +.Ar month is the month name (the first three characters are sufficient), -.I day +.Ar day is the day of the month, and -.I year +.Ar year is the year. -.PP +.Pp The -.I class +.Ar class field is currently unused. In the near future it will be a key to a -.IR termcap (5) +.Xr termcap 5 style database of user attributes. -.PP +.Pp The user's home directory is the full UNIX path name where the user will be placed at login. -.PP +.Pp The shell field is the command interpreter the user prefers. If the -.I shell -field is empty, the Bourne shell (\fI/bin/sh\fP) is assumed. +.Ar shell +field is empty, the Bourne shell, +.Pa /bin/sh , +is assumed. When altering a login shell, and not the super-user, the user may not change from a non-standard shell or to a non-standard shell. Non-standard is defined as a shell not found in -.IR /etc/shells . -.PP +.Pa /etc/shells . +.Pp The last four fields are for storing the user's full name, office location, and home and work telephone numbers. -.PP -The options are as follows: -.TP -.I -a -The super-user is allowed to directly supply a user database -entry, in the format specified by -.IR passwd (5), -as an argument. -This argument must be a colon (``:'') separated list of all the -user database fields, although they may be empty. -.TP -.I -s -The -.I -s -option attempts to change the user's shell to -.IR newsh . -.PP +.Pp Once the information has been verified, -.I chpass +.Nm chpass uses -.IR mkpasswd (8) +.Xr mkpasswd 8 to update the user database. This is run in the background, and, at very large sites could take several minutes. Until this update is completed, the password file is unavailable for other updates and the new information will not be available to programs. -.SH FILES -.DT -/etc/master.passwd The user database -/etc/shells The list of approved shells -.RE -.SH "SEE ALSO" -login(1), finger(1), getusershell(3), passwd(5), mkpasswd(8), vipw(8) -.br +.Sh ENVIRONMENT +The +.Xr vi 1 +editor will be used unless the environment variable EDITOR is set to +an alternate editor. +When the editor terminates, the information is re-read and used to +update the user database itself. +Only the user, or the super-user, may edit the information associated +with the user. +.Sh FILES +.Dw /etc/master.passwd +.Di L +.Dp Pa /etc/master.passwd +The user database +.Dp Pa /etc/shells +The list of approved shells +.Dp +.Sh SEE ALSO +.Xr login 1 , +.Xr finger 1 , +.Xr getusershell 3 , +.Xr passwd 5 , +.Xr mkpasswd 8 , +.Xr vipw 8 +.Pp Robert Morris and Ken Thompson, -.I UNIX password security -.SH BUGS +.Ar UNIX Password security +.Sh HISTORY +First release 4.4 Bsd. +.Sh BUGS User information should (and eventually will) be stored elsewhere. diff --git a/usr/src/usr.bin/cmp/cmp.1 b/usr/src/usr.bin/cmp/cmp.1 index 85279e0693..0c7d73dec1 100644 --- a/usr/src/usr.bin/cmp/cmp.1 +++ b/usr/src/usr.bin/cmp/cmp.1 @@ -1,39 +1,115 @@ -.\" Copyright (c) 1987 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1987, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)cmp.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH CMP 1 "" -.AT 3 -.SH NAME -cmp \- compare two files -.SH SYNOPSIS -.B cmp -[ -.B \-l -] [ -.B \-s -] file1 file2 [ skip1 [ skip2 ]] -.SH DESCRIPTION -The two files are compared. (If \fIfile1\fP is `\-', the standard -input is used.) With no options, \fIcmp\fP makes no comment if the -files are the same; if they differ, it reports the byte and line -number at which the difference occurred, or, that one file is an -initial subsequence of the other. \fISkip1\fP and \fIskip2\fP are -initial byte offsets into \fIfile1\fP and \fIfile2\fP respectively, -and may be either octal or decimal; a leading ``0'' denotes octal. -.PP -Options: -.TP 6 -.B \-s -Print nothing for differing files; set exit codes only. -.TP 6 -.B \-l -Print the byte number (in decimal) and the differing bytes (in octal) -for all differences between the two files. -.SH "SEE ALSO" -diff(1), comm(1) -.SH DIAGNOSTICS -Exit code 0 is returned for identical files, 1 for different files, -and 2 for an inaccessible or missing argument, or a system error. +.\" @(#)cmp.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt CMP 1 +.Os BSD 4.4 +.Sh NAME +.Nm cmp +.Nd compare two files +.Sh SYNOPSIS +.Nm cmp +.Op Fl l Fl s +.Ar file1 file2 +.Sh DESCRIPTION +The cmp utility compares two files. +Under default options, +cmp writes no output if the files are the same; if they +differ, it writes to standard output the byte and line +number at which the first difference occurred. +Bytes and +lines are numbered beginning with one. +.Pp +The following options are available: +.Tp Fl l +Print the byte number (decimal) and the differing +bytes (octal) for each difference. +.Tp Fl s +Print nothing for differing files; return exit +status only. +.Tp +.Pp +Nothing is guaranteed if both +.Fl s +and +.Fl l +are given. +.Pp +The following operands are available: +.Tw file1 +.Tp Ar file1 +A pathname of the first file to be compared. +If +.Ar file1 +is +.Cx Fl +.Cx , +.Cx +the standard input is used. +.Tp Ar file2 +A pathname of the second file to be compared. +.Tp +.Pp +The input files can be any file type. +.Pp +Results of the comparison are written to standard output. +When no options are used, the format is: +.Pp +.Ds I +"%s %s differ: char %d, line %d\en", , +, , +.De +.Pp +When the +.Fl l +option is used, the format is: +.Pp +.Ds I +"%d %o %o\en", , , + +.De +.Pp +for each byte that differs. The first byte number is from +file1 while the second is from file2. +.Pp +If file1 and file2 are identical for the entire length of +the shorter file, the following format is used, unless the +.Fl s +option is specified. +.Pp +.Ds I +"cmp: EOF on %s\en", +.De +.Pp +No output is written to standard output when the +.Fl s option +is used. +.Pp +The +.Nm cmp +utility exits with one of the following values: +.Tw Fl +.Tp 0 +The files are identical. +.Tp 1 +The files are different; this includes the case +where one file is identical to the first part of +the other. +In the latter case, if the -s option has +not been specified, cmp writes to standard error +that EOF was reached in the shorter file (before +any differences were found). +.Tp >1 +An error occurred. +.Tp +.Sh SEE ALSO +diff 1 , +diff3 1 +.Sh STANDARDS +The +.Nm cmp +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/col/col.1 b/usr/src/usr.bin/col/col.1 index 6ba5941a63..37386fcebb 100644 --- a/usr/src/usr.bin/col/col.1 +++ b/usr/src/usr.bin/col/col.1 @@ -6,119 +6,100 @@ .\" .\" %sccs.include.redist.man% .\" -.\" @(#)col.1 6.3 (Berkeley) %G% +.\" @(#)col.1 6.4 (Berkeley) %G% .\" -.TH COL 1 "" -.UC 7 -.SH NAME -col \- filter reverse line feeds from input -.SH SYNOPSIS -.nf -.ft B -col [ \-bfx ] [ \-l num ] -.ft R -.fi -.SH DESCRIPTION -.I Col +.Dd +.Dt COL 1 +.Os ATT 7 +.Sh NAME +.Nm col +.Nd filter reverse line feeds from input +.Sh SYNOPSIS +.Nm col +.Op Fl bfx +.Op Fl l Ar num +.Sh DESCRIPTION +.Nm Col filters out reverse (and half reverse) line feeds so that the output is in the correct order and contains only forward and half forward line feeds, and replaces white-space characters with tabs where possible. This can be useful in processing the output of -.IR nroff (1) +.Xr nroff 1 and -.IR tbl (1). -.PP -.I Col +.Xr tbl 1 . +.Pp +.Nm Col reads from standard input and writes to standard output. -.PP +.Pp The options are as follows: -.TP -.I \-b +.Tw Fl +.Tp Fl b Do not output any backspaces \- print only the last character written to each column position. -.TP -.I \-f +.Tp Fl f Forward half line feeds are permitted (``fine'' mode). Normally characters printed on a half line boundary are printed on the following line. -.TP -.I \-x +.Tp Fl x Output multiple spaces instead of tabs. -.TP -.I "\-l num" +.Tp Cx Fl l +.Cx Ar num +.Cx Buffer at least -.I num +.Ar num lines in memory. By default, 128 lines are buffered. -.PP +.Tp +.Pp The control sequences for carriage motion that -.I col +.Nm col understands and their decimal values are listed in the following table: -.sp -.TP 17 -ESC\-7 +.Pp +.Dw carriage\ return +.Di L +.Dp ESC\-7 reverse line feed (escape then 7) -.br -.ns -.TP 17 -ESC\-8 +.Dp ESC\-8 half reverse line feed (escape then 8) -.br -.ns -.TP 17 -ESC\-9 +.Dp ESC\-9 half forward line feed (escape then 9) -.br -.ns -.TP 17 -backspace +.Dp backspace moves back one column (8); ignored in the first column -.br -.ns -.TP 17 -carriage return +.Dp carriage return (13) -.br -.ns -.TP 17 -newline +.Dp newline forward line feed (10); also does carriage return -.br -.ns -.TP 17 -shift in +.Dp shift in shift to normal character set (15) -.br -.ns -.TP 17 -shift out +.Dp shift out shift to alternate character set (14) -.br -.ns -.TP 17 -space +.Dp space moves forward one column (32) -.br -.ns -.TP 17 -tab +.Dp tab moves forward to next tab stop (9) -.br -.ns -.TP 17 -vertical tab +.Dp vertical tab reverse line feed (11) -.PP +.Dp +.Pp All unrecognized control characters and escape sequences are discarded. -.PP -.I Col +.Pp +.Nm Col keeps track of the character set as characters are read and makes sure the character set is correct when they are output. -.PP +.Pp If the input attempts to back up to the last flushed line, -.I col +.Nm col will display a warning message. -.SH "SEE ALSO" -expand(1), nroff(1), tbl(1) +.Sh SEE ALSO +.Xr expand 1 , +.Xr nroff 1 , +.Xr tbl 1 +.Sh HISTORY +A +.Nm col +command +appeared in Version 6 AT&T UNIX. The BSD +.Nm col +is derived from code written by Michael Rendell. diff --git a/usr/src/usr.bin/colcrt/colcrt.1 b/usr/src/usr.bin/colcrt/colcrt.1 index 23f85b6e70..e00fbd95ab 100644 --- a/usr/src/usr.bin/colcrt/colcrt.1 +++ b/usr/src/usr.bin/colcrt/colcrt.1 @@ -1,85 +1,77 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)colcrt.1 6.3 (Berkeley) %G% +.\" @(#)colcrt.1 6.4 (Berkeley) %G% .\" -.TH COLCRT 1 "" -.UC -.SH NAME -colcrt \- filter nroff output for CRT previewing -.SH SYNOPSIS -.B colcrt -[ -.B \- -] [ -.B \-2 -] [ -file ... -] -.SH DESCRIPTION -.I Colcrt +.Dd +.Dt COLCRT 1 +.OS BSD 3 +.Sh NAME +.Nm colcrt +.Nd filter nroff output for CRT previewing +.Sh SYNOPSIS +.Nm colcrt +.Op Fl +.Op Fl 2 +.Ar +.Sh DESCRIPTION +.Nm Colcrt provides virtual half-line and reverse line feed sequences for terminals without such capability, and on which overstriking is destructive. Half-line characters and underlining (changed to dashing `\-') are placed on new lines in between the normal output lines. -.PP -The optional -.B \- -suppresses all underlining. +.Pp +.Tp Fl +Suppress all underlining. It is especially useful for previewing -.I allboxed +.Ar allboxed tables from -.IR tbl (1). -.PP -The option -.B \-2 -causes all half-lines to be printed, effectively double spacing the output. +.Xr tbl 1 . +.Pp +.Tp Fl 2 +Causes all half-lines to be printed, effectively double spacing the output. Normally, a minimal space output format is used which will suppress empty lines. The program never suppresses two consecutive empty lines, however. The -.B \-2 +.Fl 2 option is useful for sending output to the line printer when the output contains superscripts and subscripts which would otherwise be invisible. -.PP +.Tp +.Pp A typical use of -.I colcrt +.Nm colcrt would be -.PP -.DT - tbl exum2.n | nroff \-ms | colcrt \- | more -.SH "SEE ALSO" -nroff/troff(1), col(1), more(1), ul(1) -.SH BUGS +.Pp +.Dl tbl exum2.n nroff \-ms colcrt \- more +.Sh SEE ALSO +.Xr nroff 1 , +.Xr troff 1 , +.Xr col 1 , +.Xr more 1 , +.Xr ul 1 +.Sh HISTORY +Appeared in 3 BSD. +.Sh BUGS Should fold underlines onto blanks even with the -`\fB\-\fR' +.Fl option so that a true underline character would show; if we did this, however, -.I colcrt +.Nm colcrt wouldn't get rid of -.I cu'd +.Ar cu'd underlining completely. -.PP +.Pp Can't back up more than 102 lines. -.PP +.Pp General overstriking is lost; -as a special case `|' overstruck with `\-' or underline becomes `+'. -.PP +as a special case `' overstruck with `\-' or underline becomes `+'. +.Pp Lines are trimmed to 132 characters. -.PP +.Pp Some provision should be made for processing superscripts and subscripts in documents which are already double-spaced. diff --git a/usr/src/usr.bin/colrm/colrm.1 b/usr/src/usr.bin/colrm/colrm.1 index 36610114fd..61e523c4ae 100644 --- a/usr/src/usr.bin/colrm/colrm.1 +++ b/usr/src/usr.bin/colrm/colrm.1 @@ -1,42 +1,37 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)colrm.1 6.3 (Berkeley) %G% +.\" @(#)colrm.1 6.4 (Berkeley) %G% .\" -.TH COLRM 1 "" -.UC 4 -.SH NAME -colrm \- remove columns from a file -.SH SYNOPSIS -.B colrm -[ -startcol -[ -endcol -] -] -.SH DESCRIPTION -.I Colrm +.Dd +.Dt COLRM 1 +.Os BSD 3 +.Sh NAME +.Nm colrm +.Nd remove columns from a file +.Sh SYNOPSIS +.Nm colrm +.Cx [ startcol +.Op endcol +.Cx ] +.Cx +.Sh DESCRIPTION +.Nm Colrm removes selected columns from a file. Input is taken from standard input. Output is sent to standard output. -.PP +.Pp If called with one parameter the columns of each line will be removed starting with the specified column. If called with two parameters the columns from the first column to the last column will be removed. -.PP +.Pp Column numbering starts with column 1. -.SH "SEE ALSO" -awk(1), column(1), expand(1), paste(1) +.Sh SEE ALSO +.Xr awk 1 , +.Xr column 1 , +.Xr expand 1 , +.Xr paste 1 +.Sh HISTORY +Appeared in 3 BSD. diff --git a/usr/src/usr.bin/column/column.1 b/usr/src/usr.bin/column/column.1 index 8d064208f0..a83bd4bfd5 100644 --- a/usr/src/usr.bin/column/column.1 +++ b/usr/src/usr.bin/column/column.1 @@ -1,73 +1,68 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)column.1 5.4 (Berkeley) %G% +.\" @(#)column.1 5.5 (Berkeley) %G% .\" -.UC 7 -.TH COLUMN 1 "" -.UC 1 -.SH NAME -column \- columnate lists -.SH SYNOPSIS -\fBcolumn [ \fI\-tx\fB ] [ \fI\-s sep\fB ] [\fI\-c columns\fB ] [ \fIfile ...\fB ] -.ft R -.SH DESCRIPTION +.Dd +.Os BSD 4.4 +.Dt COLUMN 1 +.Sh NAME +.Nm column +.Nd columnate lists +.Sh SYNOPSIS +.Nm column +.Oo +.Op Fl t Ar x +.Op Fl s Ar sep +.Op Fl c Ar columns +.Oo +.Cx +.Ar +.Sh DESCRIPTION The -.I column +.Nm column utility formats its input into multiple columns. Rows are filled before columns. Input is taken from -.I file +.Ar file operands, or, by default, from the standard input. Empty lines are ignored. -.PP +.Pp The options are as follows: -.TP -.I \-c +.Tp Fl c Output is formatted for a display -.I columns +.Ar columns wide. -.TP -.I \-s +.Tp Fl s Specify a set of characters to be used to delimit columns for the -.I \-t +.Fl t option. -.TP -.I \-t +.Tp Fl t Determine the number of columns the input contains and create a table. Columns are delimited by whitespace, by default, or by the characters supplied using the -.I \-s +.Fl s option. Useful for pretty-printing displays. -.TP -.I \-x +.Tp Fl x Fill columns before filling rows. -.PP -.I Column +.Tp +.Pp +.Nm Column exits 0 on success, >0 if an error occurred. -.SH ENVIRONMENT -.TP -.I COLUMNS +.Sh ENVIRONMENT +.Tp Ar COLUMNS The environmental variable COLUMNS is used to determine the size of the screen if no other information is available. -.SH EXAMPLES -(printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME\en"; -.br -.RS -ls -l | sed 1d) | column -t -.RE -.SH "SEE ALSO" -colrm(1), ls(1), paste(1), sort(1) +.Sh EXAMPLES +.Dl (printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME\en"; +.Dl ls -l sed 1d) column -t +.Sh SEE ALSO +.Xr colrm 1 , +.Xr ls 1 , +.Xr paste 1 , +.Xr sort 1 +.Sh HISTORY +4.4 BSD. diff --git a/usr/src/usr.bin/comm/comm.1 b/usr/src/usr.bin/comm/comm.1 index 686764a2db..90196da502 100644 --- a/usr/src/usr.bin/comm/comm.1 +++ b/usr/src/usr.bin/comm/comm.1 @@ -1,62 +1,64 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)comm.1 6.2 (Berkeley) %G% +.\" @(#)comm.1 6.3 (Berkeley) %G% .\" -.TH COMM 1 "" -.SH NAME -comm - select or reject lines common to two files -.SH SYNOPSIS -\fBcomm [ \fI-123\fP ] [ \fI-\fP ] file1 file2 -.SH DESCRIPTION +.Dd +.Os BSD 4.4 +.Dt COMM 1 +.Sh NAME +.Nm comm +.Nd select or reject lines common to two files +.Sh SYNOPSIS +.Nm comm +.Op Fl 123 +.Ar file1 file2 +.Sh DESCRIPTION The -.I comm +.Nm comm utility reads -.I file1 +.Ar file1 and -.I file2 -and produces a three-column output: lines only in -.IR file1 , +.Ar file2 , +which should be +sorted lexically, and produces three text +columns as output: lines only in +.Ar file1 ; lines only in -.IR file2 , +.Ar file2 ; and lines in both files. -.PP +.Pp The filename ``-'' means the standard input. -.PP +.Pp The following options are available: -.TP --1 +.Tp Fl 1 Suppress printing of column 1. -.TP --2 +.Tp Fl 2 Suppress printing of column 2. -.TP --3 +.Tp Fl 3 Suppress printing of column 3. -.PP +.Tp +.Pp Each column will have a number of tab characters prepended to it equal to the number of lower numbered columns that are being printed. For example, if column number two is being suppressed, lines printed in column number one will not have any tabs preceding them, and lines printed in column number three will have one. -.PP -.I Comm +.Pp +.Nm Comm assumes that the files are lexically sorted; all characters participate in line comparisons. -.PP -.I Comm +.Pp +.Nm Comm exits 0 on success, >0 if an error occurred. -.SH "SEE ALSO" -cmp(1), diff(1), sort(1), uniq(1) +.Sh SEE ALSO +.Xr cmp 1 , +.Xr diff 1 , +.Xr sort 1 , +.Xr uniq 1 +.Sh STANDARDS +The +.Nm comm +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/compress/compress.1 b/usr/src/usr.bin/compress/compress.1 index 4da064df28..c0d19fca6f 100644 --- a/usr/src/usr.bin/compress/compress.1 +++ b/usr/src/usr.bin/compress/compress.1 @@ -1,252 +1,256 @@ -.\" Copyright (c) 1986 The Regents of the University of California. +.\" Copyright (c) 1986, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" James A. Woods, derived from original work by Spencer Thomas .\" and Joseph Orost. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)compress.1 6.6 (Berkeley) %G% +.\" @(#)compress.1 6.7 (Berkeley) %G% .\" -.TH COMPRESS 1 "" -.UC 6 -.SH NAME -compress, uncompress, zcat \- compress and expand data -.SH SYNOPSIS -.PU -.ll +8 -.B compress -[ -.B \-f -] [ -.B \-v -] [ -.B \-c -] [ -.B \-b -.I bits -] [ -.I "name \&..." -] -.ll -8 +.Dd +.Dt COMPRESS 1 +.Os BSD 4.3 +.Sh NAME +.Nm compress , +.Nm uncompress , +.Nm zcat +.Nd compress and expand data +.Sh SYNOPSIS +.Nm compress +.Op Fl f +.Op Fl v +.Op Fl c +.Op Fl b Ar bits +.Ar .br -.B uncompress -[ -.B \-f -] [ -.B \-v -] [ -.B \-c -] [ -.I "name \&..." -] +.Nm uncompress +.Op Fl f +.Op Fl v +.Op Fl c +.Ar .br -.B zcat -[ -.I "name \&..." -] -.SH DESCRIPTION -.I Compress +.Nm zcat +.Ar +.Sh DESCRIPTION +.Nm Compress reduces the size of the named files using adaptive Lempel-Ziv coding. Whenever possible, -each file is replaced by one with the extension -.B "\&.Z," +each +.Ar file +is replaced by one with the extension +.Sy \&.Z , while keeping the same ownership modes, access and modification times. If no files are specified, the standard input is compressed to the standard output. Compressed files can be restored to their original form using -.I uncompress +.Nm uncompress or -.I zcat. -.PP -The -.B \-f -option will force compression of -.IR name , +.Nm zcat +.Tw Ds +.Tp Fl f +Force compression of +.Ar file , even if it does not actually shrink or the corresponding -.IR name .Z +.Ar file.Z file already exists. Except when run in the background under -.IR /bin/sh , +.Pa /bin/sh , if -.B \-f +.Fl f is not given the user is prompted as to whether an existing -.IR name .Z +.Ar file.Z file should be overwritten. -.PP -The -.B \-c -(``cat'') option makes -.I compress/uncompress +.Pp +.Tp Fl c +(``cat'') makes +.Nm compress/uncompress write to the standard output; no files are changed. The nondestructive behavior of -.I zcat +.Nm zcat is identical to that of -.I uncompress -.B \-c. -.PP -.I Compress +.Nm uncompress +.Fl c. +.Tp Fl b +Specify +.Ar bits +code limit (see below). +The +.Tp Fl v +option causes +the printing of the percentage reduction of each file. +.Tp +.Pp +.Nm Compress uses the modified Lempel-Ziv algorithm popularized in "A Technique for High Performance Data Compression", Terry A. Welch, -.I "IEEE Computer," +.Em IEEE Computer , vol. 17, no. 6 (June 1984), pp. 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the -.B \-b +.Fl b flag is reached (default 16). -.I Bits +.Ar Bits must be between 9 and 16. The default can be changed in the source to allow -.I compress +.Nm compress to be run on a smaller machine. -.PP +.Pp After the -.I bits +.Ar bits limit is attained, -.I compress +.Nm compress periodically checks the compression ratio. If it is increasing, -.I compress +.Nm compress continues to use the existing code dictionary. However, if the compression ratio decreases, -.I compress +.Nm compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. -.PP +.Pp Note that the -.B \-b +.Fl b flag is omitted for -.I uncompress, -since the -.I bits +.Ar uncompress +since the +.Ar bits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor -recompression of compressed data is attempted. -.PP +recompression of compressed data is attempted. +.Pp .ne 8 The amount of compression obtained depends on the size of the input, the number of -.I bits +.Ar bits per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50\-60%. Compression is generally much better than that achieved by Huffman coding (as used in -.IR pack ), -or adaptive Huffman coding -.RI ( compact ), +.Xr pack ) , +or adaptive Huffman coding (as +used in +.Xr compact ) , and takes less time to compute. -.PP -The -.B \-v -option causes -the printing of the percentage reduction of each file. -.PP +.Pp If an error occurs, exit status is 1, else if the last file was not compressed because it became larger, the status is 2; else the status is 0. -.SH "DIAGNOSTICS" -Usage: compress [\-fvc] [\-b maxbits] [file ...] -.in +8 -Invalid options were specified on the command line. -.in -8 +.Sh DIAGNOSTICS +Usage: compress +.Op Fl fvc +.Op Fl b Ar maxbits +.Ar +.Dl Invalid options were specified on the command line. +.Pp Missing maxbits -.in +8 +.Df I Maxbits must follow -.BR \-b \. -.in -8 -.IR file : +.Fl b . +.De +.Pp +.Ar file : not in compressed format -.in +8 +.Df I The file specified to -.I uncompress +.Ar uncompress has not been compressed. -.in -8 -.IR file : -compressed with -.I xx -bits, can only handle -.I yy +.De +.Pp +.Ar file : +compressed with +.Ar xx +bits, can only handle +.Ar yy bits -.in +8 -.I File +.Df I +.Ar File was compressed by a program that could deal with -more -.I bits +more +.Ar bits than the compress code on this machine. Recompress the file with smaller -.IR bits \. -.in -8 -.IR file : +.Ar bits . +.De +.Pp +.Ar file : already has .Z suffix -- no change -.in +8 +.Df I The file is assumed to be already compressed. Rename the file and try again. -.in -8 -.IR file : +.De +.Pp +.Ar file : filename too long to tack on .Z -.in +8 +.Df I The file cannot be compressed because its name is longer than 12 characters. Rename and try again. This message does not occur on BSD systems. -.in -8 -.I file +.De +.Pp +.Ar file already exists; do you wish to overwrite (y or n)? -.in +8 +.Df I Respond "y" if you want the output file to be replaced; "n" if not. -.in -8 +.De +.Pp uncompress: corrupt input -.in +8 +.Df I A SIGSEGV violation was detected which usually means that the input file is corrupted. -.in -8 -Compression: -.I "xx.xx%" -.in +8 +.De +.Pp +Compression: +.Em xx.xx% +.Df I Percentage of the input saved by compression. (Relevant only for -.BR \-v \.) -.in -8 +.Fl v . ) +.De +.Pp -- not a regular file: unchanged -.in +8 +.Df I When the input file is not a regular file, (e.g. a directory), it is left unaltered. -.in -8 --- has -.I xx +.De +.Pp +-- has +.Ar xx other links: unchanged -.in +8 +.Df I The input file has links; it is left unchanged. See -.IR ln "(1)" +.Xr ln 1 for more information. -.in -8 +.De +.Pp -- file unchanged -.in +8 +.Df I No savings is achieved by compression. The input remains virgin. -.in -8 -.SH "BUGS" +.De +.Pp +.Sh FILES +.Tw file.Z +.Tp Pa file.Z +compressed file is file.Z +.Tp +.Sh HISTORY +Appeared in 4.3 BSD. +.Sh "BUGS" Although compressed files are compatible between machines with large memory, -.BR \-b \12 -should be used for file transfer to architectures with +.Cx Fl b +.Ar 12 +.Cx +should be used for file transfer to architectures with a small process data space (64KB or less, as exhibited by the DEC PDP series, the Intel 80286, etc.) -.PP -.I compress +.Pp +.Nm compress should be more flexible about the existence of the `.Z' suffix. diff --git a/usr/src/usr.bin/ctags/ctags.1 b/usr/src/usr.bin/ctags/ctags.1 index c2fd33fc2c..91a47a815a 100644 --- a/usr/src/usr.bin/ctags/ctags.1 +++ b/usr/src/usr.bin/ctags/ctags.1 @@ -1,136 +1,188 @@ -.\" Copyright (c) 1987 The Regents of the University of California. +.\" Copyright (c) 1987, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)ctags.1 6.5 (Berkeley) %G% +.\" @(#)ctags.1 6.6 (Berkeley) %G% .\" -.TH CTAGS 1 "" -.UC 4 -.SH NAME -ctags \- create a tags file -.SH SYNOPSIS -.B ctags -[ -.B \-BFadtuwvx -] [ -.B \-f -.I tagsfile -] -name ... -.SH DESCRIPTION -\fICtags\fP makes a tags file for \fIex\fP(1) from the specified C, +.Dd +.Dt CTAGS 1 +.Os BSD 4 +.Sh NAME +.Nm ctags +.Nd create a tags file +.Sh SYNOPSIS +.Nm ctags +.Op Fl BFadtuwvx +.Op Fl f Ar tagsfile +.Ar name ... +.Sh DESCRIPTION +.Nm Ctags +makes a tags file for +.Xr ex 1 +from the specified C, Pascal, Fortran, YACC, lex, and lisp sources. A tags file gives the locations of specified objects in a group of files. Each line of the tags file contains the object name, the file in which it is defined, and a search pattern for the object definition, separated by white-space. -Using the \fItags\fP file, \fIex\fP(1) can quickly locate these object -definitions. Depending on the options provided to \fIctags\fP, +Using the +.Ar tags +file, +.Xr ex 1 +can quickly locate these object +definitions. Depending on the options provided to .Nm ctags , objects will consist of subroutines, typedefs, defines, structs, enums and unions. -.PP -Yacc and lex files each have a special tag. \fIYyparse\fP is the start -of the second section of the yacc file, and \fIyylex\fP is the start of -the second section of the lex file. -.PP -If the \fB-x\fP flag is given, \fIctags\fP produces a list of object +.Pp +.Tp Fl x +.Nm ctags +produces a list of object names, the line number and file name on which each is defined, as well as the text of that line and prints this on the standard output. This is a simple index which can be printed out as an off-line readable function index. -.PP -If the \fB-v\fP flag is given, an index of the form expected by -\fIvgrind\fP(1) is produced on the standard output. This listing +.Pp +.Tp Fl v +An index of the form expected by +.Xr vgrind 1 +is produced on the standard output. This listing contains the object name, file name, and page number (assuming 64 line pages). Since the output will be sorted into lexicographic order, -it may be desired to run the output through \fBsort -f\fP. +it may be desired to run the output through +.Xr sort 1 . Sample use: -.nf - ctags \-v files | sort \-f > index - vgrind \-x index -.fi -.PP -Normally \fIctags\fP places the tag descriptions in a file called -\fItags\fP; this may be overridden with the \fB-f\fP option. -.PP -Files whose names end in \fB.c\fP or \fB.h\fP are assumed to be C -source files and are searched for C style routine and macro definitions. -Files whose names end in \fB.y\fP are assumed to be YACC source files. -Files whose names end in \fB.l\fP are assumed to be lisp files if their -first non-blank character is `;', `(', or `[', otherwise, they are -treated as lex files. Other files are first examined to see if they -contain any Pascal or Fortran routine definitions, and, if not, are -searched for C style definitions. -.PP -Other options are: -.TP 5 -.B \-F +.Pp +.Ds I +ctags \-v files sort \-f > index +vgrind \-x index +.De +.Tp Fl f +Places the tag descriptions in a file called +.Ar tagsfile. The default behaviour is to place them in a file +named +.Ar tags . +.Tp Fl F use forward searching patterns (/.../) (the default). -.TP 5 -.B \-B +.Tp Fl B use backward searching patterns (?...?). -.TP 5 -.B \-a -append to \fItags\fP file. -.TP 5 -.B \-d -create tags for \fI#defines\fP that don't take arguments; \fI#defines\fP +.Tp Fl a +append to +.Ar tags +file. +.Tp Fl d +create tags for +.Ar #defines +that don't take arguments; +.Ar #defines that take arguments are tagged automatically. -.TP 5 -.B \-t +.Tp Fl t create tags for typedefs, structs, unions, and enums. -.TP 5 -.B \-w +.Tp Fl w suppress warning diagnostics. -.TP 5 -.B \-u -update the specified files in the \fItags\fP file, that is, all +.Tp Fl u +update the specified files in the +.Ar tags +file, that is, all references to them are deleted, and the new values are appended to the file. (Beware: this option is implemented in a way which is rather -slow; it is usually faster to simply rebuild the \fItags\fP file.) -.PP -The tag \fImain\fP is treated specially in C programs. The tag formed -is created by prepending \fIM\fP to the name of the file, with the -trailing \fB.c\fP and any leading pathname components removed. This -makes use of \fIctags\fP practical in directories with more than one +slow; it is usually faster to simply rebuild the +.Ar tags +file.) +.Tp +.Pp +Files whose names end in +.Nm \&.c +or +.Nm \&.h +are assumed to be C +source files and are searched for C style routine and macro definitions. +Files whose names end in +.Nm \&.y +are assumed to be YACC source files. +Files whose names end in +.Nm \&.l +are assumed to be lisp files if their +first non-blank character is `;', `(', or `[', +otherwise, they are +treated as lex files. Other files are first examined to see if they +contain any Pascal or Fortran routine definitions, and, if not, are +searched for C style definitions. +.Pp +The tag +.Ar main +is treated specially in C programs. The tag formed +is created by prepending +.Ar M +to the name of the file, with the +trailing +.Nm \&.c +and any leading pathname components removed. This +makes use of +.Nm ctags +practical in directories with more than one program. -.SH FILES -.DT -tags default output tags file -.SH DIAGNOSTICS -\fICtags\fP exits with a value of 1 if an error occurred, where +.Pp +Yacc and lex files each have a special tag. +.Ar Yyparse +is the start +of the second section of the yacc file, and +.Ar yylex +is the start of +the second section of the lex file. +.Sh FILES +.Dw tags +.Di L +.Dp Pa tags +default output tags file +.Dp +.Sh DIAGNOSTICS +.Nm Ctags +exits with a value of 1 if an error occurred, where duplicate objects are not considered errors, 0 otherwise. -.SH SEE ALSO -ex(1), vi(1) -.SH AUTHOR +.Sh SEE ALSO +.Xr ex 1 , +.Xr vi 1 +.Sh HISTORY +.Nm +appeared in 3 BSD. +.Sh AUTHOR Ken Arnold; FORTRAN added by Jim Kleckner; Bill Joy added Pascal and -\fB-x\fP, replacing \fIcxref\fP; C typedefs added by Ed Pelegri-Llopart. -.SH BUGS -Recognition of \fBfunctions\fR, \fBsubroutines\fR and \fBprocedures\fR +.Fl x , +replacing +.Ar cxref ; +C typedefs added by Ed Pelegri-Llopart. +.Sh BUGS +Recognition of +.Nm functions , +.Nm subroutines +and +.Nm procedures for FORTRAN and Pascal is done is a very simpleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures -in different blocks with the same name you lose. \fICtags\fP doesn't +in different blocks with the same name you lose. +.Nm Ctags +doesn't understand about Pascal types. -.PP +.Pp The method of deciding whether to look for C, Pascal or FORTRAN functions is a hack. -.PP -\fICtags\fP relies on the input being well formed, and any syntactical +.Pp +.Nm Ctags +relies on the input being well formed, and any syntactical errors will completely confuse it. It also finds some legal syntax -confusing; for example, as it doesn't understand \fI#ifdef\fP's, +confusing; for example, as it doesn't understand +.Cx Ar #ifdef +.Cx 's, +.Cx (incidentally, that's a feature, not a bug) any code with unbalanced -braces inside \fI#ifdef\fP's will cause it to become somewhat disoriented. +braces inside +.Cx Ar #ifdef +.Cx 's +will cause it to become somewhat disoriented. +.Cx In a similar fashion, multiple line changes within a definition will cause it to enter the last line of the object, rather than the first, as -the searching pattern. The last line of multiple line \fItypedef\fP's +the searching pattern. The last line of multiple line +.Ar typedef +'s will similarly be noted. diff --git a/usr/src/usr.bin/cut/cut.1 b/usr/src/usr.bin/cut/cut.1 index bb8b11538e..7c0d6ac47d 100644 --- a/usr/src/usr.bin/cut/cut.1 +++ b/usr/src/usr.bin/cut/cut.1 @@ -1,47 +1,46 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)cut.1 5.1 (Berkeley) %G% +.\" @(#)cut.1 5.2 (Berkeley) %G% .\" -.TH CUT 1 "" -.UC 7 -.SH NAME -cut - select portions of each line of a file -.SH SYNOPSIS -.nf -cut -c list [file ...] -cut -f list [-s] [-d string] [file ...] -.fi -.SH DESCRIPTION +.Dd +.Dt CUT 1 +.Os BSD 4.4 +.Sh NAME +.Nm cut +.Nd select portions of each line of a file +.Sh SYNOPSIS +.Nm cut +.Ar list +.Ar +.br +.Nm cut +.Ar list +.Op Fl s +.Op Fl d Ar string +.Ar +.Sh DESCRIPTION The -.I cut +.Nm cut utility selects portions of each line (as specified by -.IR list ) +.Ar list ) from each -.I file +.Ar file (or the standard input by default), and writes them to the standard output. The items specified by -.I list +.Ar list can be in terms of column position or in terms of fields delimited by a special character. -.PP -.I List +.Pp +.Ar List is a comma or whitespace separated set of one-based numbers and/or number ranges. -Number ranges consist of a number, a dash (``-''), and a second number +Number ranges consist of a number, a dash +.Li (``\-'') , +and a second number and select the fields or columns from the first number to the second, inclusive. Numbers or number ranges may be preceded by a dash, which selects all @@ -51,35 +50,41 @@ fields or columns from the last number to the end of the line. Numbers and number ranges may be repeated, overlapping, and in any order. It is not an error to select fields or columns not present in the input line. -.PP +.Pp The options are as follows: -.TP --c list +.Tw Fl +.Tp Cx Fl c +.Cx \&\ \& +.Ar list +.Cx The -.I list +.Ar list specifies character positions. -.TP --f list +.Tp Cx Fl f +.Cx \&\ \& +.Ar list +.Cx The -.I list +.Ar list specifies fields, delimited in the input by a single tab character. Output fields are separated by a single tab character. -.TP --d char +.Tp Cx Fl d +.Cx \&\ \& +.Ar char +.Cx Use -.I char +.Ar char as the field delimiter character instead of the tab character. -.TP --s +.Tp Fl s Suppresses lines with no field delimiter characters. Unless specified, lines with no delimiters are passed through unmodified. -.PP -.I Cut +.Tp +.Pp +.Nm Cut exit 0 on success, 1 if an error occurred. -.SH ENVIRONMENT -.SH "SEE ALSO" -paste(1) -.SH STANDARDS +.Sh SEE ALSO +.Xr paste 1 +.Sh STANDARDS The -.I cut +.Nm cut function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/find/find.1 b/usr/src/usr.bin/find/find.1 index b5eebbc65e..54d8bd8030 100644 --- a/usr/src/usr.bin/find/find.1 +++ b/usr/src/usr.bin/find/find.1 @@ -3,128 +3,148 @@ .\" .\" %sccs.include.redist.man% .\" -.\" @(#)find.1 6.12 (Berkeley) %G% +.\" @(#)find.1 6.13 (Berkeley) %G% .\" -.TH FIND 1 "" -.AT 3 -.SH NAME -find \- walk a file hierarchy -.SH SYNOPSIS -.ft B -find [ \-dsx ] [ path ] expression -.br -find [ \-dsx ] [ \-f path ] expression -.ft R -.SH DESCRIPTION -.I Find +.Dd +.Dt FIND 1 +.Os ATT 7th +.Sh NAME +.Nm find +.Nd walk a file hierarchy +.Sh SYNOPSIS +.Nm find +.Op Fl dsx +.Op Ar path +.Ar expression +.Nm find +.Op Fl dsx +.Op Fl f Ar path +.Ar expression +.Sh DESCRIPTION +.Nm Find recursively descends the directory tree for each -.I path +.Ar path listed, evaluating an -.I expression +.Ar expression (composed of the ``primaries'' and ``operands'' listed below) in terms of each file in the tree. -.PP +.Pp The options are as follows: -.TP -.B \-d +.Pp +.Tw Ds +.Tp Fl d The -.B \-d +.Fl d option causes find to perform a depth\-first traversal, i.e. directories are visited in post\-order and all entries in a directory will be acted on before the directory itself. By default, -.I find +.Nm find visits directories in pre\-order, i.e. before their contents. Note, the default is -.I not +.Ar not a breadth\-first traversal. -.TP -.B \-f +.Tp Fl f The -.B \-f +.Fl f option specifies a file hierarchy for -.I find +.Nm find to traverse. If no -.B \-f +.Fl f option is specified, the first operand after the options is expected to be the file hierarchy to be traversed. -.TP -.B \-s +.Tp Fl s The -.B \-s +.Fl s option causes the file information and file type (see -.IR stat (2)), +.Xr stat 2 ) , returned for each symbolic link to be those of the file referenced by the link, not the link itself. If the referenced file does not exist, the file information and type will be for the link itself. -.TP -.B \-x +.Tp Fl x The -.B \-x +.Fl x option prevents -.I find +.Nm find from descending into directories that have a device number different than that of the file from which the descent began. -.SH PRIMARIES -.TP -.B atime n +.Tp +.Sh PRIMARIES +.Tw Ds +.Tp Cx Ic atime +.Cx \&\ \& +.Ar n +.Cx True if the difference between the file last access time and the time -.I find +.Nm find was started, rounded up to the next full 24\-hour period, is -.B n +.Ar n 24\-hour periods. -.TP -.B ctime n +.Tp Cx Ic ctime +.Cx \&\ \& +.Ar n +.Cx True if the difference between the time of last change of file status information and the time -.I find +.Nm find was started, rounded up to the next full 24\-hour period, is -.B n +.Ar n 24\-hour periods. -.TP -.B exec utility [argument ...] ; +.Tp Cx Ic exec +.Cx \&\ \& +.Ar utility +.Cx \&\ \& +.Op argument ... ; +.Cx True if the program named -.B utility +.Ar utility returns a zero value as its exit status. Optional arguments may be passed to the utility. The expression must be terminated by a semicolon (``;''). If the string ``{}'' appears anywhere in the utility name or the arguments it is replaced by the pathname of the current file. Utility will be executed in the directory from which -.I find +.Nm find was executed. -.TP -.B fstype type +.Tp Cx Ic fstype +.Cx \&\ \& +.Ar type +.Cx True if the file is contained in a file system of type -.BR type. +.Ar type . Currently supported types are ``local'', ``mfs'', ``nfs'', ``pc'' and ``ufs''. The type ``local'' is not a specific file system type, but matches any file system physically mounted on the system where the -.I find +.Nm find is being executed. -.TP -.B group gname +.Tp Cx Ic group +.Cx \&\ \& +.Ar gname +.Cx True if the file belongs to the group -.BR gname . +.Ar gname . If -.B gname +.Ar gname is numeric and there is no such group name, then -.B gname +.Ar gname is treated as a group id. -.TP -.B inum n +.Tp Cx Ic inum +.Cx \&\ \& +.Ar n +.Cx True if the file has inode number -.BR n . -.TP -.B links n +.Ar n . +.Tp Cx Ic links +.Cx \&\ \& +.Ar n +.Cx True if the file has -.B n +.Ar n links. -.TP -.B ls +.Tp Ic ls This primary always evaluates to true. The following information for the current file is written to standard output: its inode number, size in 512\-byte blocks, file permissions, number of hard @@ -134,52 +154,61 @@ will be displayed instead of the size in bytes. If the file is a symbolic link, the pathname of the linked\-to file will be displayed preceded by ``\->''. The format is identical to that produced by ``ls \-dgils''. -.TP -.B mtime n +.Tp Cx Ic mtime +.Cx \&\ \& +.Ar n +.Cx True if the difference between the file last modification time and the time -.I find +.Nm find was started, rounded up to the next full 24\-hour period, is -.B n +.Ar n 24\-hour periods. -.TP -.B ok utility [argument ...] ; +.Tp Cx Ic ok +.Cx \&\ \& +.Ar utility +.Op argument ... ; The -.B ok +.Ic ok primary is identical to the -.B exec +.Ic exec primary with the exception that -.I find +.Nm find requests user affirmation for the execution of the utility by printing a message to the terminal and reading a response. If the response is other than ``y'' the command is not executed and the value of the -.B ok +.Ar ok expression is false. -.TP -.B name pattern +.Tp Cx Ic name +.Cx \&\ \& +.Ar pattern +.Cx True if the last component of the pathname being examined matches -.BR pattern . +.Ar pattern . Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') may be used as part of -.BR pattern . +.Ar pattern . These characters may be matched explicitly by escaping them with a backslash (``\e''). -.TP -.B newer file +.Tp Cx Ic newer +.Cx \&\ \& +.Ar file +.Cx True if the current file has a more recent last modification time than -.BR file . -.TP -.B nouser +.Ar file . +.Tp Ic nouser True if the file belongs to an unknown user. -.TP -.B nogroup +.Tp Ic nogroup True if the file belongs to an unknown group. -.TP -.B perm [\-]mode +.Tp Cx Ic perm +.Cx \&\ \& +.Op Fl +.Ar mode +.Cx The -.B mode +.Ar mode may be either symbolic (see -.IR chmod (1)) +.Xr chmod 1 ) or an octal number. If the mode is symbolic, a starting value of zero is assumed and the mode sets or clears permissions without regard to the process' file mode @@ -191,174 +220,182 @@ if at least all of the bits in the mode are set in the file's mode bits. If the mode is not preceded by a dash, this primary evaluates to true if the bits in the mode exactly match the file's mode bits. Note, the first character of a symbolic mode may not be a dash (``\-''). -.TP -.B print +.Tp Ic print This primary always evaluates to true. It prints the pathname of the current file to standard output. The expression is appended to the user specified expression if neither -.BR exec , -.BR ls , +.Ic exec , +.Ic ls , or -.B ok +.Ic ok is specified. -.TP -.B prune +.Tp Ic prune This primary always evaluates to true. It causes -.I find +.Nm find to not descend into the current file. -.TP -.B size n[c] +.Tp Cx Ic size +.Cx \&\ \& +.Ar n +.Op Cm c +.Cx True if the file's size, rounded up, in 512\-byte blocks is -.BR n . -If -.B n +.Ar n . +If +.Ar n is followed by a ``c'', then the primary is true if the -file's size is -.I n +file's size is +.Ar n bytes. -.TP -.B type t +.Tp Cx Ic type +.Cx \&\ \& +.Ar t +.Cx True if the file is of the specified type. Possible file types are as follows: -.RS -.TP -.B b +.Pp +.Tw Ds +.Tp Cm b block special -.br -.ns -.TP -.B c +.Tp Cm c character special -.br -.ns -.TP -.B d +.Tp Cm d directory -.br -.ns -.TP -.B f +.Tp Cm f regular file -.br -.ns -.TP -.B l +.Tp Cm l symbolic link -.br -.ns -.TP -.B p +.Tp Cm p FIFO -.br -.ns -.TP -.B s +.Tp Cm s socket -.RE -.TP -.B user uname +.Tp +.Pp +.Tp Cx Ic user +.Cx \&\ \& +.Ar uname +.Cx True if the file belongs to the user -.BR uname . +.Ar uname . If -.B uname +.Ar uname is numeric and there is no such user name, then -.B uname +.Ar uname is treated as a user id. -.PP +.Tp +.Pp All primaries which take a numeric argument allow the number to be preceded by a plus sign (``+'') or a minus sign (``\-''). A preceding plus sign means ``more than -.BR n '', +.Ar n ' ' , a preceding minus sign means ``less than -.BR n '' +.Ar n ' ' and neither means ``exactly -.BR n ''. -.SH OPERATORS +.Ar n ' ' . +.Sh OPERATORS The primaries may be combined using the following operators. The operators are listed in order of decreasing precedence. -.TP -.B "( expression )" +.Di L +.Dp Cx Ic \&( +.Ar expression +.Cx \&) +.Cx This evaluates to true if the parenthesized expression evaluates to true. -.TP -.B "! expression" +.Pp +.Dp Cx Ic \&! +.Cx \&\ \& +.Ar expression +.Cx This is the unary NOT operator. It evaluates to true if the expression is false. -.TP -.B "expression and expression" -.br -.ns -.TP -.B "expression expression" +.Pp +.Dp Cx Ar expression +.Cx \&\ \& +.Ic and +.Cx \&\ \& +.Ar expression +.Cx +.Dp Cx Ar expression expression +.Cx The -.B and +.Ic and operator is the logical AND operator. As it is implied by the juxtaposition of two expressions it does not have to be specified. The expression evaluates to true if both expressions are true. The second expression is not evaluated if the first expression is false. -.TP -.B "expression or expression" +.Pp +.Dp Cx Ar expression +.Cx \&\ \& +.Ic or +.Cx \&\ \& +.Ar expression +.Cx The -.B or +.Ic or operator is the logical OR operator. The expression evaluates to true if either the first or the second expression is true. The second expression is not evaluated if the first expression is true. -.PP +.Dp +.Pp All operands and primaries must be separate arguments to -.IR find . +.Nm find . Primaries which themselves take arguments expect each argument to be a separate argument to -.IR find . -.SH EXAMPLES -.PP +.Nm find . +.Sh EXAMPLES +.Pp The following examples are shown as given to the shell: -.TP -find / \e! name "*.c" print +.Tw findx +.Tp Li find / \e! name "*.c" print Print out a list of all the files whose names do not end in ``.c''. -.TP -find / newer ttt user wnj print +.Tp Li find / newer ttt user wnj print Print out a list of all the files owned by user ``wnj'' that are newer than the file ``ttt''. -.TP -find / \e! \e( newer ttt user wnj \e) print +.Tp Li find / \e! \e( newer ttt user wnj \e) print Print out a list of all the files which are not both newer than ``ttt'' and owned by ``wnj''. -.TP -find / \e( newer ttt or user wnj \e) print +.Tp Li find / \e( newer ttt or user wnj \e) print Print out a list of all the files that are either owned by ``wnj'' or that are newer than ``ttt''. -.SH "SEE ALSO" -chmod(1), sh(1), test(1), stat(2), umask(2), -getpwent(3), getgrent(3), strmode(3) -.SH STANDARDS +.Tp +.Sh SEE ALSO +.Xr chmod 1 , +.Xr sh 1 , +.Xr test 1 , +.Xr stat 2 , +.Xr umask 2 , +.Xr getpwent 3 , +.Xr getgrent 3 , +.Xr strmode 3 +.Sh STANDARDS The -.I find +.Nm find utility syntax is a replacement for the syntax specified by the POSIX 1003.2 standard. The standard syntax is also supported; see the COMPATIBILITY section below for details. -.PP +.Pp The -.B \-s +.Fl s option as well as the primaries -.B inum +.Ic inum and -.BR ls +.Ic ls are extensions to the POSIX standard. -.SH COMPATIBILITY +.Sh COMPATIBILITY The traditional, and standardized, syntax for -.I find +.Nm find is as follows. All of the primaries are preceded by a dash (``\-''), i.e. the primary ``group'' is specified as ``\-group''. The -.BR \-d , -.BR \-s , +.Fl d , +.Fl s , and -.BR \-x +.Fl x options are implemented using the primaries ``\-depth'', ``\-follow'', and ``\-xdev''. These primaries always evaluate to true. @@ -366,13 +403,13 @@ The operator ``or'' is implemented as ``\-o'', and the operator ``and'' is implemented as ``\-a''. The set of file trees to be traversed are specified as the first operands to -.IR find . +.Nm find . The first operand beginning with a dash (``\-''), exclamation point (``!'') or left parenthesis (``('') is assumed to be the beginning of the expression and the end of the files to be traversed. -.PP +.Pp The -.I find +.Nm find syntax was changed for two reasons. The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries are really global variables that take effect before the traversal begins. @@ -381,12 +418,12 @@ An example is the expression ``\-print \-o \-depth''. As \-print always evaluates to true, the standard order of evaluation implies that \-depth would never be evaluated. This is not the case. -.PP +.Pp The second reason is that traversing file trees with names beginning with a dash, exclamation point or left parenthesis was impossible. -.SH BUGS +.Sh BUGS The special characters used by -.I find +.Nm find are also special characters to many shell programs. In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', ``!'', ``\e'' and ``;'' may have to be escaped from the shell. diff --git a/usr/src/usr.bin/fpr/fpr.1 b/usr/src/usr.bin/fpr/fpr.1 index 7c6117bacf..690ab7c27b 100644 --- a/usr/src/usr.bin/fpr/fpr.1 +++ b/usr/src/usr.bin/fpr/fpr.1 @@ -16,7 +16,7 @@ .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.\" @(#)fpr.1 6.3 (Berkeley) %G% +.\" @(#)fpr.1 6.4 (Berkeley) %G% .\" .TH FPR 1 "" .UC 5 diff --git a/usr/src/usr.bin/ftp/ftp.1 b/usr/src/usr.bin/ftp/ftp.1 index 632eefa019..04a3e3a7f3 100644 --- a/usr/src/usr.bin/ftp/ftp.1 +++ b/usr/src/usr.bin/ftp/ftp.1 @@ -1,284 +1,372 @@ -.\" Copyright (c) 1985, 1989 The Regents of the University of California. +.\" Copyright (c) 1985, 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)ftp.1 6.13 (Berkeley) %G% +.\" @(#)ftp.1 6.14 (Berkeley) %G% .\" -.TH FTP 1 "March 14, 1989" -.UC 5 -.SH NAME -ftp \- ARPANET file transfer program -.SH SYNOPSIS -.B ftp -[ -.B \-v -] [ -.B \-d -] [ -.B \-i -] [ -.B \-n -] [ -.B \-g -] [ -.B host -] -.SH DESCRIPTION -.I Ftp +.Dd +.Dt FTP 1 +.Os BSD 4.2 +.Sh NAME +.Nm ftp +.Nd ARPANET file transfer program +.Sh SYNOPSIS +.Nm ftp +.Op Fl v +.Op Fl d +.Op Fl i +.Op Fl n +.Op Fl g +.Op Ar host +.Sh DESCRIPTION +.Nm Ftp is the user interface to the ARPANET standard File Transfer Protocol. The program allows a user to transfer files to and from a remote network site. -.PP -The client host with which -.I ftp +.Pp +Options may be specified at the command line, or to the +command interpreter. +.Tp Fl v +Verbose option forces +.Nm ftp +to show all responses from the remote server, as well +as report on data transfer statistics. +.Tp Fl n +Restrains +.Nm ftp +from attempting \*(Lqauto-login\*(Rq upon initial connection. +If auto-login is enabled, +.Nm ftp +will check the +.Pa .netrc +(see below) file in the user's home directory for an entry describing +an account on the remote machine. If no entry exists, +.Nm ftp +will prompt for the remote machine login name (default is the user +identity on the local machine), and, if necessary, prompt for a password +and an account with which to login. +.Tp Fl i +Turns off interactive prompting during +multiple file transfers. +.Tp Fl d +Enables debugging. +.Tp Fl g +Disables file name globbing. +.Tp +.Pp +The client host with which +.Nm ftp is to communicate may be specified on the command line. If this is done, -.I ftp +.Nm ftp will immediately attempt to establish a connection to an FTP -server on that host; otherwise, -.I ftp +server on that host; otherwise, +.Nm ftp will enter its command interpreter and await instructions -from the user. When -.I ftp -is awaiting commands from the user the prompt \*(lqftp>\*(rq +from the user. When +.Nm ftp +is awaiting commands from the user the prompt \*(Lqftp>\*(Rq is provided to the user. The following commands are recognized by -.IR ftp : -.TP -\fB\&!\fP [ \fIcommand\fP [ \fIargs\fP ] ] +.Nm ftp : +.Tw Fl +.Tp Cx Ic \&! +.Cx \&\ \& +.Op Ar command Op Ar args +.Cx Invoke an interactive shell on the local machine. If there are arguments, the first is taken to be a command to execute directly, with the rest of the arguments as its arguments. -.TP -\fB\&$\fP \fImacro-name\fP [ \fIargs\fP ] -Execute the macro \fImacro-name\fP that was defined with the -\fBmacdef\fP command. +.Tp Cx Ic \&$ +.Cx \&\ \& +.Ar macro-name +.Op Ar args +.Cx +Execute the macro +.Ar macro-name +that was defined with the +.Ic macdef +command. Arguments are passed to the macro unglobbed. -.TP -\fBaccount\fP [ \fIpasswd\fP ] +.Tp Cx Ic account +.Cx \&\ \& +.Op Ar passwd +.Cx Supply a supplemental password required by a remote system for access to resources once a login has been successfully completed. If no argument is included, the user will be prompted for an account password in a non-echoing input mode. -.TP -\fBappend\fP \fIlocal-file\fP [ \fIremote-file\fP ] +.Tp Cx Ic append +.Cx \&\ \& +.Ar local-file +.Cx \&\ \& +.Op Ar remote-file +.Cx Append a local file to a file on the remote machine. If -.I remote-file +.Ar remote-file is left unspecified, the local file name is used in naming the remote file after being altered by any -.I ntrans +.Ic ntrans or -.I nmap +.Ic nmap setting. File transfer uses the current settings for -.IR type , -.IR format , -.IR mode , +.Ic type , +.Ic format , +.Ic mode , and -.IR structure . -.TP -.B ascii -Set the file transfer -.I type +.Ic structure . +.Tp Ic ascii +Set the file transfer +.Ic type to network ASCII. This is the default type. -.TP -.B bell +.Tp Ic bell Arrange that a bell be sounded after each file transfer command is completed. -.TP -.B binary +.Tp Ic binary Set the file transfer -.I type +.Ic type to support binary image transfer. -.TP -.B bye +.Tp Ic bye Terminate the FTP session with the remote server and exit -.IR ftp . +.Nm ftp . An end of file will also terminate the session and exit. -.TP -.B case +.Tp Ic case Toggle remote computer file name case mapping during -.B mget +.Ic mget commands. When -.B case +.Ic case is on (default is off), remote computer file names with all letters in upper case are written in the local directory with the letters mapped to lower case. -.TP -.BI cd " remote-directory" +.Tp Cx Ic cd +.Cx \&\ \& +.Ar remote-directory +.Cx Change the working directory on the remote machine -to -.IR remote-directory . -.TP -.B cdup +to +.Ar remote-directory . +.Tp Ic cdup Change the remote machine working directory to the parent of the current remote machine working directory. -.TP -.BI chmod " mode file-name" -Change the permission modes the file \fIfile-name\fR on the remote -sytem to \fImode\fR. -.TP -.B close +.Tp Cx Ic chmod +.Cx \&\ \& +.Ar mode file-name +.Cx +Change the permission modes the file +.Ar file-name +on the remote +sytem to +.Ic mode . +.Tp Ic close Terminate the FTP session with the remote server, and return to the command interpreter. Any defined macros are erased. -.TP -.B cr +.Tp Ic cr Toggle carriage return stripping during ascii type file retrieval. Records are denoted by a carriage return/linefeed sequence during ascii type file transfer. When -.B cr +.Ic cr is on (the default), carriage returns are stripped from this sequence to conform with the UNIX single linefeed record delimiter. Records on non-UNIX remote systems may contain single linefeeds; when an ascii type transfer is made, these linefeeds may be distinguished from a record delimiter only when -.B cr +.Ic cr is off. -.TP -.BI delete " remote-file" +.Tp Cx Ic delete +.Cx \&\ \& +.Ar remote-file +.Cx Delete the file -.I remote-file +.Ar remote-file on the remote machine. -.TP -\fBdebug\fP [ \fIdebug-value\fP ] +.Tp Cx Ic debug +.Cx \&\ \& +.Op Ar debug-value +.Cx Toggle debugging mode. If an optional -.I debug-value +.Ar debug-value is specified it is used to set the debugging level. When debugging is on, -.I ftp +.Nm ftp prints each command sent to the remote machine, preceded -by the string \*(lq-->\*(rq. -.TP -\fBdir\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ] +by the string \*(Lq-->\*(Rq. +.Tp Cx Ic dir +.Cx \&\ \& +.Op Ar remote-directory +.Cx \&\ \& +.Op Ar local-file +.Cx Print a listing of the directory contents in the directory, -.IR remote-directory , +.Ar remote-directory , and, optionally, placing the output in -.IR local-file . +.Ar local-file . If interactive prompting is on, -.I ftp +.Nm ftp will prompt the user to verify that the last argument is indeed the target local file for receiving -.B dir +.Ic dir output. If no directory is specified, the current working directory on the remote machine is used. If no local -file is specified, or \fIlocal-file\fP is \fB-\fP, +file is specified, or +.Ar local-file +is +.Fl , output comes to the terminal. -.TP -.B disconnect +.Tp Ic disconnect A synonym for -.BR close . -.TP -.BI form " format" -Set the file transfer -.I form -to -.IR format . -The default format is \*(lqfile\*(rq. -.TP -\fBget\fP \fIremote-file\fP [ \fIlocal-file\fP ] -Retrieve the -.I remote-file +.Ar close . +.Tp Cx Ic form +.Cx \&\ \& +.Ar format +.Cx +Set the file transfer +.Ic form +to +.Ar format . +The default format is \*(Lqfile\*(Rq. +.Tp Cx Ic get +.Cx \&\ \& +.Ar remote-file +.Cx \&\ \& +.Op Ar local-file +.Cx +Retrieve the +.Ar remote-file and store it on the local machine. If the local file name is not specified, it is given the same name it has on the remote machine, subject to alteration by the current -.IR case , -.IR ntrans , +.Ic case , +.Ic ntrans , and -.I nmap +.Ic nmap settings. -The current settings for -.IR type , -.IR form , -.IR mode , +The current settings for +.Ic type , +.Ic form , +.Ic mode , and -.I structure +.Ic structure are used while transferring the file. -.TP -\fBglob\fP -Toggle filename expansion for \fBmdelete\fP, \fBmget\fP and \fBmput\fP. -If globbing is turned off with \fBglob\fP, the file name arguments +.Tp Ic glob +Toggle filename expansion for +.Ic mdelete , +.Ic mget +and +.Ic mput . +If globbing is turned off with +.Ic glob , +the file name arguments are taken literally and not expanded. -Globbing for \fBmput\fP is done as in \fBcsh\fP(1). -For \fBmdelete\fP and \fBmget\fP, each remote file name is expanded +Globbing for +.Ic mput +is done as in +.Xr csh 1 . +For +.Ic mdelete +and +.Ic mget , +each remote file name is expanded separately on the remote machine and the lists are not merged. -Expansion of a directory name is likely to be +Expansion of a directory name is likely to be different from expansion of the name of an ordinary file: the exact result depends on the foreign operating system and ftp server, -and can be previewed by doing `\fBmls\fP\ \fIremote-files\fP\ \fB-\fP'. -Note: \fBmget\fP and \fBmput\fP are not meant to transfer +and can be previewed by doing +.Cx ` +.Cx Li mls remote-files \- +.Cx \'. +.Cx +Note: +.Ic mget +and +.Ic mput +are not meant to transfer entire directory subtrees of files. That can be done by -transferring a \fBtar\fP(1) archive of the subtree (in binary mode). -.TP -\fBhash\f +transferring a +.Xr tar 1 +archive of the subtree (in binary mode). +.Tp Ic hash Toggle hash-sign (``#'') printing for each data block transferred. The size of a data block is 1024 bytes. -.TP -\fBhelp\fP [ \fIcommand\fP ] +.Tp Cx Ic help +.Cx \&\ \& +.Op Ar command +.Cx Print an informative message about the meaning of -.IR command . -If no argument is given, -.I ftp +.Ar command . +If no argument is given, +.Nm ftp prints a list of the known commands. -.TP -\fBidle\fP [ \fIseconds\fP ] -Set the inactivity timer on the remote server to \fIseconds\fR seconds. -If \fIseconds\fR is ommitted, the current inactivity timer is printed. -.TP -\fBlcd\fP [ \fIdirectory\fP ] +.Tp Cx Ic idle +.Cx \&\ \& +.Op Ar seconds +.Cx +Set the inactivity timer on the remote server to +.Ar seconds +seconds. +If +.Ar seconds +is ommitted, the current inactivity timer is printed. +.Tp Cx Ic lcd +.Cx \&\ \& +.Op Ar directory +.Cx Change the working directory on the local machine. If -no -.I directory +no +.Ar directory is specified, the user's home directory is used. -.TP -\fBls\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ] +.Tp Cx Ic ls +.Cx \&\ \& +.Op Ar remote-directory +.Cx \&\ \& +.Op Ar local-file +.Cx Print a listing of the contents of a directory on the remote machine. The listing includes any system-dependent information that the server chooses to include; for example, most UNIX systems will produce -output from the command \*(lqls -l\*(rq. -(See also \fBnlist\fP.) +output from the command \*(Lqls -l\*(Rq. +(See also +.Ic nlist . +) If -.I remote-directory +.Ar remote-directory is left unspecified, the current working directory is used. If interactive prompting is on, -.I ftp +.Nm ftp will prompt the user to verify that the last argument is indeed the target local file for receiving -.B ls +.Ic ls output. -If no local file is specified, or if \fIlocal-file\fR is \fB-\fR, +If no local file is specified, or if +.Ar local-file +is +.Fl , the output is sent to the terminal. -.TP -\fBmacdef\fP \fImacro-name\fP +.Tp Cx Ic macdef +.Cx \&\ \& +.Ar macro-name +.Cx Define a macro. Subsequent lines are stored as the macro -\fImacro-name\fP; a null line (consecutive newline characters +.Ar macro-name ; +a null line (consecutive newline characters in a file or carriage returns from the terminal) terminates macro input mode. There is a limit of 16 macros and 4096 total characters in all defined macros. Macros remain defined until a -.B close +.Ic close command is executed. The macro processor interprets '$' and '\\' as special characters. A '$' followed by a number (or numbers) is replaced by the @@ -289,285 +377,385 @@ replaced by the first argument on the macro invocation command line, on the second pass it is replaced by the second argument, and so on. A '\\' followed by any character is replaced by that character. Use the '\\' to prevent special treatment of the '$'. -.TP -\fBmdelete\fP [ \fIremote-files\fP ] -Delete the \fIremote-files\fP on the remote machine. -.TP -\fBmdir\fP \fIremote-files\fP \fIlocal-file\fP -Like \fBdir\fP, except multiple remote files may be specified. +.Tp Cx Ic mdelete +.Cx \&\ \& +.Op Ar remote-files +.Cx +Delete the +.Ar remote-files +on the remote machine. +.Tp Cx Ic mdir +.Cx \&\ \& +.Ar remote-files +.Cx \&\ \& +.Ar local-file +.Cx +Like +.Ic dir , +except multiple remote files may be specified. If interactive prompting is on, -.I ftp +.Nm ftp will prompt the user to verify that the last argument is indeed the target local file for receiving -.B mdir +.Ic mdir output. -.TP -\fBmget\fP \fIremote-files\fP -Expand the \fIremote-files\fP on the remote machine -and do a \fBget\fP for each file name thus produced. -See \fBglob\fR for details on the filename expansion. +.Tp Cx Ic mget +.Cx \&\ \& +.Ar remote-files +.Cx +Expand the +.Ar remote-files +on the remote machine +and do a +.Ic get +for each file name thus produced. +See +.Ic glob +for details on the filename expansion. Resulting file names will then be processed according to -.IR case , -.IR ntrans , +.Ic case , +.Ic ntrans , and -.I nmap +.Ic nmap settings. Files are transferred into the local working directory, -which can be changed with `\fBlcd\fP\ directory'; -new local directories can be created with `\fB!\fP\ mkdir\ directory'. -.TP -\fBmkdir\fP \fIdirectory-name\fP +which can be changed with +.Cx ` +.Cx Li lcd directory +.Cx \'; +new local directories can be created with +.Cx Li \&! mkdir directory +.Cx \'. +.Tp Cx Ic mkdir +.Cx \&\ \& +.Ar directory-name +.Cx Make a directory on the remote machine. -.TP -\fBmls\fP \fIremote-files\fP \fIlocal-file\fP -Like \fBnlist\fP, except multiple remote files may be specified, -and the \fIlocal-file\fP must be specified. +.Tp Cx Ic mls +.Cx \&\ \& +.Ar remote-files +.Cx \&\ \& +.Ar local-file +.Cx +Like +.Ic nlist , +except multiple remote files may be specified, +and the +.Ar local-file +must be specified. If interactive prompting is on, -.I ftp +.Nm ftp will prompt the user to verify that the last argument is indeed the target local file for receiving -.B mls +.Ic mls output. -.TP -\fBmode\fP [ \fImode-name\fP ] +.Tp Cx Ic mode +.Cx \&\ \& +.Op Ar mode-name +.Cx Set the file transfer -.I mode +.Ic mode to -.IR mode-name . -The default mode is \*(lqstream\*(rq mode. -.TP -\fBmodtime\fP \fIfile-name\fP +.Ar mode-name . +The default mode is \*(Lqstream\*(Rq mode. +.Tp Cx Ic modtime +.Cx \&\ \& +.Ar file-name +.Cx Show the last modification time of the file on the remote machine. -.TP -\fBmput\fP \fIlocal-files\fP +.Tp Cx Ic mput +.Cx \&\ \& +.Ar local-files +.Cx Expand wild cards in the list of local files given as arguments -and do a \fBput\fR for each file in the resulting list. -See \fBglob\fP for details of filename expansion. +and do a +.Ic put +for each file in the resulting list. +See +.Ic glob +for details of filename expansion. Resulting file names will then be processed according to -.I ntrans +.Ic ntrans and -.I nmap +.Ic nmap settings. -.TP -\fBnlist\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ] +exist on the current system, the remote file is considered +.Ic newer . +Otherwise, this command is identical to +.Ar get . +.Tp Cx Ic nlist +.Cx \&\ \& +.Op Ar remote-directory +.Cx \&\ \& +.Op Ar local-file +.Cx Print a list of the files of a directory on the remote machine. If -.I remote-directory +.Ar remote-directory is left unspecified, the current working directory is used. If interactive prompting is on, -.I ftp +.Nm ftp will prompt the user to verify that the last argument is indeed the target local file for receiving -.B nlist +.Ic nlist output. -If no local file is specified, or if \fIlocal-file\fR is \fB-\fR, +If no local file is specified, or if +.Ar local-file +is +.Fl , the output is sent to the terminal. -.TP -\fBnmap\fP [ \fIinpattern\fP \fIoutpattern\fP ] +.Tp Cx Ic nmap +.Cx \&\ \& +.Op Ar inpattern outpattern +.Cx Set or unset the filename mapping mechanism. If no arguments are specified, the filename mapping mechanism is unset. If arguments are specified, remote filenames are mapped during -.B mput +.Ic mput commands and -.B put +.Ic put commands issued without a specified remote target filename. If arguments are specified, local filenames are mapped during -.B mget +.Ic mget commands and -.B get +.Ic get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX remote computer with different file naming conventions or practices. The mapping follows the pattern set by -.I inpattern +.Ar inpattern and -.IR outpattern . -.I Inpattern +.Ar outpattern . +.Op Ar Inpattern is a template for incoming filenames (which may have already been processed according to the -.B ntrans +.Ic ntrans and -.B case +.Ic case settings). Variable templating is accomplished by including the sequences '$1', '$2', ..., '$9' in -.IR inpattern . +.Ar inpattern . Use '\\' to prevent this special treatment of the '$' character. All other characters are treated literally, and are used to determine the -.B nmap -.I inpattern +.Ic nmap +.Op Ar inpattern variable values. For example, given -.I inpattern +.Ar inpattern $1.$2 and the remote file name "mydata.data", $1 would have the value "mydata", and $2 would have the value "data". The -.I outpattern +.Ar outpattern determines the resulting mapped filename. The sequences '$1', '$2', ...., '$9' are replaced by any value resulting from the -.I inpattern +.Ar inpattern template. The sequence '$0' is replace by the original filename. -Additionally, the sequence '[\fIseq1\fP,\fIseq2\f\P]' is replaced by -.I seq1 +Additionally, the sequence +.Cx ` +.Op Ar seq1 , Ar seq2 +.Cx \' +is replaced by +.Op Ar seq1 if -.I seq1 +.Ar seq1 is not a null string; otherwise it is replaced by -.IR seq2 . -For example, the command "nmap $1.$2.$3 [$1,$2].[$2,file]" would yield +.Ar seq2 . +For example, the command +.Pp +.Df I +nmap $1.$2.$3 +.Cx Op $1,$2 +.Cx . +.Op $2,file +.Cx +.De +.Pp +would yield the output filename "myfile.data" for input filenames "myfile.data" and "myfile.data.old", "myfile.file" for the input filename "myfile", and "myfile.myfile" for the input filename ".myfile". Spaces may be included in -.IR outpattern , -as in the example: nmap $1 |sed "s/ *$//" > $1 . +.Ar outpattern , +as in the example: nmap $1 sed "s/ *$//" > $1 . Use the '\\' character to prevent special treatment -of the '$', '[', ']', and ',' characters. -.TP -\fBntrans\fP [ \fIinchars\fP [ \fIoutchars\fP ] ] +of the '$','[','[', and ',' characters. +.Tp Cx Ic ntrans +.Cx \&\ \& +.Op Ar inchars Op Ar outchars +.Cx Set or unset the filename character translation mechanism. If no arguments are specified, the filename character translation mechanism is unset. If arguments are specified, characters in remote filenames are translated during -.B mput +.Ic mput commands and -.B put +.Ic put commands issued without a specified remote target filename. If arguments are specified, characters in local filenames are translated during -.B mget +.Ic mget commands and -.B get +.Ic get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX remote computer with different file naming conventions or practices. Characters in a filename matching a character in -.I inchars +.Ar inchars are replaced with the corresponding character in -.IR outchars . +.Ar outchars . If the character's position in -.I inchars +.Ar inchars is longer than the length of -.IR outchars , +.Ar outchars , the character is deleted from the file name. -.TP -\fBopen\fP \fIhost\fP [ \fIport\fP ] +.Tp Cx Ic open +.Cx \&\ \& +.Ar host +.Cx \&\ \& +.Op Ar port +.Cx Establish a connection to the specified -.I host +.Ar host FTP server. An optional port number may be supplied, -in which case, -.I ftp +in which case, +.Nm ftp will attempt to contact an FTP server at that port. -If the -.I auto-login -option is on (default), -.I ftp +If the +.Ic auto-login +option is on (default), +.Nm ftp will also attempt to automatically log the user in to the FTP server (see below). -.TP -.B prompt +.Tp Ic prompt Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to allow the user to selectively retrieve or store files. -If prompting is turned off (default is on), any \fBmget\fP or \fBmput\fP -will transfer all files, and any \fBmdelete\fP will delete all files. -.TP -\fBproxy\fP \fIftp-command\fP +If prompting is turned off (default is on), any +.Ic mget +or +.Ic mput +will transfer all files, and any +.Ic mdelete +will delete all files. +.Tp Cx Ic proxy +.Cx \&\ \& +.Ar ftp-command +.Cx Execute an ftp command on a secondary control connection. This command allows simultaneous connection to two remote ftp servers for transferring files between the two servers. The first -.B proxy +.Ic proxy command should be an -.BR open , +.Ic open , to establish the secondary control connection. Enter the command "proxy ?" to see other ftp commands executable on the secondary connection. The following commands behave differently when prefaced by -.BR proxy : -.B open +.Ic proxy : +.Ic open will not define new macros during the auto-login process, -.B close +.Ic close will not erase existing macro definitions, -.B get +.Ic get and -.B mget +.Ic mget transfer files from the host on the primary control connection to the host on the secondary control connection, and -.BR put , -.BR mput , +.Ic put , +.Ic mput , and -.B append +.Ic append transfer files from the host on the secondary control connection to the host on the primary control connection. Third party file transfers depend upon support of the ftp protocol PASV command by the server on the secondary control connection. -.TP -\fBput\fP \fIlocal-file\fP [ \fIremote-file\fP ] -Store a local file on the remote machine. If -.I remote-file +.Tp Cx Ic put +.Cx \&\ \& +.Ar local-file +.Cx \&\ \& +.Op Ar remote-file +.Cx +Store a local file on the remote machine. If +.Ar remote-file is left unspecified, the local file name is used after processing according to any -.I ntrans +.Ic ntrans or -.I nmap +.Ic nmap settings in naming the remote file. File transfer uses the current settings for -.IR type , -.IR format , -.IR mode , +.Ic type , +.Ic format , +.Ic mode , and -.IR structure . -.TP -.B pwd +.Ic structure . +.Tp Ic pwd Print the name of the current working directory on the remote machine. -.TP -.B quit +.Tp Ic quit A synonym for -.BR bye . -.TP -.BI quote " arg1 arg2 ..." +.Ic bye . +.Tp Cx Ic quote +.Cx \&\ \& +.Ar crg1 arg2 ... +.Cx The arguments specified are sent, verbatim, to the remote FTP server. -.TP -\fBrecv\fP \fIremote-file\fP [ \fIlocal-file\fP ] +.Tp Cx Ic recv +.Cx \&\ \& +.Ar remote-file +.Cx \&\ \& +.Op Ar local-file +.Cx A synonym for get. -.TP -\fBremotehelp\fP [ \fIcommand-name\fP ] -Request help from the remote FTP server. If a -.I command-name +.Tp Cx Ic remotehelp +.Cx \&\ \& +.Op Ar command-name +.Cx +Request help from the remote FTP server. If a +.Ar command-name is specified it is supplied to the server as well. -.TP -\fBremotestatus\fP [ \fIfile-name\fP ] -With no arguments, show status of remote machine. If \fIfile-name\fP -is specified, show status of \fIfile-name\fP on remote machine. -.TP -\fBrename\fP [ \fIfrom\fP ] [ \fIto\fP ] +.Tp Cx Ic remotestatus +.Op Ar file-name +.Cx +With no arguments, show status of remote machine. If +.Ar file-name +is specified, show status of +.Ar file-name +on remote machine. +.Tp Cx Ic rename +.Cx \&\ \& +.Op Ar from +.Cx \&\ \& +.Op Ar to +.Cx Rename the file -.I from +.Ar from on the remote machine, to the file -.IR to . -.TP -.B reset +.Ar to . +.Tp Ic reset Clear reply queue. This command re-synchronizes command/reply sequencing with the remote ftp server. Resynchronization may be necessary following a violation of the ftp protocol by the remote server. -.TP -.BI rmdir " directory-name" +.Tp Cx Ic rmdir +.Cx \&\ \& +.Ar directory-name +.Cx Delete a directory on the remote machine. -.TP -.B runique +.Tp Ic runique Toggle storing of files on the local system with unique filenames. If a file already exists with a name equal to the target local filename for a -.B get +.Ic get or -.B mget +.Ic mget command, a ".1" is appended to the name. If the resulting name matches another existing file, a ".2" is appended to the original name. @@ -575,80 +763,99 @@ If this process continues up to ".99", an error message is printed, and the transfer does not take place. The generated unique filename will be reported. Note that -.B runique +.Ic runique will not affect local files generated from a shell command (see below). The default value is off. -.TP -\fBsend\fP \fIlocal-file\fP [ \fIremote-file\fP ] +.Tp Cx Ic send +.Cx \&\ \& +.Ar local-file +.Cx \&\ \& +.Op Ar remote-file +.Cx A synonym for put. -.TP -.B sendport -Toggle the use of PORT commands. By default, -.I ftp +.Tp Ic sendport +Toggle the use of PORT commands. By default, +.Nm ftp will attempt to use a PORT command when establishing a connection for each data transfer. The use of PORT commands can prevent delays when performing multiple file transfers. If the PORT -command fails, -.I ftp +command fails, +.Nm ftp will use the default data port. When the use of PORT commands is disabled, no attempt will be made to use PORT commands for each data transfer. This is useful for certain FTP implementations which do ignore PORT commands but, incorrectly, indicate they've been accepted. -.TP -.BI site " arg1 arg2 ..." +.Tp Cx Ic site +.Cx \&\ \& +.Ar arg1 arg2 ... +.Cx The arguments specified are sent, verbatim, to the remote FTP server as a SITE command. -.TP -.BI size " file-name" -Return size of \fIfile-name\fP on remote machine. -.TP -.B status +.Tp Cx Ic size +.Cx \&\ \& +.Ar file-name +.Cx +Return size of +.Ar file-name +on remote machine. +.Tp Ic status Show the current status of -.IR ftp . -.TP -\fBstruct\fP [ \fIstruct-name\fP ] +.Nm ftp . +.Tp Cx Ic struct +.Cx \&\ \& +.Op Ar struct-name +.Cx Set the file transfer -.I structure +.Ar structure to -.IR struct-name . -By default \*(lqstream\*(rq structure is used. -.TP -.B sunique +.Ar struct-name . +By default \*(Lqstream\*(Rq structure is used. +.Tp Ic sunique Toggle storing of files on remote machine under unique file names. Remote ftp server must support ftp protocol STOU command for successful completion. The remote server will report unique name. Default value is off. -.TP -.B system +.Tp Ic system Show the type of operating system running on the remote machine. -.TP -.B tenex +.Tp Ic tenex Set the file transfer type to that needed to talk to TENEX machines. -.TP -.B trace +.Tp Ic trace Toggle packet tracing. -.TP -\fBtype\fP [ \fItype-name\fP ] +.Tp Cx Ic type +.Cx \&\ \& +.Op Ar type-name +.Cx Set the file transfer -.I type +.Ic type to -.IR type-name . +.Ar type-name . If no type is specified, the current type is printed. The default type is network ASCII. -.TP -\fBumask\fP [ \fInewmask\fP ] -Set the default umask on the remote server to \fInewmask\fR. -If \fInewmask\fR is ommitted, the current umask is printed. -.TP -\fBuser\fP \fIuser-name\fP [ \fIpassword\fP ] [ \fIaccount\fP ] +.Tp Cx Ic umask +.Cx \&\ \& +.Op Ar newmask +.Cx +Set the default umask on the remote server to +.Ic newmask . +If +.Ic newmask +is ommitted, the current umask is printed. +.Tp Cx Ic user +.Cx \&\ \& +.Ar user-name +.Cx \&\ \& +.Op Ar password +.Cx \&\ \& +.Op Ar account +.Cx Identify yourself to the remote FTP server. If the password is not specified and the server requires it, -.I ftp +.Nm ftp will prompt the user for it (after disabling local echo). If an account field is not specified, and the FTP server requires it, the user will be prompted for it. @@ -657,24 +864,26 @@ be relayed to the remote server after the login sequence is completed if the remote server did not require it for logging in. Unless -.I ftp -is invoked with \*(lqauto-login\*(rq disabled, this +.Nm ftp +is invoked with \*(Lqauto-login\*(Rq disabled, this process is done automatically on initial connection to the FTP server. -.TP -.B verbose +.Tp Ic verbose Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the user. In addition, if verbose is on, when a file transfer completes, statistics regarding the efficiency of the transfer are reported. By default, verbose is on. -.TP -\fB?\fP [ \fIcommand\fP ] +.Tp Cx Ic ? +.Cx \&\ \& +.Op Ar command +.Cx A synonym for help. -.PP +.Tp +.Pp Command arguments which have embedded spaces may be quoted with quote (") marks. -.SH "ABORTING A FILE TRANSFER" +.Sh "ABORTING A FILE TRANSFER" To abort a file transfer, use the terminal interrupt key (usually Ctrl-C). Sending transfers will be immediately halted. @@ -685,218 +894,220 @@ server's support for ABOR processing. If the remote server does not support the ABOR command, an "ftp>" prompt will not appear until the remote server has completed sending the requested file. -.PP +.Pp The terminal interrupt key sequence will be ignored when -.I ftp +.Nm ftp has completed any local processing and is awaiting a reply from the remote server. A long delay in this mode may result from the ABOR processing described above, or from unexpected behavior by the remote server, including violations of the ftp protocol. If the delay results from unexpected remote server behavior, the local -.I ftp +.Nm ftp program must be killed by hand. -.SH "FILE NAMING CONVENTIONS" +.Sh "FILE NAMING CONVENTIONS" Files specified as arguments to -.I ftp +.Nm ftp commands are processed according to the following rules. -.TP -1) -If the file name \*(lq\-\*(rq is specified, the -.B stdin +.Tw Fl +.Tp \&1) +If the file name \*(Lq\-\*(Rq is specified, the +.Ar stdin (for reading) or -.B stdout +.Ar stdout (for writing) is used. -.TP -2) -If the first character of the file name is \*(lq|\*(rq, the +.Tp \&2) +If the first character of the file name is \*(Lq\*(Rq, the remainder of the argument is interpreted as a shell command. -.I Ftp -then forks a shell, using -.IR popen (3) +.Nm Ftp +then forks a shell, using +.Xr popen 3 with the argument supplied, and reads (writes) from the stdout (stdin). If the shell command includes spaces, the argument -must be quoted; e.g. \*(lq"| ls -lt"\*(rq. A particularly -useful example of this mechanism is: \*(lqdir |more\*(rq. -.TP -3) -Failing the above checks, if ``globbing'' is enabled, +must be quoted; e.g. \*(Lq" ls -lt"\*(Rq. A particularly +useful example of this mechanism is: \*(Lqdir more\*(Rq. +.Tp \&3) +Failing the above checks, if ``globbing'' is enabled, local file names are expanded -according to the rules used in the -.IR csh (1); -c.f. the -.I glob -command. +according to the rules used in the +.Xr csh 1 ; +c.f. the +.Ic glob +command. If the -.I ftp +.Nm ftp command expects a single local file ( .e.g. -.BR put ), +.Ic put ) , only the first filename generated by the "globbing" operation is used. -.TP -4) +.Tp \&4) For -.B mget +.Ic mget commands and -.B get +.Ic get commands with unspecified local file names, the local filename is the remote filename, which may be altered by a -.BR case , -.BR ntrans , +.Ic case , +.Ic ntrans , or -.B nmap +.Ic nmap setting. The resulting filename may then be altered if -.B runique +.Ic runique is on. -.TP -5) +.Tp \&5) For -.B mput +.Ic mput commands and -.B put +.Ic put commands with unspecified remote file names, the remote filename is the local filename, which may be altered by a -.B ntrans +.Ic ntrans or -.B nmap +.Ic nmap setting. The resulting filename may then be altered by the remote server if -.B sunique +.Ic sunique is on. -.SH "FILE TRANSFER PARAMETERS" +.Tp +.Sh "FILE TRANSFER PARAMETERS" The FTP specification specifies many parameters which may -affect a file transfer. The -.I type -may be one of \*(lqascii\*(rq, \*(lqimage\*(rq (binary), -\*(lqebcdic\*(rq, and \*(lqlocal byte size\*(rq (for PDP-10's +affect a file transfer. The +.Ic type +may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary), +\*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for PDP-10's and PDP-20's mostly). -.I Ftp +.Nm Ftp supports the ascii and image types of file transfer, -plus local byte size 8 for \fBtenex\fP mode transfers. -.PP -.I Ftp +plus local byte size 8 for +.Ic tenex +mode transfers. +.Pp +.Nm Ftp supports only the default values for the remaining -file transfer parameters: -.IR mode , -.IR form , +file transfer parameters: +.Ic mode , +.Ic form , and -.IR struct . -.SH OPTIONS -Options may be specified at the command line, or to the -command interpreter. -.PP +.Ic struct . +.Sh "THE .netrc FILE" The -.B \-v -(verbose on) option forces -.I ftp -to show all responses from the remote server, as well -as report on data transfer statistics. -.PP -The -.B \-n -option restrains -.I ftp -from attempting \*(lqauto-login\*(rq upon initial connection. -If auto-login is enabled, -.I ftp -will check the -.I .netrc -(see below) file in the user's home directory for an entry describing -an account on the remote machine. If no entry exists, -.I ftp -will prompt for the remote machine login name (default is the user -identity on the local machine), and, if necessary, prompt for a password -and an account with which to login. -.PP -The -.B \-i -option turns off interactive prompting during -multiple file transfers. -.PP -The -.B \-d -option enables debugging. -.PP -The -.B \-g -option disables file name globbing. -.SH "THE .netrc FILE" -The .netrc file contains login and initialization information +.Pa .netrc +file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines: -.TP -\fBmachine\fP \fIname\fP +.Tw password +.Tp Cx Ic machine +.Cx \&\ \& +.Ar name +.Cx Identify a remote machine name. The auto-login process searches the .netrc file for a -.B machine +.Ic machine token that matches the remote machine specified on the -.I ftp +.Nm ftp command line or as an -.B open +.Ic open command argument. Once a match is made, the subsequent .netrc tokens are processed, stopping when the end of file is reached or another -.B machine +.Ic machine or a -.B default +.Ic default token is encountered. -.TP -\fBdefault\fP -This is the same as \fBmachine\fP \fIname\fP except that \fBdefault\fP +.Tp Ic default +This is the same as +.Ic machine +.Ar name +except that +.Ic default matches any name. -There can be only one \fBdefault\fP token, and it must be after all -\fBmachine\fP tokens. +There can be only one +.Ic default +token, and it must be after all +.Ic machine +tokens. This is normally used as: -.ce -default login anonymous password user@site -thereby giving the user \fIautomatic\fP anonymous ftp login to -machines not specified in \fB.netrc\fP. This can be overridden -by using the \fB\-n\fP flag to disable auto-login. -.TP -\fBlogin\fP \fIname\fP +.Dl default login anonymous password user@site +thereby giving the user +.Ar automatic +anonymous ftp login to +machines not specified in +.Pa .netrc . +This can be overridden +by using the +.Fl n +flag to disable auto-login. +.Tp Cx Ic login +.Cx \&\ \& +.Ar name +.Cx Identify a user on the remote machine. If this token is present, the auto-login process will initiate a login using the specified name. -.TP -\fBpassword\fP \fIstring\fP +.Tp Cx Ic password +.Cx \&\ \& +.Ar string +.Cx Supply a password. If this token is present, the auto-login process will supply the specified string if the remote server requires a password as part of the login process. -Note that if this token is present in the .netrc file for any user other -than \fIanonymous\fP, -.I ftp -will abort the auto-login process if the .netrc is readable by +Note that if this token is present in the +.Pa .netrc +file for any user other +than +.Ar anonymous , +.Nm ftp +will abort the auto-login process if the +.Pa .netrc +is readable by anyone besides the user. -.TP -\fBaccount\fP \fIstring\fP +.Tp Cx Ic account +.Cx \&\ \& +.Ar string +.Cx Supply an additional account password. If this token is present, the auto-login process will supply the specified string if the remote server requires an additional account password, or the auto-login process will initiate an ACCT command if it does not. -.TP -\fBmacdef\fP \fIname\fP +.Tp Cx Ic macdef +.Cx \&\ \& +.Ar name +.Cx Define a macro. This token functions like the -.I ftp -.B macdef +.Nm ftp +.Ic macdef command functions. A macro is defined with the specified name; its contents begin with the -next .netrc line and continue until a null line (consecutive new-line +next +.Pa .netrc +line and continue until a null line (consecutive new-line characters) is encountered. If a macro named -.I init +.Ic init is defined, it is automatically executed as the last step in the auto-login process. -.SH "SEE ALSO" -ftpd(8) -.SH BUGS +.Tp +.Sh ENVIRONMENT +.Nm Ftp +makes use of the +.Ev HOME +and +.Ev SHELL +environment variables. +.Sh SEE ALSO +.Xr ftpd 8 +.Sh HISTORY +.Nm Ftp +appeared in 4.2 BSD. +.Sh BUGS Correct execution of many commands depends upon proper behavior by the remote server. -.PP +.Pp An error in the treatment of carriage returns in the 4.2BSD UNIX ascii-mode transfer code has been corrected. diff --git a/usr/src/usr.bin/indent/indent.1 b/usr/src/usr.bin/indent/indent.1 index 5e33f6ef36..84e6ab0be5 100644 --- a/usr/src/usr.bin/indent/indent.1 +++ b/usr/src/usr.bin/indent/indent.1 @@ -1,413 +1,502 @@ +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" Copyright (c) 1985 Sun Microsystems, Inc. -.\" Copyright (c) 1980 The Regents of the University of California. .\" Copyright (c) 1976 Board of Trustees of the University of Illinois. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley, the University of Illinois, -.\" Urbana, and Sun Microsystems, Inc. The name of either University -.\" or Sun Microsystems may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" @(#)indent.1 6.6 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" - -.TH INDENT 1 " -.SH NAME -indent \- indent and format C program source -.SH SYNOPSIS -.in +\w'\fBindent \fR'u -.ti -\w'\fBindent \fR'u -\fBindent \fR [ \fIinput-file\fR [ \fIoutput-file\fR ] ] -[\ \fB\-bad\fR\ |\ \fB\-nbad\fR\ ] -[\ \fB\-bap\fR\ |\ \fB\-nbap\fR\ ] -[\ \fB\-bbb\fR\ |\ \fB\-nbbb\fR\ ] -[\ \fB\-bc\fR\ |\ \fB\-nbc\fR\ ] -[\ \fB\-bl\fR\ ] -[\ \fB\-br\fR\ ] -[\ \fB\-c\fIn\fR\ ] -[\ \fB\-cd\fIn\fR\ ] -[\ \fB\-cdb\fR\ |\ \fB\-ncdb\fR\ ] -[\ \fB\-ce\fR\ |\ \fB\-nce\fR\ ] -[\ \fB\-ci\fIn\fR\ ] -[\ \fB\-cli\fIn\fR\ ] -[\ \fB\-d\fIn\fR\ ] -[\ \fB\-di\fIn\fR\ ] -[\ \fB\-fc1\fR\ |\ \fB\-nfc1\fR\ ] -[\ \fB\-i\fIn\fR\ ] -[\ \fB\-ip\fR\ |\ \fB\-nip\fR\ ] -[\ \fB\-l\fIn\fR\ ] -[\ \fB\-lc\fIn\fR\ ] -[\ \fB\-lp\fR\ |\ \fB\-nlp\fR\ ] -[\ \fB\-npro\fR\ ] -[\ \fB\-pcs\fR\ |\ \fB\-npcs\fR\ ] -[\ \fB\-psl\fR\ |\ \fB\-npsl\fR\ ] -[\ \fB\-sc\fR\ |\ \fB\-nsc\fR\ ] -[\ \fB\-sob\fR\ |\ \fB\-nsob\fR\ ] -[\ \fB\-st\fR\ ] -[\ \fB\-troff\fR\ ] -[\ \fB\-v\fR\ |\ \fB\-nv\fR\ ] -.SH DESCRIPTION -.I Indent -is a \fBC\fR program formatter. It reformats the \fBC\fR program in the -\fIinput-file\fR according to the switches. The switches which can be +.\" @(#)indent.1 6.7 (Berkeley) %G% +.\" +.Dd +.Dt INDENT 1 +.Sh NAME +.Nm indent +.Nd indent and format C program source +.Sh SYNOPSIS +.Nm indent +.Op Ar input-file Op Ar output-file +.Cx \&[ +.Fl bad +.Cx \&\ |\ \& +.Fl nbad +.Cx \&] +.Cx +.Cx \&[ +.Fl bap +.Cx \&\ |\ \& +.Fl nbap +.Cx \&] +.Cx +.Cx \&[ +.Fl bbb +.Cx \&\ |\ \& +.Fl nbbb +.Cx \&] +.Cx +.Cx \&[ +.Fl bc +.Cx \&\ |\ \& +.Fl nbc +.Cx \&] +.Cx +.Op Fl bl +.Op Fl br +.Oo +.Op Fl c Ar n +.Op Fl cd Ar n +.Oo +.Cx \&[ +.Fl cdb +.Cx \&\ |\ \& +.Fl ncdb +.Cx \&] +.Cx +.Cx \&[ +.Fl ce +.Cx \&\ |\ \& +.Fl nce +.Cx \&] +.Cx +.Oo +.Op Fl ci Ar n +.Op Fl cli Ar n +.Op Fl d Ar n +.Op Fl di Ar n +.Oo +.Cx \&[ +.Fl fc1 +.Cx \&\ |\ \& +.Fl nfc1 +.Cx \&] +.Cx +.Oo +.Op Fl i Ar n +.Oo +.Cx \&[ +.Fl ip +.Cx \&\ |\ \& +.Fl nip +.Cx \&] +.Cx +.Oo +.Op Fl l Ar n +.Op Fl lc Ar n +.Oo +.Cx \&[ +.Fl lp +.Cx \&\ |\ \& +.Fl nlp +.Cx \&] +.Cx +.Op Fl npro +.Cx \&[ +.Fl pcs +.Cx \&\ |\ \& +.Fl npcs +.Cx \&] +.Cx +.Cx \&[ +.Fl psl +.Cx \&\ |\ \& +.Fl npsl +.Cx \&] +.Cx +.Cx \&[ +.Fl sc +.Cx \&\ |\ \& +.Fl nsc +.Cx \&] +.Cx +.Cx \&[ +.Fl sob +.Cx \&\ |\ \& +.Fl nsob +.Cx \&] +.Cx +.Op Fl st +.Op Fl troff +.Cx \&[ +.Fl v +.Cx \&\ |\ \& +.Fl nv +.Cx \&] +.Cx +.Sh DESCRIPTION +.Nm Indent +is a +.Ar C +program formatter. It reformats the +.Ar C +program in the +.Ar input-file +according to the switches. The switches which can be specified are described below. They may appear before or after the file names. -.LP -\fBNOTE\fP: If you only specify an \fIinput-file\fR, the formatting is +.Pp +.Sy NOTE : +If you only specify an +.Ar input-file , +the formatting is done `in-place', that is, the formatted file is written back into -.I input-file +.Ar input-file and a backup copy of -.I input-file +.Ar input-file is written in the current directory. If -.I input-file -is named `/blah/blah/file', the backup file is named -.RI file .BAK. -.LP +.Ar input-file +is named +.Sq Pa /blah/blah/file , +the backup file is named +.Pa file.BAK . +.Pp If -.I output-file +.Ar output-file is specified, -.I indent +.Nm indent checks to make sure it is different from -.IR input-file . -.SH OPTIONS -.LP +.Ar input-file . +.Pp The options listed below control the formatting style imposed by -.IR indent . -.TP 15 -.BR \-bad , \-nbad +.Nm indent . +.Tw Op +.Tp Fl bad , nbad If -.B \-bad +.Fl bad is specified, a blank line is forced after every block of -declarations. Default: -.BR \-nbad . -.TP 15 -.BR \-bap , \-nbap +declarations. Default: +.Fl nbad . +.Tp Fl bap , nbap If -.B \-bap +.Fl bap is specified, a blank line is forced after every procedure body. Default: -.B \-nbap. -.TP 15 -.BR \-bbb , \-nbbb +.Fl nbap . +.Tp Fl bbb , nbbb If -.B \-bbb +.Fl bbb is specified, a blank line is forced before every block comment. Default: -.B \-nbbb. -.TP 15 -.BR \-bc , \-nbc +.Fl nbbb . +.Tp Fl bc , nbc If -.B \-bc -is specified, then a newline is forced after each comma in a declaration. -.B \-nbc +.Fl bc +is specified, then a newline is forced after each comma in a declaration. +.Fl nbc turns off this option. The default is -.BR \-bc . -.TP 15 -.BR \-br , \-bl +.Fl bc . +.Tp Fl br , bl Specifying -.B \-bl +.Fl bl lines up compound statements like this: .ne 4 -.nf -.ft L - if (...) - { - code - } -.ft R -.fi +.Ds I +if (...) +{ + code +} +.De Specifying -.B \-br +.Fl br (the default) makes them look like this: .ne 3 -.nf -.ft L - if (...) { - code - } -.ft R -.fi -.LP -.TP 15 -.BI \-c n -The column in which comments on code start. The default is 33. -.TP 15 -.BI \-cd n +.Ds I +if (...) { + code +} +.De +.Pp +.Tp Fl c n +The column in which comments on code start. The default is 33. +.Tp Fl cd n The column in which comments on declarations start. The default is for these comments to start in the same column as those on code. -.TP 15 -.BI \-cdb , \-ncdb +.Tp Fl cdb , ncdb Enables (disables) the placement of comment delimiters on blank lines. With this option enabled, comments look like this: -.nf -.ft L +.Ds I .ne 3 /* - * this is a comment - */ -.ft R -.fi + * this is a comment + */ +.De Rather than like this: -.nf -.ft L +.Ds I /* this is a comment */ -.ft R -.fi +.De This only affects block comments, not comments to the right of code. The default is -.BR \-cdb . -.TP 15 -.BI \-ce , \-nce +.Fl cdb . +.Tp Fl ce , nce Enables (disables) forcing `else's to cuddle up to the immediately preceding `}'. The default is -.BR \-ce . -.TP 15 -.BI \-ci n -Sets the continuation indent to be \fIn\fR. Continuation +.Fl ce . +.Tp Cx Fl ci +.Ar n +.Cx +Sets the continuation indent to be +.Ar n . +Continuation lines will be indented that far from the beginning of the first line of the statement. Parenthesized expressions have extra indentation added to -indicate the nesting, unless \fB\-lp\fR is in effect. -\fB\-ci\fR defaults to the same value as \fB\-i\fR. -.TP 15 -.BI \-cli n +indicate the nesting, unless +.Fl lp +is in effect. +.Fl ci +defaults to the same value as +.Fl i . +.Tp Cx Fl cli +.Ar n +.Cx Causes case labels to be indented -.I n -tab stops to the right of the containing \fBswitch\fR statement. -\fB\-cli0.5\fR causes case labels to be indented half a tab stop. The +.Ar n +tab stops to the right of the containing +.Ic switch +statement. +.Fl cli0 .5 +causes case labels to be indented half a tab stop. The default is -.BR \-cli0 . -.TP 15 -.BI \-d n +.Fl cli0 . +.Tp Cx Fl d +.Ar n +.Cx Controls the placement of comments which are not to the right of code. The default -.B \-d1 +.Fl d1 means that such comments are placed one indentation level to the left of code. Specifying -.B \-d0 +.Fl d0 lines up these comments with the code. See the section on comment indentation below. -.TP 15 -.BI \-di n +.Tp Cx Fl di +.Ar n +.Cx Specifies the indentation, in character positions, from a declaration keyword to the following identifier. The default is -.BR \-di16 . -.if 0 \{.TP 15 -.BR \-dj , \-ndj -.B \-dj +.Fl di16 . +.Tp Fl dj , ndj +.Fl dj left justifies declarations. -.B \-ndj +.Fl ndj indents declarations the same as code. The default is -.BR \-ndj . -.TP 15 -.BI \-ei , \-nei +.Fl ndj . +.Tp Fl ei , nei Enables (disables) special -.B else-if -processing. If it's enabled, -.BR if "s" -following -.BR else "s" +.Ic else-if +processing. If it's enabled, an +.Ic if +following an +.Ic else will have the same indentation as the preceding -.B if -statement.\} -.TP 15 -.BI \-fc1 , \-nfc1 +.Ic if +statement. +.Tp Fl fc1 , nfc1 Enables (disables) the formatting of comments that start in column 1. Often, comments whose leading `/' is in column 1 have been carefully -hand formatted by the programmer. In such cases, \fB\-nfc1\fR should be -used. The default is \fB\-fc1\fR. -.TP 15 -.BI \-i n +hand formatted by the programmer. In such cases, +.Fl nfc1 +should be +used. The default is +.Fl fc1 . +.Tp Cx Fl i +.Ar n +.Cx The number of spaces for one indentation level. The default is 4. -.TP 15 -.BI \-ip , \-nip +.Tp Fl ip , nip Enables (disables) the indentation of parameter declarations from the left margin. The default is -.BR \-ip . -.TP 15 -.BI \-l n +.Fl ip . +.Tp Cx Fl l +.Ar n +.Cx Maximum length of an output line. The default is 75. -.TP 15 -.BI \-lp , \-nlp +.Tp Fl lp , nlp Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren which is not closed on that line, then continuation lines will be lined up to start at the character position just after the left paren. For example, here is how a piece of continued code looks with -\fB\-nlp\fR in effect: +.Fl nlp +in effect: .ne 2 -.nf -.ft L - p1 = first_procedure(second_procedure(p2, p3), - third_procedure(p4, p5)); -.ft R -.fi +.Ds I +.Li p1 = first_procedure(second_procedure(p2, p3), +.Li \ \ third_procedure(p4,p5)); +.De .ne 5 -With \fB\-lp\fR in effect (the default) the code looks somewhat clearer: -.nf -.ft L -.ta \w' p1 = first_procedure('u - p1 = first_procedure(second_procedure(p2, p3), - third_procedure(p4, p5)); -.ft R -.fi +With +.Fl lp +in effect (the default) the code looks somewhat clearer: +.Ds I +.Li p1\ =\ first_procedure(second_procedure(p2,\ p3), +.Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5)); +.De .ne 5 Inserting two more newlines we get: -.nf -.ft L -.ta \w' p1 = first_procedure('u +\w'second_procedure('u - p1 = first_procedure(second_procedure(p2, - p3), -.ta \w' p1 = first_procedure('u +\w'third_procedure('u - third_procedure(p4, - p5)); -.ft R -.fi -.TP 15 -.B \-npro -Causes the profile files, `./.indent.pro' and `~/.indent.pro', to be ignored. -.TP 15 -.BR \-pcs , \-npcs -If true (\fB\-pcs\fR) all procedure calls will have a space inserted between -the name and the `('. The default is -.BR \-npcs . -.TP 15 -.BR \-psl , \-npsl -If true (\fB\-psl\fR) the names of procedures being defined are placed in +.Ds I +.Li p1\ =\ first_procedure(second_procedure(p2, +.Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3), +.Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4 +.Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5)); +.De +.Pp +.Tp Fl npro +Causes the profile files, +.Sq Pa ./.indent.pro +and +.Sq Pa ~/.indent.pro , +to be ignored. +.Tp Fl pcs , npcs +If true +.Pq Fl pcs +all procedure calls will have a space inserted between +the name and the `('. The default is +.Fl npcs . +.Tp Fl psl , npsl +If true +.Pq Fl psl +the names of procedures being defined are placed in column 1 \- their types, if any, will be left on the previous lines. The -default is -.BR \-psl . -.TP 15 -.BR \-sc , \-nsc +default is +.Fl psl . +.Tp Fl sc , nsc Enables (disables) the placement of asterisks (`*'s) at the left edge of all comments. -.TP 15 -.BR \-sob , \-nsob +.Tp Fl sob , nsob If -.B \-sob +.Fl sob is specified, indent will swallow optional blank lines. You can use this to get rid of blank lines after declarations. Default: -.BR \-nsob . -.TP 15 -.B \-st +.Fl nsob . +.Tp Fl st Causes -.B indent +.Nm indent to take its input from stdin, and put its output to stdout. -.TP 15 -.BI \-T typename +.Tp Cx Fl T +.Ar typename +.Cx Adds -.I typename +.Ar typename to the list of type keywords. Names accumulate: -.B \-T +.Fl T can be specified more than once. You need to specify all the typenames that -appear in your program that are defined by \fBtypedef\fRs \- nothing will be +appear in your program that are defined by +.Ic typedef +\- nothing will be harmed if you miss a few, but the program won't be formatted as nicely as it should. This sounds like a painful thing to have to do, but it's really -a symptom of a problem in C: \fBtypedef\fR causes a syntactic change in the -language and \fIindent\fR can't find all \fBtypedef\fRs. -.TP 15 -.B \-troff +a symptom of a problem in C: +.Ic typedef +causes a syntactic change in the +language and +.Nm indent +can't find all +instances of +.Ic typedef . +.Tp Fl troff Causes -.B indent +.Nm indent to format the program for processing by troff. It will produce a fancy listing in much the same spirit as -.BR vgrind . +.Xr vgrind 1 . If the output file is not specified, the default is standard output, rather than formatting in place. -.TP 15 -.BR \-v , \-nv -.B \-v +.Tp Fl v , nv +.Fl v turns on `verbose' mode; -.B \-nv +.Fl nv turns it off. When in verbose mode, -.I indent +.Nm indent reports when it splits one line of input into two or more lines of output, and gives some size statistics at completion. The default is -.BR \-nv . -.SH "FURTHER DESCRIPTION" -.LP +.Fl nv . +.Tp +.Pp You may set up your own `profile' of defaults to -.I indent +.Nm indent by creating a file called -.BI . indent . pro +.Pa .indent.pro in your login directory and/or the current directory and including whatever switches you like. A `.indent.pro' in the current directory takes precedence over the one in your login directory. If -.I indent +.Nm indent is run and a profile file exists, then it is read to set up the program's defaults. Switches on the command line, though, always override profile switches. The switches should be separated by spaces, tabs or newlines. -.LP -.B Comments -.LP -.IR "`Box' comments" . -.I Indent +.Pp +.Ss Comments +.Sq Em Box +.Em comments . +.Nm Indent assumes that any comment with a dash or star immediately after the start of comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. Each line of such a comment is left unchanged, except that its indentation may be adjusted to account for the change in indentation of the first line of the comment. -.LP -.IR "Straight text" . +.Pp +.Em Straight text . All other comments are treated as straight text. -.I Indent +.Nm Indent fits as many words (separated by blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. -.LP -.B Comment indentation -.LP +.Pp +.Ss Comment indentation If a comment is on a line with code it is started in the `comment column', which is set by the -.BI \-c n +.Cx Fl c +.Ar n +.Cx command line parameter. Otherwise, the comment is started at -.I n +.Ar n indentation levels less than where code is currently being placed, where -.I n +.Ar n is specified by the -.BI \-d n +.Cx Fl d +.Ar n +.Cx command line parameter. If the code on a line extends past the comment column, the comment starts further to the right, and the right margin may be automatically extended in extreme cases. -.LP -.B Preprocessor lines -.LP -In general, \fIindent\fR leaves preprocessor lines alone. The only +.Pp +.Ss Preprocessor lines +In general, +.Nm indent +leaves preprocessor lines alone. The only reformatting that it will do is to straighten up trailing comments. It leaves embedded comments alone. Conditional compilation -(\fB#ifdef...#endif\fR) is recognized and \fIindent\fR attempts to correctly +.Pq Ic #ifdef...#endif +is recognized and +.Nm indent +attempts to correctly compensate for the syntactic peculiarities introduced. -.LP -.B C syntax -.LP -\fIIndent\fR understands a substantial amount about the syntax of C, but it +.Pp +.Ss C syntax +.Nm Indent +understands a substantial amount about the syntax of C, but it has a `forgiving' parser. It attempts to cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros like: -.nf -.ft L - #define forever for(;;) -.ft R -.fi +.Dl #define forever for(;;) is handled properly. -.SH FILES -.DT -.br -\&./.indent.pro profile file -.br -~/.indent.pro profile file -.SH BUGS -.I Indent -has even more switches than \fIls\fR. -.sp +.Sh ENVIRONMENT +.Nm Indent +uses the +.Ev HOME +environment variable. +.Sh FILES +.Dw \&./.indent.pro +.Di L +.Dp \&./.indent.pro +profile file +.Dp ~/.indent.pro +profile file +.Dp +.Sh HISTORY +.Nm Indent +appeared in 4.2 BSD. +.Sh BUGS +.Nm Indent +has even more switches than +.Xr ls 1 . +.Pp .ne 5 A common mistake that often causes grief is typing: -.nf -.ft L - indent *.c -.ft R -.fi -to the shell in an attempt to indent all the \fBC\fR programs in a directory. +.Dl indent *.c +to the shell in an attempt to indent all the +.Nm C +programs in a directory. This is probably a bug, not a feature. diff --git a/usr/src/usr.bin/m4/m4.1 b/usr/src/usr.bin/m4/m4.1 index 81b99f9061..db1e5a80c1 100644 --- a/usr/src/usr.bin/m4/m4.1 +++ b/usr/src/usr.bin/m4/m4.1 @@ -1,321 +1,377 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Ozan Yigit. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)m4.1 6.3 (Berkeley) %G% +.\" @(#)m4.1 6.4 (Berkeley) %G% .\" -.TH M4 1 "August 28, 1989" +.Dd +.Dt M4 1 .DA 08 Jan 1986 -.SH NAME -m4 \- macro processor -.SH SYNOPSIS -.BI m4 "[ options ]" -.SH DESCRIPTION -.I M4 -is a macro processor -intended as a front end for Ratfor, Pascal, and other languages that do not +.Sh NAME +.Nm m4 +.Nd macro language preprocessor for Ratfor and Pascal +.Sh SYNOPSIS +.Nm m4 +.Op options +.Sh DESCRIPTION +.Nm M4 +is a macro language +preprocessor +for Ratfor, Pascal, and similar languages which do not have a built-in macro processing capability. -M4 reads standard input, the processed text is written on the standard output. -.PP +M4 reads standard input, and writes the results to the standard output. +.Pp The options and their effects are as follows: -.TP -\f3\-D\fP\f2name\^\fP[\f3=\fP\f2val\^\fP] +.Pp +.Tp Cx Fl D +.Ar name +.Op Ar \&=Val +.Cx Defines -.I name +.Ar name to -.I val +.Ar val or to null in -.IR val 's -absence. -.TP -.BI \-U name +the absence of +.Ar val . +.Tp Cx Fl U +.Ar name +.Cx undefines -.IR name . -.PP -Macro calls -have the form: -.PP -.RS -\fBname\fI(arg1,arg2, .\|.\|., argn)\fR -.RE -.PP +.Ar name . +.Tp +.Pp The -.B ( -must immediately follow the name of the macro. -If the name of a defined macro is not followed by a -.BR ( , -it is taken to be a call of that macro with no arguments, i.e. name(). -Potential macro names consist of alphabetic letters and digits. -.PP -Leading unquoted blanks, tabs and newlines are ignored while collecting -arguments. -Left and right single quotes are used to quote strings. -The value of a quoted string is the string stripped of the quotes. -.PP -When a macro name is recognized, -its arguments are collected by searching for a matching -.BR ) . -If fewer arguments are supplied than are in the macro definition, -the trailing arguments are taken to be null. -Macro evaluation proceeds normally during the collection of the arguments, -and any commas or right parentheses -which happen to turn up within the value of a nested -call are as effective as those in the original input text. (This is typically -referred as -.I inside-out -macro expansion.) -After argument collection, -the value of the macro is pushed back onto the input stream -and rescanned. -.PP -.I M4 -makes available the following built-in macros. -They may be redefined, but once this is done the original meaning is lost. -Their values are null unless otherwise stated. -.de MC -.TP 14 -.B \\$1 -usage: \\fI\\$1\\$2\\fR -.br -.. -.MC define "(name [, val])" +.Nm m4 +processor provides a kind of +.Nm C +like syntax and +some of the macro functions will +be familiar: +.Tw Ds +.Tp Ic define +usage: +.Ar define(name [, val]) +.br the second argument is installed as the value of the macro whose name is the first argument. If there is no second argument, the value is null. Each occurrence of -.BI $ n +.Cx Ic $ +.Ar n +.Cx in the replacement text, where -.I n +.Ar n is a digit, is replaced by the -.IR n -th +.Cx Ar n +.Cx \'th +.Cx argument. Argument 0 is the name of the macro; missing arguments are replaced by the null string. -.MC defn "(name [, name ...]) +.Tp Ic defn +usage: +.Ar defn(name [, name ...]) +.br returns the quoted definition of its argument(s). Useful in renaming macros. -.MC undefine "(name [, name ...])" +.Tp Ic undefine +usage: +.Ar undefine(name [, name ...]) +.br removes the definition of the macro(s) named. If there is more than one definition for the named macro, (due to previous use of -.IR pushdef ) +.Ic pushdef ) all definitions are removed. -.MC pushdef "(name [, val])" +.Tp Ic pushdef +usage: +.Ar pushdef(name [, val]) +.br like -.IR define , +.Ic define , but saves any previous definition by stacking the current definition. -.MC popdef "(name [, name ...])" +.Tp Ic popdef +usage: +.Ar popdef(name [, name ...]) +.br removes current definition of its argument(s), exposing the previous one if any. -.MC ifdef "(name, if-def [, ifnot-def])" -if the first argument is defined, the value is the second argument, +.Tp Ic ifdef +usage: +.Ar ifdef(name, if-def [, ifnot-def]) +.br +if the first argument is defined, the value is the second argument, otherwise the third. If there is no third argument, the value is null. -.MC shift "(arg, arg, arg, ...)" +.Tp Ic shift +usage: +.Ar shift(arg, arg, arg, ...) +.br returns all but its first argument. The other arguments are quoted and pushed back with commas in between. The quoting nullifies the effect of the extra scan that will subsequently be performed. -.MC changequote "(lqchar, rqchar)" +.Tp Ic changequote +usage: +.Ar changequote(lqchar, rqchar) +.br change quote symbols to the first and second arguments. With no arguments, the quotes are reset back to the default -characters. (i.e., \*`\|\*'). -.MC changecom "(lcchar, rcchar)" +characters. (i.e., \*`\\*'). +.Tp Ic changecom +usage: +.Ar changecom(lcchar, rcchar) +.br change left and right comment markers from the default -.B # -and -.BR newline . -With no arguments, the comment mechanism is reset back to +.Ic # +and +.Ic newline . +With no arguments, the comment mechanism is reset back to the default characters. With one argument, the left marker becomes the argument and the right marker becomes newline. With two arguments, both markers are affected. -.MC divert "(divnum)" -.I m4 +.Tp Ic divert +usage: +.Ar divert(divnum) +.br +.Nm m4 maintains 10 output streams, -numbered 0-9. initially stream 0 is the current stream. +numbered 0-9. initially stream 0 is the current stream. The -.I divert +.Ic divert macro changes the current output stream to its (digit-string) argument. Output diverted to a stream other than 0 through 9 disappears into bitbucket. -.MC undivert "([divnum [, divnum ...]])" +.Tp Ic undivert +usage: +.Ar undivert([divnum [, divnum ...]) +.br causes immediate output of text from diversions named as argument(s), or all diversions if no argument. Text may be undiverted into another diversion. Undiverting discards the diverted text. At the end of input processing, -.I M4 +.Nm M4 forces an automatic -.IR undivert , +.Ic undivert , unless -.I m4wrap +.Ic m4wrap is defined. -.MC divnum "()" +.Tp Ic divnum +usage: +.Ar divnum() +.br returns the value of the current output stream. -.MC dnl "()" +.Tp Ic dnl +usage: +.Ar dnl() +.br reads and discards characters up to and including the next newline. -.MC ifelse "(arg, arg, if-same [, ifnot-same | arg, arg ...])" +.Tp Ic ifelse +usage: +.Ar ifelse(arg, arg, if-same [, ifnot-same \&| arg,\ arg\ ...]) +.br has three or more arguments. If the first argument is the same string as the second, then the value is the third argument. -If not, and if there are more than four arguments, the process is +If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not present, null. -.MC incr "(num)" +.Tp Ic incr +usage: +.Ar incr(num) +.br returns the value of its argument incremented by 1. The value of the argument is calculated by interpreting an initial digit-string as a decimal number. -.MC decr "(num)" +.Tp Ic decr +usage: +.Ar decr(num) +.br returns the value of its argument decremented by 1. -.MC eval "(expression)" +.Tp Ic eval +usage: +.Ar eval(expression) +.br evaluates its argument as a constant expression, using integer arithmetic. The evaluation mechanism is very similar to that of -.I cpp -(#if expression). +.Xr cpp +(#if expression). The expression can involve only integer constants and character constants, possibly connected by the binary operators -.nf -.ft B - -* / % + - >> << < > -<= >= == != & ^ | && || - -.ft R -.fi -or the unary operators \fB\- ~ !\fR -or by the ternary operator \fB ? : \fR. +.Ds I +* / % + - >> << < > +<= >= == != & ^ && +.De +or the unary operators +.Ic \&~ \&! +or by the ternary operator +.Ic \&? \&: . Parentheses may be used for grouping. Octal numbers may be specified as in C. -.MC len "(string)" +.Tp Ic len +usage: +.Ar len(string) +.br returns the number of characters in its argument. -.MC index "(search-string, string)" -returns the position in its first argument where the second argument +.Tp Ic index +usage: +.Ar index(search-string, string) +.br +returns the position in its first argument where the second argument begins (zero origin), or \-1 if the second argument does not occur. -.MC substr "(string, index [, length])" +.Tp Ic substr +usage: +.Ar substr(string, index [, length]) +.br returns a substring of its first argument. The second argument is a zero origin number selecting the first character (internally treated as an expression); the third argument indicates the length of the substring. A missing third argument is taken to be large enough to extend to -the end of the first string. -.MC translit "(source, from [, to])" +the end of the first string. +.Tp Ic translit +usage: +.Ar translit(source, from [, to]) +.br transliterates the characters in its first argument from the set given by the second argument to the set given by the third. If the third argument is shorter than the second, all extra characters in the second argument are deleted from the first argument. If the third argument is missing altogether, all characters in the second argument are deleted from the first argument. -.MC include "(filename)" +.Tp Ic include +usage: +.Ar include(filename) +.br returns the contents of the file named in the argument. -.MC sinclude "(filename)" +.Tp Ic sinclude +usage: +.Ar sinclude(filename) +.br is identical to -.IR include , +.Ic include , except that it says nothing if the file is inaccessible. -.MC paste "(filename)" +.Tp Ic paste +usage: +.Ar paste(filename) +.br returns the contents of the file named in the argument without any -processing, unlike -.IR include. -.MC spaste "(filename)" +processing, unlike +.Ic include . +.Tp Ic spaste +usage: +.Ar spaste(filename) +.br is identical to -.IR paste , +.Ic paste , except that it says nothing if the file is inaccessible. -.MC syscmd "(command)" +.Tp Ic syscmd +usage: +.Ar syscmd(command) +.br executes the -.SM UNIX +UNIX command given in the first argument. No value is returned. -.MC sysval "()" +.Tp Ic sysval +usage: +.Ar sysval() +.br is the return code from the last call to -.IR syscmd . -.MC maketemp "(string)" +.Ic syscmd . +.Tp Ic maketemp +usage: +.Ar maketemp(string) +.br fills in a string of -.SM XXXXXX +XXXXXX in its argument with the current process -.SM ID\*S. -.MC m4exit "([exitcode])" +ID. +.Tp Ic m4exit +usage: +.Ar m4exit([exitcode]) +.br causes immediate exit from -.IR m4 . +.Nm m4 . Argument 1, if given, is the exit code; the default is 0. -.MC m4wrap "(m4-macro-or-built-in)" +.Tp Ic m4wrap +usage: +.Ar m4wrap(m4-macro-or-built-in) +.br argument 1 will be pushed back at final -.BR EOF ; -example: m4wrap(`dumptable()'). -.MC errprint "(str [, str, str, ...])" +.Ic EOF ; +.Dl example: m4wrap(`dumptable()'). +.Tp Ic errprint "(str +usage: +.Ar errprint(str [, str, str, ...]) +.br prints its argument(s) on stderr. If there is more than one argument, each argument is separated by a space during the output. -.MC dumpdef "([name, name, ...])" +.Tp Ic dumpdef +usage: +.Ar dumpdef([name, name, ...]) +.br prints current names and definitions, for the named items, or for all if no arguments are given. -.dt -.SH AUTHOR +.Tp +.Sh AUTHOR Ozan S. Yigit (oz) -.SH BUGS +.Sh BUGS A sufficiently complex M4 macro set is about as readable as -.BR APL . -.PP +.Ar APL . +.Pp All complex uses of M4 require the ability to program in deep recursion. Previous lisp experience is recommended. -.SH EXAMPLES +.Sh EXAMPLES The following macro program illustrates the type of things that -can be done with M4. -.PP -.RS -.nf -\fBchangequote\fR(<,>) \fBdefine\fR(HASHVAL,99) \fBdnl\fR -\fBdefine\fR(hash,<\fBexpr\fR(str(\fBsubstr\fR($1,1),0)%HASHVAL)>) \fBdnl\fR -\fBdefine\fR(str, - <\fBifelse\fR($1,",$2, - ,1),<\fBexpr\fR($2+'\fBsubstr\fR($1,0,1)')>)>) - >) \fBdnl\fR -\fBdefine\fR(KEYWORD,<$1,hash($1),>) \fBdnl\fR -\fBdefine\fR(TSTART, +can be done with M4. +.Pp +.Ds I +changequote(<,>) define(HASHVAL,99) dnl +define(hash,) dnl +define(str, + ,1),)>) + >) dnl +define(KEYWORD,<$1,hash($1),>) dnl +define(TSTART, ) \fBdnl\fR -\fBdefine\fR(TEND,< "",0 -};>) \fBdnl\fR -.fi -.RE -.PP +} keytab[] = {>) dnl +define(TEND,< "",0 +};>) +dnl +.De +.Pp Thus a keyword table containing the keyword string and its pre-calculated hash value may be generated thus: -.PP -.RS -.nf +.Pp +.Ds I TSTART KEYWORD("foo") KEYWORD("bar") KEYWORD("baz") TEND -.fi -.RE -.PP +.De +.Pp which will expand into: -.RS -.nf +.Pp +.Ds I struct prehash { char *keyword; int hashval; @@ -325,20 +381,24 @@ struct prehash { "baz",20, "",0 }; -.fi -.RE -.PP +.De +.Pp Presumably, such a table would speed up the installation of the keywords into a dynamic hash table. (Note that the above macro -cannot be used with -.IR M4 , -since -.B eval +cannot be used with +.Nm m4 , +since +.Ic eval does not handle character constants.) -.SH SEE ALSO -cc(1), -cpp(1). -m4(1), -.I "The M4 Macro Processor\^" +.Sh SEE ALSO +.Xr cc 1 , +.Xr cpp 1 . +.Xr m4 1 , +.Em The M4 Macro Processor by B. W. Kernighan and D. M. Ritchie. - +.Sh HISTORY +.Nm M4 +command appeared in Version 7 AT&T UNIX. The +.Nm m4 +command this page describes is derived from code +contributed by Ozan S. Yigit. diff --git a/usr/src/usr.bin/mail/mail.1 b/usr/src/usr.bin/mail/mail.1 index 7b3d07729a..e0bf5bb5e7 100644 --- a/usr/src/usr.bin/mail/mail.1 +++ b/usr/src/usr.bin/mail/mail.1 @@ -1,255 +1,271 @@ -.\" Copyright (c) 1980 Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)mail.1 6.13 (Berkeley) %G% +.\" @(#)mail.1 6.14 (Berkeley) %G% .\" -.TH MAIL 1 "" -.UC 4 -.SH NAME -mail \- send and receive mail -.SH SYNOPSIS -.B mail -[ -.B \-iInv -] -[ -.B \-s -subject -] -[ -.B \-c -cc-addr -] -[ -.B \-b -bcc-addr -] -to-addr... +.Dd +.Dt MAIL 1 +.Os BSD 4 +.Sh NAME +.Nm mail +.Nd send and receive mail +.Sh SYNOPSIS +.Nm mail +.Op Fl iInv +.Op Fl s Ar subject +.Op Fl c Ar cc-addr +.Op Fl b Ar bcc-addr +.Ar to-addr... .br -.B mail -[ -.B \-iInNv -] -.B \-f -[ -name -] +.Nm mail +.Op Fl iInNv +.Fl f +.Op Ar name .br -.B mail -[ -.B \-iInNv -] -[ -.B \-u -user -] -.SH INTRODUCTION -.I Mail +.Nm mail +.Op Fl iInNv +.Op Fl u Ar user +.Sh INTRODUCTION +.Nm Mail is a intelligent mail processing system, which has a command syntax reminiscent of -.I ed +.Xr ed 1 with lines replaced by messages. -.PP -The -.B \-v -flag puts mail into verbose mode; the details of +.Pp +.Tp Fl v +Verbose mode. The details of delivery are displayed on the users terminal. -The -.B \-i -flag causes tty interrupt signals to be ignored. This is +.Tp Fl i +Ignore tty interrupt signals. This is particularly useful when using -.I mail +.Nm mail on noisy phone lines. -The -.B \-I -flag forces mail to run in interactive mode even when -input isn't a terminal. In particular, the `~' special +.Tp Fl I +Forces mail to run in interactive mode even when +input isn't a terminal. In particular, the +.Sq Ic \&~ +special character when sending mail is only active in interactive mode. -The -.B \-n -flag inhibits the reading of /usr/lib/Mail.rc. -The -.B \-N -flag inhibits the initial display of message headers +.Tp Fl n +Inhibits reading /usr/share/misc/Mail.rc upon startup. +.Tp Fl N +Inhibits the initial display of message headers when reading mail or editing a mail folder. -.PP -.I "Sending mail.\ " +.Tp Fl s +Specify subject on command line +(only the first argument after the +Fl s +flag is used as a subject; be careful to quote subjects +containing spaces.) +.Tp Fl c +Send carbon copies to +.Ar list +of users. +.Tp Fl b +Send blind carbon copies to +.Ar list . +List should be a comma-separated list of names. +.Tp Fl f +Read in the contents of your +.Ar mbox +(or the specified file) +for processing; when you +.Ar quit , +.Nm mail +writes undeleted messages back to this file. +.Tp Fl u +Is equivalent to: +.Dl mail -f /usr/spool/mail/user +.Tp +.Ss Sending mail To send a message to one or more people, -.I mail -can be invoked with arguments which are the names of people to -whom the mail will be sent. You are then expected to type in +.Nm mail +can be invoked with arguments which are the names of people to +whom the mail will be sent. You are then expected to type in your message, followed -by an \s-2EOT\s0 (control\-D) at the beginning of a line. -A subject may be specified on the command line by using the -.B \-s -flag. (Only the first argument after the -.B \-s -flag is used as a subject; be careful to quote subjects -containing spaces.) Lists of users to send carbon copies and -blind carbon copies to may be specified using the -.B \-c -and -.B \-b -options, respectively. The single argument following the -flag is taken to be a comma-separated list of names. -The section below, labeled -.I "Replying to or originating mail," +by an +.Sq Li control\-D +at the beginning of a line. +The section below +.Ar Replying to or originating mail , describes some features of -.I mail +.Nm mail available to help you compose your letter. -.PP -.I "Reading mail.\ " +.Pp +.Ss Reading mail In normal usage -.I mail +.Nm mail is given no arguments and checks your mail out of the post office, then prints out a one line header of each message there. The current message is initially the first message (numbered 1) and can be printed using the -.B print -command (which can be abbreviated \fBp\fR). +.Ic print +command (which can be abbreviated +.Cx \&( +.Ic p +.Cx \&)). +.Cx You can move among the messages much as you move between lines in -.IR ed , -with the commands `+' and `\-' moving backwards and forwards, and +.Xr ed 1 , +with the commands +.Sq Ic \&+ +and +.Sq Ic \&\- +moving backwards and forwards, and simple numbers. -.PP -.I "Disposing of mail.\ " +.Pp +.Ss Disposing of mail. After examining a message you can -.B delete -(\fBd\fR) +.Ic delete +.Cx \&( +.Ic d +.Cx \&) +.Cx the message or -.B reply -(\fBr\fR) +.Ic reply +.Cx \&( +.Ic r +.Cx \&) +.Cx to it. Deletion causes the -.I mail +.Nm mail program to forget about the message. This is not irreversible; the message can be -.B undeleted -(\fBu\fR) +.Ic undeleted +.Cx \&( +.Ic u +.Cx \&) +.Cx by giving its number, or the -.I mail +.Nm mail session can be aborted by giving the -.B exit -(\fBx\fR) +.Ic exit +.Cx \&( +.Ic x +.Cx \&) +.Cx command. Deleted messages will, however, usually disappear never to be seen again. -.PP -.I "Specifying messages.\ " +.Pp +.Ss Specifying messages Commands such as -.B print +.Ic print and -.B delete +.Ic delete can be given a list of message numbers as arguments to apply to a number of messages at once. -Thus ``delete 1 2'' deletes messages 1 and 2, while ``delete 1\-5'' +Thus +.Dq Li delete 1 2 +deletes messages 1 and 2, while +.Dq Li delete 1\-5 deletes messages 1 through 5. -The special name ``*'' addresses all messages, and ``$'' addresses +The special name +.Sq Li \&* +addresses all messages, and +.Sq Li \&$ +addresses the last message; thus the command -.B top +.Ic top which prints the first few lines of a message could be used in -``top *'' to print the first few lines of all messages. -.PP -.I "Replying to or originating mail.\ " +.Dq Li top \&* +to print the first few lines of all messages. +.Pp +.Ss Replying to or originating mail. You can use the -.B reply +.Ic reply command to set up a response to a message, sending it back to the person who it was from. Text you then type in, up to an end-of-file, defines the contents of the message. While you are composing a message, -.I mail -treats lines beginning with the character `~' specially. -For instance, typing ``~m'' (alone on a line) will place a copy +.Nm mail +treats lines beginning with the character +.Sq Ic \&~ +specially. +For instance, typing +.Sq Ic \&~m +(alone on a line) will place a copy of the current message into the response right shifting it by a tabstop -(see ``indentprefix'' variable, below). +(see +.Em indentprefix +variable, below). Other escapes will set up subject fields, add and delete recipients to the message and allow you to escape to an editor to revise the message or to a shell to run some commands. (These options are given in the summary below.) -.PP -.I "Ending a mail processing session.\ " +.Pp +.Ss Ending a mail processing session. You can end a -.I mail +.Nm mail session with the -.B quit -(\fBq\fR) +.Ic quit +.Cx \&( +.Ic q +.Cx \&) +.Cx command. Messages which have been examined go to your -.I mbox +.Ar mbox file unless they have been deleted in which case they are discarded. -Unexamined messages go back to the post office. -The -.B \-f -option causes -.I mail -to read in the contents of your -.I mbox -(or the specified file) -for processing; when you -.BR quit , -.I mail -writes undeleted messages back to this file. -The -.B \-u -flag is a short way of doing -"mail -.B \-f -/usr/spool/mail/user". -.PP -.I "Personal and systemwide distribution lists.\ " +Unexamined messages go back to the post office. (See the +.Fl f +option above). +.Pp +.Ss Personal and systemwide distribution lists. It is also possible to create a personal distribution lists so that, -for instance, you can send mail to ``cohorts'' and have it go +for instance, you can send mail to +.Dq Li cohorts +and have it go to a group of people. Such lists can be defined by placing a line like -.IP -alias cohorts bill ozalp jkf mark kridle@ucbcory -.PP -in the file \&.mailrc in your home directory. +.Pp +.Dl alias cohorts bill ozalp jkf mark kridle@ucbcory +.Pp +in the file +.Pa \&.mailrc +in your home directory. The current list of such aliases can be displayed with the -.B alias -.B (a) +.Ic alias command in -.IR mail . +.Nm mail . System wide distribution lists can be created by editing /usr/lib/aliases, see -.IR aliases (5) +.Xr aliases 5 and -.IR sendmail (8); +.Xr sendmail 8 ; these are kept in a different syntax. In mail you send, personal aliases will be expanded in mail sent -to others so that they will be able to \fBreply\fR to the recipients. -System wide \fIaliases\fR are not expanded when the mail is sent, +to others so that they will be able to +.Ic reply +to the recipients. +System wide +.Ic aliases +are not expanded when the mail is sent, but any reply returned to the machine will have the system wide alias expanded as all mail goes through -.IR sendmail . -.PP -.I "Network mail (ARPA, UUCP, Berknet)\ " +.Xr sendmail . +.Pp +.Ss Network mail (ARPA, UUCP, Berknet) See -.IR mailaddr(7) +.Xr mailaddr 7 for a description of network addresses. -.PP -.I Mail +.Pp +.Nm Mail has a number of options which can be set in the -.I \&.mailrc -file to alter its behavior; thus ``set askcc'' enables the ``askcc'' +.Pa \& .mailrc +file to alter its behavior; thus +.Dq Li set askcc +enables the +.Ar askcc feature. (These options are summarized below.) -.SH SUMMARY +.Sh SUMMARY (Adapted from the `Mail Reference Manual') -.PP +.Pp Each command is typed on a line by itself, and may take arguments following the command word. The command need not be typed in its entirety \- the first command which matches the typed prefix is used. @@ -258,118 +274,154 @@ list is given, then the next message forward which satisfies the command's requirements is used. If there are no messages forward of the current message, the search proceeds backwards, and if there are no good messages at all, -.I mail -types ``No applicable messages'' and +.Nm mail +types +.Dq Li No applicable messages +and aborts the command. -.TP 12n -.B \- -Goes to the previous message and prints it out. If given a numeric +.Tp Ic \&\- +Print out the preceding message. If given a numeric argument -.IR n , +.Ar n , goes to the -.IR n -th +.Cx Ar n +.Cx \'th +.Cx previous message and prints it. -.TP -.B ? +.Tp Ic \&? Prints a brief summary of commands. -.TP -.B ! -Executes the \s-2UNIX\s0 shell command which follows. -.TP -.B Print -(\fBP\fR) +.Tp Ic \&! +Executes the shell +(see +.Xr sh 1 +and +.Xr csh 1 ) +command which follows. +.Tp Ic Print +.Cx \&( +.Ic P +.Cx \&) +.Cx Like -.B print +.Ic print but also prints out ignored header fields. See also -.B print -, -.B ignore +.Ic print , +.Ic ignore and -.B retain. -.TP -.B Reply -(\fBR\fR) +.Ic retain . +.Tp Ic Reply +.Cx \&( +.Ic R +.Cx \&) +.Cx Reply to originator. Does not reply to other recipients of the original message. -.TP -.B Type -(\fBT\fR) +.Tp Ic Type +.Cx \&( +.Ic T +.Cx \&) +.Cx Identical to the -.B Print +.Ic Print command. -.TP -.B alias -(\fBa\fR) With no arguments, prints out all currently-defined aliases. With one +.Tp Ic alias +.Cx \&( +.Ic a +.Cx \&) +.Cx +With no arguments, prints out all currently-defined aliases. With one argument, prints out that alias. With more than one argument, creates a new alias or changes an old one. -.TP -.B alternates -(\fBalt\fR) +.Tp Ic alternates +.Cx \&( +.Ic alt +.Cx \&) +.Cx The -.B alternates +.Ic alternates command is useful if you have accounts on several machines. It can be used to inform -.I mail +.Nm mail that the listed addresses are really you. When you -.B reply +.Ic reply to messages, -.I mail +.Nm mail will not send a copy of the message to any of the addresses listed on the -.I alternates +.Ic alternates list. If the -.B alternates +.Ic alternates command is given with no argument, the current set of alternate names is displayed. -.TP -.B chdir -(\fBc\fR) Changes the user's working directory to that specified, if given. If +.Tp Ic chdir +.Cx \&( +.Ic c +.Cx \&) +.Cx +Changes the user's working directory to that specified, if given. If no directory is given, then changes to the user's login directory. -.TP -.B copy -(\fBco\fR) +.Tp Ic copy +.Cx \&( +.Ic co +.Cx \&) +.Cx The -.B copy +.Ic copy command does the same thing that -.B save +.Ic save does, except that it does not mark the messages it is used on for deletion when you quit. -.TP -.B delete -(\fBd\fR) Takes a list of messages as argument and marks them all as deleted. +.Tp Ic delete +.Cx \&( +.Ic d +.Cx \&) +.Cx +Takes a list of messages as argument and marks them all as deleted. Deleted messages will not be saved in -.IR mbox , -nor will they be available for most other commands. -.TP -.B dp -(also \fBdt\fR) Deletes the current message and prints the next message. -If there is no next message, -.I mail -says ``at EOF.'' -.TP -.B edit -(\fBe\fR) Takes a list of messages and points the text editor at each one in +.Ar mbox , +nor will they be available for most other commands. +.Tp Ic dp +(also +.Ic dt ) +Deletes the current message and prints the next message. +If there is no next message, +.Nm mail +says +.Dq Li at EOF. +.Tp Ic edit +.Cx \&( +.Ic e +.Cx \&) +.Cx +Takes a list of messages and points the text editor at each one in turn. On return from the editor, the message is read back in. -.TP -.B exit -(\fBex\fR or \fBx\fR) Effects an immediate return to the Shell without +.Tp Ic exit +.Cx \&( +.Ic ex +.Cx +or +.Ic x ) +Effects an immediate return to the Shell without modifying the user's system mailbox, his -.I mbox +.Ar mbox file, or his edit file in -.BR \-f . -.TP -.B file -(\fBfi\fR) +.Fl f . +.Tp Ic file +.Cx \&( +.Ic fi +.Cx ) +.Cx The same as -.BR folder . -.TP -.B folders +.Ic folder . +.Tp Ic folders List the names of the folders in your folder directory. -.TP -.B folder -(\fBfo\fR) +.Tp Ic folder +.Cx \&( +.Ic fo +.Cx \&) +.Cx The -.B folder +.Ic folder command switches to a new mail file or folder. With no arguments, it tells you which file you are currently reading. If you give it an argument, it will write out changes (such @@ -377,527 +429,648 @@ as deletions) you have made in the current file and read in the new file. Some special conventions are recognized for the name. # means the previous file, % means your system mailbox, %user means user's system mailbox, & means -your \fImbox\fP file, and +folder means a file in your folder +your +.Ar mbox +file, and +folder means a file in your folder directory. -.TP -.B from -(\fBf\fR) Takes a list of messages and prints their message headers. -.TP -.B headers -(\fBh\fR) Lists the current range of headers, which is an 18\-message group. If -a ``+'' argument is given, then the next 18\-message group is printed, and if -a ``\-'' argument is given, the previous 18\-message group is printed. -.TP -.B help -A synonym for ? -.TP -.B hold -(\fBho\fR, also \fBpreserve\fR) Takes a message list and marks each +.Tp Ic from +.Cx \&( +.Ic f +.Cx \&) +.Cx +Takes a list of messages and prints their message headers. +.Tp Ic headers +.Cx \&( +.Ic h +.Cx \&) +.Cx +Lists the current range of headers, which is an 18\-message group. If +a +.Sq Li \&+ +argument is given, then the next 18\-message group is printed, and if +a +.Sq Li \&\- +argument is given, the previous 18\-message group is printed. +.Tp Ic help +A synonym for +.Ic \&? +.Tp Ic hold +.Cx \&( +.Ic ho , +.Cx +also +.Ic preserve ) +Takes a message list and marks each message therein to be saved in the user's system mailbox instead of in -.IR mbox . +.Ar mbox . Does not override the -.B delete +.Ic delete command. -.TP -.B ignore -.B N.B.: -.I Ignore +.Tp Ic ignore +.Sy N.B.: +.Ic Ignore has been superseded by -.I retain. +.Ic retain . .br Add the list of header fields named to the -.IR "ignored list" . +.Ar ignored list Header fields in the ignore list are not printed on your terminal when you print a message. This command is very handy for suppression of certain machine-generated header fields. The -.B Type +.Ic Type and -.B Print +.Ic Print commands can be used to print a message in its entirety, including ignored fields. If -.B ignore +.Ic ignore is executed with no arguments, it lists the current set of ignored fields. -.TP -.B mail -(\fBm\fR) Takes as argument login names and distribution group names and sends +.Tp Ic mail +.Cx \&( +.Ic m +.Cx \&) +.Cx +Takes as argument login names and distribution group names and sends mail to those people. -.TP -.B mbox +.Tp Ic mbox Indicate that a list of messages be sent to -.I mbox +.Ic mbox in your home directory when you quit. This is the default action for messages if you do -.I not +.Em not have the -.I hold +.Ic hold option set. -.TP -.B next -(\fBn\fR like \fB+\fR or CR) Goes to the next message in sequence and types it. +.Tp Ic next +.Cx \&( +.Ic n +.Cx +like +.Ic \&+ +or CR) Goes to the next message in sequence and types it. With an argument list, types the next matching message. -.TP -.B preserve -(\fBpre\fR) +.Tp Ic preserve +.Cx \&( +.Ic pre +.Cx \&) +.Cx A synonym for -.BR hold . -.TP -.B print -(\fBp\fR) +.Ic hold . +.Tp Ic print +.Cx \&( +.Ic p +.Cx \&) +.Cx Takes a message list and types out each message on the user's terminal. -.TP -.B quit -(\fBq\fR) Terminates the session, saving all undeleted, unsaved messages in +.Tp Ic quit +.Cx \&( +.Ic q +.Cx \&) +.Cx +Terminates the session, saving all undeleted, unsaved messages in the user's -.I mbox +.Ar mbox file in his login directory, preserving all messages marked with -.B hold +.Ic hold or -.B preserve +.Ic preserve or never referenced in his system mailbox, and removing all other messages from his system mailbox. If new mail has arrived during the session, the message -``You have new mail'' is given. If given while editing a +.Dq LI You have new mail +is given. If given while editing a mailbox file with the -.B \-f +.Fl f flag, then the edit file is rewritten. A return to the Shell is effected, unless the rewrite of edit file fails, in which case the user can escape with the -.B exit +.Ic exit command. -.TP -.B reply -(\fBr\fR) +.Tp Ic reply +.Cx \&( +.Ic r +.Cx \&) +.Cx Takes a message list and sends mail to the sender and all recipients of the specified message. The default message must not be deleted. -.TP -.B respond +.Tp Ic respond A synonym for -.BR reply . -.TP -.B retain +.Ic reply . +.Tp Ic retain Add the list of header fields named to the -.IR "retained list" . +.Ar retained list Only the header fields in the retain list are shown on your terminal when you print a message. All other header fields are suppressed. The -.B Type +.Ic Type and -.B Print +.Ic Print commands can be used to print a message in its entirety. If -.B retain +.Ic retain is executed with no arguments, it lists the current set of retained fields. -.TP -.B save -(\fBs\fR) Takes a message list and a filename and appends each message in +.Tp Ic save +.Cx \&( +.Ic s +.Cx \&) +.Cx +Takes a message list and a filename and appends each message in turn to the end of the file. The filename in quotes, followed by the line -count and character count is echoed on the user's terminal. -.TP -.B set -(\fBse\fR) With no arguments, prints all variable values. Otherwise, sets +count and character count is echoed on the user's terminal. +.Tp Ic set +.Cx \&( +.Ic se +.Cx \&) +.Cx +With no arguments, prints all variable values. Otherwise, sets option. Arguments are of the form -``option=value'' +.Ar option=value (no space before or after =) or -``option.'' +.Ar option . Quotation marks may be placed around any part of the assignment statement to -quote blanks or tabs, i.e. ``set indentprefix="-> "''. -.TP -.B saveignore -\fBSaveignore\fP is to \fBsave\fP what \fBignore\fP is to \fBprint\fP -and \fBtype\fP. Header fields thus marked are filtered out when -saving a message by \fBsave\fP or when automatically saving to \fImbox\fP. -.TP -.B saveretain -\fBSaveretain\fP is to \fBsave\fP what \fBretain\fP is to \fBprint\fP -and \fBtype\fP. Header fields thus marked are the only ones saved -with a message when saving by \fBsave\fP or when automatically saving to -\fImbox\fP. -\fBSaveretain\fP overrides \fBsaveignore\fP. -.TP -.B shell -(\fBsh\fR) Invokes an interactive version of the shell. -.TP -.B size +quote blanks or tabs, i.e. +.Dq Li set indentprefix=\*(Lq \*(Rq +.Tp Ic saveignore +.Ic Saveignore +is to +.Ic save +what +.Ic ignore +is to +.Ic print +and +.Ic type . +Header fields thus marked are filtered out when +saving a message by +.Ic save +or when automatically saving to +.Ar mbox . +.Tp Ic saveretain +.Ic Saveretain +is to +.Ic save +what +.Ic retain +is to +.Ic print +and +.Ic type . +Header fields thus marked are the only ones saved +with a message when saving by +.Ic save +or when automatically saving to +.Ar mbox . +.Ic Saveretain +overrides +.Ic saveignore . +.Tp Ic shell +.Cx \&( +.Ic sh +.Cx \&) +.Cx +Invokes an interactive version of the shell. +.Tp Ic size Takes a message list and prints out the size in characters of each message. -.TP -.B source -(\fBso\fR) +.Tp Ic source +.Cx \&( +.Ic so +.Cx \&) The -.B source +.Ic source command reads -.I mail +.Nm mail commands from a file. -.TP -.B top +.Tp Ic top Takes a message list and prints the top few lines of each. The number of lines printed is controlled by the variable -.B toplines +.Ic toplines and defaults to five. -.TP -.B type -(\fBt\fR) A synonym for -.BR print . -.TP -.B unalias +.Tp Ic type +.Cx \&( +.Ic t +.Cx \&) +.Cx +A synonym for +.Ic print . +.Tp Ic unalias Takes a list of names defined by -.B alias +.Ic alias commands and discards the remembered groups of users. The group names no longer have any significance. -.TP -.B undelete -(\fBu\fR) Takes a message list and marks each message as -.I not +.Tp Ic undelete +.Cx \&( +.Ic u +.Cx \&) +.Cx +Takes a message list and marks each message as +.Ic not being deleted. -.TP -.B unread -(\fBU\fR) Takes a message list and marks each message as -.I not +.Tp Ic unread +.Cx \&( +.Ic U +.Cx \&) +.Cx +Takes a message list and marks each message as +.Ic not having been read. -.TP -.B unset +.Tp Ic unset Takes a list of option names and discards their remembered values; the inverse of -.BR set . -.TP -.B visual -(\fBv\fR) Takes a message list and invokes the display editor on each message. -.TP -.B write -(\fBw\fR) Similar to -.BR save , +.Ic set . +.Tp Ic visual +.Cx \&( +.Ic v +.Cx \&) +.Cx +Takes a message list and invokes the display editor on each message. +.Tp Ic write +.Cx \&( +.Ic w +.Cx \&) +.Cx +Similar to +.Ic save , except that -.I only -the message body (\fIwithout\fP the header) is saved. +.Ic only +the message body +.Cx \&( +.Ar without +.Cx +the header) is saved. Extremely useful for such tasks as sending and receiving source program text over the message system. -.TP -.B xit -(\fBx\fR) A synonym for -.BR exit . -.TP -.B z -.I Mail +.Tp Ic xit +.Cx \&( +.Ic x +.Cx \&) +.Cx +A synonym for +.Ic exit . +.Tp Ic z +.Nm Mail presents message headers in windowfuls as described under the -.B headers +.Ic headers command. You can move -.IR mail 's +.Cx Nm mail +.Cx 's +.Cx attention forward to the next window with the -.B z +.Ic \&z command. Also, you can move to the previous window by using -.BR z\- . -.PP +.Ic \&z\&\- . +.Tp +.Ss Tilde/Escapes +.Pp Here is a summary of the tilde escapes, which are used when composing messages to perform special functions. Tilde escapes are only recognized at the beginning of lines. The name -``tilde\ escape'' +.Dq Em tilde\ escape is somewhat of a misnomer since the actual escape character can be set by the option -.B escape. -.TP 12n -.BR ~! command +.Ic escape . +.Tw Ds +.Tp Cx Ic \&~! +.Ar command +.Cx Execute the indicated shell command, then return to the message. -.TP -\fB~b\fR name ... +.Tp Cx Ic \&~b +.Ar name ... +.Cx Add the given names to the list of carbon copy recipients but do not make the names visible in the Cc: line ("blind" carbon copy). -.TP -\fB~c\fR name ... +.Tp Cx Ic \&~c +.Ar name ... +.Cx Add the given names to the list of carbon copy recipients. -.TP -.B ~d -Read the file ``dead.letter'' from your home directory into the message. -.TP -.B ~e +.Tp Ic \&~d +Read the file +.Dq Pa dead.letter +from your home directory into the message. +.Tp Ic \&~e Invoke the text editor on the message collected so far. After the editing session is finished, you may continue appending text to the message. -.TP -\fB~f\fR messages +.Tp Cx Ic \&~f +.Ar messages +.Cx Read the named messages into the message being sent. If no messages are specified, read in the current message. -Message headers currently being ignored (by the \fIignore\fP or \fIretain\fP +Message headers currently being ignored (by the +.Ic ignore +or +.Ic retain command) are not included. -.TP -\fB~F\fR messages -Identical to \fB~f\fP, except all message headers are included. -.TP -.B ~h +.Tp Cx Ic \&~F +.Ar messages +.Cx +Identical to +Ic \&~f , +except all message headers are included. +.Tp Ic \&~h Edit the message header fields by typing each one in turn and allowing the user to append text to the end or modify the field by using the current terminal erase and kill characters. -.TP -\fB~m\fR messages +.Tp Cx Ic \&~m +.Ar messages +.Cx Read the named messages into the message being sent, indented by a -tab or by the value of \fIindentprefix\fP. If no messages are specified, +tab or by the value of +.Ar indentprefix . +If no messages are specified, read the current message. -Message headers currently being ignored (by the \fIignore\fP or \fIretain\fP +Message headers currently being ignored (by the +.Ic ignore +or +.Ic retain command) are not included. -.TP -\fB~M\fR messages -Identical to \fB~m\fP, except all message headers are included. -.TP -.B ~p +.Tp Cx Ic \&~M +.Ar messages +.Cx +Identical to +.Ic \&~m , +except all message headers are included. +.Tp Ic \&~p Print out the message collected so far, prefaced by the message header fields. -.TP -.B ~q +.Tp Ic \&~q Abort the message being sent, copying the message to -``dead.letter'' +.Dq Pa dead.letter in your home directory if -.B save +.Ic save is set. -.TP -\fB~r\fR filename +.Tp Cx Ic \&~r +.Ar filename +.Cx Read the named file into the message. -.TP -\fB~s\fR string +.Tp Ic \&~s +string Cause the named string to become the current subject field. -.TP -\fB~t\fR name ... +.Tp Cx Ic \&~\&t +.Ar name ... +.Cx Add the given names to the direct recipient list. -.TP -.B ~v +.\" This .br should have to be here +.br +.Tp Ic \&~\&v Invoke an alternate editor (defined by the VISUAL option) on the message collected so far. Usually, the alternate editor will be a screen editor. After you quit the editor, you may resume appending text to the end of your message. -.TP -\fB~w\fR filename +.Tp Cx Ic \&~w +.Ar filename +.Cx Write the message onto the named file. -.TP -\fB~\||\|\fRcommand +.Tp Cx Ic \&~\\ +.Ar command +.Cx Pipe the message through the command as a filter. If the command gives no output or terminates abnormally, retain the original text of the message. The command -.IR fmt (1) +.Xr fmt 1 is often used as -.I command +.Ic command to rejustify the message. -.TP -\fB~:\fR mail-command +.Tp Cx Ic \&~: +.Ar mail-command +.Cx Execute the given mail command. Not all commands, however, are allowed. -.TP -.BR ~~ string +.Tp Cx Ic \&~~ +.Ar string +.Cx Insert the string of text in the message prefaced by a single ~. If you have changed the escape character, then you should double that character in order to send it. -.PP -Options are controlled via the -.B set +.Tp +.Ss Mail Options +Options are controlled via +.Ic set and -.B unset +.Ic unset commands. Options may be either binary, in which case it is only significant to see whether they are set or not; or string, in which case the actual value is of interest. The binary options include the following: -.TP 15n -.B append +.Tp Ar append Causes messages saved in -.I mbox +.Ar mbox to be appended to the end rather than prepended. This should always be set (perhaps in /usr/lib/Mail.rc). -.TP -.B ask +.Tp Ar ask Causes -.I mail +.Nm mail to prompt you for the subject of each message you send. If you respond with simply a newline, no subject field will be sent. -.TP -.B askcc +.Tp Ar askcc Causes you to be prompted for additional carbon copy recipients at the end of each message. Responding with a newline indicates your satisfaction with the current list. -.TP -.B autoprint +.Tp Ar autoprint Causes the -.B delete +.Ic delete command to behave like -.B dp +.Ic dp \- thus, after deleting a message, the next one will be typed automatically. -.TP -.B debug +.Tp Ar debug Setting the binary option -.I debug +.Ar debug is the same as specifying -.B \-d +.Fl d on the command line and causes -.I mail +.Nm mail to output all sorts of information useful for debugging -.IR mail . -.TP -.B dot +.Nm mail . +.Tp Ar dot The binary option -.I dot +.Ar dot causes -.I mail +.Nm mail to interpret a period alone on a line as the terminator of a message you are sending. -.TP -.B hold +.Tp Ar hold This option is used to hold messages in the system mailbox by default. -.TP -.B ignore +.Tp Ar ignore Causes interrupt signals from your terminal to be ignored and echoed as @'s. -.TP -.B ignoreeof +.Tp Ar ignoreeof An option related to -.I dot +.Ar dot is -.I ignoreeof +.Ar ignoreeof which makes -.I mail +.Nm mail refuse to accept a control-d as the end of a message. -.I Ignoreeof +.Ar Ignoreeof also applies to -.I mail +.Nm mail command mode. -.TP -.B metoo +.Tp Ar metoo Usually, when a group is expanded that contains the sender, the sender is removed from the expansion. Setting this option causes the sender to be included in the group. -.TP -.B noheader +.Tp Ar noheader Setting the option -.I noheader +.Ar noheader is the same as giving the -.B \-N +.Fl N flag on the command line. -.TP -.B nosave -Normally, when you abort a message with two \s-2RUBOUT\s0, -.I mail -copies the partial letter to the file ``dead.letter'' +.Tp Ar nosave +Normally, when you abort a message with two +.Li RUBOUT +(erase or delete) +.Nm mail +copies the partial letter to the file +.Dq Pa dead.letter in your home directory. Setting the binary option -.I nosave +.Ar nosave prevents this. -.TP -.B Replyall +.Tp Ar Replyall Reverses the sense of -.I reply +.Ic reply and -.I Reply +.Ic Reply commands. -.TP -.B quiet +.Tp Ar quiet Suppresses the printing of the version when first invoked. -.TP -.B verbose +.Tp Ar verbose Setting the option -.I verbose +.Ar verbose is the same as using the -.B \-v +.Fl v flag on the command line. When mail runs in verbose mode, the actual delivery of messages is displayed on he users terminal. -.PP -The following options have string values: -.TP 15n -EDITOR +.Tp +.Ss Option String Values +.Tw Va +.Tp Va EDITOR Pathname of the text editor to use in the -.B edit -command and ~e escape. If not defined, then a default editor is used. -.TP -LISTER +.Ic edit +command and +.Ic \&~e +escape. If not defined, then a default editor is used. +.Tp Va LISTER Pathname of the directory lister to use in the -.B folders -command. Default is /bin/ls. -.TP -PAGER +.Ic folders +command. Default is +.Pa /bin/ls . +.Tp Va PAGER Pathname of the program to use in the -.B more +.Ic more command or when -.I crt +.Ic crt variable is set. The default paginator -.I more(1) +.Xr more 1 is used if this option is not defined. -.TP -SHELL +.Tp Va SHELL Pathname of the shell to use in the -.B ! -command and the ~! escape. A default shell is used if this option is +.Ic \&! +command and the +.Ic \&~! +escape. A default shell is used if this option is not defined. -.TP -VISUAL +.Tp Va VISUAL Pathname of the text editor to use in the -.B visual -command and ~v escape. -.TP -.B crt +.Ic visual +command and +.Ic \&~v +escape. +.Tp Va crt The valued option -.I crt +.Va crt is used as a threshold to determine how long a message must be before -.B PAGER -is used to read it. If \fIcrt\fP is set without a value, +.Va PAGER +is used to read it. If +.Va crt +is set without a value, then the height of the terminal screen stored in the system -is used to compute the threshold (see \fIstty(1)\fP). -.TP -.B escape +is used to compute the threshold (see +.Xr stty 1 ) . +.Tp Ar escape If defined, the first character of this option gives the character to use in the place of ~ to denote escapes. -.TP -.B folder +.Tp Ar folder The name of the directory to use for storing folders of messages. If this name begins with a `/', -.I mail +.Nm mail considers it to be an absolute pathname; otherwise, the folder directory is found relative to your home directory. -.TP -.B MBOX -The name of the \fImbox\fP file. It can be the name of a folder. -The default is ``mbox'' in the user's home directory. -.TP -.B record +.Tp Ar MBOX +The name of the +.Ar mbox +file. It can be the name of a folder. +The default is +.Dq Li mbox +in the user's home directory. +.Tp Ar record If defined, gives the pathname of the file used to record all outgoing mail. If not defined, then outgoing mail is not so saved. -.TP -.B indentprefix +.Tp Ar indentprefix String used by the ``~m'' tilde escape for indenting messages, in place of the normal tab character (^I). Be sure to quote the value if it contains spaces or tabs. -.TP -.B toplines +.Tp Ar toplines If defined, gives the number of lines of a message to be printed out with the -.B top +.Ic top command; normally, the first five lines are printed. -.SH FILES -.if n .ta 2.5i -.if t .ta 1.8i -/usr/spool/mail/* post office -.br -~/mbox your old mail -.br -~/.mailrc file giving initial mail commands -.br -/tmp/R* temporary files -.br -/usr/lib/Mail.help* help files -.br -/usr/lib/Mail.rc system initialization file -.SH "SEE ALSO" -binmail(1), fmt(1), newaliases(1), vacation(1), aliases(5), -mailaddr(7), sendmail(8) -.br -`The Mail Reference Manual' -.SH BUGS +.Tp +.Sh ENVIRONMENT +.Nm Mail +utilizes the +.Ev HOME +and +.Ev USER +environment variables. +.Sh FILES +.Dw /usr/share/misc/Mail.help* +.Di L +.Dp Pa /var/spool/mail/* +post office +.Dp ~/mbox +your old mail +.Dp ~/.mailrc +file giving initial mail commands +.Dp Pa /tmp/R* +temporary files +.Dp Pa /usr/share/misc/Mail.help* +help files +.Dp Pa /usr/share/misc/Mail.rc +system initialization file +.Dp +.Sh SEE ALSO +.Xr binmail 1 , +.Xr fmt 1 , +.Xr newaliases 1 , +.Xr vacation 1 , +.Xr aliases 5 , +.Xr mailaddr 7 , +.Xr sendmail 8 +and +.Em The Mail Reference Manual . +.Sh HISTORY +A +.Nm mail +command +appeared in Version 6 AT&T UNIX. +This man page is derived from +.Em The Mail Reference Manual +originally written by Kurt Shoens. +.Sh BUGS There are some flags that are not documented here. Most are not useful to the general user. -.br +.Pp Usually, -.I mail +.Nm mail is just a link to -.IR Mail , +.Nm Mail , which can be confusing. diff --git a/usr/src/usr.bin/make/make.1 b/usr/src/usr.bin/make/make.1 index acfe0d754a..afd5f84ebc 100644 --- a/usr/src/usr.bin/make/make.1 +++ b/usr/src/usr.bin/make/make.1 @@ -1,154 +1,139 @@ .\" Copyright (c) 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)make.1 5.1 (Berkeley) %G% +.\" @(#)make.1 5.2 (Berkeley) %G% .\" -.TH MAKE 1 "" -.UC 7 -.SH NAME -make \- maintain program dependencies -.SH SYNOPSIS -.ft B -make [-eiknqrstv] [-D variable] [-d flags] [-f makefile ] [-I directory] -[-j max_jobs] [variable=value] [target ...] -.ft R -.SH DESCRIPTION -.I Make +.Dd +.Dt MAKE 1 +.Os BSD 4.4 +.Sh NAME +.Nm make +.Nd maintain program dependencies +.Sh SYNOPSIS +.Nm make +.Op Fl eiknqrstv +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl f Ar makefile +.Op Fl I Ar directory +.Op Fl j Ar max_jobs +.Op Ar variable=value +.Op Ar target ... +.Sh DESCRIPTION +.Nm Make is a program designed to simplify the maintenance of other programs. Its input is a ``makefile'' which specifies files that programs and other files are dependent upon. -.PP +.Pp This manual page is intended as a reference document only. For a more thorough description of -.I make +.Nm make and makefiles, please refer to -.IR "Make -- A Tutorial" . -.PP +.Em Make \-\- A Tutorial . +.Pp The options are as follows: -.TP -\-D variable +.Tw Ds +.Tp Cx Fl +.Ar variable +.Cx Define -.I variable +.Ar variable to be 1, in the global context. -.TP -\-d flags +.Tp Cx Fl d +.Ar flags +.Cx Turn on debugging, and specify which portions of -.I make +.Nm make are to print debugging information. -.I Flags +.Ar Flags is one or more of the following: -.RS -.TP -A +.Tw Ds +.Tp Ic A Print all possible debugging information; equivalent to specifying all of the debugging flags. -.TP -a +.Tp Ic a Print debugging information about archive searching and caching. -.TP -c +.Tp Ic c Print debugging information about conditional evaluation. -.TP -d +.Tp Ic d Print debugging information about directory searching and caching. -.TP -g1 +.Tp Ic g1 Print the input graph before making anything. -.TP -g2 +.Tp Ic g2 Print the input graph after making everything, or before exiting on error. -.TP -j +.Tp Ic j Print debugging information about running multiple shells. -.TP -m +.Tp Ic m Print debugging information about making targets, including modification dates. -.TP -s +.Tp Ic s Print debugging information about suffix-transformation rules. -.TP -t +.Tp Ic t Print debugging information about target list maintenance. -.TP -v +.Tp Ic v Print debugging information about variable assignment. -.RE -.TP -\-f makefile +.Tp +.Tp Cx Fl f +.Ar makefile +.Cx Specify a makefile to read. If no makefile is specified, the files ``makefile'' and ``Makefile'' are searched for, in that order. If -.I makefile +.Ar makefile is ``\-'', standard input is read. Multiple makefile's may be specified, and are read in the order specified. -.TP -\-I directory +.Tp Cx Fl I +.Ar directory +.Cx Specify a directory in which to search for makefiles and included makefiles. The system makefile directory is automatically included as part of this list. -.TP -\-i +.Tp Fl i Ignore non-zero exit of shell commands in the makefile. Equivalent to specifying ``\-'' before each command line in the makefile. -.TP -\-j max_jobs +.Tp Cx Fl j +.Ar max_jobs +.Cx Specify the maximum number of jobs that -.I make +.Nm make may have running at any one time. -.TP -\-k +.Tp Fl k Continue processing after errors are encountered, but only on those targets that do not depend on the target whose creation caused the error. -.TP -\-n +.Tp Fl n Display the commands that would have been executed, but do not actually execute them. -.TP -\-q +.Tp Fl q Do not execute any commands, but exit 0 if the specified targets are up-to-date and 1, otherwise. -.TP -\-r +.Tp Fl r Do not use the built-in rules specified in the system makefile. -.TP -\-s +.Tp Fl s Do not echo any commands as they are executed. Equivalent to specifying ``@'' before each command line in the makefile. -.TP -\-t +.Tp Fl t Rather than re-building a target as specified in the makefile, create it or update its modification time to make it appear up-to-date. -.TP -variable=value +.Tp Ar variable=value Set the value of the variable -.I variable +.Ar variable to -.IR value . -.PP +.Ar value . +.Tp +.Pp There are six different types of lines in a makefile: file dependency specifications, shell commands, variable assignments, include statements, conditional directives, and comments. -.PP +.Pp In general, lines may be continued from one line to the next by ending them with a backslash (``\e''). The trailing newline character and initial whitespace on the following line are compressed into a single space. -.SH "FILE DEPENDENCY SPECIFICATIONS" +.Sh FILE DEPENDENCY SPECIFICATIONS Dependency lines consist of one or more targets, an operator, and zero or more sources. This creates a relationship where the targets ``depend'' on the sources @@ -156,260 +141,256 @@ and are usually created from them. The exact relationship between the target and the source is determined by the operator that separates them. The three operators are as follows: -.TP -: +.Tp Ic \&: A target is considered out-of-date if its modification time is less than those of any of its sources. Sources for a target accumulate over dependency lines when this operator is used. The target is removed if -.I make +.Nm make is interrupted. -.TP -! +.Tp Ic \&! Targets are always re-created, but not until all sources have been examined and re-created as necessary. Sources for a target accumulate over dependency lines when this operator is used. The target is removed if -.I make +.Nm make is interrupted. -.TP -:: +.Tp Ic \&:: If no sources are specified, the target is always re-created. Otherwise, a target is considered out-of-date if any of its sources has been modified more recently than the target. Sources for a target do not accumulate over dependency lines when this operator is used. The target will not be removed if -.I make +.Nm make is interrupted. -.PP +.Tp +.Pp Targets and sources may contain the shell wildcard values ``?'', ``*'', -``[]'' and ``{}''. -The values ``?'', ``*'' and ``[]'' may only be used as part of the final +.Dq Op +and ``{}''. +The values ``?'', ``*'' and +.Dq Op +may only be used as part of the final component of the target or source, and must be used to describe existing files. The value ``{}'' need not necessarily be used to describe existing files. Expansion is in directory order, not alphabetically as done in the shell. -.SH "SHELL COMMANDS" +.Sh SHELL COMMANDS Each target may have associated with it a series of shell commands, normally used to create the target. Each of the commands in this script -.B must +.Em must be preceded by a tab. While any target may appear on a dependency line, only one of these dependencies may be followed by a creation script, unless the ``::'' operator is used. -.PP +.Pp If the first or first two characters of the command line are ``@'' and/or ``\-'', the command is treated specially. A ``@'' causes the command not to be echoed before it is executed. A ``\-'' causes any non-zero exit status of the command line to be ignored. -.SH "VARIABLE ASSIGNMENTS" +.Sh VARIABLE ASSIGNMENTS Variables in make are much like variables in the shell, and, by tradition, consist of all upper-case letters. The five operators that can be used to assign values to variables are as follows: -.TP -= +.Tp Ic \&= Assign the value to the variable. Any previous value is overridden. -.TP -+= +.Tp Ic \&+= Append the value to the current value of the variable. -.TP -?= +.Tp Ic \&?= Assign the value to the variable if it is not already defined. -.TP -:= +.Tp Ic \&:= Assign with expansion, i.e. expand the value before assigning it to the variable. Normally, expansion is not done until the variable is referenced. -.TP -!= +.Tp Ic \&!= Expand the value and pass it to the shell for execution and assign the result to the variable. Any newlines in the result are replaced with spaces. -.PP +.Tp +.Pp Any white-space before the assigned -.I value +.Ar value is removed; if the value is being appended, a single space is inserted between the previous contents of the variable and the appended value. -.PP +.Pp Variables are expanded by surrounding the variable name with either curly braces (``{}'') or parenthesis (``()'') and preceding it with a dollar sign (``$''). If the variable name contains only a single letter, the surrounding braces or parenthesis are not required. This shorter form is not recommended. -.PP +.Pp Variable substitution occurs at two distinct times, depending on where the variable is being used. Variables in dependency lines are expanded as the line is read. Variables in shell commands are expanded when the shell command is executed. -.PP +.Pp The four different classes of variables (in order of increasing precedence) are: -.TP -environmental variables +.Tw Ds +.Tp environment variables Variables defined as part of -.IR make 's +.Cx Nm make +.Cx \'s +.Cx environment. -.TP -global variables +.Tp global variables Variables defined in the makefile or in included makefiles. -.TP -command line variables +.Tp command line variables Variables defined as part of the command line. -.TP -local variables +.Tp local variables Variables that are defined specific to a certain target. The seven local variables are as follows: -.RS -.TP -\&.ALLSRC +.Tw Ds +.Tp Va \&.ALLSRC The list of all sources for this target; also known as ``>''. -.TP -\&.ARCHIVE +.Tp Va \&.ARCHIVE The name of the archive file. -.TP -\&.IMPSRC +.Tp Va \&.IMPSRC The name/path of the source from which the target is to be transformed (the ``implied'' source); also known as ``<''. -.TP -\&.MEMBER +.Tp Va \&.MEMBER The name of the archive member. -.TP -\&.OODATE +.Tp Va \&.OODATE The list of sources for this target that were deemed out-of-date; also known as ``?''. -.TP -\&.PREFIX +.Tp Va \&.PREFIX The file prefix of the file, containing only the file portion, no suffix or preceding directory components; also known as ``*'. -.TP -\&.TARGET +.Tp Va \&.TARGET The name of the target; also known as ``@''. -.RE -.PP +.Tp +.Pp The shorter forms ``@'', ``?'', ``>'' and ``*'' are permitted for backward compatibility with historical makefiles and are not recommended. The six variables ``@F'', ``@D'', ``'' or ``.include "file"''. @@ -420,98 +401,155 @@ the system makefile directory. If double quotes are used, the including makefile's directory and any directories specified using the -I option are searched before the system makefile directory. -.PP +.Pp Conditional expressions are also preceded by a single dot as the first chraracter of a line. The possible conditionals are as follows: -.TP -\&.undef variable +.Tw Ds +.Tp Cx Ic \&.undef +.Cx \&\ \& +.Ar variable +.Cx Un-define the specified global variable. Only global variables may be un-defined. -.TP -\&.if [!] expression [ operator expression ... ] +.Tp Cx Ic \&.if +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Op Ar operator expression ... +.Cx Test the value of an expression. -.TP -\&.ifdef [!] variable [ operator variable ... ] +.Tp Cx Ic \&.ifdef +.Cx \&\ \& +.Op \&! +.Ar variable +.Cx \&\ \& +.Op Ar operator variable ... +.Cx Test the value of an variable. -.TP -\&.ifndef [!] variable [ operator variable ... ] +.Tp Cx Ic \&.ifndef +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ar operator variable ... +.Cx Test the value of an variable. -.TP -\&.ifmake [!] target [ operator target ... ] +.Tp Cx Ic \&.ifmake +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar target +.Cx \&\ \& +.Op Ar operator target ... +.Cx Test the the target being built. -.TP -\&.ifnmake [!] target [ operator target ... ] +.Tp Cx Ic \&.ifnmake +.Cx \&\ \& +.Op \&! +.Ar target +.Cx \&\ \& +.Op Ar operator target ... +.Cx Test the target being built. -.TP -\&.else +.Tp Ic \&.else Reverse the sense of the last conditional. -.TP -\&.elif [!] expression [ operator expression ...] +.Tp Cx Ic \&.elif +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Op Ar operator expression ... +.Cx A combination of ``.else'' followed by ``.if''. -.TP -\&.elifdef [!] variable [ operator variable ...] +.Tp Cx Ic \&.elifdef +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ar operator variable ... +.Cx A combination of ``.else'' followed by ``.ifdef''. -.TP -\&.elifndef [!] variable [ operator variable ...] +.Tp Cx Ic \&.elifndef +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ar operator variable ... +.Cx A combination of ``.else'' followed by ``.ifndef''. -.TP -\&.elifmake [!] target [ operator target ...] +.Tp Cx Ic \&.elifmake +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar target +.Cx \&\ \& +.Op Ar operator target ... +.Cx A combination of ``.else'' followed by ``.ifmake''. -.TP -\&.elifnmake [!] target [ operator target ...] +.Tp Cx Ic \&.elifnmake +.Cx \&\ \& +.Op \&! +.Cx \&\ \& +.Ar target +.Cx \&\ \& +.Op Ar operator target ... +.Cx A combination of ``.else'' followed by ``.ifnmake''. -.TP -\&.endif +.Tp Ic \&.endif End the body of the conditional. -.PP +.Tp +.Pp The -.I operator +.Ar operator may be any one of the following: -.TP -|| +.Tp Cm \&|\&| logical OR -.TP -&& -Logical AND; of higher precedence than ``||''. -.PP +.Tp Cm \&&& +Logical AND; of higher precedence than ``''. +.Tp +.Pp As in C, -.I make +.Nm make will only evaluate a conditional as far as is necessary to determine its value. Parenthesis may be used to change the order of evaluation. The boolean operator ``!'' may be used to logically negate an entire conditional. It is of higher precendence than ``&&''. -.PP +.Pp The value of -.I expression +.Ar expression may be any of the following: -.TP -defined +.Tp Ic defined Takes a variable name as an argument and evaluates to true if the variable has been defined. -.TP -make +.Tp Ic make Takes a target name as an argument and evaluates to true if the target was specified as part of -.IR make 's +.Cx Nm make +.Cx \'s +.Cx command line or was declared the default target (either implicitly or explicitly, see .MAIN) before the line containing the conditional. -.TP -empty +.Tp Ic empty Takes a variable, with possible modifiers, and evalutes to true if the expansion of the variable would result in an empty string. -.TP -exists +.Tp Ic exists Takes a file name as an argument and evaluates to true if the file exists. The file is searched for on the system search path (see .PATH). -.TP -target +.Tp Ic target Takes a target name as an argument and evaluates to true if the target has been defined. -.PP -.I Expression +.Tp +.Pp +.Ar Expression may also be an arithmetic or string comparison, with the left-hand side being a variable expansion. The standard C relational operators are all supported, and the usual @@ -522,9 +560,9 @@ quotation mark (``"'') a string comparison is done between the expanded variable and the text between the quotation marks. If no relational operator is given, it is assumed that the expanded variable is being compared against 0. -.PP +.Pp When -.I make +.Nm make is evaluating one of these conditional expression, and it encounters a word it doesn't recognize, either the ``make'' or ``defined'' expression is applied to it, depending on the form of the conditional. @@ -532,130 +570,133 @@ If the form is ``.ifdef'' or ``.ifndef'', the ``defined'' expression is applied. Similarly, if the form is ``.ifmake'' or ``.ifnmake'', the ``make'' expression is applied. -.PP +.Pp If the conditional evaluates to true the parsing of the makefile continues as before. If it evaluates to false, the following lines are skipped. In both cases this continues until a ``.else'' or ``.endif'' is found. -.SH COMMENTS +.Sh COMMENTS Comments begin with a hash (``#'') character, anywhere but in a shell command line, and continue to the end of the line. -.SH "SPECIAL SOURCES" -.TP -\&.IGNORE +.Sh SPECIAL SOURCES +.Tp Ic \&.IGNORE Ignore any errors from the commands associated with this target, exactly as if they all were preceded by a dash (``\-''). -.TP -\&.MAKE +.Tp Ic \&.MAKE Execute the commands associated with this target even if the -n or -t options were specified. Normally used to mark recursive -.IR make 's. -.TP -\&.NOTMAIN +.Cx Nm make +.Cx \'s . +.Cx +.Tp Ic \&.NOTMAIN Normally -.I make +.Nm make selects the first target it encounters as the default target to be built if no target was specified. This source prevents this target from being selected. -.TP -\&.OPTIONAL +.Tp Ic \&.OPTIONAL If a target is marked with this attribute and -.I make +.Nm make can't figure out how to create it, it will ignore this fact and assume the file isn't needed or already exists. -.TP -\&.PRECIOUS +.Tp Ic \&.PRECIOUS When -.I make +.Nm make is interrupted, it removes any partially made targets. This source prevents the target from being removed. -.TP -\&.SILENT +.Tp Ic \&.SILENT Do not echo any of the commands associated with this target, exactly as if they all were preceded by an at sign (``@''). -.TP -\&.USE +.Tp Ic \&.USE Turn the target into -.IR make 's +.Cx Nm make +.Cx \'s . +.Cx version of a macro. When the target is used as a source for another target, the other target acquires the commands, sources, and attributes (except for .USE) of the source. If the target already has commands, the .USE target's commands are appended to them. -.SH "SPECIAL TARGETS" +.Tp +.Sh "SPECIAL TARGETS" Special targets may not be included with other targets, i.e. they must be the only target specified. -.TP -\&.BEGIN +.Tp Ic \&.BEGIN Any command lines attached to this target are executed before anything else is done. -.TP -\&.DEFAULT +.Tp Ic \&.DEFAULT This is sort of a .USE rule for any target (that was used only as a source) that -.I make +.Nm make can't figure out any other way to create. Only the shell script is used. The .IMPSRC variable of a target that inherits .DEFAULT's commands is set to the target's own name. -.TP -\&.END +.Tp Ic \&.END Any command lines attached to this target are executed after everything else is done. -.TP -\&.IGNORE +.Tp Ic \&.IGNORE Mark each of the sources with the .IGNORE attribute. If no sources are specified, this is the equivalent of specifying the -i option. -.TP -\&.INTERRUPT +.Tp Ic \&.INTERRUPT If -.I make +.Nm make is interrupted, the commands for this target will be executed. -.TP -\&.MAIN +.Tp Ic \&.MAIN If no target is specified when -.I make +.Nm make is invoked, this target will be built. -.TP -\&.MAKEFLAGS +.Tp Ic \&.MAKEFLAGS This target provides a way to specify flags for -.I make +.Nm make when the makefile is used. The flags are as if typed to the shell, though the -f option will have no effect. -.TP -\&.PATH +.Tp Ic \&.PATH The sources are directories which are to be searched for files not found in the current directory. If no sources are specified, any previously specified directories are deleted. -.TP -\&.PRECIOUS +.Tp Ic \&.PRECIOUS Apply the .PRECIOUS attribute to any specified sources. If no sources are specified, the .PRECIOUS attribute is applied to every target in the file. -.TP -\&.SILENT +.Tp Ic \&.SILENT Apply the .SILENT attribute to any specified sources. If no sources are specified, the .SILENT attribute is applied to every command in the file. -.TP -\&.SUFFIXES +.Tp Ic \&.SUFFIXES Each source specifies a suffix to -.IR make . +.Nm make . If no sources are specified, any previous specifies suffices are deleted. -.SH FILES -.ta \w'/usr/share/mk\ \ \ 'u -/usr/share/mk system makefile directory -.br -sys.mk include system makefile -.br -bsd.mk BSD source tree template -.br -subdir.mk BSD source tree subdirectory template -.SH SEE ALSO -.SH DIAGNOSTICS -.SH BUGS +.Sh ENVIRONMENT +.Nm make +can utilize the +.Ev MAKE , +.Ev MAKEFLAGS +and +.Ev MAKEOBJDIR +environment variables. +.Sh FILES +.Dw /usr/share/mk +.Di L +.Dp Pa /usr/share/mk +system makefile directory +.Dp Pa sys.mk +include system makefile +.Dp Pa bsd.mk +BSD source tree template +.Dp Pa subdir.mk +BSD source tree subdirectory template +.Dp +.Sh SEE ALSO +.Sh HISTORY +.Nm Make +appeared in Version 7 AT&T UNIX. +The +.Nm make +this man page describes is derived from code contributed by Adam +de Boor. diff --git a/usr/src/usr.bin/more/more.1 b/usr/src/usr.bin/more/more.1 index c63805b0a1..d9ae6528a4 100644 --- a/usr/src/usr.bin/more/more.1 +++ b/usr/src/usr.bin/more/more.1 @@ -1,159 +1,205 @@ -.\" +.\" Copyright (c) 1988, 1990 The Regents of the University of California. .\" Copyright (c) 1988 Mark Nudleman -.\" Copyright (c) 1988 Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by Mark Nudleman and the University of California, Berkeley. The -.\" name of Mark Nudleman or the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)more.1 5.11 (Berkeley) %G% +.\" @(#)more.1 5.12 (Berkeley) %G% .\" -.TH MORE 1 -.SH NAME -more \- file perusal filter for crt viewing -.SH SYNOPSIS -.B "more [-ceinus] [-t tag] [-x tabs] [-/ pattern] [-#] [file ...]" -.SH DESCRIPTION -.I More +.Dd +.Dt MORE 1 +.Sh NAME +.Nm more +.Nd file perusal filter for crt viewing +.Sh SYNOPSIS +.Nm more +.Op Fl ceinus +.Op Fl t Ar tag +.Op Fl x Ar tabs +.Op Fl / Ar pattern +.Op Fl # +.Ar +.Sh DESCRIPTION +.Nm More is a filter for paging through text one screenful at a time. It uses -.IR termcap (3) +.Xr termcap 3 so it can run on a variety of terminals. There is even limited support for hardcopy terminals. (On a hardcopy terminal, lines which should be printed at the top of the screen are prefixed with an up-arrow.) -.I File +.Ar File may be a single dash (``-''), implying stdin. -.SH OPTIONS +.Sh OPTIONS Command line options are described below. -Options are also taken from the environment variable "MORE" +Options are also taken from the environment variable +.Ev MORE (make sure to precede them with a dash (``-'')) but command line options will override them. -.IP -c -Normally, -.I more +.Tw Fl +.Tp Fl c +Normally, +.Nm more will repaint the screen by scrolling from the bottom of the screen. -If the -c option is set, when -.I more +If the +.Fl c +option is set, when +.Nm more needs to change the entire display, it will paint from the top line down. -.IP -e +.Tp Fl e Normally, if displaying a single file, -.I more -exits as soon as it reaches end-of-file. The -e option tells more to +.Nm more +exits as soon as it reaches end-of-file. The +.Fl e +option tells more to exit if it reaches end-of-file twice without an intervening operation. If the file is shorter than a single screen -.I more +.Nm more will exit at end-of-file regardless. -.IP -i -The -i option causes searches to ignore case; that is, +.Tp Fl i +The +.Fl i +option causes searches to ignore case; that is, uppercase and lowercase are considered identical. -.IP -n -The -n flag suppresses line numbers. +.Tp Fl n +The +.Fl n +flag suppresses line numbers. The default (to use line numbers) may cause -.I more +.Nm more to run more slowly in some cases, especially with a very large input file. -Suppressing line numbers with the -n flag will avoid this problem. -Using line numbers means: the line number will be displayed in the +Suppressing line numbers with the +.Fl n +flag will avoid this problem. +Using line numbers means: the line number will be displayed in the = command, and the v command will pass the current line number to the editor. -.IP -s -The -s option causes +.Tp Fl s +The +.Fl s +option causes consecutive blank lines to be squeezed into a single blank line. -.IP -t -The -t option, followed immediately by a tag, will edit the file +.Tp Fl t +The +.Fl t +option, followed immediately by a tag, will edit the file containing that tag. For more information, see the -.IR ctags (1) +.Xr ctags 1 command. -.IP -u +.Tp Fl u By default, -.I more +.Nm more treats backspaces and CR-LF sequences specially. Backspaces which appear adjacent to an underscore character are displayed as underlined text. Backspaces which appear between two identical characters are displayed as emboldened text. CR-LF sequences are compressed to a single linefeed -character. The -u option causes backspaces to always be displayed as +character. The +.Fl u +option causes backspaces to always be displayed as control characters, i.e. as the two character sequence ``^H'', and CR-LF to be left alone. -.IP -x -The -x option sets tab stops every -.I N +.Tp Fl x +The +.Fl x +option sets tab stops every +.Ar N positions. The default for -.I N +.Ar N is 8. -.IP -/ -The -/ option specifies a string that will be searched for before +.Tp Fl \&/ +The +.Fl \&/ +option specifies a string that will be searched for before each file is displayed. -.SH COMMANDS +.Sh COMMANDS Interactive commands for -.I more +.Nm more are based on -.IR vi (1). +.Xr vi 1 . Some commands may be preceeded by a decimal number, called N in the descriptions below. In the following descriptions, ^X means control-X. -.IP h +.Pp +.Tw Ic +.Tp Ic h help: display a summary of these commands. If you forget all the other commands, remember this one. -.PP -.IP "SPACE or f or ^F" +.Tp Cx Ic SPACE +.Ws +.Cx or +.Ws +.Ic f +.Ws +.Cx or +.Ws +.Ic \&^F +.Cx Scroll forward N lines, default one window. If N is more than the screen size, only the final screenful is displayed. -.PP -.IP "b or ^B" +.Tp Cx Ic b +.Ws +.Cx or +.Ws +.Ic \&^B +.Cx Scroll backward N lines, default one window (see option -z below). If N is more than the screen size, only the final screenful is displayed. -.PP -.IP "j or RETURN" +.Tp Cx Ic j +.Ws +.Cx or +.Ws +.Ic RETURN +.Cx Scroll forward N lines, default 1. The entire N lines are displayed, even if N is more than the screen size. -.PP -.IP "k" +.Tp Ic k Scroll backward N lines, default 1. The entire N lines are displayed, even if N is more than the screen size. -.PP -.IP "d or ^D" +.Tp Ic d +.Ws +.Cx or +.Ws +.Ic \&^D +.Cx Scroll forward N lines, default one half of the screen size. -If N is specified, it becomes the new default for +If N is specified, it becomes the new default for subsequent d and u commands. -.PP -.IP "u or ^U" +.Tp Ic u +.Ws +.Cx or +.Ws +.Ic \&^U +.Cx Scroll backward N lines, default one half of the screen size. -If N is specified, it becomes the new default for +If N is specified, it becomes the new default for subsequent d and u commands. -.PP -.IP "g" +.Tp Ic g Go to line N in the file, default 1 (beginning of file). -.PP -.IP "G" +.Tp Ic G Go to line N in the file, default the end of the file. -.PP -.IP "p or %" +.Tp Ic p +.Ws +.Cx or +.Ws +.Ic \&% +.Cx Go to a position N percent into the file. N should be between 0 and 100. (This works if standard input is being read, but only if -.I more +.Nm more has already read to the end of the file. It is always fast, but not always useful.) -.PP -.IP "r or ^L" +.Tp Ic r +.Ws +.Cx or +.Ws +.Ic \&^L +.Cx Repaint the screen. -.PP -.IP "R" +.Tp Ic R Repaint the screen, discarding any buffered input. Useful if the file is changing while it is being viewed. -.PP -.IP m -Followed by any lowercase letter, +.Tp Ic m +Followed by any lowercase letter, marks the current position with that letter. -.PP -.IP "'" +.Tp Ic \&\' (Single quote.) Followed by any lowercase letter, returns to the position which was previously marked with that letter. @@ -161,71 +207,108 @@ Followed by another single quote, returns to the postion at which the last "large" movement command was executed, or the beginning of the file if no such movements have occurred. All marks are lost when a new file is examined. -.PP -.IP /pattern +.Tp Cx Ic \&/ +.Ar pattern +.Cx Search forward in the file for the N-th line containing the pattern. N defaults to 1. The pattern is a regular expression, as recognized by -.I ed. +.Xr ed . The search starts at the second line displayed. -.PP -.IP ?pattern +.Tp Cx Ic \&? +.Ar pattern +.Cx Search backward in the file for the N-th line containing the pattern. The search starts at the line immediately before the top line displayed. -.PP -.IP /!pattern +.Tp Ic \&/! +.Ar pattern +.Cx Like /, but the search is for the N-th line which does NOT contain the pattern. -.PP -.IP ?!pattern +.Tp Ic \&?! +.Ar pattern +.Cx Like ?, but the search is for the N-th line which does NOT contain the pattern. -.PP -.IP n +.Tp Ic n Repeat previous search, for N-th line containing the last pattern (or NOT containing the last pattern, if the previous search was /! or ?!). -.PP -.IP "E [filename]" +.Tp Cx Ic E +.Ws +.Op Ar filename +.Cx Examine a new file. If the filename is missing, the "current" file (see the N and P commands below) from the list of files in the command line is re-examined. If the filename is a pound sign (#), the previously examined file is re-examined. -.PP -.IP "N or :n" +.Tp Cx Ic N +.Ws +.Cx or +.Ws +.Ic \&:n +.Cx Examine the next file (from the list of files given in the command line). If a number N is specified (not to be confused with the command N), the N-th next file is examined. -.PP -.IP "P or :p" +.Tp Cx Ic P +.Ws +.Cx or +.Ws +.Ic \&:p +.Cx Examine the previous file. If a number N is specified, the N-th previous file is examined. -.PP -.IP ":t" +.Tp Ic \&:t Go to supplied tag. -.PP -.IP v +.Tp Ic v Invokes an editor to edit the current file being viewed. -The editor is taken from the environment variable EDITOR, +The editor is taken from the environment variable +.Ev EDITOR , or defaults to -.IR vi (1). -.PP -.IP "= or ^G" +.Xr vi 1 . +.Tp Cx Ic \&= +.Ws +.Cx or +.Ws +.Ic \&^G +.Cx These options print out the number of the file currently being displayed relative to the total number of files there are to display, the current line number, the current byte number and the total bytes to display, and what percentage of the file has been displayed. If -.I more +.Nm more is reading from stdin, or the file is shorter than a single screen, some of these items may not be available. Note, all of these items reference the first byte of the last line displayed on the screen. -.PP -.IP "q or :q or ZZ" +.Tp Cx Ic q +.Ws +.Cx or +.Ws +.Ic \&:q +.Ws +.Cx or +.Ws +.Ic ZZ +.Cx Exits -.I more. -.SH "SEE ALSO -ctags(1), vi(1) -.SH AUTHOR +.Nm more . +.Tp +.Sh ENVIRONMENT +.Nm More +uses the following environment variables: +.Ev MORE , +.Ev EDITOR , +.Ev SHELL +and +.Ev TERM . +.Sh SEE ALSO +.Xr ctags 1 , +.Xr vi 1 +.Sh AUTHOR This software is derived from software contributed to Berkeley by Mark Nudleman. +.Sh HISTORY +.Nm more +appeared in 3 BSD. diff --git a/usr/src/usr.bin/msgs/msgs.1 b/usr/src/usr.bin/msgs/msgs.1 index 9b4f62a265..dd4de67190 100644 --- a/usr/src/usr.bin/msgs/msgs.1 +++ b/usr/src/usr.bin/msgs/msgs.1 @@ -1,191 +1,193 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)msgs.1 6.4 (Berkeley) %G% +.\" @(#)msgs.1 6.5 (Berkeley) %G% .\" -.TH MSGS 1 "" -.UC 4 -.SH NAME -msgs \- system messages and junk mail program -.SH SYNOPSIS -.B msgs -[ -.B \-fhlpq -] [ -number -] [ -\-number -] -.LP -.B msgs -.B \-s -.LP -.B msgs -.B \-c -[ -\-days -] -.SH DESCRIPTION -.I Msgs +.Dd +.Dt MSGS 1 +.Os BSD 4 +.Sh NAME +.Nm msgs +.Nd system messages and junk mail program +.Sh SYNOPSIS +.Nm msgs +.Op Fl fhlpq +.Op Ar number +.Op Ar \-number +.Pp +.Nm msgs +.Op Fl s +.Pp +.Nm msgs +.Op Fl c +.Op \-days +.Sh DESCRIPTION +.Nm Msgs is used to read system messages. These messages are sent by mailing to the login `msgs' and should be short pieces of information which are suitable to be read once by most users of the system. -.PP -.I Msgs +.Pp +.Nm Msgs is normally invoked each time you login, by placing it in the file -.I \&.login -.I (\&.profile +.Pa \& .login +(or +.Pa \&.profile if you use -.IR /bin/sh ). +.Xr sh 1 ) . It will then prompt you with the source and subject of each new message. If there is no subject line, the first few non-blank lines of the message will be displayed. If there is more to the message, you will be told how long it is and asked whether you wish to see the rest of the message. The possible responses are: -.TP 7 -.B y +.Tw Fl +.Tp Fl y type the rest of the message. -.TP 7 -RETURN +.Tp Ic RETURN synonym for y. -.TP 7 -.B n +.Tp Fl n skip this message and go on to the next message. -.TP 7 -.B \- +.Tp Fl redisplay the last message. -.TP 7 -.B q +.Tp Fl q drops you out of -.I msgs; +.Nm msgs ; the next time you run the program it will pick up where you left off. -.TP 7 -.B s +.Tp Fl 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 be followed by a space and a file name to receive the message replacing the default ``Messages''. -.TP 7 -.B m +.Tp Fl m or `m\-' causes a copy of the specified message to be placed in a temporary -mailbox and -.IR mail (1) +mailbox and +.Xr mail 1 to be invoked on that mailbox. Both `m' and `s' accept a numeric argument in place of the `\-'. -.PP -.I Msgs +.Tp +.Pp +.Nm Msgs keeps track of the next message you will see by a number in the file -.I \&.msgsrc +.Pa \&.msgsrc in your home directory. In the directory -.I /usr/msgs +.Pa /var/msgs it keeps a set of files whose names are the (sequential) numbers of the messages they represent. The file -.I /usr/msgs/bounds +.Pa /var/msgs/bounds shows the low and high number of the messages in the directory so that -.I msgs +.Nm msgs can quickly determine if there are no messages for you. If the contents of -.I bounds +.Pa bounds is incorrect it can be fixed by removing it; -.I msgs +.Nm msgs will make a new -.I bounds +.Pa bounds file the next time it is run. -.PP +.Pp The -.B \-s +.Fl s option is used for setting up the posting of messages. The line -.IP -.DT -msgs: "| /usr/ucb/msgs \-s" -.PP -should be include in -.I /usr/lib/aliases +.Pp +.Dl msgs: /usr/ucb/msgs \-s" +.Pp +should be included in +.Pa /etc/aliases +(see +.Xr newaliases 1 ) to enable posting of messages. -.PP +.Pp The -.B \-c +.Fl c option is used for performing cleanup on -.I /usr/msgs. +.Pa /var/msgs. An entry with the -.B \-c +.Fl c option should be placed in -.I /usr/lib/crontab +.Pa /etc/crontab 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 +.Pp Options when reading messages include: -.TP 7 -.B \-f +.Tw Fl +.Tp Fl f which causes it not to say ``No new messages.''. This is useful in your -.I \&.login +.Pa \& .login file since this is often the case here. -.TP 7 -.B \-q +.Tp Fl q Queries whether there are messages, printing ``There are new messages.'' if there are. The command ``msgs \-q'' is often used in login scripts. -.TP 7 -.B \-h +.Tp Fl h causes -.I msgs +.Nm msgs to print the first part of messages only. -.TP 7 -.B \-l +.Tp Fl l option causes only locally originated messages to be reported. -.TP 7 -\fInum\fR +.Tp Ar num A message number can be given on the command line, causing -.I msgs +.Nm msgs to start at the specified message rather than at the next message indicated by your -.I \&.msgsrc +.Pa \&.msgsrc file. Thus -.IP "" 7 - msgs \-h 1 -.IP "" 7 +.Pp +.Dl msgs \-h 1 +.Pp prints the first part of all messages. -.TP 7 -.I "\-number" +.Tp Ar \-number will cause -.I msgs +.Nm msgs to start -.I number -messages back from the one indicated by your -.I \&.msgsrc +.Ar number +messages back from the one indicated by your +.Pa \&.msgsrc file, useful for reviews of recent messages. -.TP 7 -.B \-p +.Tp Fl p causes long messages to be piped through -.IR more (1). -.PP +.Xr more 1 . +.Pp Within -.I msgs +.Nm msgs you can also go to any specific message by typing its number when -.I msgs +.Nm msgs requests input as to what to do. -.SH FILES -.ta 2i -/usr/msgs/* database -.br -~/.msgsrc number of next message to be presented -.SH AUTHORS +.Sh ENVIRONMENT +.Nm Msgs uses the +.Ev HOME +and +.Ev TERM +environment variables. +.Sh FILES +.Dw /usr/msgs/* +.Di L +.Dp Pa /usr/msgs/* +database +.Dp ~/.msgsrc +number of next message to be presented +.Dp +.Sh AUTHORS William Joy .br David Wasley -.SH SEE ALSO -aliases(5), crontab(5), mail(1), more(1) -.SH BUGS +.Sh SEE ALSO +.Xr aliases 5 , +.\".Xr crontab 5 , +.Xr mail 1 , +.Xr more 1 +.Sh HISTORY +.Nm Msgs +appeared in 3 BSD. +.Sh BUGS diff --git a/usr/src/usr.bin/mt/mt.1 b/usr/src/usr.bin/mt/mt.1 index 5692dfa9fc..0a06bc1b14 100644 --- a/usr/src/usr.bin/mt/mt.1 +++ b/usr/src/usr.bin/mt/mt.1 @@ -1,100 +1,100 @@ -.\" Copyright (c) 1981 The Regents of the University of California. +.\" Copyright (c) 1981, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)mt.1 6.3 (Berkeley) %G% +.\" @(#)mt.1 6.4 (Berkeley) %G% .\" -.UC 7 -.TH MT 1 "" -.UC 4 -.SH NAME -mt \- magnetic tape manipulating program -.SH SYNOPSIS -.B mt -[ -.B \-f -.I tapename -] -.I command -[ -.I count -] -.SH DESCRIPTION -.I Mt +.Dd +.Os BSD 4.4 +.Dt MT 1 +.Os BSD 4 +.Sh NAME +.Nm mt +.Nd magnetic tape manipulating program +.Sh SYNOPSIS +.Nm mt +.Op Fl f Ar tapename +.Ar command +.Op Ar count +.Sh DESCRIPTION +.Nm Mt is used to give commands to a magnetic tape drive. If a tape name is not specified, the environment variable -TAPE is used; if TAPE does not exist, -.I mt +.Ev TAPE +is used; if +.Ev TAPE +does not exist, +.Nm mt uses the device -.IR /dev/rmt12 . +.Pa /dev/rmt12 . Note that -.I tapename +.Ar tapename must reference a raw (not block) tape device. By default -.I mt +.Nm mt performs the requested operation once. Operations may be performed multiple times by specifying -.IR count . -.PP +.Ar count . +.Pp The available commands are listed below. Only as many characters as are required to uniquely identify a command need be specified. -.TP -.BR eof , " weof" -Write -.I count +.Tp Cm eof , weof +Write +.Ar count end-of-file marks at the current position on the tape. -.TP -.B fsf +.Tp Cm fsf Forward space -.I count +.Ar count files. -.TP -.B fsr -Forward space -.I count +.Tp Cm fsr +Forward space +.Ar count records. -.TP -.B bsf -Back space -.I count +.Tp Cm bsf +Back space +.Ar count files. -.TP -.B bsr +.Tp Cm bsr Back space -.I count +.Ar count records. -.TP -.B rewind +.Tp Cm rewind Rewind the tape -.RI ( Count -is ignored). -.TP -.BR offline , " rewoffl" +(Count is ignored). +.Tp Cm offline , rewoffl Rewind the tape and place the tape unit off-line -.RI ( Count -is ignored). -.TP -.B status +(Count is ignored). +.Tp Cm status Print status information about the tape unit. -.PP -.I Mt +.Tp +.Pp +.Nm Mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2 if an operation failed. -.SH FILES -.DT -/dev/rmt* Raw magnetic tape interface -.SH "SEE ALSO" -mtio(4), dd(1), ioctl(2), environ(7) +.Sh ENVIRONMENT +.Tw Fl +.Tp Ev TAPE +.Nm Mt +checks the +.Ev TAPE +environment variable if the +argument +.Ar tapename is not given. +.Sh FILES +.Dw /dev/rmt* +.Di L +.Dp Pa /dev/rmt* +Raw magnetic tape interface +.Dp +.Sh SEE ALSO +.\".Xr mtio 4 , +.Xr dd 1 , +.Xr ioctl 2 , +.Xr environ 7 +.Sh HISTORY +.Nm Mt +appeared in 4.3 BSD. +.\" mt.1: mtio(4) missing diff --git a/usr/src/usr.bin/netstat/netstat.1 b/usr/src/usr.bin/netstat/netstat.1 index 9c54639126..a1e0500dd0 100644 --- a/usr/src/usr.bin/netstat/netstat.1 +++ b/usr/src/usr.bin/netstat/netstat.1 @@ -1,75 +1,40 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)netstat.1 6.8 (Berkeley) %G% +.\" @(#)netstat.1 6.9 (Berkeley) %G% .\" -.TH NETSTAT 1 "" -.UC 5 -.SH NAME -netstat \- show network status -.SH SYNOPSIS -.B netstat -[ -.B \-Aan -] [ -.B \-f -.I address_family -] [ -.I system -] [ -.I core -] -.br -.B netstat -[ -.B \-himnrs -] [ -.B \-f -.I address_family -] [ -.I system -] [ -.I core -] -.br -.B netstat -[ -.B \-n -] [ -.B \-I -.I interface -] -.I interval -[ -.I system -] [ -.I core -] -.br -.B netstat -[ -.B \-p -.I protocol -] [ -.I system -] [ -.I core -] -.SH DESCRIPTION +.Dd +.Dt NETSTAT 1 +.Os BSD 4.2 +.Sh NAME +.Nm netstat +.Nd show network status +.Sh SYNOPSIS +.Nm netstat +.Op Fl Aan +.Op .Fl f Ar address_family +.Op Ar system +.Op Ar core +.Nm netstat +.Op Fl himnrs +.Op Fl f Ar address_family +.Op Ar system +.Op Ar core +.Nm netstat +.Op Fl n +.Op Fl I Op Ar interface +.Ar interval +.Op Ar system +.Op Ar core +.Nm netstat +.Op Fl p Ar protocol +.Op Ar system +.Op Ar core +.Sh DESCRIPTION The -.I netstat +.Nm netstat command symbolically displays the contents of various network-related data structures. There are a number of output formats, @@ -78,100 +43,103 @@ The first form of the command displays a list of active sockets for each protocol. The second form presents the contents of one of the other network data structures according to the option selected. -Using the third form, with an -.I interval +Using the third form, with an +.Ar interval specified, -.I netstat +.Nm netstat will continuously display the information regarding packet traffic on the configured network interfaces. The fourth form displays statistics about the named protocol. -.PP +.Pp The options have the following meaning: -.TP -.B \-A +.Tw Fl +.Tp Fl A With the default display, show the address of any protocol control blocks associated with sockets; used for debugging. -.TP -.B \-a +.Tp Fl a With the default display, show the state of all sockets; normally sockets used by server processes are not shown. -.B \-d +.Fl d With either interface display (option -.B \-i +.Fl i or an interval, as described below), show the number of dropped packets. -.TP -.B \-h +.Tp Fl h Show the state of the IMP host table. -.TP -.B \-i +.Tp Fl i Show the state of interfaces which have been auto-configured (interfaces statically configured into a system, but not located at boot time are not shown). -.TP -.BI \-I " interface" +.Tp Cx Fl I +.Ws +.Ar interface +.Cx Show information only about this interface; used with an -.I interval +.Ar interval as described below. -.TP -.B \-m +.Tp Fl m Show statistics recorded by the memory management routines (the network manages a private pool of memory buffers). -.TP -.B \-n -Show network addresses as numbers (normally -.I netstat +.Tp Fl n +Show network addresses as numbers (normally +.Nm netstat interprets addresses and attempts to display them symbolically). This option may be used with any of the display formats. -.TP -.BI \-p " protocol" -Show statistics about -.IR protocol , +.Tp Cx Fl p +.Ws +.Ar protocol +.Cx +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 -.IR /etc/protocols . -A null response typically means that there are no interesting numbers to +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. The program will complain if -.I protocol +.Ar protocol is unknown or if there is no statistics routine for it. -.TP -.B \-s +.Tp Fl s Show per-protocol statistics. -.TP -.B \-r +.Tp Fl r Show the routing tables. When -.B \-s +.Fl s is also present, show routing statistics instead. -.TP -.BI \-f " address_family" +.Tp Cx Fl f +.Ws +.Ar address_family +.Cx Limit statistics or address control block reports to those of the specified -.IR address\ family . +.Ar address family . The following address families are recognized: -.IR inet , +.Ar inet , for -.BR AF_INET , -.IR ns , +.Li AF _INET , +.Ar ns , for -.BR AF_NS , +.Li AF _NS , and -.IR unix , +.Ar unix , for -.BR AF_UNIX . -.PP -The arguments, -.I system +.Li AF _UNIX . +.Tp +.Pp +The arguments, +.Ar system and -.I core -allow substitutes for the defaults ``/vmunix'' and ``/dev/kmem''. -.PP +.Ar core +allow substitutes for the defaults +.Dq Pa vmunix +and +.Dq Pa /dev/kmem . +.Pp The default display, for active sockets, shows the local and remote addresses, send and receive queue sizes (in bytes), protocol, and the internal state of the protocol. @@ -179,26 +147,26 @@ Address formats are of the form ``host.port'' or ``network.port'' if a socket's address specifies a network but no specific host address. When known the host and network addresses are displayed symbolically according to the data bases -.I /etc/hosts +.Pa /etc/hosts and -.IR /etc/networks , +.Pa /etc/networks , respectively. If a symbolic name for an address is unknown, or if -the -.B \-n +the +.Fl n option is specified, the address is printed numerically, according to the address family. -For more information regarding +For more information regarding the Internet ``dot format,'' -refer to -.IR inet (3N). +refer to +.Xr inet 3 ) . Unspecified, -or ``wildcard'', addresses and ports appear as ``*''. -.PP +or ``wildcard'', addresses and ports appear as ``*''. +.Pp The interface display provides a table of cumulative statistics regarding packets transferred, errors, and collisions. The network addresses of the interface and the maximum transmission unit (``mtu'') are also displayed. -.PP +.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 @@ -216,11 +184,11 @@ to the same destination. The use field provides a count of the number of packets sent using that route. The interface entry indicates the network interface utilized for the route. -.PP -When -.I netstat +.Pp +When +.Nm netstat is invoked with an -.I interval +.Ar interval argument, it displays a running count of statistics related to network interfaces. This display consists of a column for the primary interface @@ -228,19 +196,22 @@ column for the primary interface and a column summarizing information for all interfaces. The primary interface may be replaced with another interface with the -.I \-I +.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 accumulated over the preceding interval. -.SH SEE ALSO -iostat(1), -vmstat(1), -hosts(5), -networks(5), -protocols(5), -services(5), -trpt(8) -.SH BUGS +.Sh SEE ALSO +.Xr iostat 1 , +.Xr vmstat 1 , +.Xr hosts 5 , +.Xr networks 5 , +.Xr protocols 5 , +.Xr services 5 , +.Xr trpt 8 +.Sh HISTORY +.Nm Netstat +appeared in 4.2 BSD. +.Sh BUGS The notion of errors is ill-defined. Collisions mean something else for the IMP. diff --git a/usr/src/usr.bin/nfsstat/nfsstat.1 b/usr/src/usr.bin/nfsstat/nfsstat.1 index 7412658fc3..ebde2f4747 100644 --- a/usr/src/usr.bin/nfsstat/nfsstat.1 +++ b/usr/src/usr.bin/nfsstat/nfsstat.1 @@ -1,57 +1,59 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)nfsstat.1 5.1 (Berkeley) %G% +.\" @(#)nfsstat.1 5.2 (Berkeley) %G% .\" -.TH NFSSTAT 1 "" -.UC 7 -.SH NAME -nfsstat \- report NFS statistics -.SH SYNOPSIS -.B nfsstat -[ -.B interval -[ -.B system -[ -.B corefile -] ] ] -.SH DESCRIPTION -.I Nfsstat +.Dd +.Dt NFSSTAT 1 +.Os BSD 4.4 +.Sh NAME +.Nm nfsstat +.Nd report NFS statistics +.Sh SYNOPSIS +.Nm nfsstat +.Ob +.Ar interval +.Op Ar system Op Ar corefile +.Oe +.Sh DESCRIPTION +.Nm Nfsstat delves into the system and normally reports certain statistics kept about -.SM NFS +.Li NFS client and server activity. If -.I interval +.Ar interval is specified, then successive lines are summaries over the last -.I interval +.Ar interval seconds. -The command ``nfsstat 5'' will print what -.SM NFS +The command +.Dq Li nfsstat 5 +will print what +.Li NFS is doing every five seconds. -.PP -A second argument is taken +.Pp +A second argument is taken to be the file containing the system's namelist. -Otherwise, /vmunix is used. +Otherwise, +.Pa /vmunix +is used. A third argument tells -.I nfsstat +.Nm nfsstat where to look for -.IR core . -Otherwise, /dev/kmem is used. -.SH FILES -/dev/kmem, /vmunix -.SH SEE ALSO -.IR netstat (1), -.IR vmstat (1) +.Pa core . +Otherwise, +.Pa /dev/kmem +is used. +.Sh FILES +.Dw /dev/kmem +.Di L +.Dp Pa /dev/kmem +.Dp Pa /vmunix +.Dp +.Sh SEE ALSO +.Xr netstat 1 , +.Xr vmstat 1 +.Sh HISTORY +.Nm Nfsstat +appears in 4.4 BSD. diff --git a/usr/src/usr.bin/nice/nice.1 b/usr/src/usr.bin/nice/nice.1 index ee82872277..4cf7faf59d 100644 --- a/usr/src/usr.bin/nice/nice.1 +++ b/usr/src/usr.bin/nice/nice.1 @@ -1,53 +1,69 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)nice.1 6.3 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH NICE 1 "" -.UC 4 -.SH NAME -nice \- run a command at low priority (\fIsh\fR only) -.SH SYNOPSIS -.B nice -[ -.BI \- number -] -command [ arguments ] -.SH DESCRIPTION -.I Nice -executes -.I command -with low scheduling priority. -If the -.I number -argument is present, the priority is incremented (higher -numbers mean lower priorities) by that amount up to a limit of 20. -The default -.I number -is 10. -.PP -The super-user may run commands with -priority higher than normal -by using a negative priority, -e.g. `\-\-10'. -.SH "SEE ALSO" -csh(1), nice(1), setpriority(2), renice(8) -.SH DIAGNOSTICS -.I Nice -returns the exit status of the subject command. -.SH BUGS -.I Nice +.\" @(#)nice.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt NICE 1 +.Os BSD 4 +.Sh NAME +.Nm nice +.Nd execute a command at a low scheduling priority +.Sh SYNOPSIS +.Nm nice +.Oo +.Op Fl Ar number +.Oo +.Ar command +.Op Ar arguments +.Sh DESCRIPTION +.Nm Nice +runs +.Ar command +at a low priority. +(Think of low and slow). +If +.Ar \-number +is specified, and if it is greater than or equal +to 10 (the default), +.Nm nice +will execute +.Ar command +at that priority. +The upper bound, or lowest priority that +.Nm nice +will run a command is 20. +The lower bounds or +higher priorities (integers less than 10) +can only be requested by the super-user. +Negative numbers are expressed as +.Ar \-\-number. +.Pp +The returned exit status is the exit value from the +command executed by +.Nm nice . +.Sh SEE ALSO +.Xr csh 1 , +.Xr nice 1 , +.\" .Xr setpriority 2 , +.Xr renice 8 +.Sh HISTORY +.Nm Nice +appeared in Version 6 AT&T UNIX. +.Sh BUGS +.Nm Nice is particular to -.IR sh (1). +.Xr sh 1 . If you use -.IR csh (1), +.Xr csh 1 , then commands executed with ``&'' are automatically immune to hangup signals while in the background. -.PP -.I Nice +.Pp +.Nm Nice is built into -.IR csh (1) +.Xr csh 1 with a slightly different syntax than described here. The form ``nice +10'' nices to positive nice, and ``nice \-10'' can be used by the super-user to give a process more of the processor. diff --git a/usr/src/usr.bin/nm/nm.1 b/usr/src/usr.bin/nm/nm.1 index 705f5572e1..96bb870b2b 100644 --- a/usr/src/usr.bin/nm/nm.1 +++ b/usr/src/usr.bin/nm/nm.1 @@ -1,88 +1,88 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)nm.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH NM 1 "" -.UC 4 -.SH NAME -nm \- print name list -.SH SYNOPSIS -.B nm -[ -.B \-agnopruw -] -[ file ... ] -.SH DESCRIPTION -.I Nm -prints the name list (symbol table) of each object -.I file -in the argument list. -If an argument is an archive, a listing for each object file in the -archive will be produced. -If no -.I file -is given, the symbols in ``a.out'' are listed. -.PP -The options are as follows: -.TP -.B \-a -Print symbol table entries inserted for use by debuggers. -.TP -.B \-g -Print only global (external) symbols. -.TP -.B \-n -Sort numerically rather than alphabetically. -.TP -.B \-o -Prepend file or archive element name to each output line rather than only once. -.TP -.B \-p -Don't sort; print in symbol-table order. -.TP -.B \-r -Sort in reverse order. -.TP -.B \-u -Print only undefined symbols. -.TP -.B \-w +.\" @(#)nm.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt NM 1 +.Os BSD 4 +.Sh NAME +.Nm nm +.Nd display name list (symbol table) +.Sh SYNOPSIS +.Nm nm +.Op Fl agnopruw +.Ar +.Sh DESCRIPTION +The symbol table (name list) of each object in +.Ar file(s) +is displayed. +If a library (archive) is given, +.Nm +displays a list for each +object archive member. +If +.Ar file +is not present, +.Nm +searches for the file +.Pa a.out +and if present, displays the symbol +table for +.Pa a.out . +.Pp +.Tp Fl a +Display symbol table entries inserted for use by debuggers. +.Tp Fl g +Restrict display to external (global) symbols. +.Tp Fl n +Present results in numerical order. +.Tp Fl o +Display full path or library name of object on every line. +.Tp Fl p +Do not sort at all. +.Tp Fl r +Reverse order sort. +.Tp Fl u +Display undefined symbols only. +.Tp Fl w Warn about non-object archive members. Normally, nm will silently ignore all archive members which are not object files. -.PP +.Tp +.Pp Each symbol name is preceded by its value (a blank field if the symbol is undefined) and one of the following letters: -.TP -.B \- +.Tw Ds +.Tp Fl debugger symbol table entries (see the -.B \-a +.Fl a option). -.TP -.B A +.Tp Li A absolute -.TP -.B B +.Tp Li B bss segment symbol -.TP -.B C +.Tp Li C common symbol -.TP -.B D +.Tp Li D data segment symbol -.TP -.B f +.Tp Li f file name -.TP -.B T +.Tp Li T text segment symbol -.TP -.B U +.Tp Li U undefined -.PP +.Tp +.Pp If the symbol is local (non-external) the type letter is in lower case. The output is sorted alphabetically. -.SH SEE ALSO -ar(1), ar(5), a.out(5), stab(5) +.Sh SEE ALSO +.Xr ar 1 , +.Xr ar 5 , +.Xr a.out 5 , +.Xr stab 5 +.Sh HISTORY +.Nm Nm +appeared in Version 6 AT&T UNIX. diff --git a/usr/src/usr.bin/nohup/nohup.1 b/usr/src/usr.bin/nohup/nohup.1 index ede10ba9c9..d89ed352bb 100644 --- a/usr/src/usr.bin/nohup/nohup.1 +++ b/usr/src/usr.bin/nohup/nohup.1 @@ -1,49 +1,51 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)nohup.1 6.3 (Berkeley) %G% +.\" @(#)nohup.1 6.4 (Berkeley) %G% .\" -.TH NOHUP 1 "" -.SH NAME -nohup - run a utility immune to hangups and quits -.SH SYNOPSIS -.B nohup command -.SH DESCRIPTION +.Dd +.Dt NOHUP 1 +.Sh NAME +.Nm nohup +.Nd invoke a command immune to hangups +.Sh SYNOPSIS +.Nm nohup +.Ar command +.Op Ar arg ... +.Sh DESCRIPTION The -.I nohup -utility invokes a command with the signals SIGHUP and SIGQUIT -initially ignored. +.Nm nohup +utility invokes +.Ar command +with +its arguments +and at this time sets the signal SIGHUP +to be ignored. The signal SIGQUIT may also be set +to be ignored. If the standard output is a terminal, the standard output is appended to the file -.I nohup.out +.Pa nohup.out in the current directory. If standard error is a terminal, it is directed to the same place as the standard output. -.PP -.I Nohup +.Pp +.Nm Nohup exits 1 if an error occurs, otherwise the exit status is that of -.IR command . -.SH "ENVIRONMENTAL VARIABLES" -.TP -.I HOME +.Ar command . +.Sh ENVIRONMENT +.Tw Fl +.Tp Ev HOME If the output file -.I nohup.out +.Pa nohup.out cannot be created in the current directory, the -.I nohup +.Nm nohup utility uses the directory named by -.I HOME +.Ev HOME to create the file. -.SH "SEE ALSO" -signal(3) +.Tp +.Sh SEE ALSO +.Xr signal 3 +.Sh STANDARDS +The nohup function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/pagesize/pagesize.1 b/usr/src/usr.bin/pagesize/pagesize.1 index 62674ec4ee..0690466cd1 100644 --- a/usr/src/usr.bin/pagesize/pagesize.1 +++ b/usr/src/usr.bin/pagesize/pagesize.1 @@ -1,21 +1,27 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pagesize.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PAGESIZE 1 "" -.UC 5 -.SH NAME -pagesize \- print system page size -.SH SYNOPSIS -.B pagesize -.SH DESCRIPTION -.I Pagesize +.\" @(#)pagesize.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PAGESIZE 1 +.Os BSD 4.2 +.Sh NAME +.Nm pagesize +.Nd print system page size +.Sh SYNOPSIS +.Nm pagesize +.Sh DESCRIPTION +.Nm Pagesize prints the size of a page of memory in bytes, as returned by -.IR getpagesize (2). +.Xr getpagesize 2 . This program is useful in constructing portable shell scripts. -.SH SEE ALSO -getpagesize(2) +.Sh SEE ALSO +.Xr getpagesize 2 +.Sh HISTORY +.Nm Pagesize +appeared in 4.2 BSD. diff --git a/usr/src/usr.bin/pascal/pc/pc.1 b/usr/src/usr.bin/pascal/pc/pc.1 index 675bae734e..69cb95e16e 100644 --- a/usr/src/usr.bin/pascal/pc/pc.1 +++ b/usr/src/usr.bin/pascal/pc/pc.1 @@ -1,255 +1,268 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pc.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PC 1 "" -.UC 4 -.SH NAME -pc \- Pascal compiler -.SH SYNOPSIS -.B pc -[ option ] [ -.B \-i -name ... -] name ... -.SH DESCRIPTION -.I Pc +.\" @(#)pc.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PC 1 +.Os BSD 4 +.Sh NAME +.Nm pc +.Nd Pascal compiler +.Sh SYNOPSIS +.Nm pc +.Op option +.Op Fl i Ar name \&... +.Ar name \&... +.Sh DESCRIPTION +.Nm Pc is a Pascal compiler. If given an argument file ending with -.BR .p , -it will compile the file +.Pa \&.p , +it will compile the file and load it into an executable file called, by default, -.IR a.out . -.PP -A program may be separated into more than one -.B .p +.Pa a.out . +.Pp +A program may be separated into more than one +.Pa \&.p file. -.I Pc +.Nm Pc will compile a number of argument -.B .p +.Pa \&.p files into object files (with the extension -.B .o +.Pa \&.o in place of -.BR .p ). -Object files may then be loaded +.Pa \&.p ) . +Object files may then be loaded into an executable -.I a.out +.Pa a.out file. -Exactly one object file must supply a -.B program +Exactly one object file must supply a +.Ar program statement to successfully create an executable a.out file. -The rest of the files must consist only of +The rest of the files must consist only of declarations which logically nest within the program. References to objects shared between separately compiled files are allowed if the objects are declared in -.BR include d +.Ic included header files, whose names must end with -.BR .h . +.Pa \&.h . Header files may only be included at the outermost level, and thus declare only globally available objects. To allow -.BR function s +.Cx Ic function +.Cx s +.Cx and -.BR procedure s +.Cx Ic procedure +.Cx s +.Cx to be declared, an -.B external +.Ic external directive has been added, whose use is similar to the -.B forward +.Ic forward directive but restricted to appear only in -.B .h +.Pa \&.h files. -.B Function -and -.B procedure +.Ic Function +and +.Ic procedure bodies may not appear in -.B .h +.Pa \&.h files. A binding phase of the compiler checks that declarations are used consistently, to enforce the type checking rules of Pascal. -.PP -Object files +.Pp +Object files created by other language processors may be loaded together with -object files created by -.IR pc . +object files created by +.Nm pc . The -.BR function s +.Cx Ic function +.Cx s +.Cx and -.BR procedure s +.Cx Ic procedure +.Cx s +.Cx they define must have been declared in -.B .h +.Pa \&.h files included by all the -.B .p +.Pa \&.p files which call those routines. Calling conventions are as in C, with -.B var +.Ic var parameters passed by address. -.PP +.Pp See the Berkeley Pascal User's Manual for details. -.PP +.Pp The following options have the same meaning as in -.IR cc (1) +.Xr cc 1 and -.IR f77 (1). +.Xr f77 1 . See -.IR ld (1) +.Xr ld 1 for load-time options. -.TP 6 -.B \-c +.Tw Fl +.Tp Fl c Suppress loading and produce `.o' file(s) from source file(s). -.TP 6 -.B \-g +.Tp Fl g Have the compiler produce additional symbol table information for -.IR dbx (1). -.TP 6 -.BR \-w +.Xr dbx 1 . +.Tp Fl w Suppress warning messages. -.TP 6 -.B \-p +.Tp Fl p Prepare object files for profiling, see -.IR prof (1). -.TP 6 -.SM -.B \-O +.Xr prof 1 . +.Tp Fl O Invoke an object-code improver. -.TP 6 -.SM -.B \-S +.Tp Fl S Compile the named program, and leave the assembler-language output on the corresponding file suffixed `.s'. (No `.o' is created.). -.TP 6 -.BR \-o " output" +.Tp Cx Fl o +.Ws +.Ar output +.Cx Name the final output file -.I output +.Ar output instead of -.I a.out. -.PP +.Pa a.out . +.Tp +.Pp The following options are peculiar to -.IR pc . -.TP 6 -.B \-C +.Nm pc . +.Tw Fl +.Tp Fl C Compile code to perform runtime checks, verify -.B assert +.Ic assert calls, and initialize all variables to zero as in -.IR pi . -.TP 6 -.B \-b +.Nm pi . +.Tp Fl b Block buffer the file -.I output. -.TP 6 -.B \-i +.Ar output . +.Tp Fl i Produce a listing for the specified procedures, functions and -.B include +.Ar include files. -.TP 6 -.B \-l +.Tp Fl l Make a program listing during translation. -.TP 6 -.B \-s +.Tp Fl s Accept standard Pascal only; non-standard constructs cause warning diagnostics. -.TP 6 -.BR \-t " directory" +.Tp Cx Fl t +.Ws +.Ar directory +.Cx Use the given -.I directory +.Ar directory for compiler temporary files. -.TP 6 -.B \-z +.Tp Fl z Allow execution profiling with -.I pxp +.Nm pxp by generating statement counters, and arranging for the creation of the profile data file -.I pmon.out +.Pa pmon.out when the resulting object is executed. -.PP +.Pp +.Tp Other arguments are taken to be loader option arguments, perhaps libraries of -.IR pc +.Nm pc compatible routines. Certain flags can also be controlled in comments within the program as described in the -.I "Berkeley Pascal User's Manual." -.SH FILES -.ta 2.5i -file.p pascal source files -.br -/usr/lib/pc0 compiler -.br -/lib/f1 code generator -.br -/usr/lib/pc2 runtime integrator (inline expander) -.br -/lib/c2 peephole optimizer -.br -/usr/lib/pc3 separate compilation consistency checker +.Em "Berkeley Pascal User's Manual." +.Sh FILES +.Dw /usr/lib.pc2.*strings +.Di L +.Dp Pa file.p +pascal source files +.Dp Pa /usr/lib/pc0 +compiler +.Dp Pa /lib/f1 +code generator +.Dp Pa /usr/lib/pc2 +runtime integrator (inline expander) +.Dp Pa /lib/c2 +peephole optimizer +.Dp Pa /usr/lib/pc3 +separate compilation consistency checker +.Dp Pa /usr/lib/pc2.*strings +text of the error messages +.Dp Pa /usr/lib/how_pc +basic usage explanation +.Dp Pa /usr/lib/libpc.a +intrinsic functions and I/O library +.Dp Pa /usr/lib/libm.a +math library +.Dp Pa /lib/libc.a +standard library, see +.Xr intro 3 +.Dp +.Sh SEE ALSO +.Em Berkeley Pascal User's Manual .br -/usr/lib/pc2.*strings text of the error messages -.br -/usr/lib/how_pc basic usage explanation -.br -/usr/lib/libpc.a intrinsic functions and I/O library -.br -/usr/lib/libm.a math library -.br -/lib/libc.a standard library, see \fIintro\fP(3) -.SH "SEE ALSO" -Berkeley Pascal User's Manual -.br -pi(1), -pxp(1), -pxref(1), -sdb(1) -.SH DIAGNOSTICS +.Xr pi 1 , +.Xr pxp 1 , +.Xr pxref 1 , +.\" .Xr sdb 1 +.Sh HISTORY +.Nm Pc +appeared in 4.0 BSD. +.Sh DIAGNOSTICS For a basic explanation do -.IP -.B pc -.PP -See -.IR pi (1). +.Pp +.Df I +.Nm pc +.De +.Pp +See +.Xr pi 1 . for an explanation of the error message format. Internal errors cause messages containing the word SNARK. -.SH AUTHORS +.Sh AUTHORS Charles B. Haley, William N. Joy, and Ken Thompson .br Retargetted to the second pass of the portable -.IR C +.Ar C compiler by Peter Kessler .br Runtime library and inline optimizer by M. Kirk McKusick .br Separate compilation consistency checking by Louise Madrid -.SH BUGS +.Sh BUGS The keyword -.B packed +.Ic packed is recognized but has no effect. -.PP +.Pp The binder is not as strict as described here, with regard to the rules about external declarations only in `.h' files and including `.h' files only at the outermost level. It will be made to perform these checks in its next incarnation, so users are warned not to be sloppy. -.PP +.Pp The -.B \-z +.Fl z flag doesn't work for separately compiled files. -.PP +.Pp Because the -.B \-s +.Fl s option is usurped by the compiler, it is not possible to pass the strip option to the loader. -Thus programs which are to be stripped, must be run through -.IR strip (1) +Thus programs which are to be stripped, must be run through +.Xr strip 1 after they are compiled. diff --git a/usr/src/usr.bin/pascal/pdx/pdx.1 b/usr/src/usr.bin/pascal/pdx/pdx.1 index a3c4ee1fe6..152b7f4b8d 100644 --- a/usr/src/usr.bin/pascal/pdx/pdx.1 +++ b/usr/src/usr.bin/pascal/pdx/pdx.1 @@ -1,274 +1,553 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pdx.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PDX 1 "" -.UC 5 -.SH NAME -pdx \- pascal debugger -.SH SYNOPSIS -pdx [\fB\-r\fP] [\fIobjfile\fP] -.SH DESCRIPTION -\fIPdx\fP is a tool for source level debugging and execution of +.\" @(#)pdx.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PDX 1 +.Os BSD 4.2 +.Sh NAME +.Nm pdx +.Nd pascal debugger +.Sh SYNOPSIS +.Nm pdx +.Op Fl r +.Op Ar objfile +.Sh DESCRIPTION +.Nm Pdx +is a tool for source level debugging and execution of Pascal programs. -The \fIobjfile\fP is an object file produced by the Pascal translator -\fIpi\fP(1). If no \fIobjfile\fP is specified, \fIpdx\fP looks +The +.Ar objfile +is an object file produced by the Pascal translator +.Xr pi 1 . +If no +.Ar objfile +is specified, +.Nm pdx +looks for a file named ``obj'' in the current directory. The object file contains a symbol table which includes the name of the -all the source files translated by \fIpi\fP to create it. +all the source files translated by +.Xr pi 1 +to create it. These files are available for perusal while using the debugger. -.PP -If the file ``.pdxinit'' exists in the current directory, then the +.Pp +If the file +.Dq Pa .pdxinit +exists in the current directory, then the debugger commands in it are executed. -.PP -The \fB\-r\fP option causes the \fIobjfile\fP to be executed immediately; -if it terminates successfully \fIpdx\fP exits. +.Pp +.Tp Fl r +The +.Fl r +option causes the +.Ar objfile +to be executed immediately; +if it terminates successfully +.Nm pdx +exits. Otherwise it reports the reason for termination and offers the user the option of entering the debugger -or simply letting \fIpx\fP continue with a traceback. -If \fB\-r\fP is not specified, \fIpdx\fP just prompts and waits for a command. -.PP +or simply letting +.Xr px +continue with a traceback. +If +.Fl r +is not specified, +.Nm pdx +just prompts and waits for a command. +.Tp +.Pp The commands are: -.TP -\fBrun\fP [\fIargs\fP] [\fB<\fP \fIfilename\fP] [\fB>\fP \fIfilename\fP] -Start executing \fIobjfile\fP, passing \fIargs\fP as command line arguments; -\fB<\fP or \fB>\fP can be used to redirect input or output in the usual manner. -.TP -\fBtrace\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIprocedure/function\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIexpression\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP] -.ns -.TP -\fBtrace\fP \fIvariable\fP [\fBin\fP \fIprocedure/function\fP] [\fBif\fP \fIcondition\fP] +.Dw Fl +.Di L +.Dp Cx Ic run +.Cx \&\ \& +.Op Ar args +.Cx \&\ \& +.Op Ic \&< Ar filename +.Cx \&\ \& +.Op Ic \&> Ar filename +.Cx +Start executing +.Ar objfile , +passing +.Ar args +as command line arguments; +.Ic \&< +or +.Ic \&> +can be used to redirect input or output in the usual manner. +.Pp +.Dp Cx Ic trace +.Pp +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar source-line-number +.Op Ic if Ar condition +.Cx \&\ \& +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar procedure/function +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Ic at +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic trace +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ic in Ar procedure/function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx Have tracing information printed when the program is executed. A number is associated with the command that is used -to turn the tracing off (see the \fBdelete\fP command). -.sp 1 +to turn the tracing off (see the +.Ic delete +command). +.Pp The first argument describes what is to be traced. -If it is a \fIsource-line-number\fP, then the line is printed +If it is a +.Ar source-line-number , +then the line is printed immediately prior to being executed. Source line numbers in a file other than the current one must be preceded by the name of the file and a colon, e.g. ``mumble.p:17''. -.sp 1 +.Pp If the argument is a procedure or function name then every time it is called, information is printed telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it's a function then the value it is returning is also printed. -.sp 1 -If the argument is an \fIexpression\fP with an \fBat\fP clause +.Pp +If the argument is an +.Ar expression +with an +.Ic at +clause then the value of the expression is printed whenever the identified source line is reached. -.sp 1 +.Pp If the argument is a variable then the name and value of the variable is printed whenever it changes. Execution is substantially slower during this form of tracing. -.sp 1 +.Pp If no argument is specified then all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. -.sp 1 -The clause ``\fBin\fP \fIprocedure/function\fP'' restricts tracing information +.Pp +The clause +.Dq Cx Ic in +.Cx \&\ \& +.Ar procedure/function +.Cx +restricts tracing information to be printed only while executing inside the given procedure or function. -.sp 1 -\fICondition\fP is a Pascal boolean expression and is +.Pp +.Ar Condition +is a Pascal boolean expression and is evaluated prior to printing the tracing information; if it is false then the information is not printed. -.sp 1 +.Pp There is no restriction on the amount of information that can be traced. -.br +.Pp .ne 10 -.IP "\fBstop\fP \fBif\fP \fIcondition\fP" -.ns -.IP "\fBstop\fP \fBat\fP \fIsource-line-number\fP [\fBif\fP \fIcondition\fP]" -.ns -.IP "\fBstop\fP \fBin\fP \fIprocedure/function\fP [\fBif\fP \fIcondition\fP]" -.ns -.IP "\fBstop\fP \fIvariable\fP [\fBif\fP \fIcondition\fP]" +.Dp Cx Ic stop +.Cx \&\ \& +.Ic if +.Cx \&\ \& +.Ar condition +.Cx +.Dp Cx Ic stop +.Cx \&\ \& +.Ic at +.Cx \&\ \& +.Ar source-line-number +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic stop +.Cx \&\ \& +.Ic in +.Cx \&\ \& +.Ar procedure /function +.Cx \&\ \& +.Op Ic if Ar condition +.Cx +.Dp Cx Ic stop +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Op Ic if Ar condition +.Cx Stop execution when the given line is reached, procedure or function called, variable changed, or condition true. -.IP "\fBdelete\fP \fIcommand-number\fP" +.Pp +.Dp Cx Ic delete +.Cx \&\ \& +.Ar command-number +.Cx The trace or stop corresponding to the given number is removed. The numbers associated with traces and stops are printed by -the \fBstatus\fP command. -.IP "\fBstatus\fP [\fB>\fP \fIfilename\fP]" +the +.Ic status +command. +.Pp +.Dp Cx Ic status +.Cx \&\ \& +.Op Ic \&> Ar filename +.Cx Print out -the currently active \fBtrace\fP and \fBstop\fP commands. -.IP \fBcont\fP +the currently active +.Ic trace +and +.Ic stop +commands. +.Pp +.Dp Ic cont Continue execution from where it stopped. This can only be done when the program was stopped by an interrupt -or through use of the \fBstop\fP command. -.IP \fBstep\fP +or through use of the +.Ic stop +command. +.Pp +.Dp Ic step Execute one source line. -.IP \fBnext\fP +.Pp +.Dp Ic next Execute up to the next source line. -The difference between this and \fBstep\fP is that +The difference between this and +.Ic step +is that if the line contains a call to a procedure or function -the \fBstep\fP command will stop at the beginning of that -block, while the \fBnext\fP command will not. -.IP "\fBprint\fP \fIexpression\fP [\fB,\fP \fIexpression\fP ...]" +the +.Ic step +command will stop at the beginning of that +block, while the +.Ic next +command will not. +.Pp +.Dp Cx Ic print +.Cx \&\ \& +.Ar expression +.Cx \&\ \& +.Op Ic \&, Ar expression ... +.Cx Print out the values of the Pascal expressions. Variables declared in an outer block but having the same identifier as one in the current block may be -referenced as ``\fIblock-name\fP\ \fB.\fP\ \fIvariable\fP''. -.IP "\fBwhatis\fP \fIidentifier\fP" +referenced as +.Dq Ar block-name \&. variable +.Pp +.Dp Cx Ic whatis +.Cx \&\ \& +.Ar identifier +.Cx Print the declaration of the given identifier. -.IP "\fBwhich\fP \fIidentifier\fP" +.Pp +.Dp Cx Ic which +.Cx \&\ \& +.Ar identifier +.Cx Print the full qualification of the given identifer, i.e. the outer blocks that the identifier is associated with. -.IP "\fBassign\fP \fIvariable\fP \fIexpression\fP" +.Pp +.Dp Cx Ic assign +.Cx \&\ \& +.Ar variable +.Cx \&\ \& +.Ar expression +.Cx Assign the value of the expression to the variable. -.IP "\fBcall\fP \fIprocedure(parameters)\fP" +.Pp +.Dp Cx Ic call +.Cx \&\ \& +.Ar procedure (parameters) +.Cx Execute the object code associated with the named procedure or function. -.IP \fBhelp\fP -Print out a synopsis of \fIpdx\fP commands. -.IP \fBgripe\fP -Invokes a mail program to send a message to the person in charge of \fIpdx\fP. -.IP \fBwhere\fP +.Pp +.Dp Ic help +Print out a synopsis of +.Nm pdx +commands. +.Pp +.Dp Ic gripe +Invokes a mail program to send a message to the person in charge of +.Nm pdx . +.Pp +.Dp Ic where Print out a list of the active procedures and functions and the respective source line where they are called. -.TP -\fBsource\fP \fIfilename\fP -Read \fIpdx\fP commands from the given \fIfilename\fP. -Especially useful when the \fIfilename\fP has been created by redirecting -a \fBstatus\fP command from an earlier debugging session. -.IP "\fBdump\fP [\fB>\fP \fIfilename\fP]" +.Pp +.Dp Cx Ic source +.Cx \&\ \& +.Ar filename +.Cx +Read +.Nm pdx +commands from the given +.Ar filename . +Especially useful when the +.Ar filename +has been created by redirecting +a +.Ic status +command from an earlier debugging session. +.Pp +.Dp Cx Ic dump +.Cx \&\ \& +.Op Ic \&> Ar filename +.Cx Print the names and values of all active data. -.IP "\fBlist\fP [\fIsource-line-number\fP [\fB,\fP \fIsource-line-number\fP]]" -.ns -.IP "\fBlist\fP \fIprocedure/function\fP" +.Pp +.Dp Cx Ic list +.Cx \&\ \&[ +.Ar source-line-number +.Cx \&\ \& +.Op \&, Ar source-line-number +.Cx \&] +.Cx +.Dp Cx Ic list +.Cx \&\ \& +.Ar procedure/function +.Cx List the lines in the current source file from the first line number to the second inclusive. As in the editor ``$'' can be used to refer to the last line. If no lines are specified, the entire file is listed. If the name of a procedure or function is given -lines \fIn-k\fP to \fIn+k\fP are listed where \fIn\fP is the first statement -in the procedure or function and \fIk\fP is small. -.IP "\fBfile\fP [\fIfilename\fP]" -Change the current source file name to \fIfilename\fP. +lines +.Ar n-k +to +.Ar n+k +are listed where +.Ar n +is the first statement +in the procedure or function and +.Ar k +is small. +.Pp +.Dp Cx Ic file +.Cx \&\ \& +.Op Ar filename +.Cx +Change the current source file name to +.Ar filename . If none is specified then the current source file name is printed. -.IP "\fBedit\fP [\fIfilename\fP]" -.ns -.IP "\fBedit\fP \fIprocedure/function-name\fP" -Invoke an editor on \fIfilename\fP or the current source file if none +.Pp +.Dp Cx Ic edit +.Cx \&\ \& +.Op Ar filename +.Cx +.Dp Cx Ic edit +.Cx \&\ \& +.Ar procedure/function-name +.Cx +Invoke an editor on +.Ar filename +or the current source file if none is specified. -If a \fIprocedure\fP or \fIfunction\fP name is specified, +If a +.Ar procedure +or +.Ar function +name is specified, the editor is invoked on the file that contains it. Which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable EDITOR to the name of the desired editor. -.IP \fBpi\fP +.Pp +.Dp Ic pi Recompile the program and read in the new symbol table information. -.IP "\fBsh\fP \fIcommand-line\fP" +.Pp +.Dp Cx Ic sh +.Cx \&\ \& +.Ar command-line +.Cx Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used. -.IP "\fBalias\fP \fInew-command-name\fP \fIold-command-name\fP" -This command makes \fIpdx\fP respond to \fInew-command-name\fP -the way it used to respond to \fIold-command-name\fP. -.IP "\fBquit\fP" -Exit \fIpdx\fP. -.sp 4 -.PP -The following commands deal with the program at the \fIpx\fP instruction +.Pp +.Dp Cx Ic alias +.Cx \&\ \& +.Ar new-command-name +.Cx \&\ \& +.Ar old-command-name +.Cx +This command makes +.Nm pdx +respond to +.Ar new-command-name +the way it used to respond to +.Ar old-command-name . +.Pp +.Dp Ic quit +Exit +.Nm pdx . +.Dp +.Pp +The following commands deal with the program at the +.Ar px +instruction level rather than source level. They are not intended for general use. -.TP -\fBtracei\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBtracei\fP [\fIvariable\fP] [\fBat\fP \fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBstopi\fP [\fIaddress\fP] [\fBif\fP \fIcond\fP] -.ns -.TP -\fBstopi\fP [\fBat\fP] [\fIaddress\fP] [\fBif\fP \fIcond\fP] -Turn on tracing or set a stop using a \fIpx\fP machine +.Dw Fl +.Di L +.Dp Cx Ic tracei +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +.Dp Cx Ic tracei +.Cx \&\ \& +.Op Ar variable +.Cx \&\ \& +.Op Ic at Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +.Dp Cx Ic stopi +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +.Dp Cx Ic stopi +.Cx \&\ \& +.Op Ic at +.Cx \&\ \& +.Op Ar address +.Cx \&\ \& +.Op Ic if Ar cond +.Cx +Turn on tracing or set a stop using a +.Ic px +machine instruction addresses. -.TP -\fBxi\fP \fIaddress\fP [\fB,\fP \fIaddress\fP] -Print the instructions starting at the first \fIaddress\fP. +.Pp +.Dp Cx Ic xi +.Cx \&\ \& +.Ar address +.Cx \&\ \& +.Op Ic \&, Ar address +.Cx +Print the instructions starting at the first +.Ar address . Instructions up to -the second \fIaddress\fP are printed. -.TP -\fBxd\fP \fIaddress\fP [\fB,\fP \fIaddress\fP] +the second +.Ar address +are printed. +.Pp +.Dp Cx Ic xd +.Cx \&\ \& +.Ar address +.Cx \&\ \& +.Op Ic \&, Ar address +.Cx Print in octal the specified data location(s). -.SH FILES -.nr In 25 -.in +\n(Inn -.ta \n(Inn -.br -.nr wg 1v -.ie \n(.h=\n(vk .nr wg -\n(vhu -.el .nr vh 0 -.if \n(wg>0 \{\ -.sp \n(wgu -.nr vh +\n(wgu \} -.nr vk \n(.h -.ti -\n(Inn -\&obj \c +.Dp +.Sh ENVIRONMENT +.Tw Ar +.Tp Ev EDITOR +The +.Ic edit +function uses the +.Ev EDITOR +environment variable to see what editor to use. +.Tp Ev SHELL +The function +.Ic sh +checks the +.Ev SHELL +variable to see which shell to +execute. +.Tp +.Sh FILES +.Dw .pdxinit +.Di L +.Dp Pa \&obj Pascal object file +.Dp Pa \&.pdxinit +.Nm Pdx +initialization file +.Dp +.Sh SEE ALSO +.Xr pi 1 , +.Xr px 1 .br -.nr wg 0v -.ie \n(.h=\n(vk .nr wg -\n(vhu -.el .nr vh 0 -.if \n(wg>0 \{\ -.sp \n(wgu -.nr vh +\n(wgu \} -.nr vk \n(.h -.ti -\n(Inn -\&\&.pdxinit \c -\fIPdx\fP initialization file -.in -\n(Inn -.br -.nr wg 1v -.ie \n(.h=\n(vk .nr wg -\n(vhu -.el .nr vh 0 -.if \n(wg>0 \{\ -.sp \n(wgu -.nr vh +\n(wgu \} -.nr vk \n(.h -.SH SEE ALSO -pi(1), px(1) -.br -\fIAn Introduction to Pdx\fP -.SH BUGS -\fIPdx\fP does not understand sets, +.Em Ar An Introduction to Pdx +.Sh HISTORY +.Nm Pdx +appeared in 4.2 BSD. +.Sh BUGS +.Nm Pdx +does not understand sets, and provides no information about files. -.sp 1 -The \fIwhatis\fP command doesn't quite work for variant records. -.sp 1 +.Pp +The +.Ic whatis +command doesn't quite work for variant records. +.Pp Bad things will happen if a procedure invoked with -the \fBcall\fP command does a non-local goto. -.sp 1 -The commands \fBstep\fP and \fBnext\fP should be able to take a \fIcount\fP +the +.Ic call +command does a non-local goto. +.Pp +The commands +.Ic step +and +.Ic next +should be able to take a +.Ar count that specifies how many lines to execute. -.sp 1 -There should be commands \fBstepi\fP and \fBnexti\fP that correspond -to \fBstep\fP and \fBnext\fP but work at the instruction level. -.sp 1 +.Pp +There should be commands +.Ic stepi +and +.Ic nexti +that correspond +to +.Ic step +and +.Ic next +but work at the instruction level. +.Pp There should be a way to get an address associated with a line number, procedure or function, and variable. -.sp 1 +.Pp Most of the command names are too long. -.sp 1 +.Pp The alias facility is quite weak. -.sp 1 -A \fIcsh\fP-like history capability would improve the situation. +.Pp +A +.Xr csh 1 +\- like history capability would improve the situation. diff --git a/usr/src/usr.bin/pascal/pi/pi.1 b/usr/src/usr.bin/pascal/pi/pi.1 index 6cec2492ee..700c592214 100644 --- a/usr/src/usr.bin/pascal/pi/pi.1 +++ b/usr/src/usr.bin/pascal/pi/pi.1 @@ -1,113 +1,109 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pi.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PI 1 "" +.\" @(#)pi.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PI 1 .UC -.SH NAME -pi \- Pascal interpreter code translator -.SH SYNOPSIS -.B pi -[ -.B option -] [ -.B \-i -name ... -] name.p -.SH DESCRIPTION -.I Pi +.Sh NAME +.Nm pi +.Nd Pascal interpreter code translator +.Sh SYNOPSIS +.Nm pi +.Op Fl blnpstuwz +.Op Fl i Ar name ... +.Ar name.p +.Sh DESCRIPTION +.Nm Pi translates the program in the file -.I name.p +.Ar name.p leaving interpreter code in the file -.I obj +.Pa obj in the current directory. The interpreter code can be executed using -.I px. -.I Pix +.Nm px . +.Nm Pix performs the functions of -.I pi +.Nm pi and -.I px +.Nm px for `load and go' Pascal. -.PP -The following flags are interpreted by -.I pi; +.Pp +The following flags are interpreted by +.Nm pi ; the associated options can also be controlled in comments within the program as described in the -.I "Berkeley Pascal User's Manual." -.TP 6 -.B \-b +.Em "Berkeley Pascal User's Manual." +.Tw Fl +.Tp Fl b Block buffer the file -.I output. -.TP 6 -.B \-i +.Ar output . +.Tp Fl i Enable the listing for any specified procedures and functions and while processing any specified -.B include +.Ic include files. -.TP 6 -.B \-l +.Tp Fl l Make a program listing during translation. -.TP 6 -.B \-n +.Tp Fl n Begin each listed -.B include +.Ic include file on a new page with a banner line. -.TP 6 -.B \-p +.Tp Fl p Suppress the post-mortem control flow backtrace if an error occurs; suppress statement limit counting. -.TP 6 -.B \-s +.Tp Fl s Accept standard Pascal only; non-standard constructs cause warning diagnostics. -.TP 6 -.B \-t +.Tp Fl t Suppress runtime tests of subrange variables and treat -.B assert +.Ic assert statements as comments. -.TP 6 -.B \-u +.Tp Fl u Card image mode; only the first 72 characters of input lines are used. -.TP 6 -.B \-w +.Tp Fl w Suppress warning diagnostics. -.TP 6 -.B \-z +.Tp Fl z Allow execution profiling with -.I pxp +.Nm pxp by generating statement counters, and arranging for the creation of the profile data file -.I pmon.out +.Pa pmon.out when the resulting object is executed. -.dt -.SH FILES -file.p input file -.br -file.i \fBinclude\fR file(s) -.br -/usr/lib/pi2.*strings text of the error messages -.br -.nf -/usr/lib/how_pi* basic usage explanation -.fi -obj interpreter code output -.SH "SEE ALSO" -Berkeley Pascal User's Manual +.Tp +.Sh FILES +.Dw /usr/lib/pi1.*strings +.Di L +.Dp Pa file.p +input file +.Dp Pa file.i +include file(s) +.Dp Pa /usr/lib/pi2.*strings +text of the error messages +.Dp Pa /usr/lib/how_pi* +basic usage explanation +.Dp Pa obj +interpreter code output +.Dp +.Sh SEE ALSO +.Em Berkeley Pascal User'.Xr s Manual .br -pix(1), -px(1), -pxp(1), -pxref(1) -.SH DIAGNOSTICS +.Xr pix 1 , +.Xr px 1 , +.Xr pxp 1 , +.Xr pxref 1 +.Sh DIAGNOSTICS For a basic explanation do -.IP -.B pi -.PP +.Pp +.Df I +.Nm pi +.De +.Pp In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the point of error. @@ -116,46 +112,53 @@ took in order to be able to continue parsing. Some diagnostics indicate only that the input is `malformed.' This occurs if the recovery can find no simple correction to make the input syntactically valid. -.LP +.Pp Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis `...'. -.LP +.Pp .ne 8 The first character of each error message indicates its class: -.LP -.ta 1ic 2.i - E Fatal error; no code will be generated. -.br - e Non-fatal error. -.br - w Warning \- a potential problem. -.br - s Non-standard Pascal construct warning. -.LP +.Pp +.Dw Fl +.Di L +.Dp Li E +Fatal error; no code will be generated. +.Dp e +Non-fatal error. +.Dp w +Warning \- a potential problem. +.Dp s +Non-standard Pascal construct warning. +.Dp +.Pp If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then `QUIT'. -.SH AUTHORS +.Sh AUTHORS Charles B. Haley, William N. Joy, and Ken Thompson .br Ported to VAX-11 by Peter Kessler -.SH BUGS +.Sh BUGS The keyword -.B packed +.Ic packed is recognized but has no effect. -.PP +.Pp For clarity, semantic errors should be flagged at an appropriate place in the source text, and multiple instances of the `same' semantic error should be summarized at the end of a -.B procedure +.Ic procedure or -.B function +.Ic function rather than evoking many diagnostics. -.PP +.Pp When -.B include +.Ic include files are present, diagnostics relating to the last procedure in one file may appear after the beginning of the listing of the next. +.\" .Sh ENVIRONMENT +.Sh HISTORY +.Nm Pi +appeared in 3 BSD. diff --git a/usr/src/usr.bin/pascal/pix/pix.1 b/usr/src/usr.bin/pascal/pix/pix.1 index b2760b0f5d..57bee2d3e2 100644 --- a/usr/src/usr.bin/pascal/pix/pix.1 +++ b/usr/src/usr.bin/pascal/pix/pix.1 @@ -1,60 +1,63 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pix.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PIX 1 "" +.\" @(#)pix.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt PIX 1 .UC -.SH NAME -pix \- Pascal interpreter and executor -.SH SYNOPSIS -.B pix -[ -.B \-blnpstuwz -] [ -.B \-i -name ... -] -name.p -[ -argument ... -] -.SH DESCRIPTION -.I Pix +.Sh NAME +.Nm pix +.Nd Pascal interpreter and executor +.Sh SYNOPSIS +.Nm pix +.Op Fl blnpstuwz +.Op Fl i Ar name ... +.Ar name.p +.Op Ar argument ... +.Sh DESCRIPTION +.Nm Pix is a `load and go' version of Pascal which combines the functions of the interpreter code translator -.I pi +.Nm pi and the executor -.IR px . +.Nm px . It uses -.I pi +.Nm pi to translate the program in the file -.I name.p +.Pa name.p and, if there were no fatal errors during translation, causes the resulting interpreter code to be executed by -.I px +.Nm px with the specified arguments. A temporary file is used for the object code; the file -.I obj +.Pa obj is neither created nor destroyed. -.SH FILES -.ta 2i -/usr/ucb/pi Pascal translator -.br -/usr/ucb/px Pascal executor -.br -/tmp/pix* temporary -.br -/usr/lib/how_pix basic explanation -.SH SEE\ ALSO -Berkeley Pascal User's Manual +.Sh FILES +.Dw /usr/lib/how_pix +.Di L +.Dp Pa /usr/ucb/pi +Pascal translator +.Dp Pa /usr/ucb/px +Pascal executor +.Dp Pa /tmp/pix* +temporary +.Dp Pa /usr/lib/how_pix +basic explanation +.Dp +.Sh SEE ALSO +.Em Berkeley Pascal User'.Xr s Manual .br -pi(1), px(1) -.SH DIAGNOSTICS +.Xr pi 1 , +.Xr px 1 +.Sh DIAGNOSTICS For a basic explanation do -.PP -.DT -.B pix +.Pp +.Dl Nm pix +.Sh HISTORY +.Nm Pix +appeared in 3 BSD. diff --git a/usr/src/usr.bin/pascal/pmerge/pmerge.1 b/usr/src/usr.bin/pascal/pmerge/pmerge.1 index 6ddac82fbb..09775ab1b6 100644 --- a/usr/src/usr.bin/pascal/pmerge/pmerge.1 +++ b/usr/src/usr.bin/pascal/pmerge/pmerge.1 @@ -1,37 +1,45 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pmerge.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PMERGE 1 "" -.UC 4 -.SH NAME -pmerge \- pascal file merger -.SH SYNOPSIS -.B pmerge -name.p ... -.SH DESCRIPTION -.I Pmerge +.\" @(#)pmerge.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PMERGE 1 +.Os BSD 4 +.Sh NAME +.Nm pmerge +.Nd pascal file merger +.Sh SYNOPSIS +.Nm pmerge +.Ar name.p ... +.Sh DESCRIPTION +.Nm Pmerge assembles the named Pascal files into a single standard Pascal program. The resulting program is listed on the standard output. It is intended to be used to merge a collection of separately compiled -modules so that they can be run through -.B pi -, or exported to other sites. -.SH FILES -.ta 1.5i -/usr/tmp/MG\(** default temporary files -.br -.SH "SEE ALSO" -pc(1), -pi(1), +modules so that they can be run through +.Ic pi , +or exported to other sites. +.Sh FILES +.Dw /usr/tmp/MG* +.Di L +.Dp Pa /usr/tmp/MG* +default temporary files +.Dp +.Sh SEE ALSO +.Xr pc 1 , +.Xr pi 1 , .br Auxiliary documentation -.I Berkeley Pascal User's Manual. -.SH AUTHOR +.Em Ar Berkeley Pascal User's Manual . +.Sh HISTORY +.Nm Pmerge +appeared in 4.1 BSD. +.Sh AUTHOR M. Kirk McKusick -.SH BUGS +.Sh BUGS Very minimal error checking is done, so incorrect programs will produce unpredictable results. Block comments should be placed after the keyword to which they refer diff --git a/usr/src/usr.bin/pascal/px/px.1 b/usr/src/usr.bin/pascal/px/px.1 index bff0773e63..414ffcf748 100644 --- a/usr/src/usr.bin/pascal/px/px.1 +++ b/usr/src/usr.bin/pascal/px/px.1 @@ -1,93 +1,94 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)px.1 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PX 1 "" +.\" @(#)px.1 6.3 (Berkeley) %G% +.\" +.Dd +.Dt PX 1 .UC -.SH NAME -px \- Pascal interpreter -.SH SYNOPSIS -.B px -[ obj [ argument ... ] ] -.SH DESCRIPTION -.I Px +.Sh NAME +.Nm px +.Nd Pascal interpreter +.Sh SYNOPSIS +.Nm px +.Op Ar obj Op Ar argument ... +.Sh DESCRIPTION +.Nm Px interprets the abstract machine code generated by -.I pi. +.Xr pi 1 . The first argument is the file to be interpreted, and defaults to -.IR obj \|; +.Ar obj ; remaining arguments are available to the Pascal program using the built-ins -.I argv +.Ar argv and -.I argc. -.I Px +.Ar argc . +.Nm Px is also invoked by -.I pix +.Nm pix when running `load and go'. -.PP -If the program terminates abnormally an error message and a +.Pp +If the program terminates abnormally an error message and a control flow backtrace are printed. The number of statements executed and total execution time are printed after normal termination. The -.B p +.Cm p option of -.I pi +.Nm pi suppresses all of this except the message indicating the cause of abnormal termination. -.SH FILES -.DT -obj default object file -.br -pmon.out profile data file -.SH "SEE ALSO" -Berkeley Pascal User's Manual +.Sh FILES +.Dw pmon.out +.Di L +.Dp Pa obj +default object file +.Dp Pa pmon.out +profile data file +.Dp +.Sh SEE ALSO +.Em Berkeley Pascal User's Manual .br -pi(1), pix(1) -.SH DIAGNOSTICS +.Xr pi 1 , +.Xr pix 1 +.Sh DIAGNOSTICS Most run-time error messages are self-explanatory. Some of the more unusual ones are: -.HP 6 -Reference to an inactive file -.br +.Tw Ds +.Tp Reference to an inactive file A file other than -.I input +.Ar input or -.I output +.Ar output was used before a call to -.I reset +.Ar reset or -.I rewrite. -.HP 6 -Statement count limit exceeded -.br +.Ar rewrite . +.Tp Statement count limit exceeded The limit of 500,000 executed statements (which prevents excessive looping or recursion) has been exceeded. -.HP 6 -Bad data found on integer read -.br -.ns -.HP 6 -Bad data found on real read -.br +.Tp Bad data found on integer read +.Tp Bad data found on real read Usually, non-numeric input was found for a number. For reals, Pascal requires digits before and after the decimal point so that numbers like `.1' or `21.' evoke the second diagnostic. -.HP 6 -panic: -.I "Some message" -.br +.Tp panic: +.Em Some message Indicates an internal inconsistency detected in -.I px +.Nm px probably due to a Pascal system bug. -.SH AUTHORS +.Tp +.Sh AUTHORS Charles B. Haley, William Joy, and Ken Thompson .br VAX-11 version by Kirk McKusick -.SH BUGS +.Sh HISTORY +.Nm Px +appeared in 3 BSD. +.Sh BUGS Post-mortem traceback is not limited; infinite recursion leads to almost infinite traceback. diff --git a/usr/src/usr.bin/pascal/pxp/pxp.1 b/usr/src/usr.bin/pascal/pxp/pxp.1 index 77e5b897f3..c1b1ffdf54 100644 --- a/usr/src/usr.bin/pascal/pxp/pxp.1 +++ b/usr/src/usr.bin/pascal/pxp/pxp.1 @@ -1,174 +1,169 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pxp.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PXP 1 "" +.\" @(#)pxp.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PXP 1 .UC -.SH NAME -pxp \- Pascal execution profiler -.SH SYNOPSIS -.B pxp -[ -.B \-acdefjnstuw_ -] [ -.B \-23456789 -] [ -.B \-z -[ name ... ] ] name.p -.SH DESCRIPTION -.I Pxp +.Sh NAME +.Nm pxp +.Nd Pascal execution profiler +.Sh SYNOPSIS +.Nm pxp +.Op Fl acdefjnstuw_ +.Op Fl 23456789 +.Op Fl z Op Ar name ... +.Ar name.p +.Sh DESCRIPTION +.Nm Pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To produce an execution profile all that is necessary is to translate the program specifying the -.B z +.Fl z option to -.I pi +.Xr pi 1 or -.I pix, +.Xr pix 1 , to execute the program, and to then issue the command -.DT -.PP - \fBpxp \-z\fR name.p -.PP +.Pp +.Dl pxp -x name.p +.Pp A reformatted listing is output if none of the -.BR c , -.BR t , +.Fl c , +.Fl t , or -.B z +.Fl z options are specified; thus -.PP - \fBpxp\fR old.p > new.p -.PP +.Pp +.Dl pxp old.p > new.p +.Pp places a pretty-printed version of the program in `old.p' in the file `new.p'. -.PP +.Pp The use of the following options of -.I pxp +.Nm pxp is discussed in sections 2.6, 5.4, 5.5 and 5.10 of the -.IR "Berkeley Pascal User's Manual" "." -.TP 6 -.B \-a +.Em Berkeley Pascal User's Manual . +.Tp Fl a Print the bodies of all procedures and functions in the profile; even those which were never executed. -.TP 6 -.B \-c +.Tp Fl c Extract profile data from the file -.IR core . -.TP 6 -.B \-d +.Pa core . +.Tp Fl d Include declaration parts in a profile. -.TP 6 -.B \-e +.Tp Fl e Eliminate -.B include +.Ic include directives when reformatting a file; the -.B include +.Ic include is replaced by the reformatted contents of the specified file. -.TP 6 -.B \-f +.Tp Fl f Fully parenthesize expressions. -.TP 6 -.B \-j +.Tp Fl j Left justify all procedures and functions. -.TP 6 -.B \-n -Eject a new page +.Tp Fl n +Eject a new page as each file is included; in profiles, print a blank line at the top of the page. -.TP 6 -.B \-s +.Tp Fl s Strip comments from the input text. -.TP 6 -.B \-t +.Tp Fl t Print a table summarizing -.B procedure +.Ic procedure and -.B function +.Ic function call counts. -.TP 6 -.B \-u +.Tp Fl u Card image mode; only the first 72 characters of input lines are used. -.TP 6 -.B \-w +.Tp Fl w Suppress warning diagnostics. -.TP 6 -.B \-z +.Tp Fl z Generate an execution profile. If no -.IR name \|s, +.Cx Ar name +.Cx \&\'s +.Cx are given the profile is of the entire program. If a list of names is given, then only any specified -.BR procedure s +.Cx Ic procedure +.Cx \&s +.Cx or -.BR function s +.Cx Ic function +.Cx \&s +.Cx and the contents of any specified -.B include +.Ic include files will appear in the profile. -.TP 6 -.B \-\_ +.Tp Fl \&_ Underline keywords. -.TP 6 -.BI \- d +.Tp Fl d With -.I d +.Ar d a digit, 2 \(<= -.IR d "" +.Ar d \(<= 9, causes -.I pxp +.Nm pxp to use -.IR d "" +.Ar d spaces as the basic indenting unit. The default is 4. -.SH FILES -.DT -name.p input file -.br -name.i include file(s) -.br -pmon.out profile data -.br -core profile data source with -.B \-c -.br -/usr/lib/how_pxp information on basic usage -.br -.ne 8 -.SH "SEE ALSO" -Berkeley Pascal User's Manual +.Sh FILES +.Dw /usr/lib/how_pxp +.Di L +.Dp Pa name.p +input file +.Dp Pa name.i +include file(s) +.Dp Pa pmon.out +profile data +.Dp Pa core +profile data source with +.Fl c +.Dp Pa /usr/lib/how_pxp +information on basic usage +.Dp +.Sh SEE ALSO +.Em Berkeley Pascal User's Manual .br -pi(1), -px(1) -.ne 5 -.SH DIAGNOSTICS +.Xr pi 1 , +.Xr px 1 +.Sh DIAGNOSTICS For a basic explanation do -.IP -.DT -.B pxp -.PP +.Pp +.Df I +.Nm pxp +.De +.Pp Error diagnostics include `No profile data in file' with the -.B c +.Fl c option if the -.B z +.Fl z option was not enabled to -.I pi; +.Nm pi ; `Not a Pascal system core file' if the core is not from a -.I px +.Nm px execution; `Program and count data do not correspond' if the program was changed after compilation, before profiling; or if the wrong program is specified. -.SH AUTHOR +.Sh AUTHOR William Joy -.SH BUGS +.Sh HISTORY +.Nm Pxp +appeared in 3 BSD. +.Sh BUGS Does not place multiple statements per line. diff --git a/usr/src/usr.bin/pascal/pxref/pxref.1 b/usr/src/usr.bin/pascal/pxref/pxref.1 index bd3d46c925..488e0b8bb9 100644 --- a/usr/src/usr.bin/pascal/pxref/pxref.1 +++ b/usr/src/usr.bin/pascal/pxref/pxref.1 @@ -1,35 +1,41 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)pxref.1 6.1 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH PXREF 1 "" +.\" @(#)pxref.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PXREF 1 .UC -.SH NAME -pxref \- Pascal cross-reference program -.SH SYNOPSIS -.B pxref -[ -.BR \- "" -] -name -.SH DESCRIPTION -.I Pxref +.Sh NAME +.Nm pxref +.Nd Pascal cross-reference program +.Sh SYNOPSIS +.Nm pxref +.Op Fl +.Ar name +.Sh DESCRIPTION +.Nm Pxref makes a line numbered listing and a cross-reference of identifier usage for the program in -.I name. -The optional `\fB\-\fP' argument suppresses the listing. The keywords -.B goto +.Ar name . +The optional +.Sq Fl +argument suppresses the listing. The keywords +.Ic goto and -.B label +.Ic label are treated as identifiers for the purpose of the cross-reference. -.B Include +.Ic Include directives are not processed, but cause the placement of an entry indexed by `#include' in the cross-reference. -.SH "SEE ALSO" -Berkeley Pascal User's Manual -.SH AUTHOR +.Sh SEE ALSO +.Em Berkeley Pascal User's Manual +.Sh AUTHOR Niklaus Wirth -.SH BUGS +.Sh HISTORY +.Nm Pxref +appeared in 3 BSD. +.Sh BUGS Identifiers are trimmed to 10 characters. diff --git a/usr/src/usr.bin/passwd/passwd.1 b/usr/src/usr.bin/passwd/passwd.1 index de079ad3b3..bdfa33997e 100644 --- a/usr/src/usr.bin/passwd/passwd.1 +++ b/usr/src/usr.bin/passwd/passwd.1 @@ -1,48 +1,55 @@ -.\" Copyright (c) 1988 The Regents of the University of California. +.\" Copyright (c) 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)passwd.1 6.5 (Berkeley) %G% +.\" @(#)passwd.1 6.6 (Berkeley) %G% .\" -.TH PASSWD 1 "" -.UC 4 -.SH NAME -passwd \- change password file information -.SH SYNOPSIS -.B passwd -[ user ] -.SH DESCRIPTION -.I Passwd -changes the user's password. First, the user is prompted for their old -password, and then, if that is correct, for the new password. The new -password must be entered twice to forestall any typing errors. The +.Dd +.Dt PASSWD 1 +.Os BSD 4 +.Sh NAME +.Nm passwd +.Nd modify password file information +.Sh SYNOPSIS +.Nm passwd +.Op Ar user +.Sh DESCRIPTION +.Nm Passwd +changes the user's password. First, the user is prompted for their +current +password, and, if that is correct typed, for a new password. The new +password must be entered two times to verify any typing errors. The super-user is not prompted for the old password. -.PP +.Pp +The new password must be at least six characters long and cannot be +purely alphabetic. Numbers, upper case letters and meta characters +are encouraged. +.Pp Once the password has been verified, -.I passwd +.Nm passwd uses -.IR mkpasswd (8) +.Xr mkpasswd 8 to update the user database. This is run in the background, and, at very large sites could take several minutes. Until this update is completed, the password file is unavailable for other updates and the new password will not be available to programs. -.SH FILES -.DT -/etc/master.passwd the user database -.RE -.SH "SEE ALSO" -chpass(1), login(1), passwd(5), mkpasswd(8), vipw(8) +.Sh FILES +.Dw /etc/master.passwd +.Di L +.Dp Pa /etc/master.passwd +the user database +.Dp +.Sh SEE ALSO +.Xr chpass 1 , +.Xr login 1 , +.Xr passwd 5 , +.Xr mkpasswd 8 , +.Xr vipw 8 .br Robert Morris and Ken Thompson, -.I UNIX password security +.Em UNIX password security +.Sh HISTORY +A +.Nm passwd +command appeared in Version 6 AT&T UNIX. diff --git a/usr/src/usr.bin/paste/paste.1 b/usr/src/usr.bin/paste/paste.1 index 3aa4077cad..c99d8efa3a 100644 --- a/usr/src/usr.bin/paste/paste.1 +++ b/usr/src/usr.bin/paste/paste.1 @@ -1,105 +1,91 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. +.\" .\" This code is derived from software contributed to Berkeley by .\" Adam S. Moskowitz of Menlo Consulting. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)paste.1 5.1 (Berkeley) %G% +.\" @(#)paste.1 5.2 (Berkeley) %G% .\" -.TH PASTE 1 "" -.UC 7 -.SH NAME -paste - merge corresponding or subsequent lines of files -.SH SYNOPSIS -.ft B -.nf -paste [-s] [-d list] file ... -.fi -.ft R -.SH DESCRIPTION +.Dd +.Dt PASTE 1 +.Os BSD 4.4 +.Sh NAME +.Nm paste +.Nd merge corresponding or subsequent lines of files +.Sh SYNOPSIS +.Nm paste +.Op Fl s +.Op Fl d Ar list +.Ar file ... +.Sh DESCRIPTION The -.I paste +.Nm paste utility concatenates the corresponding lines of the given input files, replacing all but the last file's newline characters with a single tab character, and writes the resulting lines to standard output. If end-of-file is reached on an input file while other input files still contain data, the file is treated as if it were an endless source of empty lines. -.PP +.Pp The options are as follows: -.TP --d list +.Tw Fl +.Tp Cx Fl d +.Ar list +.Cx Use one or more of the provided characters to replace the newline characters instead of the default tab. The characters in -.I list +.Ar list are used circularly, i.e., when -.I list +.Ar list is exhausted the first character from -.I list +.Ar list is reused. This continues until a line from the last input file (in default operation) or the last line in each file (using the -s option) is displayed, at which time -.I paste +.Nm paste begins selecting characters from the beginning of -.I list +.Ar list again. -.PP -.RS +.Pp The following special characters can also be used in list: -.TP -\en +.Tw Ds +.Tp Li \en newline character .br -.ns -.TP -\et +.Tp Li \et tab character .br -.ns -.TP -\e\e +.Tp Li \e\e backslash character .br -.ns -.TP -\e0 +.Tp Li \e0 Empty string (not a null character). -.PP +.Pp Any other character preceded by a backslash is equivalent to the character itself. -.RE -.TP --s +.Tp +.Tp Fl s Concatenate all of the lines of each separate input file in command line order. The newline character of every line except the last line in each input file is replaced with the tab character, unless otherwise specified by the -d option. -.PP +.Tp +.Pp If ``-'' is specified for one or more of the input files, the standard input is used; standard input is read one line at a time, circularly, for each instance of ``-''. -.PP +.Pp The -.I paste +.Nm paste utility exits 0 on success, and >0 if an error occurs. -.SH ENVIRONMENT -.SH "SEE ALSO" -cut(1) -.SH STANDARDS +.Sh SEE ALSO +.Xr cut 1 +.Sh STANDARDS The -.I paste +.Nm paste function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.bin/plot/plot.1 b/usr/src/usr.bin/plot/plot.1 index ef92e90972..63b4d61bf5 100644 --- a/usr/src/usr.bin/plot/plot.1 +++ b/usr/src/usr.bin/plot/plot.1 @@ -1,119 +1,138 @@ -.\" @(#)plot.1 6.3 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH PLOT 1G "" -.AT 3 -.SH NAME -plot \- graphics filters -.SH SYNOPSIS -.B plot -[ -.BR \-T terminal -] [ -.BR \-r resolution -] -[ files... ] -.SH DESCRIPTION +.\" %sccs.include.redist.man% +.\" +.\" @(#)plot.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt PLOT 1 +.Os ATT 7th +.Sh NAME +.Nm plot +.Nd graphics filters +.Sh SYNOPSIS +.Nm plot +.Oo +.Op Fl T Ar terminal +.Op Fl r Ar resolution +.Oo +.Ar +.Sh DESCRIPTION These commands read plotting instructions (see -.IR plot (5)) +.Xr plot 5 ) from the standard input or the specified -.IR files , +.Ar files , and in general produce plotting instructions suitable for a particular -.I terminal +.Ar terminal on the standard output. The -.B \-r +.Fl r flag may be used to specify the device's output resolution (currently only the Imagen laser printer understands this option). -.PP +.Pp If no -.I terminal -type is specified, the environment parameter $TERM +.Ar terminal +type is specified, the environment parameter +.Ev $TERM (see -.IR environ (7)) +.Xr environ 7 ) is used. Known -.I terminals +.Ar terminals are: -.TP -.B 4013 +.Tw Cm +.Tp Cm 4013 Tektronix 4013 storage scope. -.TP -.BR 4014\ or\ tek +.Tp Cx Cm 4014 +.Ws +.Cx or +.Ws +.Cm tek +.Cx Tektronix 4014 or 4015 storage scope with Enhanced Graphics Module. (Use 4013 for Tektronix 4014 or 4015 without the Enhanced Graphics Module). -.TP -.B 450 +.Tp Cm 450 DASI Hyterm 450 terminal (Diablo mechanism). -.TP -.B 300 +.Tp Cm 300 DASI 300 or GSI terminal (Diablo mechanism). -.TP -.B 300S +.Tp Cm 300S DASI 300S terminal (Diablo mechanism). -.TP -.B aed +.Tp Cm aed AED 512 color graphics terminal. -.TP -.BR bitgraph\ or\ bg +.Tp Cx Cm bitgraph +.Ws +.Cx or +.Ws +.Cm bg +.Cx BBN bitgraph graphics terminal. -.TP -.B imagen\ or\ ip +.Tp Cx Cm imagen +.Ws +.Cx or +.Ws +.Cm ip +.Cx Imagen laser printer (default 240 dots-per-inch resolution). -.TP -.B crt +.Tp Cm crt Any crt terminal capable of running -.IR vi (1). -.TP -.B dumb +.Xr vi 1 . +.Tp Cm dumb Dumb terminals without cursor addressing or line printers. -.TP -.B vt125 +.Tp Cm vt125 DEC vt125 terminal. -.TP -.BR hp2648\ or\ hp\ or\ hp8 +.Tp Cx Cm hp2648 +.Ws +.Cx or +.Ws +.Cm hp +.Ws +.Cx or +.Ws +.Cm hp8 +.Cx Hewlett Packard 2648 graphics terminal. -.TP -.B ver +.Tp Cm ver Versatec D1200A printer-plotter. -.TP -.B var +.Tp Cm var Benson Varian printer-plotter. -.IP +.Tp +.Pp These versions of -.I plot +.Nm plot use the -.B \-g +.Fl g option of -.IR lpr (1) +.Xr lpr 1 to send the result directly to the plotter device rather than to the standard output. -.SH FILES -/usr/bin/t4013 -.br -/usr/bin/tek -.br -/usr/bin/t450 -.br -/usr/bin/t300 -.br -/usr/bin/t300s -.br -/usr/bin/aedplot -.br -/usr/bin/bgplot -.br -/usr/bin/crtplot -.br -/usr/bin/dumbplot -.br -/usr/bin/gigiplot -.br -/usr/bin/hpplot -.br -/usr/bin/implot -.br -/usr/ucb/lpr -.SH "SEE ALSO" -plot(3X), plot(3F), plot(5), lpr(1) +.Sh ENVIRONMENT +.Tw Fl +.Tp Ev TERM +Used to determine the terminal type if not given as an argument. +.Sh FILES +.Dw /usr/bin/gigiplot +.Di L +.Dp Pa /usr/bin/t4013 +.Dp Pa /usr/bin/tek +.Dp Pa /usr/bin/t450 +.Dp Pa /usr/bin/t300 +.Dp Pa /usr/bin/t300s +.Dp Pa /usr/bin/aedplot +.Dp Pa /usr/bin/bgplot +.Dp Pa /usr/bin/crtplot +.Dp Pa /usr/bin/dumbplot +.Dp Pa /usr/bin/gigiplot +.Dp Pa /usr/bin/hpplot +.Dp Pa /usr/bin/implot +.Dp Pa /usr/ucb/lpr +.Dp +.Sh SEE ALSO +.Xr plot 3 , +.Xr plot 5 , +.Xr lpr 1 +.Sh HISTORY +.Nm Plot +appeared in Version 6 AT&T UNIX. diff --git a/usr/src/usr.bin/printenv/printenv.1 b/usr/src/usr.bin/printenv/printenv.1 index 682c672ab0..8ccb598be8 100644 --- a/usr/src/usr.bin/printenv/printenv.1 +++ b/usr/src/usr.bin/printenv/printenv.1 @@ -1,54 +1,70 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)printenv.1 6.2 (Berkeley) %G% +.\" @(#)printenv.1 6.3 (Berkeley) %G% .\" -.TH PRINTENV 1 "" +.Dd +.Dt PRINTENV 1 .UC -.SH NAME -printenv \- print out the environment -.br -env \- set and print out the environment -.SH SYNOPSIS -.B printenv -[name] -.br -.B env -[-] [name=value ...] [command] -.SH DESCRIPTION -.I Printenv +.Sh NAME +.Nm printenv +.Nd print out the environment +.Nm env +.Nd set and print out the environment +.Sh SYNOPSIS +.Nm printenv +.Op Ar name +.Nm env +.Op Fl +.Op Ar name=value \&... +.Op Ar command +.Sh DESCRIPTION +.Nm Printenv prints out the names and values of the variables in the environment, -with one name/value pair per line. If \fIname\fP is specified, only +with one name/value pair per line. If +.Ar name +is specified, only its value is printed. -.PP +.Pp If a -.I name +.Ar name is specified and it is not defined in the environment, -.I printenv +.Nm printenv returns exit status 1, else it returns status 0. -.PP -\fIEnv\fP executes \fIcommand\fP after modifying the environment as -specified on the command line. The option \fIname=value\fP specifies -an environmental variable, \fIname\fP, with a value of \fIvalue\fP. -The option \fI-\fP causes \fIenv\fP to completely ignore the environment +.Pp +.Nm Env +executes +.Ar command +after modifying the environment as +specified on the command line. The option +.Ar name=value +specifies +an environmental variable, +.Ar name , +with a value of +.Ar value . +The option +.Fl +causes +.Nm env +to completely ignore the environment it inherits. -.PP -If no command is specified, \fIenv\fP prints out the names and values +.Pp +If no command is specified, +.Nm env +prints out the names and values of the variables in the environment, with one name/value pair per line. -.SH SEE ALSO -csh(1), sh(1), execvp(3), environ(7) -.SH BUGS -\fIEnv\fP doesn't handle commands with equal (``='') signs in their +.Sh SEE ALSO +.Xr csh 1 , +.Xr sh 1 , +.Xr execvp 3 , +.Xr environ 7 +.Sh HISTORY +.Nm Printenv +appeared in 3 BSD. +.Sh BUGS +.Nm Env +doesn't handle commands with equal (``='') signs in their names, for obvious reasons. diff --git a/usr/src/usr.bin/printf/printf.1 b/usr/src/usr.bin/printf/printf.1 index 6b13161309..b2d96934e7 100644 --- a/usr/src/usr.bin/printf/printf.1 +++ b/usr/src/usr.bin/printf/printf.1 @@ -1,239 +1,242 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)printf.1 5.6 (Berkeley) %G% +.\" @(#)printf.1 5.7 (Berkeley) %G% .\" -.TH PRINTF 1 " +.Dd +.Dt PRINTF 1 .AT 1 -.SH NAME -printf \- formatted output -.SH SYNOPSIS -.PP -.B printf format [ arguments ... ] -.SH DESCRIPTION -.I Printf +.Sh NAME +.Nm printf +.Nd formatted output +.Sh SYNOPSIS +.Pp +.Nm printf format +.Op arguments ... +.Sh DESCRIPTION +.Nm Printf formats and prints its arguments, after the first, under control of the -.IR format . +.Ar format . The -.I format +.Ar format is a character string which contains three types of objects: plain characters, which are simply copied to standard output, character escape sequences which are converted and copied to the standard output, and format specifications, each of which causes printing of the next successive -.IR argument . -.PP +.Ar argument . +.Pp The -.I arguments +.Ar arguments after the first are treated as strings if the corresponding format is either -.I c +.Cm c or -.IR s ; +.Cm s ; otherwise it is evaluated as a C constant, with the following extensions: -.sp -.RS +.Pp +.Df I A leading plus or minus sign is allowed. +.br If the leading character is a single or double quote, or not a digit, plus, or minus sign, the value is the ASCII code of the next character. -.RE -.PP +.De +.Pp The format string is reused as often as necessary to satisfy the -.IR arguments . +.Ar arguments . Any extra format specifications are evaluated with zero or the null string. -.PP +.Pp Character escape sequences are in backslash notation as defined in the draft proposed ANSI C Standard X3J11. The characters and their meanings are as follows: -.TP -.B \ea +.Tw Ds +.Tp Cm \ea Write a character. -.TP -.B \eb +.Tp Cm \eb Write a character. -.TP -.B \ef +.Tp Cm \ef Write a character. -.TP -.B \en +.Tp Cm \en Write a character. -.TP -.B \er +.Tp Cm \er Write a character. -.TP -.B \et +.Tp Cm \et Write a character. -.TP -.B \ev +.Tp Cm \ev Write a character. -.TP -.B \e' +.Tp Cm \e\' Write a character. -.TP -.B \e\e +.Tp Cm \e\e Write a backslash character. -.TP -.B \enum +.Tp Cx Cm \e +.Ar num +.Cx Write an 8-bit character whose numeric value is the 1-, 2-, or 3-digit octal number -.IR num . -.PP +.Ar num . +.Tp +.Pp Each format specification is introduced by the percent character (``%''). The remainder of the format specification includes, in the following order: -.TP -.B \(bu +.Pp Zero or more of the following flags: -.RS -.TP -.B \(bu -a `#' character +.Pp +.Ds I +.Tw Ds +.Tp Cm # +A `#' character specifying that the value should be printed in an ``alternate form''. -For -.BR c , -.BR d , +For +.Cm c , +.Cm d , and -.BR s , +.Cm s , formats, this option has no effect. For the -.B o +.Cm o formats the precision of the number is increased to force the first character of the output string to a zero. For the -.BR x ( X ) +.Cm x +.Pq Cm X format, a non-zero result has the string -.BR 0x ( 0X ) -prepended to it. For -.BR e , -.BR E , -.BR f , -.BR g , +.Li 0x +.Pq Li 0X +prepended to it. For +.Cm e , +.Cm E , +.Cm f , +.Cm g , and -.BR G , +.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 -.B g +.Cm g and -.B G +.Cm G formats, trailing zeros are not removed from the result as they would otherwise be; -.TP -.B \(bu -a minus sign `\-' which specifies -.I "left adjustment" +.Tp Cm \&\- +A minus sign `\-' which specifies +.Em left adjustment of the output in the indicated field; -.TP -.B \(bu -a `+' character specifying that there should always be +.Tp Cm \&+ +A `+' character specifying that there should always be a sign placed before the number when using signed formats. -.TP -.B \(bu -a space specifying that a blank should be left before a positive number +.Tp 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; -.TP -.B \(bu -a zero `0' character indicating that zero-padding should be used +.Tp 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; -.RE -.TP -.B \(bu -an optional digit string specifying a -.I "field width;" +.Tp +.De +.Pp +.Tw Ds +.Tp Field Width: +An optional digit string specifying a +.Em field width ; if the output string has fewer characters than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width (note that a leading zero is a flag, but an embedded zero is part of a field width); -.TP -.B \(bu -an optional period, followed by an optional digit string giving a -.I precision +.Tp Precision: +An optional period, +.Sq Cm \&.\& , +followed by an optional digit string giving a +.Em precision which specifies the number of digits to appear after the decimal point, -for e- and f-formats, or the maximum number of characters to be printed +for +.Cm e +and +.Cm f +formats, or the maximum number of characters to be printed from a string; if the digit string is missing, the precision is treated as zero; -.TP -.B \(bu -a character which indicates the type of format to use. -.PP -A field width or precision may be `*' instead of a digit string. +.Tp Format: +A character which indicates the type of format to use (one of +.Cm diouxXfwEgGcs ) . +.Tp +.Pp +A field width or precision may be +.Sq Cm \&* +instead of a digit string. In this case an -.I argument +.Ar argument supplies the field width or precision. -.PP +.Pp The format characters and their meanings are: -.TP -.B diouXx +.Tw Fl +.Tp Cm diouXx The -.I argument +.Ar argument is printed as a signed decimal (d or i), unsigned decimal, unsigned octal, or unsigned hexadecimal (X or x), respectively. -.TP -.B f +.Tp Cm f The -.I argument -is printed in the style `[\fB\-\fR]ddd.ddd' where the number of d's +.Ar argument +is printed in the style `[\-]ddd.ddd' where the number of d's after the decimal point is equal to the precision specification for the argument. If the precision is missing, 6 digits are printed after the decimal point; if the precision is explicitly 0, no digits and no decimal point are printed. -.TP -.B eE +.Tp Cm eE The -.I argument -is printed in the style `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' where there +.Ar argument +is printed in the style +.Cx `[-]d.ddd +.Cm e +.Cx \(+-dd\' +.Cx +where there is one digit before the decimal point and the number after is equal to the precision specification for the argument; when the precision is missing, 6 digits are printed after the decimal point. An upper-case E is used for an `E' format. -.TP -.B gG +.Tp Cm gG The -.I argument +.Ar argument is printed in style -.B f +.Cm f or in style -.B e -.RB ( E ) +.Cm e +.Pq Cm E whichever gives full precision in minimum space. -.TP -.B c +.Tp Cm c The first character of -.I argument +.Ar argument is printed. -.TP -.B s +.Tp Cm s Characters from the string -.I argument +.Ar argument are printed until the end is reached or until the number of characters indicated by the precision specification is reached; however if the precision is 0 or missing, all characters in the string are printed. -.TP -.B % +.Tp Cm \&% Print a `%'; no argument is used. -.PP +.Tp +.Pp In no case does a non-existent or small field width cause truncation of a field; padding takes place only if the specified field width exceeds the actual width. -.SH "RETURN VALUE" -.IR Printf +.Sh RETURN VALUE +.Nm Printf exits 0 on success, 1 on failure. -.SH "SEE ALSO" -printf(3) -.SH BUGS +.Sh SEE ALSO +.Xr printf 3 +.Sh HISTORY +.Nm printf +as a command is new to 4.4 BSD. It is modeled +after the +.Xr printf 3 +function which appeared in +Version 6 AT&T UNIX. +.Sh BUGS Since the number is translated from ASCII to floating-point, and then back again, floating-point precision may be lost. -.PP +.Pp ANSI hexadecimal character constants were deliberately not provided. diff --git a/usr/src/usr.bin/ptx/ptx.1 b/usr/src/usr.bin/ptx/ptx.1 index 745b4152bb..a50f4ac51e 100644 --- a/usr/src/usr.bin/ptx/ptx.1 +++ b/usr/src/usr.bin/ptx/ptx.1 @@ -1,19 +1,27 @@ -.\" @(#)ptx.1 6.1 (Berkeley) %G% +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.TH PTX 1 "" -.AT 3 -.SH NAME -ptx \- permuted index -.SH SYNOPSIS -.B ptx -[ option ] ... -[ input [ output ] ] -.SH DESCRIPTION -.I Ptx +.\" %sccs.include.redist.man% +.\" +.\" @(#)ptx.1 6.2 (Berkeley) %G% +.\" +.Dd +.Dt PTX 1 +.Os ATT 7th +.Sh NAME +.Nm ptx +.Nd permuted index +.Sh SYNOPSIS +.Nm ptx +.Op option +\&... +.Op input Op output +.Sh DESCRIPTION +.Nm Ptx generates a permuted index to file -.I input +.Ar input on file -.I output +.Ar output (standard input and output default). It has three phases: the first does the permutation, generating one line for each keyword in an input line. @@ -22,89 +30,104 @@ The permuted file is then sorted. Finally, the sorted lines are rotated so the keyword comes at the middle of the page. -.I Ptx +.Nm Ptx produces output in the form: -.br -.IP -\&.xx "tail" "before keyword" "keyword and after" "head" -.LP +.Pp +.Dl \&.xx "tail" "before keyword" "keyword and after" "head" +.Pp where .xx may be an -.I nroff +.Xr nroff 1 or -.IR troff (1) +.Xr troff 1 macro for user-defined formatting. The -.I before keyword +.Ar before keyword and -.I keyword and after +.Ar keyword and after fields incorporate as much of the line as will fit around the keyword when it is printed at the middle of the page. -.I Tail +.Ar Tail and -.I head, +.Ar head , at least one of which is an empty string "", are wrapped-around pieces small enough to fit in the unused space at the opposite end of the line. When original text must be discarded, `/' marks the spot. -.PP +.Pp The following options can be applied: -.TP -.BR \-f +.Tw Fl +.Tp Fl f Fold upper and lower case letters for sorting. -.TP -.BR \-t +.Tp Fl t Prepare the output for the phototypesetter; the default line length is 100 characters. -.TP -.BI \-w " n" +.Tp Cx Fl w +.Ws +.Ar n +.Cx Use the next argument, -.I n, +.Ar n , as the width of the output line. The default line length is 72 characters. -.TP -.BI \-g " n" +.Tp Cx Fl g +.Ws +.Ar n +.Cx Use the next argument, -.I n, +.Ar n , as the number of characters to allow for each gap among the four parts of the line as finally printed. The default gap is 3 characters. -.TP -.BR \-o " only" -Use as keywords only the words given in the \fIonly\fR file. -.TP -.BR \-i " ignore" +.Tp Cx Fl o +.Ws +.Ar only +.Cx +Use as keywords only the words given in the +.Ar only +file. +.Tp Cx Fl i +.Ws +.Ar ignore +.Cx Do not use as keywords any words given in the -.I ignore file. -If the \fB\-i\fR and \fB\-o\fR options are missing, use -.I /usr/lib/eign -as the -.I +If the +.Fl i +and +.Fl o +options are missing, use +.Pa /usr/share/dict/eign +as the ignore file. -.TP -.BR \-b " break" -Use the characters in the -.I +.Tp Cx Fl b +.Ws +.Ar break +.Cx +Use the characters in the break file to separate words. In any case, tab, newline, and space characters are always used as break characters. -.TP -.BR \-r +.Tp Fl r Take any leading nonblank characters of each input line to be a reference identifier (as to a page or chapter) separate from the text of the line. Attach that identifier as a 5th field on each output line. -.PP +.Tp +.Pp The index for this manual was generated using -.I ptx. -.SH FILES -/usr/bin/sort -.br -/usr/lib/eign -.SH BUGS +.Nm ptx . +.Sh FILES +.Dw /usr/share/dict.eign +.Di L +.Dp /usr/bin/sort +.Dp /usr/share/dict/eign +.Dp +.Sh HISTORY +.Nm Ptx +appeared in Version 7 AT&T UNIX +.Sh BUGS Line length counts do not account for overstriking or proportional spacing. -.br diff --git a/usr/src/usr.bin/quota/quota.1 b/usr/src/usr.bin/quota/quota.1 index a5df64e731..d3da9dd8c8 100644 --- a/usr/src/usr.bin/quota/quota.1 +++ b/usr/src/usr.bin/quota/quota.1 @@ -1,99 +1,104 @@ -.\" Copyright (c) 1983, 1990 Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" +.\" .\" This code is derived from software contributed to Berkeley by .\" Robert Elz at The University of Melbourne. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)quota.1 6.4 (Berkeley) %G% +.\" @(#)quota.1 6.5 (Berkeley) %G% .\" -.TH QUOTA 1 "" -.UC 5 -.SH NAME -quota \- display disk usage and limits -.SH SYNOPSIS -.B quota -[ -.B \-g -] [ -.B \-u -] [ -.B "\-v | \-q" -] -.br -.B quota -[ -.B \-u -] [ -.B "\-v | \-q" -] -user -.br -.B quota -.B \-g -[ -.B "\-v | \-q" -] -group -.br -.SH DESCRIPTION -.I Quota -displays users' disk usage and limits. +.Dd +.Dt QUOTA 1 +.Os BSD 4.2 +.Sh NAME +.Nm quota +.Nd display disk usage and limits +.Sh SYNOPSIS +.Nm quota +.Op Fl g +.Op Fl u +.Op Fl v Li \&| Fl q +.Nm quota +.Op Fl u +.Op Fl v Li \&| Fl q +.Ar user +.Nm quota +.Op Fl g +.Op Fl v Li \&| Fl q +.Ar group +.Sh DESCRIPTION +.Nm Quota +displays users' disk usage and limits. By default only the user quotas are printed. -The optional \fI-g\fP flag specifies that group quotas +The optional +.Fl g +flag specifies that group quotas for the groups of which the user is a member should be printed. -Specifying both \fI-g\fP and \fI-u\fP +Specifying both +.Fl g +and +.Fl u specifies that both the user quotas and the group quotas for the groups of which the user is a member should be printed. -The optional \fI-u\fP flag is equivalent to the default. -.PP -Only the super-user may use the \fI-u\fP flag and the optional -.I user +The optional +.Fl u +flag is equivalent to the default. +.Pp +Only the super-user may use the +.Fl u +flag and the optional +.Ar user argument to view the limits of other users. -Non-super-users can use the the \fI-g\fP flag and optional -.I group +Non-super-users can use the the +.Fl g +flag and optional +.Ar group argument to view only the limits of groups of which they are members. -.PP +.Pp If a -.B \-v -flag is supplied, -.I quota +.Fl v +flag is supplied, +.Nm quota will also display quotas on filesystems where no storage is allocated. -.PP +.Pp The -.B \-q +.Fl q flag prints a more terse message, containing only information on filesystems where usage is over quota. -The \fI-q\fP flag takes precedence over the \fI-v\fP flag. -.PP -.I Quota +The +.Fl q +flag takes precedence over the +.Fl v +flag. +.Pp +.Nm Quota reports the quotas of all the filesystems listed in -.IR /etc/fstab . -If -.I quota +.Nm /etc/fstab . +If +.Nm quota exits with a non-zero status, one or more filesystems are over quota. -.SH FILES -.DT -\fIquota.user\fP at the filesystem root with user quotas -.br -\fIquota.group\fP at the filesystem root with group quotas -.br -/etc/fstab to find filesystem names and locations -.SH SEE ALSO -quotactl(2), -fstab(5), -edquota(8), quotacheck(8), quotaon(8), repquota(8) +.Sh FILES +.Dw quota.group +.Di L +.Nm quota.user +at the filesystem root with user quotas +.Nm quota.group +at the filesystem root with group quotas +.Dp Pa /etc/fstab +to find filesystem names and locations +.Dp +.Sh HISTORY +.Nm Quota +appeared in 4.2 BSD. +.Sh SEE ALSO +.Xr quotactl 2 , +.Xr fstab 5 , +.Xr edquota 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr repquota 8 diff --git a/usr/src/usr.bin/rdist/rdist.1 b/usr/src/usr.bin/rdist/rdist.1 index dbdc916a4b..d4a0fa1bcc 100644 --- a/usr/src/usr.bin/rdist/rdist.1 +++ b/usr/src/usr.bin/rdist/rdist.1 @@ -1,236 +1,258 @@ -.\" Copyright (c) 1985 The Regents of the University of California. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)rdist.1 6.7 (Berkeley) %G% +.\" @(#)rdist.1 6.8 (Berkeley) %G% .\" -.TH RDIST 1 "" -.UC 6 -.ad -.SH NAME -rdist \- remote file distribution program -.SH SYNOPSIS -.B rdist -[ \-nqbRhivwy ] -[ \-f distfile ] [ \-d var=value ] [ \-m host ] -[ name ... ] -.PP -.B rdist -[ \-nqbRhivwy ] -c name ... [login@]host[:dest] -.SH DESCRIPTION -.I Rdist -is a program to maintain identical copies of files over multiple hosts. +.Dd +.Dt RDIST 1 +.Os BSD 4.3 +.Sh NAME +.Nm rdist +.Nd remote file distribution program +.Sh SYNOPSIS +.Nm rdist +.Op Fl nqbRhivwy +.Op Fl f Ar distfile +.Op Fl d Ar var=value +.Op Fl m host +.Op Ar name ... +.Pp +.Nm rdist +.Op Fl nqbRhivwy +.Fl c +.Ar name ... +.Cx Op login@ +.Ar host +.Op :dest +.Cx +.Sh DESCRIPTION +.Nm Rdist +is a program to maintain identical copies of files over multiple hosts. It preserves the owner, group, mode, and mtime of files if possible and can update programs that are executing. -.I Rdist +.Nm Rdist reads commands from -.I distfile +.Ar distfile to direct the updating of files and/or directories. +.Pp +Options specific to the first SYNOPSIS form: +.Pp +.Tw Ar +.Tp Fl If -.I distfile -is `\-', the standard input is used. -If no -.B \-f -option is present, the program looks first for `distfile', -then `Distfile' to use as the input. +.Ar distfile +is +.Fl , +the standard input is used. +.Tp Cx Fl f +.Cx \&\ \& +.Ar distfile +.Cx +Use the specified +.Ar distfile. +.Tp +.Pp +If either the +.Fl f +or +.Fl +option is not specified, the program looks first for +.Dq Pa distfile , +then +.Dq Pa Distfile +to use as the input. If no names are specified on the command line, -.I rdist +.Nm rdist will update all of the files and directories listed in -.IR distfile . +.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. These may be used together to update specific files using specific commands. -.PP -The -.B \-c -option forces -.I rdist +.Pp +Options specific to the second SYNOPSIS form: +.Pp +.Tp Fl c +Forces +.Nm rdist to interpret the remaining arguments as a small -.IR distfile . +.Ar distfile . +.Pp The equivalent distfile is as follows. -.nf - -.ti +.5i -( \fIname\fP ... ) -> [\fIlogin\fP@]\fIhost\fP -.ti +1i -install [\fIdest\fP] ; - -.fi -.PP -Other options: -.TP -.B \-d +.Pp +.Df I +.Pq Ar name ... +.Li -> +.Op Ar login@ +.Ar host +.Df I +.Li install +.Op Ar dest ; +.De +.De +.Tp +.Pp +Options common to both forms: +.Pp +.Tw Ic +.Tp Cx Fl d +.Cx \&\ \& +.Ar var=value +.Cx Define -.I var +.Ar var to have -.IR value . +.Ar value . The -.B \-d +.Fl d option is used to define or override variable definitions in the -.IR distfile . -.I Value +.Ar distfile . +.Ar Value can be the empty string, one name, or a list of names surrounded by parentheses and separated by tabs and/or spaces. -.TP -.B \-m +.Tp Cx Fl m +.Cx \&\ \& +.Ar host +.Cx Limit which machines are to be updated. Multiple -.B -m +.Fl m arguments can be given to limit updates to a subset of the hosts listed the -.IR distfile . -.TP -.B \-n +.Ar distfile . +.Tp Fl n Print the commands without executing them. This option is useful for debugging -.IR distfile . -.TP -.B \-q +.Ar distfile . +.Tp Fl q Quiet mode. Files that are being modified are normally printed on standard output. The -.B \-q +.Fl q option suppresses this. -.TP -.B \-R +.Tp Fl R 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 truely identical copies of directories. -.TP -.B \-h +.Tp Fl h Follow symbolic links. Copy the file that the link points to rather than the link itself. -.TP -.B \-i +.Tp Fl i Ignore unresolved links. -.I Rdist +.Nm Rdist will normally try to maintain the link structure of files being transfered and warn the user if all the links cannot be found. -.TP -.B \-v +.Tp Fl v 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. -.TP -.B \-w +.Tp 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. This will preserve the directory structure of the files being 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. -.TP -.B \-y +.Tp Fl y Younger mode. Files are normally updated if their -.I mtime +.Ar mtime and -.I size +.Ar size (see -.IR stat (2)) +.Xr stat 2 ) disagree. The -.B \-y +.Fl y option causes -.I rdist +.Nm rdist not to update files that are younger than the master copy. This can be used to prevent newer copies on other hosts from being replaced. A warning message is printed for files which are newer than the master copy. -.TP -.B \-b +.Tp Fl b Binary comparison. Perform a binary comparison and update files if they differ rather than comparing dates and sizes. -.PP -.I Distfile +.Tp +.Pp +.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. -.nf - -.in +.5i +.Pp +.Ds I `=' -[ label: ] `\->' -[ label: ] `::' -.in - -.fi +[label:] `\->' +[label:] `::' +.De +.Pp The first format is used for defining variables. The second format is used for distributing files to other hosts. The third format is used for making lists of files that have been changed since some given date. -The \fIsource list\fP specifies a +The +.Ar source list +specifies a list of files and/or directories on the local host which are to be used as the master copy for distribution. -The \fIdestination list\fP is the list of hosts to which these files are to be +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 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 +.Pp Labels are optional. They are used to identify a command for partial updates. -.PP +.Pp Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with `#' and end with a newline. -.PP +.Pp Variables to be expanded begin with `$' followed by one character or a name enclosed in curly braces (see the examples at the end). -.PP +.Pp The source and destination lists have the following format: -.nf - -.ti +.5i +.Pp +.Ds I +.De or -.ti +.5i +.Ds I `(' `)' - -.fi +.De +.Pp The shell meta-characters `[', `]', `{', `}', `*', and `?' are recognized and expanded (on the local host only) in the same way as -.IR csh (1). +.Xr csh 1 . They can be escaped with a backslash. The `~' character is also expanded in the same way as -.IR csh +.Xr csh 1 but is expanded separately on the local and destination hosts. When the -.B \-w +.Fl w option is used with a file name that begins with `~', everything except the home directory is appended to the destination name. File names which do not begin with `/' or `~' use the destination user's home directory as the root directory for the rest of the file name. -.PP +.Pp The command list consists of zero or more commands of the following format. -.nf - -.in +.5i -.ta \w'install 'u +\w'name list 'u -`install' opt_dest_name `;' -`notify' `;' -`except' `;' -`except_pat' `;' -`special' string `;' -.in - -.fi -.PP +.Ds I +.Cw except_patx pattern\ listx +.Cl `install' opt_dest_name `;' +.Cl `notify' `;' +.Cl `except' `;' +.Cl `except_pat' `;' +.Cl `special' string `;' +.Cw +.De +.Pp The -.I install +.Ic install command is used to copy out of date files and/or directories. Each source file is copied to each host in the destination list. Directories are recursively copied in the same way. -.I Opt_dest_name +.Ar Opt_dest_name is an optional parameter to rename files. If no -.I install +.Ic install command appears in the command list or the destination name is not specified, the source file name is used. @@ -241,123 +263,138 @@ never be replaced with a regular file or a symbolic link. However, under the `\-R' option a non-empty directory will be removed if the corresponding filename is completely absent on the master host. The -.I options +.Ar options are `\-R', `\-h', `\-i', `\-v', `\-w', `\-y', and `\-b' and have the same semantics as options on the command line except they only apply to the files in the source list. The login name used on the destination host is the same as the local host unless the destination name is of the format ``login@host". -.PP +.Pp The -.I notify +.Ic notify command is used to mail the list of files updated (and any errors that may have occured) to the listed names. If no `@' appears in the name, the destination host is appended to the name (e.g., name1@host, name2@host, ...). -.PP +.Pp The -.I except +.Ic except command is used to update all of the files in the source list -.B except -for the files listed in \fIname list\fP. +.Ic except +for the files listed in +.Ar name list . This is usually used to copy everything in a directory except certain files. -.PP +.Pp The -.I except_pat +.Ic except_pat command is like the -.I except -command except that \fIpattern list\fP is a list of regular expressions +.Ic except +command except that +.Ar pattern list +is a list of regular expressions (see -.IR ed (1) +.Xr ed 1 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 \fIpattern list\fP +part of the regular expression. Variables are expanded in +.Ar pattern list but not shell file pattern matching characters. To include a `$', it must be escaped with `\e'. -.PP +.Pp The -.I special +.Ic special command is used to specify -.IR sh (1) +.Xr sh 1 commands that are to be executed on the -remote host after the file in \fIname list\fP is updated or installed. -If the \fIname list\fP is omitted then the shell commands will be executed +remote host after the file in +.Ar name list +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 to the current filename before executing the commands in -.IR string . -.I String +.Ar string . +.Ar String starts and ends with `"' and can cross multiple lines in -.I distfile. +.Ar distfile . Multiple commands to the shell should be separated by `;'. Commands are executed in the user's home directory on the host being updated. The -.I special +.Ar special command can be used to rebuild private databases, etc. after a program has been updated. -.PP -The following is a small example. -.nf - -.in +.5i +.Pp +The following is a small example: +.Pp +.Ds I HOSTS = ( matisse root@arpa) - +.sp FILES = ( /bin /lib /usr/bin /usr/games - /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h} - /usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) - +\t/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h} +\t/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) +.sp EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc - sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont ) - +\tsendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont ) +.sp ${FILES} -> ${HOSTS} - install -R ; - except /usr/lib/${EXLIB} ; - except /usr/games/lib ; - special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; - +\tinstall -R ; +\texcept /usr/lib/${EXLIB} ; +\texcept /usr/games/lib ; +\tspecial /usr/lib/sendmail "/usr/lib/sendmail -bz" ; +.sp srcs: /usr/src/bin -> arpa - except_pat ( \e\e.o\e$ /SCCS\e$ ) ; - +\texcept_pat ( \e\e.o\e$ /SCCS\e$ ) ; +.sp IMAGEN = (ips dviimp catdvi) - +.sp imagen: /usr/local/${IMAGEN} -> arpa - install /usr/local/lib ; - notify ralph ; - +\tinstall /usr/local/lib ; +\tnotify ralph ; +.sp ${FILES} :: stamp.cory - notify root@cory ; -.in - -.fi -.SH FILES -.nf -.ta \w'/tmp/rdist* 'u -distfile input command file -/tmp/rdist* temporary file for update lists -.fi -.SH "SEE ALSO" -sh(1), csh(1), stat(2) -.SH DIAGNOSTICS +\tnotify root@cory ; +.De +.Sh FILES +.Dw /tmp/rdist* +.Di L +.Dp Pa distfile +input command file +.Dp Pa /tmp/rdist* +temporary file for update lists +.Dp +.Sh SEE ALSO +.Xr sh 1 , +.Xr csh 1 , +.Xr stat 2 +.Sh HISTORY +The +.Nm +command appeared in 4.3 BSD. +.Sh DIAGNOSTICS A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shell, e.g., you are in too many groups. -.SH BUGS -Source files must reside on the local host where rdist is executed. -.PP +.Sh BUGS +Source files must reside on the local host where +.Nm rdist +is executed. +.Pp There is no easy way to have a special command executed after all files in a directory have been updated. -.PP +.Pp Variable expansion only works for name lists; there should be a general macro facility. -.PP -.I Rdist +.Pp +.Nm Rdist aborts on files which have a negative mtime (before Jan 1, 1970). -.PP +.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 of otherwise identical files is also needed. diff --git a/usr/src/usr.bin/rwho/rwho.1 b/usr/src/usr.bin/rwho/rwho.1 index 7ddd916a96..974e3c958e 100644 --- a/usr/src/usr.bin/rwho/rwho.1 +++ b/usr/src/usr.bin/rwho/rwho.1 @@ -1,54 +1,52 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)rwho.1 6.2 (Berkeley) %G% +.\" @(#)rwho.1 6.3 (Berkeley) %G% .\" -.TH RWHO 1 "" -.UC 5 -.SH NAME -rwho \- who's logged in on local machines -.SH SYNOPSIS -.B rwho -[ -.B \-a -] -.SH DESCRIPTION +.Dd +.Dt RWHO 1 +.Os BSD 4.2 +.Sh NAME +.Nm rwho +.Nd who's logged in on local machines +.Sh SYNOPSIS +.Nm rwho +.Op Fl a +.Sh DESCRIPTION The -.I rwho +.Nm rwho command produces output similar to -.I who, +.Xr who , but for all machines on the local network. If no report has been received from a machine for 5 minutes then -.I rwho +.Nm rwho assumes the machine is down, and does not report users last known to be logged into that machine. -.PP +.Pp If a users hasn't typed to the system for a minute or more, then -.I rwho +.Nm rwho 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 -.I rwho +.Nm rwho unless the -.B \-a +.Fl a flag is given. -.SH FILES -/usr/spool/rwho/whod.* information about other machines -.SH SEE ALSO -ruptime(1), rwhod(8) -.SH BUGS +.Sh FILES +.Dw /var/spool/rwho/rhowd.* +.Di L +.Dp Pa /var/spool/rwho/whod.* +information about other machines +.Dp +.Sh SEE ALSO +.Xr ruptime 1 , +.Xr rwhod 8 +.Sh HISTORY +.Nm Rwho +appeared in 4.3 BSD. +.Sh BUGS This is unwieldy when the number of machines on the local net is large. diff --git a/usr/src/usr.bin/sccs/sccs.1 b/usr/src/usr.bin/sccs/sccs.1 index 531412fba7..477513b080 100644 --- a/usr/src/usr.bin/sccs/sccs.1 +++ b/usr/src/usr.bin/sccs/sccs.1 @@ -1,331 +1,374 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)sccs.1 2.6 (Berkeley) %G% +.\" @(#)sccs.1 2.7 (Berkeley) %G% .\" -.UC 7 -.TH SCCS 1 "" -.UC 5 -.SH NAME -sccs \- front end for the \s-1SCCS\s0 subsystem -.SH SYNOPSIS -.B sccs -[ -.B \-r -] [ -.BI \-d path -] [ -.BI \-p path -] command [ flags ] [ args ] -.SH DESCRIPTION -.I Sccs -is a front end -to the -.SM SCCS +.Dd +.Os BSD 4.4 +.Dt SCCS 1 +.Os BSD 4.2 +.Sh NAME +.Nm sccs +.Nd front end for the +.Li SCCS +subsystem +.Sh SYNOPSIS +.Nm sccs +.Op Fl r +.Op Fl d Ar path +.Op Fl p Ar path +.Ar command +.Op flags +.Ar +.Sh DESCRIPTION +.Nm Sccs +is a front end to the +.Li SCCS programs -that helps them mesh more cleanly -with the rest of UNIX. -It also includes the capability to run -``set user id'' to another user -to provide additional protection. -.PP +that +helps them mesh more cleanly +with +the rest of UNIX. +It +also includes the capability to run +.Dq set user id +to another user +to +provide additional protection. +.Pp Basically, -.I sccs -runs the -.I command -with the specified -.I flags +.Nm sccs +runs the command with the specified +.Ar flags and -.I args. -Each -argument -is normally modified to be prepended -with ``SCCS/s.''. -.PP +.Ar args . +Each argument is normally modified to be prepended with +.Dq Li SCCS/s. . +.Pp Flags to be interpreted by the -.I sccs +.Nm sccs program must be before the -.I command +.Ar command argument. Flags to be passed to the actual -.SM SCCS -program -must come after the -.I command +.Li SCCS +program must come after the +.Ar command argument. -These flags are specific to the command -and are discussed in the documentation for that command. -.PP +These flags are specific to the command and +are discussed in the documentation for that command. +.Pp Besides the usual -.SM SCCS +.Li SCCS commands, -several ``pseudo-commands'' can be issued. +several +.Dq pseudo-commands +can be issued. These are: -.IP edit 1i -Equivalent to ``get \-e''. -.IP delget -Perform a delta on the named files -and then get new versions. -The new versions will have id keywords expanded, -and will not be editable. -The \-m, \-p, \-r, \-s, and \-y flags -will be passed to delta, -and the \-b, \-c, \-e, \-i, \-k, \-l, \-s, and \-x flags -will be passed to get. -.IP deledit -Equivalent to ``delget'' except that the -``get'' phase includes the ``\-e'' flag. -This option is useful for making a ``checkpoint'' -of your current editing phase. -The same flags will be passed to delta -as described above, -and all the flags listed for ``get'' -above except \-e and \-k -are passed to ``edit''. -.IP create -Creates an -.SM SCCS -file, -taking the initial contents from the file of the same name. -Any flags to ``admin'' are accepted. -If the creation is successful, +.Tw Fl +.Tp Ic edit +Equivalent +to +.Dq Li get \-e . +.Tp Ic delget +Perform a delta on the named files and +then get new versions. +The new versions will have id keywords expanded, and +will not be editable. +The +.Fl m , +.Fl p , +.Fl r , +.Fl s , +and +.Fl y +flags will be passed to +.Nm delta , +and the +.Fl b, +.Fl c , +.Fl e , +.Fl i , +.Fl k , +.Fl l , +.Fl s , +.\" anybody who has a bad xterm which is almost anyone +.if n \{\ +. br +.\} +and +.Fl x +flags will be passed to get. +.Tp Ic deledit +Equivalent +to +.Nm delget +except that the +.Nm get +phase includes the +.Fl e +flag. +This +option is useful for making a +.Em checkpoint +of your current editing phase. The same flags will be passed to delta +as described above, and +all the flags listed for +.om get +above except +.Fl e +and +.Fl k +are +passed to +.Nm edit . +.Tp Ic create +Creates +an +.Li SCCS +file , +taking +the initial contents from the file of the same name. +Any +flags to +.Nm admin +are accepted. If the creation is successful, the files are renamed with a comma on the front. -These should be removed when you are convinced that -the -.SM SCCS -files have been created successfully. -.IP fix -Must be followed by a -.B \-r +These should be removed when you are convinced that the +.Li SCCS +files +have been created successfully. +.Tp Ic fix +Must +be followed by a +.Fl r flag. -This command essentially removes the named delta, -but leaves you with a copy of the delta -with the changes that were in it. -It is useful for fixing small compiler bugs, etc. -Since it doesn't leave audit trails, -it should be used carefully. -.IP clean +This command essentially removes the named delta, but +leaves you with a copy of the delta +with the changes that were in it. It +is useful for fixing small compiler bugs, etc. +Since it doesn't leave audit trails, it should be used carefully. +.Tp Ic clean This routine removes everything from the current directory that can be recreated from SCCS files. It will not remove any files being edited. If the -.B \-b -flag is given, branches are ignored in the determination -of whether they are being edited; -this is dangerous if you are keeping the branches in the +.Fl b +flag is given, branches are ignored in the determination of +whether they are being edited; this +is dangerous if you are keeping the branches in the same directory. -.IP unedit -This is the opposite of an ``edit'' -or a ``get \-e''. -It should be used with extreme caution, -since any changes you made since the get -will be irretrievably lost. -.IP info +.Tp Ic unedit +This +is the opposite of an +.Nm edit +or +a +.Dq Li get \-e . +It should be used with extreme caution, since +any changes you made since the get will be irretrievably lost. +.Tp Ic info Gives a listing of all files being edited. If the -.B \-b -flag is given, -branches (i.e., -\s-1SID\s0's with two or fewer components) -are ignored. -If the -.B \-u -flag is given -(with an optional argument) -then only files being edited by you -(or the named user) -are listed. -.IP check -Like ``info'' -except that nothing is printed if nothing is being edited, -and a non-zero exit status is returned if anything -is being edited. -The intent is to have this included in an ``install'' -entry in a makefile -to insure that everything is included into the -.SM SCCS -file -before a version is installed. -.IP tell -Gives a newline-separated list -of the files being edited -on the standard output. -Takes the -.B \-b +.Fl b +flag +is given, branches (i.e., +.Cx Li SID +.Cx \&\'s +.Cx +with two or fewer components) +are ignored. If the +.Fl u +flag is given (with an optional argument) then +only files being edited by you (or the named user) are listed. +.Tp Ic check +Like +.Nm info +except that nothing is printed if nothing is being edited, and +a non-zero exit status is returned if anything is being edited. +The intent is to have this included in an +.Em install +entry in a makefile to insure that everything is included into the +.Li SCCS +file before a version is installed. +.Tp Ic tell +Gives a newline-separated list of the files being edited +on the standard output. Takes the +.Fl b +and +.Fl u +flags like +.Nm info and -.B \-u -flags like -``info'' and ``check''. -.IP diffs -Gives a ``diff'' listing between the current version of the -program(s) you have out for editing and the versions -in -.SM SCCS +.Nm check . +.Tp Ic diffs +Gives a +.Nm diff +listing between the current version of the +program(s) you have out for editing and the versions in +.Li SCCS format. The -.B \-r, -.B \-c, -.B \-i, -.B \-x, +.Fl r , +.Fl c , +.Fl i , +.Fl x , and -.B \-t +.Fl t flags are passed to -.I get\c -; the -.B \-l, -.B \-s, -.B \-e, -.B \-f, -.B \-h, +.if n \{\ +. br +.\} +.Nm get ; +the +.Fl l , +.Fl s , +.Fl e , +.Fl f , +.Fl h , and -.B \-b +.Fl b options are passed to -.I diff. +.if n \{\ +. br +.\} +.Nm diff . The -.B \-C +.Fl C flag is passed to -.I diff +.Nm diff as -.B \-c. -.IP print +.Fl c . +.Tp Ic print This command prints out verbose information about the named files. -.PP -The -.B \-r -flag runs -.I sccs -as the real user -rather than as whatever effective user -.I sccs -is ``set user id'' to. -The -.B \-d -flag gives a root directory for the -.SM SCCS +.Pp +.Tp Fl r +Runs +.Nm sccs +as the real user rather than as whatever effective user +.Nm sccs +is +.Dq Li set user id +to. +.Tp Fl d +Specifies a root directory for the +.Li SCCS files. The default is the current directory. -The -.B \-p -flag defines the pathname of the directory -in which the -.SM SCCS +If environment variable +.Ev PROJECT +is set, +it will be used to determine the +.Fl d +flag. +.Tp Fl p +flag defines the pathname of the directory in which the +.Li SCCS files will be found; -``SCCS'' is the default. +.Dq Li SCCS +is the default. The -.B \-p -flag differs from the -.B \-d -flag in that the -.B \-d -argument is prepended to the entire pathname -and the -.B \-p -argument is inserted before the final component of the -pathname. +.Fl p +flag +differs from the +.Fl d +flag +in that the +.Fl d +argument is prepended to the entire pathname and the +.Fl p +argument is inserted before the final component of the pathname. For example, -``sccs \-d/x \-py get a/b'' +.Dq Li sccs \-d/x \-py get a/b will convert to -``get /x/a/y/s.b''. +.Dq Li get /x/a/y/s.b . The intent here is to create aliases such as -``alias syssccs sccs -d/usr/src'' -which will be used as -``syssccs get cmd/who.c''. -Also, if the environment variable -PROJECT -is set, -its value is used to determine the -.B \-d flag. -If it begins with a slash, -it is taken directly; -otherwise, -the home directory of a user of that name -is examined for a subdirectory ``src'' or ``source''. -If such a directory is found, -it is used. -.PP -Certain commands (such as -.IR admin ) -cannot be run ``set user id'' by all users, -since this would allow anyone to change the authorizations. +.Dq Li alias syssccs sccs -d/usr/src +which +will be used as +.Dq Li syssccs get cmd/who.c . +.Pp +Certain +commands (such as +.Nm admin ) +cannot be run +.Dq Li set user id +by all users, since this would allow anyone to change the authorizations. These commands are always run as the real user. -.SH EXAMPLES -.de BX -.PP -.nf -.in +0.5i -.. -.de EX -.fi -.PP -.. +.Sh EXAMPLES To get a file for editing, edit it, and produce a new delta: -.BX -sccs get \-e file.c -ex file.c -sccs delta file.c -.EX +.Pp +.Dl sccs get \-e file.c +.Dl ex file.c +.Dl sccs delta file.c +.Pp To get a file from another directory: -.BX -sccs \-p/usr/src/sccs/s. get cc.c -.EX +.Pp +.Dl sccs \-p/usr/src/sccs/s. get cc.c +.Pp or -.BX -sccs get /usr/src/sccs/s.cc.c -.EX +.Pp +.Dl sccs get /usr/src/sccs/s.cc.c +.Pp To make a delta of a large number of files in the current directory: -.BX -sccs delta *.c -.EX +.Pp +.Dl sccs delta *.c +.Pp To get a list of files being edited that are not on branches: -.BX -sccs info \-b -.EX +.Pp +.Dl sccs info \-b +.Pp To delta everything being edited by you: -.BX -sccs delta \`sccs tell \-u\` -.EX +.Pp +.Dl sccs delta \`sccs tell \-u\` +.Pp In a makefile, to get source files from an -.SM SCCS +.Li SCCS file if it does not already exist: -.BX -SRCS = -$(SRCS): - sccs get $(REL) $@ -.EX -.SH "SEE ALSO" -admin(SCCS), -chghist(SCCS), -comb(SCCS), -delta(SCCS), -get(SCCS), -help(SCCS), -prt(SCCS), -rmdel(SCCS), -sccsdiff(SCCS), -what(SCCS) +.Pp +.Dl SRCS = +.Dl $(SRCS): +.Dl \&\tsccs get $(REL) $@ +.Sh ENVIRONMENT +.Tw Ar +.Tp Ev PROJECT +The PROJECT environment variable is checked by the +.Fl d +flag. If +it begins with a slash, it is taken directly; otherwise, +the home directory of a user of that name is +examined for a subdirectory +.Dq Li src +or +.Dq Li source . +If such a directory is found, it is used. +.Tp +.Sh SEE ALSO +.Xr what 1 +.Xr admin SCCS , +.Xr chghist SCCS , +.Xr comb SCCS , +.Xr delta SCCS , +.Xr get SCCS , +.Xr help SCCS , +.Xr prt SCCS , +.Xr rmdel SCCS , +.Xr sccsdiff SCCS , .br Eric Allman, -.ul -An Introduction to the Source Code Control System -.SH BUGS +.Em An Introduction to the Source Code Control System +.Sh HISTORY +.Nm Sccs +appeared in 4.3 BSD. +.Sh BUGS It should be able to take directory arguments on pseudo-commands like the -.SM SCCS +.Li SCCS commands do. diff --git a/usr/src/usr.bin/systat/systat.1 b/usr/src/usr.bin/systat/systat.1 index bd50b4744b..0ec349b253 100644 --- a/usr/src/usr.bin/systat/systat.1 +++ b/usr/src/usr.bin/systat/systat.1 @@ -1,119 +1,159 @@ -.\" Copyright (c) 1985 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)systat.1 6.6 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH SYSTAT 1 "" -.UC 6 -.SH NAME -systat \- display system statistics on a crt -.SH SYNOPSIS -.B systat -[ -.RI \- display -] [ -refresh-interval -] -.SH DESCRIPTION -.B Systat +.\" @(#)systat.1 6.7 (Berkeley) %G% +.\" +.Dd +.Dt SYSTAT 1 +.Os BSD 4.3 +.Sh NAME +.Nm systat +.Nd display system statistics on a crt +.Sh SYNOPSIS +.Nm systat +.Op Fl display +.Op Ar refresh-interval +.Sh DESCRIPTION +.Nm Systat displays various system statistics in a screen oriented fashion -using the curses screen display library, -.IR curses (3X). -.PP +using the curses screen display library, +.Xr curses (3X ) . +.Pp While -.I systat +.Nm systat is running the screen is usually divided into two windows (an exception is the vmstat display which uses the entire screen). The upper window depicts the current system load average. The information displayed in the lower window may vary, depending on user commands. The last line on the screen is reserved for user input and error messages. -.PP +.Pp By default -.I systat +.Nm systat displays the processes getting the largest percentage of the processor in the lower window. Other displays show swap space usage, disk i/o statistics (a la -.IR iostat (1)), +.Xr iostat 1 ) , virtual memory statistics (a la -.IR vmstat (1)), +.Xr vmstat 1 ) , network ``mbuf'' utilization, and network connections (a la -.IR netstat (1)). -.PP -Input is interpreted at two different levels. +.Xr netstat 1 ) . +.Pp +Input is interpreted at two different levels. A ``global'' command interpreter processes all keyboard input. If this command interpreter fails to recognize a command, the input line is passed to a per-display command interpreter. This allows each display to have certain display-specific commands. -.PP -Certain characters cause immediate action by -.IR systat . +.Pp +Command line options: +.Pp +.Tw refresh_interval +.Tp Cx Fl +.Ar display +.Cx +The +.Fl +flag expects +.Ar display +to be one of: +.Ic pigs , +.Ic iostat , +.Ic swap , +.Ic mbufs , +.Ic vmstat +or +.Ic netstat . +These displays can also be requested interactively (without the +.Dq Fl ) +and are described in +full detail below. +.Tp Ar refresh-interval +The +.Ar refresh-value +specifies the screen refresh time interval in seconds. +.Tp +.Pp +Certain characters cause immediate action by +.Nm systat . These are -.IP ^L +.Tw Fl +.Tp Ic \&^L Refresh the screen. -.IP ^G +.Tp Ic \&^G Print the name of the current ``display'' being shown in the lower window and the refresh interval. -.IP ^Z -Stop -.IR systat . -.IP : +.Tp Ic \&^Z +Stop +.Nm systat . +.Tp Ic \&: Move the cursor to the command line and interpret the input line typed as a command. While entering a command the current character erase, word erase, and line kill characters may be used. -.PP +.Pp The following commands are interpreted by the ``global'' command interpreter. -.IP help -.br +.Tp Ic \&help Print the names of the available displays on the command line. -.IP load -.br +.Tp Ic \&load Print the load average over the past 1, 5, and 15 minutes on the command line. -.IP stop -.br +.Tp Ic \&stop Stop refreshing the screen. -.IP "[ start ] [ number ]" -.br +.Tp Cx Op Ic start +.Cx \&\ \& +.Op Ar number +.Cx Start (continue) refreshing the screen. If a second, numeric, argument is provided it is interpreted as a refresh interval (in seconds). Supplying only a number will set the refresh interval to this value. -.IP "quit" -.br -Exit -.IR systat . +.Tp Ic \&quit +Exit +.Nm systat . (This may be abbreviated to -.IR q .) -.PP +.Ic q . ) +.Tp +.Pp The available displays are: -.IP pigs -.br +.Tw Ic +.Tp Ic pigs Display, in the lower window, those processes resident in main memory and getting the -largest portion of the processor (the default display). +largest portion of the processor (the default display). When less than 100% of the processor is scheduled to user processes, the remaining time is accounted to the ``idle'' process. -.IP iostat -.br +.Tp Ic iostat Display, in the lower window, statistics about processor use and disk throughput. Statistics on processor use appear as bar graphs of the amount of time executing in user mode (``user''), -in user mode running low priority processes (``nice''), in +in user mode running low priority processes (``nice''), in system mode (``system''), and idle (``idle''). Statistics on disk throughput show, for each drive, kilobytes of data transferred, number of disk transactions performed, and average seek time (in milliseconds). This information may be displayed as bar graphs or as rows of numbers which scroll downward. Bar -graphs are shown by default; commands specific to this display -are discussed below. -.IP swap -.br +graphs are shown by default; +.Pp +The following commands are specific to the +.Ic iostat +display; the minimum unambiguous prefix may be supplied. +.Dw Fl +.Dp Cm numbers +Show the disk i/o statistics in numeric form. Values are +displayed in numeric columns which scroll downward. +.Dp Cm bars +Show the disk i/o statistics in bar graph form (default). +.Dp Cm msps +Toggle the display of average seek time (the default is to +not display seek times). +.Dp +.Pp +.Tp Ic swap Display, in the lower window, swap space in use on each swap device configured. Two sets of bar graphs are shown. The upper graph displays swap space allocated to pure text segments @@ -125,22 +165,20 @@ is displayed along the left hand side of the text, and data and stack graphs. Space allocated to the user structure and page tables is not currently accounted for. -.IP mbufs -.br +.Tp Ic mbufs Display, in the lower window, the number of mbufs allocated for particular uses, i.e. data, socket structures, etc. -.IP vmstat -.br +.Tp Ic vmstat Take over the entire display and show a (rather crowded) compendium of statistics related to virtual memory usage, process scheduling, device interrupts, system name translation cacheing, disk i/o, etc. -.IP +.Pp The upper left quadrant of the screen shows the number of users logged in and the load average over the last one, five, and fifteen minute intervals. Below this line are statistics on memory utilization. The first row of the table reports memory usage only among -active processes, that is processes that have run in the previous +active processes, that is processes that have run in the previous twenty seconds. The second row reports on memory usage of all processes. The first column reports on the number of physical pages @@ -152,14 +190,14 @@ virtual pages, that is the number of pages that would be needed if all processes had all of their pages. Finally the last column shows the number of physical pages on the free list. -.IP +.Pp Below the memory display is the disk usage display. It reports the number of seeks, transfers, and number of kilobyte blocks transferred per second averaged over the refresh period of the display (by default, five seconds). For some disks it also reports the average milliseconds per seek. Note that the system only keeps statistics on at most four disks. -.IP +.Pp Below the disk display is a list of the average number of processes (over the last refresh interval) that are runnable (`r'), in page wait (`p'), @@ -169,14 +207,14 @@ Below the queue length listing is a numerical listing and a bar graph showing the amount of system (shown as `='), user (shown as `>'), nice (shown as `-'), and idle time (shown as ` '). -.IP +.Pp At the bottom left are statistics on name translations. It lists the number of names translated in the previous interval, the number and percentage of the translations that were handled by the system wide name translation cache, and the number and percentage of the translations that were handled by the per process name translation cache. -.IP +.Pp Under the date in the upper right hand quadrant are statistics on paging and swapping activity. The first two columns report the average number of pages @@ -189,7 +227,7 @@ The first row of the display shows the average number of disk transfers per second over the last refresh interval; the second row of the display shows the average number of pages transferred per second over the last refresh interval. -.IP +.Pp Below the paging statistics is a line listing the average number of total reclaims ('Rec'), intransit blocking page faults (`It'), @@ -197,9 +235,9 @@ swap text pages found in free list (`F/S'), file system text pages found in free list (`F/F'), reclaims from free list (`RFL'), pages freed by the clock daemon (`Fre'), -and sequential process pages freed (`SFr') +and sequential process pages freed (`SFr') per second over the refresh interval. -.IP +.Pp Below this line are statistics on the average number of zero filled pages (`zf') and demand filled text pages (`xf') per second over the refresh period. @@ -210,11 +248,11 @@ actually used. Note that this percentage is usually less than 100%, however it may exceed 100% if a large number of requests are actually used long after they were set up during a -period when no new pages are being set up. +period when no new pages are being set up. Thus this figure is most interesting when observed over a long time period, such as from boot time (see below on getting such a display). -.IP +.Pp Below the page fill statistics is a column that lists the average number of context switches (`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), @@ -223,143 +261,150 @@ network software interrupts (`Sof'), page faults (`Flt'), pages scanned by the page daemon (`Scn'), and revolutions of the page daemon's hand (`Rev') per second over the refresh interval. -.IP +.Pp Running down the right hand side of the display is a breakdown of the interrupts being handled by the system. At the top of the list is the total interrupts per second over the time interval. The rest of the column breaks down the total on a device -by device basis. +by device basis. Only devices that have interrupted at least once since boot time are shown. -.IP netstat -.br -Display, in the lower window, network connections. By default, -network servers awaiting requests are not displayed. Each address -is displayed in the format ``host.port'', with each shown symbolically, -when possible. It is possible to have addresses displayed numerically, -limit the display to a set of ports, hosts, and/or protocols; see the -list of commands below. -.PP -Commands to switch between displays may be abbreviated to the -minimum unambiguous prefix; for example, ``io'' for ``iostat''. -Certain information may be discarded when the screen size is -insufficient for display. For example, on a machine with 10 -drives the -.I iostat -bar graph displays only 3 drives on a 24 line terminal. When -a bar graph would overflow the allotted screen space it is -truncated and the actual value is printed ``over top'' of the bar. -.PP -The following commands are specific to the -.I iostat -display; the minimum unambiguous prefix may be supplied. -.IP numbers -Show the disk i/o statistics in numeric form. Values are -displayed in numeric columns which scroll downward. -.IP bars -Show the disk i/o statistics in bar graph form (default). -.IP msps -Toggle the display of average seek time (the default is to -not display seek times). -.PP +.Pp The following commands are specific to the -.I vmstat +.Ic vmstat display; the minimum unambiguous prefix may be supplied. -.IP boot +.Dp Cm boot Display cumulative statistics since the system was booted. -.IP run +.Dp Cm run Display statistics as a running total from the point this command is given. -.IP time +.Dp Cm time Display statistics averaged over the refresh interval (the default). -.IP zero +.Dp Cm zero Reset running statistics to zero. -.PP -The following commands are common to each display which shows -information about disk drives. These commands are used to -select a set of drives to report on, should your system have -more drives configured than can normally be displayed on the -screen. -.IP "ignore [ drives ]" -Do not display information about the drives indicated. Multiple -drives may be specified, separated by spaces. -.IP "display [ drives ]" -Display information about the drives indicated. Multiple drives -may be specified, separated by spaces. -.PP -The following command is specific to the -.I netstat -display; the minimum unambiguous prefix may be supplied. -.IP all +.Dp +.Tp Ic netstat +Display, in the lower window, network connections. By default, +network servers awaiting requests are not displayed. Each address +is displayed in the format ``host.port'', with each shown symbolically, +when possible. It is possible to have addresses displayed numerically, +limit the display to a set of ports, hosts, and/or protocols +(the minimum unambiguous prefix may be supplied): +.Pp +.Dw Ar +.Dp Cm all Toggle the displaying of server processes awaiting requests (this -is the equivalent of the -.B \-a +is the equivalent of the +.Fl a flag to -.IR netstat (1)). -.IP numbers +.Ar netstat 1 ) . +.Dp Cm numbers Display network addresses numerically. -.IP names +.Dp Cm names Display network addresses symbolically. -.PP -The remaining commands are common to displays which report -network connections (currently only the -.I netstat -display). These commands may be used to select a specific set -of connections for -.I systat -to report on. -.IP "\fIprotocol\fP" +.Dp Ar protocol Display only network connections using the indicated protocol (currently either ``tcp'' or ``udp''). -.IP "ignore [items]" +.Dp Cx Cm ignore +.Cx \&\ \& +.Op Ar items +.Cx Do not display information about connections associated with the specified hosts or ports. Hosts and ports may be specified by name (``ucbmonet'', ``ftp''), or numerically. Host addresses use the Internet dot notation (``128.32.0.9''). Multiple items may be specified with a single command by separating them with spaces. -.IP "display [items]" +.Dp Cx Cm display +.Cx \&\ \& +.Op Ar items +.Cx Display information about the connections associated with the -specified hosts or ports. As for -.IR ignore , -.I items +specified hosts or ports. As for +.Ar ignore , +.Op Ar items may be names or numbers. -.IP "show [ports|hosts]" +.Dp Cx Cm show +.Cx \&\ \& +.Op Ar ports\&|hosts +.Cx Show, on the command line, the currently selected protocols, hosts, and ports. Hosts and ports which are being ignored are prefixed with a `!'. If -.I ports +.Ar ports or -.I hosts -is supplied as an argument to -.IR show , +.Ar hosts +is supplied as an argument to +.Cm show , then only the requested information will be displayed. -.IP "reset" +.Dp Cm reset Reset the port, host, and protocol matching mechanisms to the default (any protocol, port, or host). -.SH FILES -.nf -.ta \w'/dev/services 'u -/vmunix for the namelist -/dev/kmem for information in main memory -/dev/drum for information about swapped out processes -/etc/hosts for host names -/etc/networks for network names -/etc/services for port names -.SH AUTHOR -The unknown hacker. The -.I pigs +.Dp +.Tp +.Pp +Commands to switch between displays may be abbreviated to the +minimum unambiguous prefix; for example, ``io'' for ``iostat''. +Certain information may be discarded when the screen size is +insufficient for display. For example, on a machine with 10 +drives the +.Ic iostat +bar graph displays only 3 drives on a 24 line terminal. When +a bar graph would overflow the allotted screen space it is +truncated and the actual value is printed ``over top'' of the bar. +.Pp +The following commands are common to each display which shows +information about disk drives. These commands are used to +select a set of drives to report on, should your system have +more drives configured than can normally be displayed on the +screen. +.Dw Tx +.Dp Cx Cm ignore +.Cx \&\ \& +.Op Ar drives +.Cx +Do not display information about the drives indicated. Multiple +drives may be specified, separated by spaces. +.Dp Cx Cm display +.Cx \&\ \& +.Op Ar drives +.Cx +Display information about the drives indicated. Multiple drives +may be specified, separated by spaces. +.Dp +.Sh FILES +.Dw /etc/networks +.Di L +.Dp Pa /vmunix +for the namelist +.Dp Pa /dev/kmem +for information in main memory +.Dp Pa /dev/drum +for information about swapped out processes +.Dp Pa /etc/hosts +for host names +.Dp Pa /etc/networks +for network names +.Dp Pa /etc/services +for port names +.Dp +.Sh AUTHOR +The unknown hacker. The +.Ic pigs display is derived from a program of the same name written by Bill Reeves. -.SH BUGS +.Sh HISTORY +.Nm +appeared in 4.3 BSD. +.Sh BUGS Takes 2-10 percent of the cpu. Certain displays presume a 24 line by 80 character terminal. The swap space display should account for space allocated to the user structure and page tables. The -.I vmstat +.Ic vmstat display looks out of place because it is (it was added in as a separate display rather than create a new program). -.PP +.Pp The whole thing is pretty hokey and was included in the distribution under serious duress. diff --git a/usr/src/usr.bin/telnet/telnet.1 b/usr/src/usr.bin/telnet/telnet.1 index 2922ccd454..70876b6b62 100644 --- a/usr/src/usr.bin/telnet/telnet.1 +++ b/usr/src/usr.bin/telnet/telnet.1 @@ -1,816 +1,790 @@ -.\" Copyright (c) 1983 The Regents of the University of California. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)telnet.1 6.8 (Berkeley) %G% +.\" @(#)telnet.1 6.9 (Berkeley) %G% .\" -.TH TELNET 1 "" -.UC 5 -.SH NAME -telnet \- User interface to the \s-1TELNET\s0 protocol -.SH SYNOPSIS -\fBtelnet\fR [\fB\-d\fR] [\fB\-n \fItracefile\fR] [\fIhost\fR [\fIport\fR]] -.SH DESCRIPTION +.Dd +.Dt TELNET 1 +.Os BSD 4.2 +.Sh NAME +.Nm telnet +.Nd user interface to the +.Li TELNET +protocol +.Sh SYNOPSIS +.Nm telnet +.Op Fl d +.Op Fl n Ar tracefile +.Op Ar host Op Ar port +.Sh DESCRIPTION The -.B telnet +.Nm telnet command -is used to communicate with another host using the \s-1TELNET\s+1 protocol. -If -.B telnet +is used to communicate with another host using the +.Li TELNET +protocol. +If +.Nm telnet is invoked without the -.I host +.Ar host argument, it enters command mode, -indicated by its prompt (\^\fBtelnet>\fR\^). +indicated by its prompt +.Pq Nm telnet\&> . In this mode, it accepts and executes the commands listed below. If it is invoked with arguments, it performs an -.B open -command (see below) with those arguments. -.PP +.Ic open +command with those arguments. +.Pp +Options: +.Tw Fl +.Tp Fl d +Sets the initial value of the +.Ic debug +toggle to +.Li TRUE +.Tp Cx Fl n +.Cx \&\ \& +.Ar tracefile +.Cx +Opens +.Ar tracefile +for recording trace information. +See the +.Ic set tracefile +command below. +.Tp Ar host +Indicates the official name, an alias, or the Internet address +of a remote host. +.Tp Ar port +Indicates a port number (address of an application). If a number is +not specified, the default +.Nm telnet +port is used. +.Tp +.Pp Once a connection has been opened, -\fBtelnet\fR +.Nm telnet will attempt to enable the -\s-1TELNET LINEMODE\s+1 +.Li TELNET LINEMODE option. If this fails, then -\fBtelnet\fR +.Nm telnet will revert to one of two input modes: -either \*(lqcharacter at a time\*(rq -or \*(lqold line by line\*(rq +either \*(Lqcharacter at a time\*(Rq +or \*(Lqold line by line\*(Rq depending on what the remote system supports. -.PP -When \s-1LINEMODE\s+1 is enabled, character processing is done on the +.Pp +When +.Li LINEMODE +is enabled, character processing is done on the 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 changes to any special characters that happen on the remote system, so that they can take effect on the local system. -.PP -In \*(lqcharacter at a time\*(rq mode, most +.Pp +In \*(Lqcharacter at a time\*(Rq mode, most text typed is immediately sent to the remote host for processing. -.PP -In \*(lqold line by line\*(rq mode, all text is echoed locally, +.Pp +In \*(Lqold line by line\*(Rq mode, all text is echoed locally, and (normally) only completed lines are sent to the remote host. -The \*(lqlocal echo character\*(rq (initially \*(lq^E\*(rq) may be used +The \*(Lqlocal echo character\*(Rq (initially \*(Lq^E\*(Rq) may be used to turn off and on the local echo (this would mostly be used to enter passwords without the password being echoed). -.PP -If the \s-1LINEMODE\s+1 option is enabled, or if the -.B localchars -toggle is TRUE (the default for \*(lqold line by line\*(lq; see below), +.Pp +If the +.Li LINEMODE +option is enabled, or if the +.Ic localchars +toggle is TRUE (the default for \*(Lqold line by line\*(Lq; see below), the user's -.BR quit , -.BR intr , +.Ic quit , +.Ic intr , and -.B flush +.Ic flush characters are trapped locally, and sent as -\s-1TELNET\s+1 +.Li TELNET protocol sequences to the remote side. -If \s-1LINEMODE\s+1 has ever been enabled, then the user's -.B susp +If +.Li LINEMODE +has ever been enabled, then the user's +.Ic susp and -.B eof +.Ic eof are also sent as -\s-1TELNET\s+1 +.Li TELNET protocol sequences, and -.B quit -is sent as a \s-1TELNET ABORT\s+1 instead of \s-1BREAK\s+1. +.Ic quit +is sent as a +.Li TELNET ABORT +instead of +.Li BREAK There are options (see -.B toggle -.B autoflush +.Ic toggle +.Ic autoflush and -.B toggle -.B autosynch +.Ic toggle +.Ic autosynch below) which cause this action to flush subsequent output to the terminal (until the remote host acknowledges the -\s-1TELNET\s+1 +.Li TELNET sequence) and flush previous terminal input (in the case of -.B quit +.Ic quit and -.BR intr ). -.PP +.Ic intr ) . +.Pp While connected to a remote host, -\fBtelnet\fR +.Nm telnet command mode may be entered by typing the -\fBtelnet\fR -\*(lqescape character\*(rq (initially \*(lq^]\*(rq). +.Nm telnet +\*(Lqescape character\*(Rq (initially \*(Lq^ +\*(Rq). When in command mode, the normal terminal editing conventions are available. -.PP -Options: -.TP 8 -\fB\-d\fR -Sets the initial value of the \fBdebug\fR toggle to \s-1TRUE\s+1. -.TP -\fB\-n\fI tracefile\fR -Opens \fItracefile\fR for recording trace information. -See the \fBset tracefile\fR command below. -.TP -\fIhost\fR -Indicates the official name, an alias, or the Internet address -of a remote host. -.TP -\fIport\fR -Indicates a port number (address of an application). If a number is -not specified, the default \fBtelnet\fR port is used. -.PP -The following \fBtelnet\fR commands are available. +.Pp +The following .Nm telnet +commands are available. Only enough of each command to uniquely identify it need be typed (this is also true for arguments to the -.BR mode , -.BR set , -.BR toggle , -.BR unset , -.BR slc , +.Ic mode , +.Ic set , +.Ic toggle , +.Ic unset , +.Ic slc , and -.B display +.Ic display commands). -.PP -.TP 10 -.B close -.br +.Pp +.Tw Ic +.Tp Ic close Close a -\s-1TELNET\s+1 +.Li TELNET session and return to command mode. -.TP -.B display \fR[\fP \fIargument...\fP \fR]\fP -.br +.Tp Cx Ic display +.Cx \&\ \& +.Ar argument ... +.Cx Displays all, or some, of the -.B set +.Ic set and -.B toggle +.Ic toggle values (see below). -.TP -.B mode \fItype\fP -.br -.I Type +.Tp Cx Ic mode +.Cx \&\ \& +.Ar type +.Cx +.Ar Type is one of several options, depending on the state of the -\s-1TELNET\s+1 +.Li TELNET session. The remote host is asked for permission to go into the requested mode. If the remote host is capable of entering that mode, the requested mode will be entered. -.RS 10 -.TP -.B character -.br +.Tw Ar +.Tp Ic character Disable the -\s-1TELNET LINEMODE\s+1 +.Li TELNET LINEMODE option, or, if the remote side does not understand the -\s-1LINEMODE\s+1 -option, then enter \*(lqcharacter at a time\*(lq mode. -.TP -.B line -.br +.Li LINEMODE +option, then enter \*(Lqcharacter at a time\*(Lq mode. +.Tp Ic line Enable the -\s-1TELNET LINEMODE\s+1 +.Li TELNET LINEMODE option, or, if the remote side does not understand the -\s-1LINEMODE\s+1 -option, then attempt to enter \*(lqold-line-by-line\*(lq mode. -.TP -.B isig (-isig) -.br -Attempt to enable (disable) the \s-1TRAPSIG\s+1 mode of the \s-1LINEMODE\s+1 option. -This requires that the \s-1LINEMODE\s+1 option be enabled. -.TP -.B edit (-edit) -.br -Attempt to enable (disable) the \s-1EDIT\s+1 mode of the \s-1LINEMODE\s+1 option. -This requires that the \s-1LINEMODE\s+1 option be enabled. -.TP -.B ? -.br +.Li LINEMODE +option, then attempt to enter \*(Lqold-line-by-line\*(Lq mode. +.Tp Cx Ic isig +.Cx \&\ \& +.Pq Ic \-isig +.Cx +Attempt to enable (disable) the +.Li TRAPSIG +mode of the +.Li LINEMODE +option. +This requires that the +.Li LINEMODE +option be enabled. +.Tp Cx Ic edit +.Cx \&\ \& +.Pq Ic \-edit +.Cx +Attempt to enable (disable) the +.Li EDIT +mode of the +.Li LINEMODE +option. +This requires that the +.Li LINEMODE +option be enabled. +.Tp Ic \&? Prints out help information for the -.B mode +.Ic mode command. -.RE -.TP -.B open \fIhost\fP \fR[\fP [\fI-\fP]\fIport\fP \fR]\fP -.br +.Tp +.Tp Cx Ic open +.Cx \&\ \& +.Ar host +.Cx \&\ \& +.Cx [ +.Op Fl +.Cx \&\ \& +.Ar port +.Cx ] +.Cx Open a connection to the named host. If no port number -is specified, -\fBtelnet\fR +is specified, +.Nm telnet will attempt to contact a -\s-1TELNET\s+1 +.Li TELNET server at the default port. -The host specification may be either a host name (see -.BR hosts (5)) -or an Internet address specified in the \*(lqdot notation\*(rq (see -.BR inet (3N)). +The host specification may be either a host name (see +.Xr hosts 5 ) +or an Internet address specified in the \*(Lqdot notation\*(Rq (see +.Xr inet 3 ) . When connecting to a non-standard port, -\fBtelnet\fR +.Nm telnet omits any automatic initiation of -\s-1TELNET\s+1 +.Li TELNET options. When the port number is preceeded by a minus sign, the inital option negotiation is done. -After establishing a connection, the \fB.telnetrc\fP in the +After establishing a connection, the file +.Pa \&.telnetrc +in the users home directory is opened. Lines begining with a # are comment lines. Blank lines are ignored. Lines that begin without whitespace 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 lines that begin with whitespace are assumed to be -.B telnet +.Nm telnet commands and are processed as if they had been typed in manually to the -.B telnet +.Nm telnet command prompt. -.TP -.B quit -.br +.Tp Ic quit Close any open -\s-1TELNET\s+1 -session and exit -.BR telnet . +.Li TELNET +session and exit +.Nm telnet . An end of file (in command mode) will also close a session and exit. -.TP -.B send \fIarguments\fP -.br +.Tp Cx Ic send +.Cx \&\ \& +.Ar arguments +.Cx Sends one or more special character sequences to the remote host. The following are the arguments which may be specified (more than one argument may be specified at a time): -.RS -.TP -.B abort -.br +.Pp +.Tw Ds +.Tp Ic abort Sends the -\s-1TELNET ABORT\s+1 +.Li TELNET ABORT (ABORT processes) sequence. -.TP -.B ao -.br +.Tp Ic ao Sends the -\s-1TELNET AO\s+1 +.Li TELNET AO (Abort Output) sequence, which should cause the remote system to flush all output -.B from +.Em from the remote system -.B to +.Em to the user's terminal. -.TP -.B ayt -.br +.Tp Ic ayt Sends the -\s-1TELNET AYT\s+1 +.Li TELNET AYT (Are You There) sequence, to which the remote system may or may not choose to respond. -.TP -.B brk -.br +.Tp Ic brk Sends the -\s-1TELNET BRK\s+1 +.Li TELNET BRK (Break) sequence, which may have significance to the remote system. -.TP -.B ec -.br +.Tp Ic ec Sends the -\s-1TELNET EC\s+1 +.Li TELNET EC (Erase Character) sequence, which should cause the remote system to erase the last character entered. -.TP -.B el -.br +.Tp Ic el Sends the -\s-1TELNET EL\s+1 +.Li TELNET EL (Erase Line) sequence, which should cause the remote system to erase the line currently being entered. -.TP -.B eof -.br +.Tp Ic eof Sends the -\s-1TELNET EOF\s+1 +.Li TELNET EOF (End Of File) sequence. -.TP -.B eor -.br +.Tp Ic eor Sends the -\s-1TELNET EOR\s+1 +.Li TELNET EOR (End of Record) sequence. -.TP -.B escape -.br +.Tp Ic escape Sends the current -.B telnet -escape character (initially \*(lq^]\*(rq). -.TP -.B ga -.br +.Nm telnet +escape character (initially \*(Lq^\*(Rq). +.Tp Ic ga Sends the -\s-1TELNET GA\s+1 +.Li TELNET GA (Go Ahead) sequence, which likely has no significance to the remote system. -.TP -.B getstatus -.br +.Tp Ic getstatus If the remote side supports the -\s-1TELNET STATUS\s+1 +.Li TELNET STATUS command, -.B getstatus +.Ic getstatus will send the subnegotiation to request that the server send its current option status. -.TP -.B ip -.br +.Tp Ic ip Sends the -\s-1TELNET IP\s+1 +.Li TELNET IP (Interrupt Process) sequence, which should cause the remote system to abort the currently running process. -.TP -.B nop -.br +.Tp Ic nop Sends the -\s-1TELNET NOP\s+1 +.Li TELNET NOP (No OPeration) sequence. -.TP -.B susp -.br +.Tp Ic susp Sends the -\s-1TELNET SUSP\s+1 +.Li TELNET SUSP (SUSPend process) sequence. -.TP -.B synch -.br +.Tp Ic synch Sends the -\s-1TELNET SYNCH\s+1 +.Li TELNET SYNCH sequence. This sequence causes the remote system to discard all previously typed (but not yet read) input. This sequence is sent as TCP urgent data (and may not work if the remote system is a 4.2 BSD system -- if -it doesn't work, a lower case \*(lqr\*(rq may be echoed on the terminal). -.TP -.B ? -.br +it doesn't work, a lower case \*(Lqr\*(Rq may be echoed on the terminal). +.Tp Ic \&? Prints out help information for the -.B send +.Ic send command. -.RE -.TP -.B set \fIargument value\fP -.TP -.B unset \fIarguments...\fP -.br +.Tp +.Tp Cx Ic set +.Cx \&\ \& +.Ar argument value +.Cx +.Tp Cx Ic unset +.Cx \&\ \& +.Ar argument value +.Cx The -.B set +.Ic set command will set any one of a number of -.B telnet +.Nm telnet variables to a specific value or to TRUE. -The special value \fBoff\fP turns off the function associated with +The special value +.Ic off +turns off the function associated with the variable, this is equivalent to using the -.B unset +.Ic unset command. The -.B unset +.Ic unset command will disable or set to FALSE any of the specified functions. The values of variables may be interrogated with the -.B display +.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 -\fBtoggle\fP command may be explicitly set or unset using -the \fBset\fP and \fBunset\fP commands. -.RS -.TP -.B echo -.br -This is the value (initially \*(lq^E\*(rq) which, when in -\*(lqline by line\*(rq mode, toggles between doing local echoing +.Ic toggle +command may be explicitly set or unset using +the +.Ic set +and +.Ic unset +commands. +.Tw Fl +.Tp Ic echo +This is the value (initially \*(Lq^E\*(Rq) which, when in +\*(Lqline by line\*(Rq mode, toggles between doing local echoing of entered characters (for normal processing), and suppressing echoing of entered characters (for entering, say, a password). -.TP -.B eof -.br +.Tp Ic eof If -.B telnet +.Nm telnet is operating in -\s-1LINEMODE\s+1 -or \*(lqold line by line\*(rq mode, entering this character +.Li LINEMODE +or \*(Lqold line by line\*(Rq mode, entering this character as the first character on a line will cause this character to be sent to the remote system. The initial value of the eof character is taken to be the terminal's -.B eof +.Ic eof character. -.TP -.B erase -.br +.Tp Ic erase If -.B telnet +.Nm telnet is in -.I localchars +.Ic localchars mode (see -.B toggle -.B localchars +.Ic toggle +.Ic localchars below), -.B and +.Sy and if -.B telnet -is operating in \*(lqcharacter at a time\*(rq mode, then when this +.Nm telnet +is operating in \*(Lqcharacter at a time\*(Rq mode, then when this character is typed, a -\s-1TELNET EC\s+1 +.Li TELNET EC sequence (see -.B send -.B ec +.Ic send +.Ic ec above) is sent to the remote system. The initial value for the erase character is taken to be the terminal's -.B erase +.Ic erase character. -.TP -.B escape -.br +.Tp Ic escape This is the -.B telnet -escape character (initially \*(lq^[\*(rq) which causes entry +.Nm telnet +escape character (initially \*(Lq^[\*(Rq) which causes entry into -.B telnet +.Nm telnet command mode (when connected to a remote system). -.TP -.B flushoutput -.br +.Tp Ic flushoutput If -.B telnet +.Nm telnet is in -.I localchars +.Ic localchars mode (see -.B toggle -.B localchars +.Ic toggle +.Ic localchars below) and the -.B flushoutput +.Ic flushoutput character is typed, a -\s-1TELNET AO\s+1 +.Li TELNET AO sequence (see -.B send -.B ao +.Ic send +.Ic ao above) is sent to the remote host. The initial value for the flush character is taken to be the terminal's -.B flush +.Ic flush character. -.TP -.B interrupt -.br +.Tp Ic interrupt If -.B telnet +.Nm telnet is in -.I localchars +.Ic localchars mode (see -.B toggle -.B localchars +.Ic toggle +.Ic localchars below) and the -.B interrupt +.Ic interrupt character is typed, a -\s-1TELNET IP\s+1 +.Li TELNET IP sequence (see -.B send -.B ip +.Ic send +.Ic ip above) is sent to the remote host. The initial value for the interrupt character is taken to be the terminal's -.B intr +.Ic intr character. -.TP -.B kill -.br +.Tp Ic kill If -.B telnet +.Nm telnet is in -.I localchars +.Ic localchars mode (see -.B toggle -.B localchars +.Ic toggle +.Ic localchars below), -.B and +.Ic and if -.B telnet -is operating in \*(lqcharacter at a time\*(rq mode, then when this +.Nm telnet +is operating in \*(Lqcharacter at a time\*(Rq mode, then when this character is typed, a -\s-1TELNET EL\s+1 +.Li TELNET EL sequence (see -.B send -.B el +.Ic send +.Ic el above) is sent to the remote system. The initial value for the kill character is taken to be the terminal's -.B kill +.Ic kill character. -.TP -.br -.B lnext +.Tp Ic lnext If -.B telnet +.Nm telnet is operating in -\s-1LINEMODE\s+1 -or \*(lqold line by line\*(lq mode, then this character is taken to +.Li LINEMODE +or \*(Lqold line by line\*(Lq mode, then this character is taken to be the terminal's -.B lnext +.Ic lnext character. The initial value for the lnext character is taken to be the terminal's -.B lnext +.Ic lnext character. -.TP -.B quit -.br +.Tp Ic quit If -.B telnet +.Nm telnet is in -.I localchars +.Ic localchars mode (see -.B toggle -.B localchars +.Ic toggle +.Ic localchars below) and the -.B quit +.Ic quit character is typed, a -\s-1TELNET BRK\s+1 +.Li TELNET BRK sequence (see -.B send -.B brk +.Ic send +.Ic brk above) is sent to the remote host. The initial value for the quit character is taken to be the terminal's -.B quit +.Ic quit character. -.TP -.B reprint -.br +.Tp Ic reprint If -.B telnet +.Nm telnet is operating in -\s-1LINEMODE\s+1 -or \*(lqold line by line\*(lq mode, then this character is taken to +.Li LINEMODE +or \*(Lqold line by line\*(Lq mode, then this character is taken to be the terminal's -.B reprint +.Ic reprint character. The initial value for the reprint character is taken to be the terminal's -.B reprint +.Ic reprint character. -.TP -.B start -.br +.Tp Ic start If the -\s-1TELNET TOGGLE-FLOW-CONTROL\s+1 +.Li TELNET TOGGLE-FLOW-CONTROL option has been enabled, then this character is taken to be the terminal's -.B start +.Ic start character. The initial value for the kill character is taken to be the terminal's -.B start +.Ic start character. -.TP -.B stop -.br +.Tp Ic stop If the -\s-1TELNET TOGGLE-FLOW-CONTROL\s+1 +.Li TELNET TOGGLE-FLOW-CONTROL option has been enabled, then this character is taken to be the terminal's -.B stop +.Ic stop character. The initial value for the kill character is taken to be the terminal's -.B stop +.Ic stop character. -.TP -.B susp -.br +.Tp Ic susp If -.B telnet +.Nm telnet is in -.B localchars +.Ic localchars mode, or -\s-1LINEMODE\s+1 +.Li LINEMODE is enabled, and the -.B suspend +.Ic suspend character is typed, a -\s-1TELNET SUSP\s+1 +.Li TELNET SUSP sequence (see -.B send -.B susp +.Ic send +.Ic susp above) is sent to the remote host. The initial value for the suspend character is taken to be the terminal's -.B suspend +.Ic suspend character. -.TP -.B tracefile -This is the file to which the output, caused by \fBnetdata\fR or -\fBoption\fR tracing being TRUE, will be written. If it is set to '-', +.Tp Ic tracefile +Thi is the file to which the output, caused by +.Ic netdata +or +.Ic option +tracing being TRUE, will be written. If it is set to +.Dq Fl , then tracing information will be written to standard output (the default). -.br -.TP -.B worderase -.br +.Tp Ic worderase If -.B telnet +.Nm telnet is operating in -\s-1LINEMODE\s+1 -or \*(lqold line by line\*(lq mode, then this character is taken to +.Li LINEMODE +or \*(Lqold line by line\*(Lq mode, then this character is taken to be the terminal's -.I worderase +.Ic worderase character. The initial value for the worderase character is taken to be the terminal's -.I worderase +.Ic worderase character. -.TP -.B slc \fIstate\fP -.br +.Tp +.Tp Cx Ic slc +.Cx \&\ \& +.Ar state +.Cx The -.B slc +.Ic slc command (Set Local Characters) is used to set or change the state of the the special -characters when the \s-1TELNET LINEMODE\s+1 option has +characters when the +.Li TELNET LINEMODE +option has been enabled. Special characters are characters that get -mapped to \s-1TELNET\s+1 commands sequences (like -.B ip +mapped to +.Li TELNET +commands sequences (like +.Ic ip or -.BR quit ) +.Ic quit ) or line editing characters (like -.B erase +.Ic erase and -.BR kill ). +.Ic kill ) . By default, the local special characters are exported. -.RS -.TP -.B export -.br +.Tw Fl +.Tp Ic export Switch to the local defaults for the special characters. The local default characters are those of the local terminal at the time when -.B telnet +.Nm telnet was started. -.br -.TP -.B import -.br +.Tp Ic import Switch to the remote defaults for the special characters. The remote default characters are those of the remote system -at the time when the \s-1TELNET\s+1 connection was established. -.br -.TP -.B check -.br +at the time when the +.Li TELNET +connection was established. +.Tp Ic check Verify the current settings for the current special characters. The remote side is requested to send all the current special character settings, and if there are any discrepencies with the local side, the local side will switch to the remote value. -.TP -.B ? -.br +.Ic Ic \&? Prints out help information for the -.B slc +.Ic slc command. -.RE -.TP -.B ? -.br +.Tp +.Tp Ic \&? Displays the legal -\fBset\fR (\fBunset\fR) +.Ic set +.Pq Ic unset commands. -.RE -.TP -.B toggle \fIarguments...\fP -.br +.Tp Cx Ic toggle +.Cx \&\ \& +.Ar arguments ... +.Cx Toggle (between TRUE and FALSE) various flags that control how -.B telnet +.Nm telnet responds to events. These flags may be set explicitly to TRUE or FALSE using the -.B set +.Ic set and -.B unset +.Ic unset commands listed above. More than one argument may be specified. The state of these flags may be interrogated with the -.B display +.Ic display command. Valid arguments are: -.RS -.TP -.B autoflush -.br +.Tw Ar +.Tp Ic autoflush If -.B autoflush +.Ic autoflush and -.B localchars +.Ic localchars are both TRUE, then when the -.BR ao , -.BR intr , +.Ic ao , or -.B quit +.Ic quit characters are recognized (and transformed into -\s-1TELNET\s+1 +.Li TELNET sequences; see -.B set +.Ic set above for details), -.B telnet +.Nm telnet refuses to display any data on the user's terminal until the remote system acknowledges (via a -\s-1TELNET TIMING MARK\s+1 +.Li TELNET TIMING MARK option) that it has processed those -\s-1TELNET\s+1 +.Li TELNET sequences. The initial value for this toggle is TRUE if the terminal user had not done an "stty noflsh", otherwise FALSE (see -.BR stty (1)). -.TP -.B autosynch +.Xr stty 1 ) . +.Tp Ic autosynch If -.B autosynch +.Ic autosynch and -.B localchars +.Ic localchars are both TRUE, then when either the -.B intr +.Ic intr or -.B quit +.Ic quit characters is typed (see -.B set +.Ic set above for descriptions of the -.B intr +.Ic intr and -.B quit +.Ic quit characters), the resulting -\s-1TELNET\s+1 +.Li TELNET sequence sent is followed by the -\s-1TELNET SYNCH\s+1 +.Li TELNET SYNCH sequence. This procedure -.B should +.Ic should cause the remote system to begin throwing away all previously typed input until both of the -\s-1TELNET\s+1 +.Li TELNET sequences have been read and acted upon. The initial value of this toggle is FALSE. -.TP -.B binary -.br +.Tp Ic binary Enable or disable the -\s-1TELNET BINARY\s+1 +.Li TELNET BINARY option on both input and output. -.TP -.B inbinary -.br +.Tp Ic inbinary Enable or disable the -\s-1TELNET BINARY\s+1 +.Li TELNET BINARY option on input. -.TP -.B outbinary -.br +.Tp Ic outbinary Enable or disable the -\s-1TELNET BINARY\s+1 +.Li TELNET BINARY option on output. -.TP -.B crlf -.br +.Tp Ic crlf If this is TRUE, then carriage returns will be sent as . If this is FALSE, then carriage returns will be send as . The initial value for this toggle is FALSE. -.TP -.B crmod -.br +.Tp Ic crmod Toggle carriage return mode. When this mode is enabled, most carriage return characters received from the remote host will be mapped into a carriage return followed by @@ -820,136 +794,133 @@ those received from the remote host. This mode is not very useful unless the remote host only sends carriage return, but never line feed. The initial value for this toggle is FALSE. -.TP -.B debug -.br +.Tp Ic debug Toggles socket level debugging (useful only to the -.IR super user ). +.Ic super user ) . The initial value for this toggle is FALSE. -.TP -.B localchars -.br +.Tp Ic localchars If this is TRUE, then the -.BR flush , -.BR interrupt , -.BR quit , -.BR erase , +.Ic flush , +.Ic quit , and -.B kill +.Ic kill characters (see -.B set +.Ic set above) are recognized locally, and transformed into (hopefully) appropriate -\s-1TELNET\s+1 +.Li TELNET control sequences (respectively -.BR ao , -.BR ip , -.BR brk , -.BR ec , +.Ic ao , +.Ic brk , and -.BR el ; +.Ic el ; see -.B send +.Ic send above). -The initial value for this toggle is TRUE in \*(lqold line by line\*(rq mode, -and FALSE in \*(lqcharacter at a time\*(rq mode. +The initial value for this toggle is TRUE in \*(Lqold line by line\*(Rq mode, +and FALSE in \*(Lqcharacter at a time\*(Rq mode. When the -\s-1LINEMODE\s+1 +.Li LINEMODE option is enabled, the value of -.B localchars +.Ic localchars is ignored, and assumed to always be TRUE. If -\s-1LINEMODE\s+1 +.Li LINEMODE has ever been enabled, then -.B quit +.Ic quit is sent as -.BR abort , +.Ic abort , and -.BR eof and +.Ic eof and .B suspend are sent as -.BR eof and -.BR susp , +.Ic eof and see -.B send +.Ic send above). -.TP -.B netdata -.br +.Tp Ic netdata Toggles the display of all network data (in hexadecimal format). The initial value for this toggle is FALSE. -.TP -.B options -.br +.Tp Ic options Toggles the display of some internal -.B telnet +.Nm telnet protocol processing (having to do with -\s-1TELNET\s+1 +.Li TELNET options). The initial value for this toggle is FALSE. -.TP -.B prettydump -.br +.Tp Ic prettydump When the -.B netdata +.Ic netdata toggle is enabled, if -.B prettydump +.Ic prettydump is enabled the output from the -.B netdata +.Ic netdata command will be formated in a more user readable format. Spaces are put between each character in the output, and the begining of any -\s-1TELNET\s+1 +.Li TELNET escape sequence is preceeded by a '*' to aid in locating them. -.TP -.B ? -.br +.Tp Ic \&? Displays the legal -.B toggle +.Ic toggle commands. -.RE -.TP -.B z -.br +.Tp +.Tp Ic z Suspend -.BR telnet . -This command only works when the user is using the -.BR csh (1). -.TP -.B ! \fR[\fP \fIcommand\fP \fR]\fP -.br +.Nm telnet . +This command only works when the user is using the +.Xr csh 1 . +.Tp Cx Ic \&! +.Cx \&\ \& +.Op Ar command +.Cx Execute a single command in a subshell on the local -system. If \fIcommand\fP is ommitted, then an interactive +system. If +.Ic command +is ommitted, then an interactive subshell is invoked. -.TP -.B status -.br -Show the current status of -.BR telnet . +.Tp Ic status +Show the current status of +.Nm telnet . This includes the peer one is connected to, as well as the current mode. -.TP -.B ? \fR[\fP \fIcommand\fP \fR]\fP -.br +.Tp Cx Ic \&? +.Cx \&\ \& +.Op Ar command +.Cx Get help. With no arguments, -.B telnet +.Nm telnet prints a help summary. -If a command is specified, -.B telnet +If a command is specified, +.Nm telnet will print the help information for just that command. -.SH FILES -.nf -~/.telnetrc -.fi -.SH NOTES -.PP +.Sh ENVIRONMENT +.Nm Telnet +uses the +.Ev HOME , +.Ev SHELL +and +.Ev TERM +environent variables. +.Sh FILES +.Dw ~/.telnetrc +.Di L +.Dp Pa ~/.telnetrc +user customized telnet startup values +.Dp +.Sh HISTORY +.Nm Telnet +appeared in 4.2 BSD. +.Sh NOTES +.Pp On some remote systems, echo has to be turned off manually when in -\*(lqold line by line\*(rq mode. -.PP -.PP -In \*(lqold line by line\*(rq mode or \s-1LINEMODE\s+1 the terminal's -.I eof +\*(Lqold line by line\*(Rq mode. +.Pp +In \*(Lqold line by line\*(Rq mode or +.Li LINEMODE +the terminal's +.Ic eof character is only recognized (and sent to the remote system) when it is the first character on a line. diff --git a/usr/src/usr.bin/tip/tip.1 b/usr/src/usr.bin/tip/tip.1 index 95ba586b0a..89041848d3 100644 --- a/usr/src/usr.bin/tip/tip.1 +++ b/usr/src/usr.bin/tip/tip.1 @@ -1,186 +1,176 @@ -.\" Copyright (c) 1980 The Regents of the University of California. +.\" Copyright (c) 1980, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)tip.1 6.4 (Berkeley) %G% +.\" @(#)tip.1 6.5 (Berkeley) %G% .\" -.TH TIP 1 "" -.UC 4 -.SH NAME -tip, cu \- connect to a remote system -.SH SYNOPSIS -.B tip -[ -.B \-v -] [ -.BI \- speed -] system-name -.br -.B tip -[ -.B \-v -] [ -.BI \- speed -] phone-number -.br -.B cu -phone-number -[ -.B \-t -] [ -.B \-s -.I speed -] [ -.B \ -a -.I acu -] [ -.B \-l -.I line -] [ -.B \-# -] -.SH DESCRIPTION -.I Tip +.Dd +.Dt TIP 1 +.Os BSD 4 +.Sh NAME +.Nm tip , +.Nm cu +.Nd connect to a remote system +.Sh SYNOPSIS +.Nm tip +.Op Fl v +.Cx Fl +.Ar speed +.Cx +.Ar system\-name +.Nm tip +.Op Fl v +.Cx Fl +.Ar speed +.Cx +.Ar phone\-number +.Nm cu +.Ar phone\-number +.Op Fl t +.Op Fl s Ar speed +.Op Fl a Ar acu +.Op Fl l Ar line +.Op Fl # +.Sh DESCRIPTION +.Nm Tip and -.I cu +.Ar 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 on the machine (or equivalent) to which you wish to connect. The preferred interface is -.IR tip . +.Nm tip . The -.I cu +.Ar cu interface is included for those people attached to the ``call UNIX'' command of version 7. This manual page -describes only -.IR tip . -.PP +describes only +.Nm tip . +.Pp +Options: +.Tp Fl v +Set verbose mode. +.Tp +.Pp Typed characters are normally transmitted directly to the remote 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: -.TP 10 -.B ~^D ~. +.Tw Ds +.Tp Ic \&~^D \&~ . Drop the connection and exit (you may still be logged in on the remote machine). -.TP 10 -\fB~c \fP [\fIname\fP] +.Pp +.Tp Cx Ic \&~c +.Cx \&\ \& +.Op Ar name +.Cx Change directory to name (no argument implies change to your home directory). -.TP 10 -.B ~! +.Tp Ic \&~! Escape to a shell (exiting the shell will return you to tip). -.TP 10 -.B ~> +.Tp Ic \&~> Copy file from local to remote. -.I Tip +.Nm Tip prompts for the name of a local file to transmit. -.TP 10 -.B ~< +.Tp Ic \&~< Copy file from remote to local. -.I Tip +.Nm Tip prompts first for the name of the file to be sent, then for a command to be executed on the remote machine. -.TP 10 -\fB~p\fP \fIfrom\fP [ \fIto\fP ] +.Tp Cx Ic \&~p +.Cx \&\ \& +.Ar from +.Cx \&\ \& +.Op Ar to +.Cx Send a file to a remote UNIX host. The put command causes the remote UNIX system to run the command string ``cat > 'to''', while -.I tip +.Nm tip sends it the ``from'' file. If the ``to'' file isn't specified the ``from'' file name is used. This command is actually a UNIX specific version of the ``~>'' command. -.TP 10 -\fB~t\fP \fIfrom\fP [ \fIto\fP ] -Take a file from a remote UNIX host. +.Tp Cx Ic \&~t +.Cx \&\ \& +.Ar from +.Cx \&\ \& +.Op Ar to +.Cx +Take a file from a remote UNIX host. As in the put command the ``to'' file -defaults to the ``from'' file name if it isn't specified. +defaults to the ``from'' file name if it isn't specified. The remote host executes the command string ``cat 'from';echo ^A'' to send the file to -.IR tip . -.TP 10 -.B ~| +.Nm tip . +.Tp Ic \&~ Pipe the output from a remote command to a local UNIX process. The command string sent to the local UNIX system is processed by the shell. -.TP 10 -.B ~$ +.Tp Ic \&~$ Pipe the output from a local UNIX process to the remote host. The command string sent to the local UNIX system is processed by the shell. -.TP 10 -.B ~# -Send a BREAK to the remote system. +.Tp Ic \&~# +Send a BREAK to the remote system. For systems which don't support the necessary -.I ioctl +.Ar ioctl call the break is simulated by a sequence of line speed changes and DEL characters. -.TP 10 -.B ~s +.Tp Ic \&~s Set a variable (see the discussion below). -.TP 10 -.B ~^Z +.Tp Ic \&~^Z Stop -.I tip +.Nm tip (only available with job control). -.TP 10 -.B ~^Y +.Tp Ic \&~^Y Stop only the ``local side'' of -.I tip +.Nm tip (only available with job control); the ``remote side'' of -.IR tip , +.Nm tip , the side that displays output from the remote host, is left running. -.TP 10 -.B ~? +.Tp Ic \&~? Get a summary of the tilde escapes -.sp -.PP -.I Tip +.Tp +.Pp +.Nm Tip uses the file /etc/remote to find how to reach a particular system and to find out how it should operate while talking to the system; refer to -.IR remote (5) +.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 to be used may be specified on the command line, e.g. ``tip -300 mds''. -.PP +.Pp When -.I tip +.Nm tip establishes a connection it sends out a connection message to the remote system; the default value, if any, -is defined in /etc/remote. -.PP +is defined in +.Pa /etc/remote (see +.Xr remote 5 ) . +.Pp When -.I tip +.Nm tip 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, or an interrupt, will abort the dialogue and return you to the remote machine. -.PP -.I Tip +.Pp +.Nm Tip guards against multiple users connecting to a remote system by opening modems and terminal lines with exclusive access, and by honoring the locking protocol used by -.IR uucp (1C). -.PP -During file transfers -.I tip +.Xr uucp 1 . +.Pp +During file transfers +.Nm tip provides a running count of the number of lines transferred. When using the ~> and ~< commands, the ``eofread'' and ``eofwrite'' variables are used to recognize end-of-file when reading, and @@ -188,39 +178,36 @@ 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 -.I tip +.Nm tip should synchronize with the remote system on the echo of each transmitted character. -.PP +.Pp When -.I tip +.Nm tip must dial a phone number to connect to a system it will print various messages indicating its actions. -.I Tip +.Nm Tip supports the DEC DN-11 and Racal-Vadic 831 auto-call-units; the DEC DF02 and DF03, Ventel 212+, Racal-Vadic 3451, and Bizcomp 1031 and 1032 integral call unit/modems. -.PP -.SM -.B VARIABLES -.PP -.I Tip +.Ss VARIABLES +.Nm Tip maintains a set of -.I variables +.Ar variables which control its operation. Some of these variable 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 after -.IR vi (1) +.Xr vi 1 and -.IR Mail (1). +.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 current escape character. -.PP +.Pp 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 @@ -229,190 +216,174 @@ 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 -.I .tiprc +.Pa .tiprc in one's home directory). The -.B \-v +.Fl v option causes -.I tip +.Nm tip to display the sets as they are made. -Certain common variables have abbreviations. +Certain common variables have abbreviations. The following is a list of common variables, their abbreviations, and their default values. -.TP -.B beautify -.br +.Tw Ar +.Tp Ar beautify (bool) Discard unprintable characters when a session is being scripted; -abbreviated -.IR be . -.TP -.B baudrate -.br +abbreviated +.Ar be . +.Tp Ar baudrate (num) The baud rate at which the connection was established; abbreviated -.IR ba . -.TP -.B dialtimeout -.br +.Ar ba . +.Tp Ar dialtimeout (num) When dialing a phone number, the time (in seconds) to wait for a connection to be established; abbreviated -.IR dial . -.TP -.B echocheck -.br +.Ar dial . +.Tp Ar echocheck (bool) Synchronize with the remote host during file transfer by waiting for the echo of the last character transmitted; default is -.IR off . -.TP -.B eofread -.br +.Ar off . +.Tp Ar eofread (str) The set of characters which signify and end-of-tranmission during a ~< file transfer command; abbreviated -.IR eofr . -.TP -.B eofwrite -.br +.Ar eofr . +.Tp Ar eofwrite (str) The string sent to indicate end-of-transmission during a ~> file transfer command; abbreviated -.IR eofw . -.TP -.B eol -.br +.Ar eofw . +.Tp Ar eol (str) The set of characters which indicate an end-of-line. -.I Tip +.Nm Tip will recognize escape characters only after an end-of-line. -.TP -.B escape -.br +.Tp Ar escape (char) The command prefix (escape) character; abbreviated -.IR es ; +.Ar es ; default value is `~'. -.TP -.B exceptions -.br +.Tp Ar exceptions (str) The set of characters which should not be discarded due to the beautification switch; abbreviated -.IR ex ; +.Ar ex ; default value is ``\et\en\ef\eb''. -.TP -.B force -.br +.Tp Ar force (char) The character used to force literal data transmission; abbreviated -.IR fo ; +.Ar fo ; default value is `^P'. -.TP -.B framesize -.br +.Tp Ar framesize (num) The amount of data (in bytes) to buffer between file system writes when receiving files; abbreviated -.IR fr . -.TP -.B host -.br +.Ar fr . +.Tp Ar host (str) The name of the host to which you are connected; abbreviated -.IR ho . -.TP -.B prompt -.br +.Ar ho . +.Tp Ar prompt (char) The character which indicates and end-of-line on the remote host; abbreviated -.IR pr ; +.Ar pr ; 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 recipt of this character. -.TP -.B raise -.br -(bool) Upper case mapping mode; abbreviated -.IR ra ; -default value is -.IR off . +.Tp Ar raise +(bool) Upper case mapping mode; abbreviated +.Ar ra ; +default value is +.Ar off . When this mode is enabled, all lower case letters will be mapped to upper case by -.I tip +.Nm tip for transmission to the remote machine. -.TP -.B raisechar -.br +.Tp Ar raisechar (char) The input character used to toggle upper case mapping mode; abbreviated -.IR rc ; +.Ar rc ; default value is `^A'. -.TP -.B record -.br +.Tp Ar record (str) The name of the file in which a session script is recorded; abbreviated -.IR rec ; +.Ar rec ; default value is ``tip.record''. -.TP -.B script -.br +.Tp Ar script (bool) Session scripting mode; abbreviated -.IR sc ; -default is -.IR off . +.Ar sc ; +default is +.Ar off . When -.I script -is -.IR true , -.I tip +.Ar script +is +.Li true , +.Nm tip will record everything transmitted by the remote machine in the script record file specified in -.IR record . +.Ar record . If the -.I beautify +.Ar beautify switch is on, only printable ASCII characters will be included in the script file (those characters betwee 040 and 0177). The variable -.I exceptions +.Ar exceptions is used to indicate characters which are an exception to the normal beautification rules. -.TP -.B tabexpand -.br +.Tp Ar tabexpand (bool) Expand tabs to spaces during file transfers; abbreviated -.IR tab ; +.Ar tab ; default value is -.IR false . +.Ar false . Each tab is expanded to 8 spaces. -.TP -.B verbose -.br +.Tp Ar verbose (bool) Verbose mode; abbreviated -.IR verb ; -default is -.IR true . -When verbose mode is enabled, -.I tip +.Ar verb ; +default is +.Ar true . +When verbose mode is enabled, +.Nm tip prints messages while dialing, shows the current number of lines transferred during a file transfer operations, and more. -.TP -.B SHELL -.br +.Tp +.Sh ENVIRONMENT +.Nm Tip +uses the followinf environment variables: +.Tp Ar SHELL (str) The name of the shell to use for the ~! command; default value is ``/bin/sh'', or taken from the environment. -.TP -.B HOME -.br +.Tp Ar HOME (str) The home directory to use for the ~c command; default value is taken from the environment. -.PP -.SH FILES -.ta \w'/usr/spool/uucp/LCK..* 'u -.nf -/etc/remote global system descriptions -/etc/phones global phone number data base -${REMOTE} private system descriptions -${PHONES} private phone numbers -~/.tiprc initialization file. -/usr/spool/uucp/LCK..* lock file to avoid conflicts with \fIuucp\fP -.fi -.SH DIAGNOSTICS +.Tp Ar HOST +Check for a default host if none specified. +.Tp +.Pp +The variables +.Ev ${REMOTE} +and +.Ev ${PHONES} +are also exported. +.Sh FILES +.Dw /var/spool/uucp/LCK..* +.Di L +.Dp Pa /etc/remote +global system descriptions +.Dp Pa /etc/phones +global phone number data base +.Dp ${REMOTE} +private system descriptions +.Dp ${PHONES} +private phone numbers +.Dp ~/.tiprc +initialization file. +.Dp /var/log/aculog +line access log +.Dp Pa /var/spool/uucp/LCK..* +lock file to avoid conflicts with +.Xr uucp +.Dp +.Sh DIAGNOSTICS Diagnostics are, hopefully, self explanatory. -.SH "SEE ALSO" -remote(5), phones(5) -.SH BUGS +.Sh SEE ALSO +.Xr remote 5 , +.Xr phones 5 +.Sh HISTORY +.Nm Tip +appeared in 4.2 BSD. +.Sh BUGS The full set of variables is undocumented and should, probably, be paired down. diff --git a/usr/src/usr.bin/tn3270/mset/mset.1 b/usr/src/usr.bin/tn3270/mset/mset.1 index cbd55e62bc..a05a318960 100644 --- a/usr/src/usr.bin/tn3270/mset/mset.1 +++ b/usr/src/usr.bin/tn3270/mset/mset.1 @@ -1,145 +1,152 @@ -.\" Copyright (c) 1986 The Regents of the University of California. +.\" Copyright (c) 1986, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)mset.1 4.2 (Berkeley) %G% +.\" @(#)mset.1 4.3 (Berkeley) %G% .\" -.TH MSET 1 "" -.UC 6 -.SH NAME -mset \- retrieve ASCII to IBM 3270 keyboard map -.SH SYNOPSIS -.B mset -[-picky] [-shell] [keyboardname] -.SH DESCRIPTION -.I Mset +.Dd +.Dt MSET 1 +.Os BSD 4.3 +.Sh NAME +.Nm mset +.Nd retrieve ASCII to IBM 3270 keyboard map +.Sh SYNOPSIS +.Nm mset +.Op Fl picky +.Op Fl shell +.Op Ar keyboardname +.Sh DESCRIPTION +.Nm Mset retrieves mapping information for the ASCII keyboard to IBM 3270 terminal special functions. Normally, these mappings are found in -.I /etc/map3270 +.Pa /usr/share/misc/map3270 (see -.IR map3270 (5)). +.Xr map3270 5 ) . This information is used by the -.I tn3270 +.Xr tn3270 command (see -.IR tn3270 (1)). -.PP +.Xr tn3270 1 ) . +.Pp The default -.I mset +.Nm mset output can be used to store the mapping information in the process environment in order to avoid scanning -.I /etc/map3270 +.Nm map3270 each time -.I tn3270 +.Nm tn3270 is invoked. To do this, place the following command in your -.I .login +.Pa .login file: -.ti 5n -.sp - set noglob; setenv \s-1MAP3270\s0 "\(gamset\(ga"; unset noglob -.PP +.Pp +.Dl set noglob; setenv MAP3270 "\(gamset\(ga"; unset noglob +.Pp If the -.I keyboardname +.Ar keyboardname argument is not supplied, -.I mset +.Nm mset attempts to determine the name of the keyboard the user is using, by checking the -.B KEYBD +.Ev KEYBD environment variable. If the -.B KEYBD +.Ev KEYBD environment variable is not set, then -.I mset +.Nm mset uses the user's terminal type from the environment variable -.B TERM +.Ev TERM as the keyboard name. Normally, -.I mset +.Nm mset then uses the file -.I /etc/map3270 +.Xr map3270 5 to find the keyboard mapping for that terminal. However, if the environment variable -.B MAP3270 +.Ev MAP3270 exists and contains the entry for the specified keyboard, then that definition is used. If the value of -.B MAP3270 +.Ev MAP3270 begins with a slash (`/') then it is assumed to be the full pathname of an alternate mapping file and that file is searched first. In any case, if the mapping for the keyboard is not found in the environment, nor in an alternate map file, nor in the standard map file, then the same search is performed for an entry for a keyboard with the name -.BR unknown . +.Ar unknown . If that search also fails, then a default mapping is used. -.PP +.Pp The arguments to -.I mset +.Nm mset are: -.sp -.TP +2 --picky -When processing the various map3270 entries (for the user's keyboard, +.Pp +.Tw Fl +.Tp Fl picky +When processing the various +.Pa map3270 +entries (for the user's keyboard, and all those encountered before the one for the user's keyboard), -.I mset +.Nm mset normally will not complain about entries for unknown functions (like -\*(lqPFX1\*(rq); the -.I -picky +.Dq PFX1 ; +the +.Fl picky argument causes -.I mset +.Nm mset to issue warning messages about these unknown entries. -.TP --shell -If the map3270 entry is longer than the shell's 1024 environmental variable +.Tp Fl shell +If the +.Pa map3270 +entry is longer than the shell's 1024 environmental variable length limit, the default -.I mset +.Nm mset output cannot be used to store the mapping information in the process environment to avoid scanning -.I /etc/map3270 +.Pa map3270 each time -.I tn3270 +.Nm tn3270 is invoked. The -.I -shell +.Fl shell argument causes -.I mset +.Nm mset to generate shell commands to set the environmental variables -.BR MAP3270 , -.BR MAP3270A , +.Ev MAP3270 , +.Ev MAP3270A , and so on, breaking up the entry to fit within the shell environmental variable length limit. To set these variables, place the following command in your -.I .login +.Pa .login file: -.sp -mset -shell > tmp ; source tmp ; /bin/rm tmp -.TP -keyboardname -When searching for the map3270 entry that matches the user's keyboard, -.I mset +.Pp +.Dl mset -shell > tmp ; source tmp ; /bin/rm tmp +.Tp Ar keyboardname +When searching for the +.Pa map3270 +entry that matches the user's keyboard, +.Nm mset will use -.I keyboardname +.Ar keyboardname instead of determining the keyboard name from the -.B KEYBD +.Ev KEYBD or -.B TERM +.Ev TERM environmental variables. -.SH FILES -/etc/map3270 keyboard mapping for known keyboards -.SH SEE ALSO -tn3270(1), map3270(5) +.Sh FILES +.Dw /usr/share/misc/map3270 +.Di L +.Dp Pa /usr/share/misc/map3270 +keyboard mapping for known keyboards +.Dp +.Sh ENVIRONMENT +.Sh SEE ALSO +.Xr tn3270 1 , +.Xr map3270 5 +.Sh HISTORY +.Nm mset +appeared in 4.3 BSD. diff --git a/usr/src/usr.bin/tn3270/tn3270/tn3270.1 b/usr/src/usr.bin/tn3270/tn3270/tn3270.1 index 78f5dd05e4..40ec5c694e 100644 --- a/usr/src/usr.bin/tn3270/tn3270/tn3270.1 +++ b/usr/src/usr.bin/tn3270/tn3270/tn3270.1 @@ -1,125 +1,126 @@ -.\" Copyright (c) 1986 The Regents of the University of California. +.\" Copyright (c) 1986, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)tn3270.1 4.2 (Berkeley) %G% +.\" @(#)tn3270.1 4.3 (Berkeley) %G% .\" -.TH TN3270 1 "" -.UC 6 -.SH NAME -tn3270 \- full-screen remote login to IBM VM/CMS -.SH SYNOPSIS -.B tn3270 -[-d] [-n filename] [-t commandname] [sysname [port]] -.SH DESCRIPTION -.I Tn3270 +.Dd +.Dt TN3270 1 +.Os BSD 4.3 +.Sh NAME +.Nm tn3270 +.Nd full-screen remote login to IBM VM/CMS +.Sh SYNOPSIS +.Nm tn3270 +.Op Fl d +.Op Fl n Ar filename +.Op Fl t Ar commandname +.Op Ar sysname Op port +.Sh DESCRIPTION +.Nm Tn3270 permits a full-screen, full-duplex connection -from a \s-UNIX\s0 machine +from a UNIX +machine to an IBM (or compatible) machine. -.I Tn3270 +.Nm Tn3270 gives the appearance of being logged in to the remote machine from an IBM 3270 terminal. Of course, you must have an account on the machine to which you connect in order to log in. -.I Tn3270 +.Nm Tn3270 looks to the user in many respects like the Yale ASCII Terminal Communication System II. -.I Tn3270 +.Nm Tn3270 is actually a modification of the Arpanet TELNET user interface (see -.IR telnet (1)) +.Xr telnet 1 ) which will, in certain circumstances, interpret and generate raw 3270 control streams. -.PP +.Pp The flags to -.I tn3270 +.Nm tn3270 are as follows: -.TP +2 --d +.Tw Fl +.Tp Fl d Turn on socket-level tracing (for super-user only) -.TP --n filename +.Ct Fl n +.Ar filename +.Cx Specify a file to receive network trace data output (from commands "toggle netdata" and "toggle options", see -.IR telnet (1c)); +.Xr telnet 1 ) ; the default is for output to be directed to the standard error file. -.TP --t commandname -Specify a \s-UNIX\s0 command to process IBM 4994 style transparent mode +.Ct Fl t +.Ar commandname +.Cx +Specify a UNIX +command to process IBM 4994 style transparent mode data received from the remote IBM machine. -.TP -sysname +.Tp Ar sysname The name of the remote system. If the remote name is NOT specified, the user will be prompted for a command (see below). -.TP -port +.Tp Ar port The port to connect to on the remote system. Normally, -.I tn3270 +.Nm tn3270 attempts to connect to the standard TELNET port (port 23) on the remote machine. -.sp -.PP +.Tp +.Pp When -.I tn3270 +.Nm tn3270 first connects to the remote system, it will negotiate to go into 3270 mode. Part of this negotiation involves telling the remote system what model 3270 it is emulating. In all cases, -.I tn3270 +.Nm tn3270 emulates a 3278 terminal. To decide which specific model, -.I tn3270 +.Nm tn3270 looks at the number of lines and columns on the actual terminal (as defined in the -.B TERM +.Ev TERM environment variable; see -.IR termcap (5)). -The terminal (or window in which tn3270 is running, on multiple +.Xr termcap 5 ) . +The terminal (or window in which +.Nm tn3270 +is running, on multiple window systems) must have at least 80 columns and 24 lines, or -.I tn3270 +.Nm tn3270 will not go into emulation mode. If the terminal does have at least 80 columns and at least 24 lines, the following table describes the emulation: -.sp +.Pp .ne 7v -.nf -.ta 0.5i 1.5i - minimum size emulated - (rows*columns) terminal - -------------- ------------ - 27*132 3278 model 5 - 43*80 3278 model 4 - 32*80 3278 model 3 - 24*80 3278 model 2. -.fi -.sp -.PP -Emulation of the 3270 terminal is done in the \s-UNIX\s0 process. +.Ds C +.Cw (rows*columns) +.Cl minimum_size emulated +.Cl (rows*columns) terminal +.Cl -------------- ------------ +.Cl 27*132 3278 model 5 +.Cl 43*80 3278 model 4 +.Cl 32*80 3278 model 3 +.Cl 24*80 3278 model 2. +.Cw +.De +.Pp +.Pp +Emulation of the 3270 terminal is done in the UNIX +process. This emulation involves mapping 3270-style commands from the host into appropriate sequences to control the user's terminal screen. -.I Tn3270 +.Nm Tn3270 uses -.IR curses (3x) +.Xr curses 3 and the -.I /etc/termcap +.Pa /usr/share/misc/termcap file to do this. The emulation also involves simulating the special 3270 keyboard keys (program function keys, etc.) @@ -127,83 +128,92 @@ by mapping sequences of keystrokes from the ASCII keyboard into appropriate 3270 control strings. This mapping is terminal dependent and is specified in a description file, -.IR /etc/map3270 , +.Pa /usr/share/misc/map3270 , (see -.IR map3270 (5)) +.Xr map3270 5 ) or in an environment variable -.I MAP3270 +.Ev MAP3270 (and, if necessary, -.IR MAP3270A , -.IR MAP3270B , +.Ev MAP3270A , +.Ev MAP3270B , and so on - see -.IR mset (1)). +.Xr mset 1 ) . Any special function keys on the ASCII keyboard are used whenever possible. If an entry for the user's terminal is not found, -.I tn3270 +.Nm tn3270 looks for an entry for the terminal type -.B unknown. +.Em unknown . If this is not found, -.I tn3270 +.Nm tn3270 uses a default keyboard mapping (see -.IR map3270 (5)). -.PP -The first character of each special keyboard mapping sequence +.Xr map3270 5 ) . +.Pp +The first character of each special keyboard mapping sequence is either an ASCII escape (ESC), a control character, or an ASCII delete (DEL). If the user types an unrecognized function key sequence, -.I tn3270 +.Nm tn3270 sends an ASCII bell (BEL), or a visual bell if defined in the user's termcap entry, to the user's terminal and nothing is sent to the IBM host. -.PP +.Pp If -.I tn3270 +.Nm tn3270 is invoked without specifying a remote host system name, it enters local command mode, -indicated by the prompt ``tn3270>''. +indicated by the prompt +.Dq Li tn3270>\ . In this mode, -.I tn3270 +.Nm tn3270 accepts and executes all the commands of -.IR telnet (1), +.Xr telnet 1 , plus one additional command: -.TP +2 -transcom -Specify \s-UNIX\s0 command for IBM 4994 style transparent mode processing. -.PP -.I Tn3270 +.Pp +.Tw Ar +.Tp Ic transcom +Specify UNIX +command for IBM 4994 style transparent mode processing. +.Tp +.Pp +.Nm Tn3270 command mode may also be entered, after connecting to a host, by typing a special escape sequence. If -.I tn3270 +.Nm tn3270 has succeeded in negotiating 3270 mode with the remote host, the escape sequence will be as defined by the map3270 (see -.IR map3270 (5)) +.Xr map3270 5 ) entry for the user's terminal type (typically control-C); otherwise the escape sequence will initially be set to the -single character '^]' +single character +.Sq Li \&^] (control right square bracket). -.PP +.Pp While in command mode, any host login session is still alive but temporarily suspended. The host login session may be resumed by entering an empty line -(press the RETURN key) +(press the +.Li RETURN +key) in response to the command prompt. A session may be terminated by logging off the foreign host, or by typing ``quit'' or ``close'' while in local command mode. -.SH FILES -/etc/termcap +.Sh FILES +.Dw /usr/share/misc/termcap +.Di L +.Dp Pa /usr/share/misc/termcap .br -/etc/map3270 -.SH AUTHOR +.Dp Pa /usr/share/misc/map3270 +.Dp +.Sh AUTHOR Greg Minshall -.SH NOTES -.PP +.Sh NOTES The IBM 4994 style transparent mode command is invoked when -.I tn3270 +.Nm tn3270 receives IBM 4994 style transparent output from the remote host. Output and input pipes are created for communication between the two processes. @@ -213,21 +223,44 @@ Transparent mode is necessary for sending ASCII control characters over the 3270 terminal connection; ASCII graphics terminal support is accomplished this way. Developers of -.I transcom +.Ic transcom commands should note that the -.I transcom +.Ic transcom stdin pipe end will be in CBREAK mode, with ECHO and CRMOD turned off. -.SH SEE ALSO -mset(1), telnet(1), curses(3x), termcap(3x), termcap(5), map3270(5), -\fIYale ASCII Terminal Communication -System II Program Description/Operator's Manual\fR -(IBM SB30-1911) -.SH BUGS +.Sh ENVIRONMENT +.Nm Tn3270 +checks the following environment variables: +.Ev TERM , +.Ev MAP3270 , +.Ev MAP3270[A...] . +Information on these can be found in +.Xr mset 1 . +.Nm Tn3270 +also checks +.Ev SHELL , +.Ev KEYBD +and +.Ev API3270 . +.Sh SEE ALSO +.Xr mset 1 , +.Xr telnet 1 , +.Xr curses 3 , +.Xr termcap 3 , +.Xr termcap 5 , +.Xr map3270 5 , +.br +.Em Yale ASCII Terminal Communication +.Em System II Program Description/Operator's Manual +.Pq IBM SB30-1911 +.Sh HISTORY +.Nm +appeared in 4.3 BSD. +.Sh BUGS Tn3270 is slow and uses system resources prodigiously. -.PP +.Pp Not all 3270 functions are supported, nor all Yale enhancements. -.PP +.Pp Error conditions (attempting to enter data in a protected field, for example) should cause a message to be sent to the user's terminal instead of just ringing a bell. diff --git a/usr/src/usr.bin/tset/tset.1 b/usr/src/usr.bin/tset/tset.1 index f4d2b4355b..7b24a1f037 100644 --- a/usr/src/usr.bin/tset/tset.1 +++ b/usr/src/usr.bin/tset/tset.1 @@ -1,208 +1,314 @@ -.\" Copyright (c) 1985 The Regents of the University of California. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %sccs.include.redist.man% .\" -.\" @(#)tset.1 6.3 (Berkeley) %G% +.\" @(#)tset.1 6.4 (Berkeley) %G% .\" -.TH TSET 1 "" -.UC 4 -.SH NAME -tset \- terminal dependent initialization -.SH SYNOPSIS -.B tset -[ options ] [ -.B \-m -[ident][test baudrate]:type ] \&... [ type ] -.sp 1 -.B reset -[ options ] [ -.B \-m -[ident][test baudrate]:type ] \&... [ type ] -.SH DESCRIPTION -.I Tset +.Dd +.Dt TSET 1 +.Os BSD 4 +.Sh NAME +.Nm tset +.Nd terminal dependent initialization +.Sh SYNOPSIS +.Nm tset +.Op Ar options +.Cx \&[\ \& +.Fl m +.Cx \&\ \& +.Op Ar ident +.Op Ar test baudrate +.Cx Cm \&: +.Ar type +.Cx \&]\ \&... +.Cx +.Op type +.Pp +.Nm reset +.Op Ar options +.Cx \&[\ \& +.Fl m +.Cx \&\ \& +.Op Ar ident +.Op Ar test baudrate +.Cx Cm \&: +.Ar type +.Cx \&]\ \&... +.Cx +.Op type +.Sh DESCRIPTION +.Nm Tset sets up your terminal when you first log in to a UNIX system. It does terminal dependent processing such as setting erase and kill characters, setting or resetting delays, sending any sequences needed to properly initialized the terminal, and the like. It first determines the -.I type +.Ar type of terminal involved, and then does necessary initializations and mode settings. -The type of terminal attached to each \s-2UNIX\s0 port is specified in the -.IR /etc/ttys (5) +The type of terminal attached to each +UNIX +port is specified in the +.Xr ttys 5 database. Type names for terminals may be found in the -.IR termcap (5) +.Xr termcap 5 database. If a port is not wired permanently to a specific terminal (not hardwired) it will be given an appropriate generic identifier such as -.IR dialup . -.PP +.Ar dialup . +.Pp In the case where no arguments are specified, -.I tset -simply reads the terminal type out of the environment variable TERM +.Nm tset +simply reads the terminal type out of the environment variable +.Ev TERM and re-initializes the terminal. The rest of this manual concerns itself with mode and environment initialization, typically done once at login, and options used at initialization time to determine the terminal type and set up terminal modes. -.PP -When used in a startup script (\fI\&.profile\fR for -.IR sh (1) +.Pp +.Tw Ds +.Tp Cx Fl e +.Ar c +.Cx +set the erase character to be the named character +.Ar c +on all terminals, +the default being the backspace character on the terminal, usually ^H. +The character +.Ar c +can either be typed directly, or entered using the hat +notation used here. +.Tp Cx Fl k +.Ar c +.Cx +is similar to +.Fl e +but for the line kill character rather than the erase character; +.Ar c +defaults to ^X (for purely historical reasons). +The kill characters is left alone if +.Fl k +is not specified. +The hat notation can also be used for this option. +.Tp Cx Fl i +.Ar c +.Cx +is similar to +.Fl e +but for the interrupt character rather than the erase character; +.Ar c +defaults to ^C. The hat notation can also be used for this option. +.Tp Fl +The name of the terminal finally decided upon is output on the +standard output. +This is intended to be captured by the shell and placed in the +environment variable +.Ev TERM. +.Tp Fl s +Print the sequence of +.Xr csh 1 +commands to initialize the environment variables +.Ev TERM +and +.Ev TERMCAP +based on +the name of the terminal finally decided upon. +.Tp Fl m +The +.FL m +Specify what terminal type to use on specific ports (i.e. map the +terminal type to a port as found in +.Xr ttys 5 . ) +See below. +.Tp Fl n +On systems with the Berkeley 4BSD tty driver, +specifies that the new tty driver modes should be initialized for this terminal. +For a +.Li CRT , +the +.Li CRTERASE +and +.Li CRTKILL +modes are set only if the baud rate is 1200 or greater. +See +.Xr tty 4 +for more detail. +.Tp Fl I +suppresses transmitting terminal initialization strings. +.Tp Fl Q +suppresses printing the +.Dq Li Erase set to +and +.Dq Li Kill set to +messages. +.Tp +.Pp +When used in a startup script ( +.Pa \&.profile +for +.Xr sh 1 users or -.I \&.login +.Pa \&.login for -.IR csh (1) +.Xr csh 1 users) it is desirable to give information about the type of terminal you will usually use on ports which are not hardwired. These ports are identified in -.I /etc/ttys +.Xr ttys 5 as -.I dialup +.Li dialup or -.I plugboard +.Li plugboard or -.I arpanet, +.Li arpanet , etc. To specify what terminal type you usually use on these ports, the -.B \-m +.Fl m (map) option flag is followed by the appropriate port type identifier, an optional baud rate specification, and the terminal type. (The effect is to ``map'' from some conditions to a terminal type, that is, to tell -.I tset +.Nm tset ``If I'm on this kind of port, guess that I'm on that kind of terminal''.) If more than one mapping is specified, the first applicable mapping prevails. A missing port type identifier matches all identifiers. Any of the alternate generic names given in -.I termcap +.Xr termcap 5 may be used for the identifier. -.PP +.Pp A -.I baudrate +.Ar baudrate is specified as with -.IR stty (1), +.Xr stty 1 , and is compared with the speed of the diagnostic output (which should be the control terminal). The baud rate -.I test +.Ar test may be any combination of: -.BR > , -.BR @ , -.BR < , +.Ic \&> , +.Ic \&@ , +.Ic \&< , and -.BR ! ; -.B @ +.Ic \&! ; +.Ic \&@ means ``at'' and -.B ! +.Ic \&! inverts the sense of the test. To avoid problems with metacharacters, it is best to place the entire argument to -.B \-m +.Fl m within ``\''' characters; users of -.IR csh (1) +.Xr csh 1 must also put a ``\e'' before any ``!'' used here. -.PP -.KS -Thus -.IP +.Pp +.Df I tset \-m \'dialup>300:adm3a\' -m dialup:dw2 -m \'plugboard:?adm3a\' -.KE -.LP +.De +.Pp causes the terminal type to be set to an -.I adm3a +.Ar adm3a if the port in use is a dialup at a speed greater than 300 baud; -to a -.I dw2 +to a +.Ar dw2 if the port is (otherwise) a dialup (i.e. at 300 baud or less). -(\fBNOTE:\fP the examples given here appear to take up more than +.Ar NOTE : +the examples given here appear to take up more than one line, for text processing reasons. When you type in real -.I tset -commands, you must enter them entirely on one line.) +.Nm tset +commands, you must enter them entirely on one line. If the -.I type +.Ar type finally determined by -.I tset +.Nm tset begins with a question mark, the user is asked if s/he really wants that type. A null response means to use that type; otherwise, another type can be entered which will be used instead. Thus, in the above case, the user will be queried on a plugboard port as to whether they are actually using an -.IR adm3a . -.PP +.Ar adm3a . +.Pp If no mapping applies and a final -.I type +.Ar type option, not preceded by a -.BR \-m , +.Fl m , is given on the command line then that type is used; otherwise the type found in the -.I /etc/ttys +.Xr ttys 5 database will be taken to be the terminal type. This should always be the case for hardwired ports. -.PP +.Pp It is usually desirable to return the terminal type, as finally determined by -.IR tset , +.Nm tset , and information about the terminal's capabilities to a shell's environment. This can be done using the -.B \- +.Fl option; using the Bourne shell, -.IR sh (1): -.IP -export TERM; TERM=\`tset \- \fIoptions...\fR\` -.LP +.Xr sh 1 : +.Pp +.Df I +.Li export TERM; TERM=\&\`tset \- +.Ar options ... +.Li \&\` +.De +.Pp or using the C shell, -.IR csh (1): -.IP -setenv TERM \`tset - \fIoptions...\fR\` -.PP +.Xr csh 1 : +.Pp +.Df I +.Li setenv TERM \`tset \- +.Ar options . . . +.Li \&\` +.De +.Pp With -.I csh +.Xr csh 1 it is preferable to use the following command in your .login file to -initialize the TERM and TERMCAP environment variables at the same time. -.IP -eval \`tset -s \fIoptions...\fR\` -.PP +initialize the +.Ev TERM +and +.Ev TERMCAP +environment variables at the same time. +.Pp +.Df I +.Li eval \`tset -s +.Ar options ... +.Li \&\` +.De +.Pp It is also convenient to make an alias in your .cshrc: -.IP -alias tset \'eval \`tset \-s \e!*\`\' -.PP +.Pp +.Dl alias tset \'eval \`tset \-s \e!*\`\' +.Pp This allows the command: -.IP -tset 2621 -.PP +.Pp +.Dl tset 2621 +.Pp to be invoked at any time to set the terminal and environment. -.B "Note to Bourne Shell users:" +.Sy Note to Bourne Shell users: It is -.B not +.Em not possible to get this aliasing effect with a shell script, because shell scripts cannot set the environment of their parent. (If a process could set its parent's environment, none of this nonsense would be necessary in the first place.) -.PP +.Pp These commands cause -.I tset +.Nm tset to place the name of your terminal in the variable -TERM in the environment; see -.IR environ (7). -.PP +.Ev TERM +in the environment; see +.Xr environ 7 . +.Pp Once the terminal type is known, -.I tset +.Nm tset engages in terminal driver mode setting. This normally involves sending an initialization sequence to the terminal, setting the single character erase (and optionally @@ -210,121 +316,82 @@ the line-kill (full line erase)) characters, and setting special character delays. Tab and newline expansion are turned off during transmission of the terminal initialization sequence. -.PP +.Pp On terminals that can backspace but not overstrike -(such as a \s-2CRT\s0), +(such as a +.Em CRT ) , and when the erase character is the default erase character (`#' on standard systems), -the erase character is changed to \s-2BACKSPACE\s0 (Control-H). -.PP -The options are: -.TP -.B \-e\fIc -set the erase character to be the named character -.I c -on all terminals, -the default being the backspace character on the terminal, usually ^H. -The character -.I c -can either be typed directly, or entered using the hat -notation used here. -.TP -.B \-k\fIc -is similar to -.B \-e -but for the line kill character rather than the erase character; -.I c -defaults to ^X (for purely historical reasons). -The kill characters is left alone if -.B \-k -is not specified. -The hat notation can also be used for this option. -.TP -.B \-i\fIc -is similar to -.B \-e -but for the interrupt character rather than the erase character; -.I c -defaults to ^C. The hat notation can also be used for this option. -.TP -.B \- -The name of the terminal finally decided upon is output on the -standard output. -This is intended to be captured by the shell and placed in the -environment variable TERM. -.TP -.B \-s -Print the sequence of -.I csh -commands to initialize the environment variables TERM and TERMCAP based on -the name of the terminal finally decided upon. -.TP -.B \-n -On systems with the Berkeley 4BSD tty driver, -specifies that the new tty driver modes should be initialized for this terminal. -For a \s-2CRT\s0, -the CRTERASE and CRTKILL -modes are set only if the baud rate is 1200 or greater. -See tty(4) for more detail. -.TP -.B \-I -suppresses transmitting terminal initialization strings. -.TP -.B \-Q -suppresses printing the -``Erase set to'' and ``Kill set to'' messages. -.PP +the erase character is changed to +.Li BACKSPACE +(Control-H). +.Pp If -.B tset +.Nm tset is invoked as -.BR reset , +.Nm reset , it will set cooked and echo modes, turn off cbreak and raw modes, turn on newline translation, and restore special characters to a sensible state before any terminal dependent processing is done. -Any special character that is found to be \s-2NULL\s0 +Any special character that is found to be +.Li NULL or ``\-1'' is reset to its default value. All arguments to -.I tset +.Nm tset may be used with reset. -.PP +.Pp This is most useful after a program dies leaving a terminal in a funny -state. You may have to type ``\s-2\s0reset\s-2\s0'' to get it to work -since \s-2\s0 may not work in this state. Often none of this will echo. -.SH EXAMPLES -.PP -These examples all assume the Bourne shell and use the - option. +state. You may have to type `` +.Dq Li reset +to get it to work +since +.Li +may not work in this state. Often none of this will echo. +.Sh EXAMPLES +.Pp +These examples all assume the Bourne shell and use the +.Fl +option. If you use -.IR csh , +.Xr csh , use one of the variations described above. Note that a typical use of -.I tset -in a .profile or .login will also use the -.B \-e +.Nm tset +in a +.Pa .profile or +.Pa .login +will also use the +.Fl e and -.B \-k +.Fl k options, and often the -.B \-n +.Fl n or -.B \-Q +.Fl Q options as well. These options have not been included here to keep the examples small. -(\fBNOTE:\fP some of the examples given here appear to take up more than +.Sy NOTE : +some of the examples given here appear to take up more than one line, for text processing reasons. When you type in real -.I tset -commands, you must enter them entirely on one line.) -.PP -At the moment, you are on a 2621. +.Nm tset +commands, you must enter them entirely on one line. +.Pp +At the moment, you are on a +.Li 2621 . This is suitable for typing by hand but -not for a .profile, unless you are -.I always +not for a +.Pa .profile, unless you are +.Em always on a 2621. -.IP -export TERM; TERM=\`tset \- 2621\` -.PP +.Pp +.Dl export TERM; TERM=\`tset \- 2621\` +.Pp You have an h19 at home which you dial up on, but your office terminal -is hardwired and known in /etc/ttys. -.IP -export TERM; TERM=\`tset \- \-m dialup:h19\` -.PP +is hardwired and known in +Xr ttys 5 . +.Pp +.Dl export +TERM; TERM=\`tset \- \-m dialup:h19\` +.Pp You have a switch which connects everything to everything, making it nearly impossible to key on what port you are coming in on. You use a vt100 in your office at 9600 baud, and dial up to switch @@ -336,12 +403,16 @@ always on a 2621. Note the placement of the question mark, and the quotes to protect the greater than and question mark from interpretation by the shell. -.IP -export TERM; TERM=\`tset \- \-m 'switch>1200:?vt100' \-m 'switch<=1200:2621' -.PP +.Pp +.Df I +.Li export TERM; +.Li TERM=\`tset \- \-m 'switch>1200:?vt100' +.Li \-m 'switch<=1200:2621' +.De +.Pp All of the above entries will fall back on the terminal type specified in -.I /etc/ttys +.Xr ttys 5 if none of the conditions hold. The following entry is appropriate if you always dial up, always at the same baud rate, @@ -349,18 +420,18 @@ on many different kinds of terminals. Your most common terminal is an adm3a. It always asks you what kind of terminal you are on, defaulting to adm3a. -.IP -export TERM; TERM=\`tset \- \?adm3a\` -.PP +.Pp +.Dl export TERM; TERM=\`tset \- \?adm3a\` +.Pp If the file -.I /etc/ttys +.Xr ttys 5 is not properly installed and you want to key entirely on the baud rate, the following can be used: -.IP -export TERM; TERM=\`tset \- \-m '>1200:vt100' 2621\` -.PP +.Pp +.Dl export TERM; TERM=\`tset \- \-m '>1200:vt100' 2621\` +.Pp Here is a fancy example to illustrate the power of -.I tset +.Nm tset and to hopelessly confuse anyone who has made it this far. You dial up at 1200 baud or less on a concept100, sometimes over switch ports and sometimes over regular dialups. @@ -370,25 +441,54 @@ However, sometimes you log in from the university you used to go to, over the ARPANET; in this case you are on an ALTO emulating a dm2500. You also often log in on various hardwired ports, such as the console, all of which are properly entered in -.IR /etc/ttys . +.Xr ttys 5 . You want your erase character set to control H, your kill character set to control U, and don't want -.I tset -to print the ``Erase set to Backspace, Kill set to Control U'' message. -.IP -export TERM; TERM=\`tset \-e \-k^U \-Q \- \-m 'switch<=1200:concept100' \-m 'switch:?vt100' \-m dialup:concept100 \-m arpanet:dm2500\` -.SH FILES -.DT -/etc/ttys port name to terminal type mapping database -.br -/etc/termcap terminal capability database -.SH SEE\ ALSO -csh(1), sh(1), stty(1), ttys(5), termcap(5), environ(7) -.SH BUGS -.PP +.Nm tset +to print the +.Dq Li Erase set to Backspace , +.Dq Li Kill set to Control U +message. +.Pp +.Df I +.Li export TERM; +.Li TERM=\`tset \-e \-k^U \-Q \- +.Li \-m 'switch<=1200:concept100' +.Li \-m 'switch:?vt100' +.Li \-m dialup:concept100 +.Li \-m arpanet:dm2500\` +.De +.Sh ENVIRONMENT +The +.Nm tset +command utilizes the +.Ev TERM +and +.Ev TERMCAP +environment variables. +.Sh FILES +.Dw /usr/share/misc/termcap +.Di L +.Dp Pa /etc/ttys +port name to terminal type mapping database +.Dp Pa /usr/share/misc/termcap +terminal capability database +.Dp +.Sh SEE ALSO +.Xr csh 1 , +.Xr sh 1 , +.Xr stty 1 , +.Xr ttys 5 , +.Xr termcap 5 , +.Xr environ 7 +.Sh HISTORY +.Nm Tset +appeared in 3 BSD. +.Sh BUGS +.Pp The -.I tset +.Nm tset command is one of the first commands a user must master when getting started on a UNIX system. Unfortunately, it is one of the most complex, @@ -396,43 +496,48 @@ largely because of the extra effort the user must go through to get the environment of the login shell set. Something needs to be done to make all this simpler, either the -.IR login (1) +.Xr login 1 program should do this stuff, or a default shell alias should be made, or a way to set the environment of the parent should exist. -.PP +.Pp This program can't intuit personal choices for erase, interrupt and line kill characters, so it leaves these set to the local system standards. .ig -.SH NOTES +.Sh NOTES For compatibility with earlier versions of -.I tset +.Nm tset a number of flags are accepted whose use is discouraged: -.TP 10 -\fB\-d\fR type +.Tw Fl +.Tp Cx Fl d +.Ar type +.Cx equivalent to -.B \-m -dialup:type -.TP 10 -\fB\-p\fR type +.Fl m +.Ar dialup:type +.Tp Cx Fl p +.Ar type +.Cx equivalent to -.B \-m -plugboard:type -.TP 10 -\fB\-a\fR type +.Fl m +.Ar plugboard:type +.Tp Cx Fl a +.Ar type +.Cx equivalent to -.B \-m -arpanet:type -.TP 10 -\fB\-E\fR c +.Fl m +.Ar arpanet:type +.Cx +.Tp Cx Fl E +.Ar c +.Cx Sets the erase character to -.I c +.Ar c only if the terminal can backspace. -.TP 10 -\fB\-\fR +.Tp Fl prints the terminal type on the standard output -.TP 10 -\fB\-r\fR +.Tp Fl r prints the terminal type on the diagnostic output. +.Tp .. diff --git a/usr/src/usr.bin/window/window.1 b/usr/src/usr.bin/window/window.1 index f01574f01a..b7dbbc930d 100644 --- a/usr/src/usr.bin/window/window.1 +++ b/usr/src/usr.bin/window/window.1 @@ -1,66 +1,99 @@ -.\" Copyright (c) 1985 The Regents of the University of California. +.\" Copyright (c) 1985, 1990 The Regents of the University of California. .\" All rights reserved. .\" -.\" This code is derived from software contributed to Berkeley by -.\" Edward Wang at The University of California, Berkeley. +.\" %sccs.include.redist.man% .\" -.\" Redistribution and use in source and binary forms are permitted -.\" provided that the above copyright notice and this paragraph are -.\" duplicated in all such forms and that any documentation, -.\" advertising materials, and other materials related to such -.\" distribution and use acknowledge that the software was developed -.\" by the University of California, Berkeley. The name of the -.\" University may not be used to endorse or promote products derived -.\" from this software without specific prior written permission. -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" @(#)window.1 6.10 (Berkeley) %G% .\" -.\" @(#)window.1 6.9 (Berkeley) %G% -.\" -.TH WINDOW 1 "" -.UC 6 -.SH NAME -window \- window environment -.SH SYNOPSIS -.B window -[ -.B \-t -] [ -.B \-f -] [ -.B \-d -] [ -.B \-e escape-char -] [ -.B \-c command -] -.SH DESCRIPTION -\fIWindow\fP implements a window environment on +.Dd +.Dt WINDOW 1 +.Os BSD 4.3 +.Sh NAME +.Nm window +.Nd window environment +.Sh SYNOPSIS +.Nm window +.Op Fl t +.Op Fl f +.Op Fl d +.Op Fl e Ar escape-char +.Op Fl c Ar command +.Sh DESCRIPTION +.Nm Window +implements a window environment on ASCII terminals. -.PP +.Pp A window is a rectangular portion of the physical terminal screen associated with a set of processes. Its size and position can be changed by the user at any time. Processes communicate with their window in the same way they normally -interact with a terminal--through their standard input, output, +interact with a terminal\-through their standard input, output, and diagnostic file descriptors. The window program handles the details of redirecting input an output to and from the windows. At any one time, only one window can receive input from the keyboard, but all windows can simultaneously send output to the display. -.PP +.Pp +When +.Nm window +starts up, the commands (see long commands below) +contained in the file +.Pa .windowrc +in the user's home directory are +executed. If it does not exist, two equal sized windows spanning +the terminal screen are created by default. +.Pp +The command line options are +.Tw Fl +.Tp Fl t +Turn on terse mode (see +.Ic terse +command below). +.Tp Fl f +Fast. Don't perform any startup action. +.Tp Fl d +Ignore +.Pa .windowrc +and create the two default +windows instead. +.Tp Cx Fl e +.Cx \&\ \& +.Ar escape-char +.Cx +Set the escape character to +.Ar escape-char . +.Ar Escape-char +can be a single character, or in the form +.Ic ^X +where +.Ar X +is any character, meaning +.Cx control\- +.Ar X . +.Cx +.Tp Cx Fl c +.Cx \&\ \& +.Ar command +.Cx +Execute the string +.Ar command +as a long command (see below) +before doing anything else. +.Tp +.Pp Windows can overlap and are framed as necessary. Each window is named by one of the digits ``1'' to ``9''. This one-character identifier, as well as a user definable label string, are displayed with the window on the top edge of its frame. A window can be -designated to be in the \fIforeground\fP, in which case it will always be +designated to be in the +.Ar foreground , +in which case it will always be on top of all normal, non-foreground windows, and can be covered only by other foreground windows. A window need not be completely within the edges of the terminal screen. Thus a large window (possibly larger than the screen) may be positioned to show only a portion of its full size. -.PP +.Pp Each window has a cursor and a set of control functions. Most intelligent terminal operations such as line and character deletion and insertion are supported. Display modes @@ -69,108 +102,128 @@ supported by the terminal. In addition, similar to terminals with multiple pages of memory, each window has a text buffer which can have more lines than the window itself. -.SH OPTIONS -When \fIwindow\fP starts up, the commands (see long commands below) -contained in the file \fI.windowrc\fP in the user's home directory are -executed. If it does not exist, two equal sized windows spanning -the terminal screen are created by default. -.PP -The command line options are -.TP -.B \-t -Turn on terse mode (see \fIterse\fP command below). -.TP -.B \-f -Fast. Don't perform any startup action. -.TP -.B \-d -Ignore \fI.windowrc\fP and create the two default -windows instead. -.TP -.B \-e escape-char -Set the escape character to \fIescape-char\fP. \fIEscape-char\fP -can be a single character, or in the form \fI^X\fP where \fIX\fP -is any character, meaning control-\fIX\fP. -.TP -.B \-c command -Execute the string \fIcommand\fP as a long command (see below) -before doing anything else. -.SH "PROCESS ENVIRONMENT" +.Ss Process Environment With each newly created window, a shell program is spawned with its process environment tailored to that window. Its standard input, output, and diagnostic file descriptors are bound to one end of either -a pseudo-terminal (\fIpty\fP (4)) or a UNIX domain socket -(\fIsocketpair\fP (4)). If a pseudo-terminal is used, then its special -characters and modes (see \fIstty\fP (1)) are copied from the physical -terminal. A \fItermcap\fP (5) entry tailored to this window is created -and passed as environment (\fIenviron\fP (5)) variable -\fITERMCAP\fP. The termcap entry contains the window's size and +a pseudo-terminal +.Xr (pty 4 ) +or a UNIX domain socket +.Xr (socketpair 4 ) . +If a pseudo-terminal is used, then its special +characters and modes (see +.Xr stty 1 ) +are copied from the physical +terminal. A +.Xr termcap 5 +entry tailored to this window is created +and passed as environment +.Xr (environ 5 ) +variable +.Ev TERMCAP . +The termcap entry contains the window's size and characteristics as well as information from the physical terminal, such as the existence of underline, reverse video, and other display modes, and the codes produced by the terminal's function keys, if any. In addition, the window size attributes of the pseudo-terminal are set to reflect the size of this window, and updated whenever -it is changed by the user. In particular, the editor \fIvi\fP (1) uses +it is changed by the user. In particular, the editor +.Xr vi 1 +uses this information to redraw its display. -.SH OPERATION -.PP -During normal execution, \fIwindow\fP can be in one of two states: +.Ss Operation +During normal execution, +.Nm window +can be in one of two states: conversation mode and command mode. In conversation mode, the terminal's real cursor is placed at the cursor position of a particular window--called the current window--and input from the keyboard is sent to the process in that window. The current window is always on top of all other windows, except those in foreground. In addition, it is set apart by highlighting its identifier and label in reverse video. -.PP -Typing \fIwindow\fP's escape character (normally ^P) in conversation +.Pp +Typing +.Cx Nm window +.Cx 's +.Cx +escape character (normally +.Ic ^P ) +in conversation mode switches it into command mode. In command mode, the top line of -the terminal screen becomes the command prompt window, and \fIwindow\fP +the terminal screen becomes the command prompt window, and +.Nm window interprets input from the keyboard as commands to manipulate windows. -.PP +.Pp There are two types of commands: short commands are usually one or two key strokes; long commands are strings either typed by the user in the -command window (see the ``:'' command below), or read from a file (see -\fIsource\fP below). -.SH "SHORT COMMANDS" -Below, \fI#\fP represents one of the digits ``1'' to ``9'' -corresponding to the windows 1 to 9. \fI^X\fP means control-\fIX\fP, -where \fPX\fP is any character. In particular, \fI^^\fP is -control-^. \fIEscape\fP is the escape key, or \fI^[\fP. -.TP -.B # -Select window \fI#\fP as the current window +command window (see the +.Dq Ic \&: +command below), or read from a file (see +.Ic source +below). +.Ss Short Commands +Below, +.Ar # +represents one of the digits ``1'' to ``9'' +corresponding to the windows 1 to 9. +.Ic ^X +means +.Cx control\- +.Ar X , +.Cx +where +.Ar X +is any character. In particular, +.Ic ^^ +is +.Li control\-^. +.Ar Escape +is the escape key, or +.Ic ^\&[ +.Tw Ds +.Tp Ar # +Select window +.Ar # +as the current window and return to conversation mode. -.TP -.B %# -Select window \fI#\fP but stay in command mode. -.TP -.B ^^ +.Tp Cx Ic % +.Ar # +.Cx +Select window +.Ar # +but stay in command mode. +.Tp Ic ^^ Select the previous window and return to conversation mode. This is useful for toggling between two windows. -.TP -.B escape +.Tp Ic escape Return to conversation mode. -.TP -.B ^P -Return to conversation mode and write ^P to the -current window. Thus, typing two ^P's in conversation -mode sends one to the current window. If the \fIwindow\fP +.Tp Ic ^P +Return to conversation mode and write +.Ic ^P +to the +current window. Thus, typing two +.Cx Ic ^P +.Cx \'s +.Cx +in conversation +mode sends one to the current window. If the +.Nm window escape is changed to some other character, that -character takes the place of ^P here. -.TP -.B ? +character takes the place of +.Ic ^P +here. +.Tp Ic ? List a short summary of commands. -.TP -.B ^L -Redraw the screen. -.TP -.B q -Exit \fIwindow\fP. Confirmation is requested. -.TP -.B ^Z -Suspend \fIwindow\fP. -.TP -.B w +.Tp Ic ^L +Refresh the screen. +.Tp Ic q +Exit +.Nm window . +Confirmation is requested. +.Tp Ic ^Z +Suspend +.Nm window . +.Tp Ic w Create a new window. The user is prompted for the positions of the upper left and lower right corners of the window. The cursor is placed on the screen and the keys ``h'', ``j'', @@ -185,83 +238,98 @@ the placement of the new window is indicated by a rectangular box drawn on the screen, corresponding to where the new window will be framed. Typing escape at any point cancels this command. -.IP +.Pp This window becomes the current window, and is given the first available ID. The default buffer size -is used (see \fIdefault_nline\fP command below). -.IP +is used (see +.Ar default_nline +command below). +.Pp Only fully visible windows can be created this way. -.TP -.B c# -Close window \fI#\fP. The process in the window is sent -the hangup signal (see \fIkill\fP (1)). \fICsh\fP (1) should +.Tp Cx Ic c +.Ar # +.Cx +Close window +.Ar # . +The process in the window is sent +the hangup signal (see +.Xr kill 1 ) . +.Xr Csh 1 +should handle this signal correctly and cause no problems. -.TP -.B m# -Move window \fI#\fP to another location. A box in the shape +.Tp Cx Ic m +.Ar # +.Cx +Move window +.Ar # +to another location. A box in the shape of the window is drawn on the screen to indicate the new position of the window, and the same keys as -those for the \fIw\fP command are used to position the box. The +those for the +.Ic w +command are used to position the box. The window can be moved partially off-screen. -.TP -.B M# -Move window \fI#\fP to its previous position. -.TP -.B s# -Change the size of window \fI#\fP. The user is prompted +.Tp Cx Ic M +.Ar # +.Cx +Move window +.Ar # +to its previous position. +.Tp Cx Ic s +.Ar # +.Cx +Change the size of window +.Ar # . +The user is prompted to enter the new lower right corner of the window. A box is drawn to indicate the new window size. The same -keys used in \fIw\fP and \fIm\fP are used to enter the position. -.TP -.B S# -Change window \fI#\fP to its previous size. -.TP -.B ^Y +keys used in +.Ic w +and +.Ic m +are used to enter the position. +.Tp Cx Ic S +.Ar # +.Cx +Change window +.Ar # +to its previous size. +.Tp Ic ^Y Scroll the current window up by one line. -.TP -.B ^E +.Tp Ic ^E Scroll the current window down by one line. -.TP -.B ^U +.Tp Ic ^U Scroll the current window up by half the window size. -.TP -.B ^D +.Tp Ic ^D Scroll the current window down by half the window size. -.TP -.B ^B +.Tp Ic ^B Scroll the current window up by the full window size. -.TP -.B ^F +.Tp Ic ^F Scroll the current window down by the full window size. -.TP -.B h +.Tp Ic h Move the cursor of the current window left by one column. -.TP -.B j +.Tp Ic j Move the cursor of the current window down by one line. -.TP -.B k +.Tp Ic k Move the cursor of the current window up by one line. -.TP -.B l +.Tp Ic l Move the cursor of the current window right by one column. -.TP -.B ^S +.Tp Ic ^S Stop output in the current window. -.TP -.B ^Q +.Tp Ic ^Q Start output in the current window. -.TP -.B : -Enter a line to be executed as long commands. Normal line -editing characters (erase character, erase word, erase line) are -supported. -.SH "LONG COMMANDS" +.Tp Ic : +Enter a line to be executed as long commands. +Normal line +editing characters (erase character, erase word, erase line) +are supported. +.Tp +.Ss Long Commands Long commands are a sequence of statements parsed much like a programming language, with a syntax similar to that of C. Numeric and string expressions and variables are supported, as well as conditional statements. -.PP +.Pp There are two data types: string and number. A string is a sequence of letters or digits beginning with a letter. ``_'' and ``.'' are considered letters. Alternately, non-alphanumeric characters can @@ -270,314 +338,904 @@ with ``\\''. In addition, the ``\\'' sequences of C are supported, both inside and outside quotes (e.g., ``\\n'' is a new line, ``\\r'' a carriage return). For example, these are legal strings: abcde01234, "&#$^*&#", ab"$#"cd, ab\\$\\#cd, "/usr/ucb/window". -.PP +.Pp A number is an integer value in one of three forms: a decimal number, an octal number preceded by ``0'', or a hexadecimal number preceded by ``0x'' or ``0X''. The natural machine integer size is used (i.e., the signed integer type of the C compiler). As in C, a non-zero number represents a boolean true. -.PP +.Pp The character ``#'' begins a comment which terminates at the end of the line. -.PP +.Pp A statement is either a conditional or an expression. Expression statements are terminated with a new line or ``;''. To continue an expression on the next line, terminate the first line with ``\\''. -.SH "CONDITIONAL STATEMENT" -\fIWindow\fP has a single control structure: +.Ss Conditional Statement +.Nm Window +has a single control structure: the fully bracketed if statement in the form -.nf - if then - - . . . - elsif then - - . . . - else - - . . . - endif -.fi -The \fIelse\fP and \fIelsif\fP parts are optional, and the latter can -be repeated any number of times. \fI\fP must be numeric. -.SH EXPRESSIONS -Expressions in \fIwindow\fP are similar to those in the +.Pp +.Ds I +if then +\t +\t... +elsif then +\t +\t... +else +\t +\t... +endif +.De +.Pp +The +.Ic else +and +.Ic elsif +parts are optional, and the latter can +be repeated any number of times. + +must be numeric. +.Ss Expressions +Expressions in +.Nm window +are similar to those in the C language, with most C operators supported on numeric operands. In addition, some are overloaded to operate on strings. -.PP +.Pp When an expression is used as a statement, its value is discarded after evaluation. Therefore, only expressions with side effects (assignments and function calls) are useful as statements. -.PP +.Pp Single valued (no arrays) variables are supported, of both numeric and string values. Some variables are predefined. They are listed below. -.PP +.Pp The operators in order of increasing precedence: -.TP -.B = -Assignment. The variable of name \fI\fP, which must be string valued, -is assigned the result of \fI\fP. Returns the value of \fI\fP. -.TP -.B ? : -Returns the value of \fI\fP if \fI\fP evaluates true -(non-zero numeric value); returns the value of \fI\fP otherwise. Only -one of \fI\fP and \fI\fP is evaluated. \fI\fP must +.Tw Fl +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic = +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx +Assignment. The variable of name +.Cx < +.Va expr1 +.Cx >, +.Cx +which must be string valued, +is assigned the result of +.Cx < +.Va expr2 +.Cx >. +.Cx +Returns the value of +.Cx < +.Va expr2 +.Cx >. +.Cx +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic ? +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx \&\ \& +.Ic : +.Cx \&\ \& +.Cx < +.Va expr3 +.Cx > +.Cx +Returns the value of +.Cx < +.Va expr2 +.Cx > +.Cx +if +.Cx < +.Va expr1 +.Cx > +.Cx +evaluates true +(non-zero numeric value); returns the value of +.Cx < +.Va expr3 +.Cx > +.Cx +otherwise. Only +one of +.Cx < +.Va expr2 +.Cx > +.Cx +and +.Cx < +.Va expr3 +.Cx > +.Cx +is evaluated. +.Cx < +.Va Expr1 +.Cx > +.Cx +must be numeric. -.TP -.B || +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&|\&| +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Logical or. Numeric values only. Short circuit evaluation is supported -(i.e., if \fI\fP evaluates true, then \fI\fP is not evaluated). -.TP -.B && +(i.e., if +.Cx < +.Va expr1 +.Cx > +.Cx +evaluates true, then +.Cx < +.Va expr2 +.Cx > +.Cx +is not evaluated). +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&&\&& +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Logical and with short circuit evaluation. Numeric values only. -.TP -.B | +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&| +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Bitwise or. Numeric values only. -.TP -.B ^ +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic ^ +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Bitwise exclusive or. Numeric values only. -.TP -.B & +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&& +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Bitwise and. Numeric values only. -.TP -.B == , != +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic = +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx \&\ \& +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic != +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Comparison (equal and not equal, respectively). The boolean result (either 1 or 0) of the comparison is returned. The operands can be numeric or string valued. One string operand forces the other to be converted to a string in necessary. -.TP -.B < , > , <= , >= +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic < +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx \&\ \& +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic > +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx \&\ \& +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic <= +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx Less than, greater than, less than or equal to, greater than or equal to. Both numeric and string values, with automatic conversion as above. -.TP -.B << , >> -If both operands are numbers, \fI\fP is bit -shifted left (or right) by \fI\fP bits. If \fI\fP is -a string, then its first (or last) \fI\fP characters are -returns (if \fI\fP is also a string, then its length is used +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic << +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx \&\ \& +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic >> +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx +If both operands are numbers, +.Cx < +.Va expr1 +.Cx > +.Cx +is bit +shifted left (or right) by +.Cx < +.Va expr2 +.Cx > +.Cx +bits. If +.Cx < +.Va expr1 +.Cx > +.Cx +is +a string, then its first (or last) +.Cx < +.Va expr2 +.Cx > +.Cx +characters are +returns (if +.Cx < +.Va expr2 +.Cx > +.Cx +is also a string, then its length is used in place of its value). -.TP -.B + , - +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic + +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx >, +.Cx \&\ \& +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic - +.Cx \&\ \& +.Cx < +.Va expr2 +.Cx > +.Cx Addition and subtraction on numbers. For ``+'', if one argument is a string, then the other is converted to a string, and the result is the concatenation of the two strings. -.TP -.B * , / , % +.Tp Cx < +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&* +.Cx \&\ \&< +.Va expr2 +.Cx >, +.Cx \&\ \&< +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&/ +.Cx \&\ \&< +.Va expr2 +.Cx >,\&\ \&< +.Va expr1 +.Cx >, +.Cx \&\ \&< +.Va expr1 +.Cx > +.Cx \&\ \& +.Ic \&% +.Cx \&\ \&< +.Va expr2 +.Cx > +.Cx Multiplication, division, modulo. Numbers only. -.TP -.B -, ~, !, $, $? +.Tp Cx < +.Va expr +.Cx >, +.Cx \&\ \& +.Ic ~ +.Cx < +.Va expr +.Cx >, +.Cx \&\ \& +.Ic \&! +.Cx < +.Va expr +.Cx >, +.Cx \&\ \& +.Ic \&$ +.Cx < +.Va expr +.Cx >, +.Cx \&\ \& +.Ic \&$? +.Cx < +.Va expr +.Cx > +.Cx The first three are unary minus, bitwise complement and logical complement -on numbers only. The operator, ``$'', takes \fI\fP and returns -the value of the variable of that name. If \fI\fP is numeric -with value \fIn\fP and it appears within an alias macro (see below), +on numbers only. The operator, ``$'', takes +.Cx < +.Va expr +.Cx > +.Cx +and returns +the value of the variable of that name. If +.Cx < +.Va expr +.Cx > +.Cx +is numeric +with value +.Ar n +and it appears within an alias macro (see below), then it refers to the nth argument of the alias invocation. ``$?'' -tests for the existence of the variable \fI\fP, and returns 1 +tests for the existence of the variable +.Cx < +.Va expr +.Cx >, +.Cx +and returns 1 if it exists or 0 otherwise. -.TP -.B () -Function call. \fI\fP must be a string that is the unique -prefix of the name of a builtin \fIwindow\fP function +.Tp Cx < +.Va expr +.Cx >(< +.Ar arglist +.Cx >) +.Cx +Function call. +.Cx < +.Va Expr +.Cx > +.Cx +must be a string that is the unique +prefix of the name of a builtin +.Nm window +function or the full name of a user defined alias macro. In the case of a builtin -function, \fI\fP can be in one of two forms: -.br - , , . . . -.br - argname1 = , argname2 = , . . . -.br +function, +.Cx < +.Ar arglist +.Cx > +.Cx +can be in one of two forms: +.Dl , , ... +.Dl argname1 = , argname2 = , ... The two forms can in fact be intermixed, but the result is unpredictable. Most arguments can be omitted; default values will -be supplied for them. The \fIargnames\fP can be unique prefixes +be supplied for them. The +.Ar argnames +can be unique prefixes of the the argument names. The commas separating arguments are used only to disambiguate, and can usually be omitted. -.IP +.Pp Only the first argument form is valid for user defined aliases. Aliases -are defined using the \fIalias\fP builtin function (see below). Arguments +are defined using the +.Ic alias +builtin function (see below). Arguments are accessed via a variant of the variable mechanism (see ``$'' operator above). -.IP +.Pp Most functions return value, but some are used for side effect only and so must be used as statements. When a function or an alias is used as a statement, the parenthesis surrounding the argument list may be omitted. Aliases return no value. -.SH "BUILTIN FUNCTIONS" +.Tp +.Ss Builtin Functions The arguments are listed by name in their natural -order. Optional arguments are in square brackets (``[ ]''). Arguments -that have no names are in angle brackets (``<>''). -An argument meant to be a boolean flag (often named \fIflag\fP) -can be one of \fIon\fP, \fIoff\fP, \fIyes\fP, \fIno\fP, \fItrue\fP, -or \fIfalse\fP, with obvious meanings, or it can be a numeric expression, +order. Optional arguments are in square brackets +.Sq Op . +Arguments +that have no names are in angle brackets +.Sq <> . +An argument meant to be a boolean flag (often named +.Ar flag ) +can be one of +.Ar on , +.Ar off , +.Ar yes , +.Ar no , +.Ar true , +or +.Ar false , +with +obvious meanings, or it can be a numeric expression, in which case a non-zero value is true. -.TP -.B alias([], []) +.Tw Fl +.Tp Cx Ic alias +.Cx \&([< +.Ar string +.Cx ]>, +.Cx \&\ \&[< +.Ar string\-list +.Cx >]\&) +.Cx If no argument is given, all currently defined alias macros are -listed. Otherwise, \fI\fP is defined as an alias, -with expansion \fI\fP. The previous definition of -\fI\fP, if any, is returned. Default for \fI\fP +listed. Otherwise, +.Cx < +.Ar string +.Cx > +.Cx +is defined as an alias, +with expansion +.Cx < +.Ar string\-list +.Cx > . +.Cx +The previous definition of +.Cx < +.Ar string +.Cx >, +.Cx +if any, is returned. Default for +.Cx < +.Ar string\-list +.Cx > +.Cx is no change. -.TP -.B close() -Close the windows specified in \fI\fP. If \fI\fP -is the word \fIall\fP, than all windows are closed. No value is returned. -.TP -.B cursormodes([modes]) -Set the window cursor to \fImodes\fP. \fIModes\fP is the bitwise -or of the mode bits defined as the variables \fIm_ul\fP (underline), -\fIm_rev\fP (reverse video), \fIm_blk\fP (blinking), -and \fIm_grp\fP (graphics, terminal dependent). Return +.Tp Cx Ic close +.Cx (< +.Ar window\-list +.Cx >) +.Cx +Close the windows specified in +.Cx < +.Ar window\-list +.Cx >. +.Cx +If +.Cx < +.Ar window\-list +.Cx > +.Cx +is the word +.Ar all , +than all windows are closed. No value is returned. +.Tp Cx Ic cursormodes +.Cx \&( +.Op Ar modes +.Cx \&) +.Cx +Set the window cursor to +.Ar modes . +.Ar Modes +is the bitwise +or of the mode bits defined as the variables +.Ar m_ul +(underline), +.Ar m_rev +(reverse video), +.Ar m_blk +(blinking), +and +.Ar m_grp +(graphics, terminal dependent). Return value is the previous modes. Default is no change. -For example, cursor($m_rev|$m_blk) sets the window cursors to blinking +For example, +.Li cursor($m_rev$m_blk) +sets the window cursors to blinking reverse video. -.TP -.B default_nline([nline]) -Set the default buffer size to \fInline\fP. Initially, it is +.Tp Cx Ic default_nline +.Cx \&( +.Op Ar nline +.Cx \&) +.Cx +Set the default buffer size to +.Ar nline . +Initially, it is 48 lines. Returns the old default buffer size. Default is no change. Using a very large buffer can slow the program down considerably. -.TP -.B default_shell([]) -Set the default window shell program to \fI\fP. Returns +.Tp Cx Ic default_shell +.Cx \&([< +.Ar string\-list +.Cx >]\&) +.Cx +Set the default window shell program to +.Cx < +.Ar string\-list +.Cx >. +.Cx +Returns the first string in the old shell setting. Default is no change. Initially, -the default shell is taken from the environment variable \fISHELL\fP. -.TP -.B default_smooth([flag]) -Set the default value of the \fIsmooth\fP argument -to the command \fIwindow\fP (see below). The argument -is a boolean flag (one of \fIon\fP, \fIoff\fP, -\fIyes\fP, \fIno\fP, \fItrue\fP, \fIfalse\fP, or a number, +the default shell is taken from the environment variable +.Ev SHELL . +.Tp Cx Ic default_smooth +.Cx \&( +.Op Ar flag +.Cx \&) +.Cx +Set the default value of the +.Ar smooth +argument +to the command +.Nm window +(see below). The argument +is a boolean flag (one of +.Ar on , +.Ar off , +.Ar yes , +.Ar no , +.Ar true , +.Ar false , +or a number, as described above). Default is no change. The old value (as a number) is returned. The initial value is 1 (true). -.TP -.B echo([window], []) -Write the list of strings, \fI\fP, to \fIwindow\fP, separated +.Tp Cx Ic echo +.Cx \&( +.Op Ar window +.Cx \&,\&\ \&[< +.Ar string\-list +.Cx >]\&) +.Cx +Write the list of strings, +.Cx < +.Ar string-list +.Cx >, +.Cx +to +.Nm window , +separated by spaces and terminated with a new line. The strings are only displayed in the window, the processes in the window are not -involved (see \fIwrite\fP below). No value is returned. Default +involved (see +.Ic write +below). No value is returned. Default is the current window. -.TP -.B escape([escapec]) -Set the escape character to \fIescape-char\fP. Returns the old +.Tp Cx Ic escape +.Cx \&( +.Op Ar escapec +.Cx \&) +.Cx +Set the escape character to +.Ar escape-char . +Returns the old escape character as a one-character string. Default is no -change. \fPEscapec\fP can be a string of a single character, or -in the form \fI^X\fP, meaning control-\fIX\fP. -.TP -.B foreground([window], [flag]) -Move \fIwindow\fP in or out of foreground. \fIFlag\fP +change. +.Ar Escapec +can be a string of a single character, or +in the form +.Fl ^X , +meaning +Cx control\- +.Ar X +.Cx . +.Cx +.Tp Cx Ic foreground +.Cx \&( +.Op Ar window +.Cx \&, +.Op Ar flag +.Cx \&) +.Cx +Move +.Nm window +in or out of foreground. +.Ar Flag is a boolean value. The old foreground flag -is returned. Default for \fIwindow\fP is the current window, -default for \fIflag\fP is no change. -.TP -.B label([window], [label]) -Set the label of \fIwindow\fP to \fIlabel\fP. Returns the old -label as a string. Default for \fIwindow\fP is the current -window, default for \fIlabel\fP is no change. To turn +is returned. Default for +.Nm window +is the current window, +default for +.Ar flag +is no change. +.Tp Cx Ic label +.Cx \&( +.Op Ar window +.Cx \&, +.Op Ar label +.Cx \&) +.Cx +Set the label of +.Nm window +to +.Ar label . +Returns the old +label as a string. Default for +.Nm window +is the current +window, default for +.Ar label +is no change. To turn off a label, set it to an empty string (""). -.TP -.B list() +.Tp Cx Ic list +.Cx \&( \&) +.Cx No arguments. List the identifiers and labels of all windows. No value is returned. -.TP -.B select([window]) -Make \fIwindow\fP the current window. The previous current window +.Tp Cx Ic select +.Cx \&( +.Op Ar window +.Cx \&) +.Cx +Make +.Nm window +the current window. The previous current window is returned. Default is no change. -.TP -.B source(filename) -Read and execute the long commands in \fIfilename\fP. Returns --1 if the file cannot be read, 0 otherwise. -.TP -.B terse([flag]) -Set terse mode to \fIflag\fP. In terse mode, the command window +.Tp Cx Ic source +.Cx \&( +.Ar filename +.Cx \&) +.Cx +Read and execute the long commands in +.Ar filename . +Returns -1 if the file cannot be read, 0 otherwise. +.Tp Cx Ic terse +.Cx \&( +.Op flag +.Cx \&) +.Cx +Set terse mode to +.Ar flag . +In terse mode, the command window stays hidden even in command mode, and errors are reported by -sounding the terminal's bell. \fIFlag\fP can take on the same -values as in \fIforeground\fP above. Returns the old terse flag. +sounding the terminal's bell. +.Ar Flag +can take on the same +values as in +.Ar foreground +above. Returns the old terse flag. Default is no change. -.TP -.B unalias(alias) -Undefine \fIalias\fP. Returns -1 if \fIalias\fP does not exist, +.Tp Cx Ic unalias +.Cx \&( +.Ar alias +.Cx \&) +.Cx +Undefine +.Ar alias . +Returns -1 if +.Ar alias +does not exist, 0 otherwise. -.TP -.B unset(variable) -Undefine \fIvariable\fP. Returns -1 if \fIvariable\fP does not exist, +.Tp Cx Ic unset +.Cx \&( +.Ar variable +.Cx \&) +.Cx +Undefine +.Ar variable . +Returns -1 if +.Ar variable +does not exist, 0 otherwise. -.TP -.B variables() +.Tp Cx Ic variables +.Cx \&( \&) +.Cx No arguments. List all variables. No value is returned. -.TP -.B window([row], [column], [nrow], [ncol], [nline], [label], -.B [pty], [frame], [mapnl], [keepopen], [smooth], [shell]) -.br -Open a window with upper left corner at \fIrow\fP, \fIcolumn\fP -and size \fInrow\fP, \fIncol\fP. If \fInline\fP is specified, +.Tp Cx Ic window +.Cx \&( +.Op Ar row +.Cx \&, +.Cx \&\ \& +.Op Ar column +.Cx \&, +.Cx \&\ \& +.Op Ar nrow +.Cx \&, +.Cx \&\ \& +.Op Ar ncol +.Cx \&, +.Cx \&\ \& +.Op Ar nline +.Cx \&, +.Cx \&\ \& +.Op Ar label +.Cx \&, +.Cx \&\ \& +.Cx Op Ar pty +.Cx \&, +.Cx +.Op Ar frame +.Cx \&, +.Cx \&\ \& +.Op Ar mapnl +.Cx \&, +.Cx \&\ \& +.Op Ar keepopen +.Cx \&, +.Cx \&\ \& +.Op Ar smooth +.Cx \&, +.Cx \&\ \& +.Op Ar shell +.Cx \&). +.Cx +Open a window with upper left corner at +.Ar row , +.Ar column +and size +.Ar nrow , +.Ar ncol . +If +.Ar nline +is specified, then that many lines are allocated for the text buffer. Otherwise, the default buffer size is used. Default values for -\fIrow\fP, \fIcolumn\fP, \fInrow\fP, and \fIncol\fP are, respectively, +.Ar row , +.Ar column , +.Ar nrow , +and +.Ar ncol +are, respectively, the upper, left-most, lower, or right-most extremes of the -screen. \fILabel\fP is the label string. -\fIFrame\fP, \fIpty\fP, and \fImapnl\fP are flag values -interpreted in the same way as the argument to \fIforeground\fP (see above); +screen. +.Ar Label +is the label string. +.Ar Frame , +.Ar pty , +and +.Ar mapnl +are flag values +interpreted in the same way as the argument to +.Ar foreground +(see above); they mean, respectively, put a frame around this window (default true), allocate pseudo-terminal for this window rather than socketpair (default true), and map new line characters in this window to carriage return and line feed (default true if socketpair is used, false otherwise). Normally, a window is automatically closed when its process -exits. Setting \fIkeepopen\fP to true (default false) prevents this -action. When \fIsmooth\fP is true, the screen is updated more frequently +exits. Setting +.Ar keepopen +to true (default false) prevents this +action. When +.Ar smooth +is true, the screen is updated more frequently (for this window) to produce a more terminal-like behavior. -The default value of \fIsmooth\fP is set by the \fIdefault_smooth\fP +The default value of +.Ar smooth +is set by the +.Ar default_smooth command (see above). -\fIShell\fP is a list of strings that will be used as the shell +.Ar Shell +is a list of strings that will be used as the shell program to place in the window (default is the program specified -by \fIdefault_shell\fP, see above). The created window's identifier +by +.Ar default_shell , +see above). The created window's identifier is returned as a number. -.TP -.B write([window], []) -Send the list of strings, \fI\fP, to \fIwindow\fP, separated +.Tp Cx Ic write +.Cx \&( +.Op Ar window +.Cx \&,\&\ \&[< +.Ar string\-list +.Cx >]\&) +.Cx +Send the list of strings, +.Cx < +.Ar string-list +.Cx >, +.Cx +to +.Nm window , +separated by spaces but not terminated with a new line. The strings are actually given to the window as input. No value is returned. Default is the current window. -.SH "PREDEFINED VARIABLES" +.Tp +.Ss Predefined Variables These variables are for information only. Redefining them does -not affect the internal operation of \fIwindow\fP. -.TP -.B baud +not affect the internal operation of +.Nm window . +.Tw Fl +.Tp Ar baud The baud rate as a number between 50 and 38400. -.TP -.B modes +.Tp Ar modes The display modes (reverse video, underline, blinking, graphics) -supported by the physical terminal. The value of \fImodes\fP is -the bitwise or of some of the one bit values, \fIm_blk\fP, \fIm_grp\fP, -\fIm_rev\fP, and \fIm_ul\fP (see below). These values are useful -in setting the window cursors' modes (see \fIcursormodes\fP above). -.TP -.B m_blk +supported by the physical terminal. The value of +.Ar modes +is the bitwise or of some of the one bit values, +.Ar m_blk , +.Ar m_grp , +.Ar m_rev , +and +.Ar m_ul +(see below). +These values are useful +in setting the window cursors' modes (see +.Ar cursormodes +above). +.Tp Ar m_blk The blinking mode bit. -.TP -.B m_grp +.Tp Ar m_grp The graphics mode bit (not very useful). -.TP -.B m_rev +.Tp Ar m_rev The reverse video mode bit. -.TP -.B m_ul +.Tp Ar m_ul The underline mode bit. -.TP -.B ncol +.Tp Ar ncol The number of columns on the physical screen. -.TP -.B nrow +.Tp Ar nrow The number of rows on the physical screen. -.TP -.B term +.Tp Ar term The terminal type. The standard name, found in the second name -field of the terminal's \fITERMCAP\fP entry, is used. -.SH FILES -.ta 15 -~/.windowrc startup command file. -.br -/dev/[pt]ty[p-t]? pseudo-terminal devices. -.SH DIAGNOSTICS +field of the terminal's +.Ev TERMCAP +entry, is used. +.Sh ENVIRONMENT +.Nm Window +utilizes these environment variables: +.Ev HOME , +.Ev SHELL , +.Ev TERM , +.Ev TERMCAP , +.Ev WINDOW_ID . +.Sh FILES +.Dw /dev/[pt]ty[pq]? +.Di L +.Dp Pa ~/.windowrc +startup command file. +.Dp Cx Pa /dev/ +.Op Pa pt +.Cx ty +.Op Pa pq +.Cx ? +.Cx +pseudo-terminal devices. +.Dp +.Sh HISTORY +.Nm window +appeared in 4.3 BSD. +.Sh DIAGNOSTICS Should be self explanatory. -.SH BUGS diff --git a/usr/src/usr.sbin/chown/chgrp.1 b/usr/src/usr.sbin/chown/chgrp.1 index 667c64082d..a2af09d878 100644 --- a/usr/src/usr.sbin/chown/chgrp.1 +++ b/usr/src/usr.sbin/chown/chgrp.1 @@ -1,44 +1,70 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1983, 1990 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)chgrp.1 6.3 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH CHGRP 1 "" -.UC 5 -.SH NAME -chgrp \- change group -.SH SYNOPSIS -.B chgrp -[ -.B -Rf -] -group file ... -.SH DESCRIPTION -.I Chgrp -changes the group-ID of the -.I files -to -.IR group . -The group may be either a decimal GID or -a group name found in the group-ID file. -.PP -The user invoking -.I chgrp -must belong -to the specified group and be the owner of the file, or be the super-user. -.PP -No errors, except for usage errors, are reported when the -.B \-f -(force) option is given. -.PP -When the -.B \-R -option is given, -.I chgrp -recursively descends its directory arguments -setting the specified group-ID. +.\" @(#)chgrp.1 6.4 (Berkeley) %G% +.\" +.Dd +.Dt CHGRP 1 +.Os BSD 4.2 +.Sh NAME +.Nm chgrp +.Nd change group +.Sh SYNOPSIS +.Nm chgrp +.Op Fl Rf +.Ar group +.Ar files ... +.Sh DESCRIPTION +The chgrp utility sets the group ID of the file named by each +.Ar file +operand to the +.Ar group +ID specified by the group operand. +.Pp +Options: +.Tp Fl R +Recursively change file group IDs. +For each file +operand that names a directory, chgrp changes the +group of the directory and all files in the file +hierarchy below it. When symbolic links are encountered, their group is changed, but they are not traversed. -.SH "SEE ALSO" -chown(1), chown(2), passwd(5), group(5) +.Tp Fl f +The force option ignores errors, except for usage errors and doesn't +query about strange modes (unless user does not have proper permissions). +.Tp +.Pp +Operands: +.Tp Ar group +The +.Ar group +can be either a group name from the group database, or a numeric +group ID. +.Tp Ar file +A pathname of a file whose group ID is to be modified. +.Tp +.Pp +The user invoking +must belong +to the specified group and be the owner of the file, or be the super-user. +.Pp +The +.Nm chgrp +utility exits 0 on success, and >0 if an error occurs. +.Sh FILES +.Dw group +.Ds L +.Dp Pa group +Group ID file +.Sh SEE ALSO +.Xr chown 2 , +.Xr chown 8 , +.Xr group 5 , +.Xr passwd 5 +.Sh STANDARDS +The +.Nm chgrp +function is expected to be POSIX 1003.2 compatible. diff --git a/usr/src/usr.sbin/lpr/lpr/lpr.1 b/usr/src/usr.sbin/lpr/lpr/lpr.1 index 7343567aa4..4f44e1060b 100644 --- a/usr/src/usr.sbin/lpr/lpr/lpr.1 +++ b/usr/src/usr.sbin/lpr/lpr/lpr.1 @@ -13,7 +13,7 @@ .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.\" @(#)lpr.1 6.3 (Berkeley) %G% +.\" @(#)lpr.1 6.4 (Berkeley) %G% .\" .TH LPR 1 "" .UC 4 diff --git a/usr/src/usr.sbin/lpr/lprm/lprm.1 b/usr/src/usr.sbin/lpr/lprm/lprm.1 index f6eab32d7b..34aeb0cde0 100644 --- a/usr/src/usr.sbin/lpr/lprm/lprm.1 +++ b/usr/src/usr.sbin/lpr/lprm/lprm.1 @@ -13,7 +13,7 @@ .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.\" @(#)lprm.1 6.2 (Berkeley) %G% +.\" @(#)lprm.1 6.3 (Berkeley) %G% .\" .TH LPRM 1 "" .UC 5 diff --git a/usr/src/usr.sbin/mtree/mtree.8 b/usr/src/usr.sbin/mtree/mtree.8 index 70dfd140f4..612b848ce5 100644 --- a/usr/src/usr.sbin/mtree/mtree.8 +++ b/usr/src/usr.sbin/mtree/mtree.8 @@ -1,133 +1,112 @@ -.\" Copyright (c) 1989 The Regents of the University of California. +.\" Copyright (c) 1989, 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" %sccs.include.redist.man% .\" -.\" @(#)mtree.8 5.5 (Berkeley) %G% +.\" @(#)mtree.8 5.6 (Berkeley) %G% .\" -.TH MTREE 8 "" -.UC 7 -.SH NAME -mtree \- map a directory hierarchy -.SH SYNOPSIS -.nf -.ft B -mtree [ \-cderux ] [ \-f spec ] [ \-p path ] -.ft R -.fi -.SH DESCRIPTION -.I Mtree +.Dd +.Dt MTREE 8 +.Os BSD 4.4 +.Sh NAME +.Nm mtree +.Nd map a directory hierarchy +.Sh SYNOPSIS +.Nm mtree +.Op Fl cderux +.Op Fl f Ar spec +.Op Fl p Ar path +.Sh DESCRIPTION +.Nm Mtree compares a directory hierarchy against a specification for a directory hierarchy. By default, the specification is read from the standard input. -.I Mtree +.Nm Mtree verifies that the tree rooted in the current directory matches the specification. -.PP +.Pp Messages are written to standard output for any files whose characteristics do not match those of the specification, or which are missing from either the specification or the tree. -.PP +.Pp The options are as follows: -.TP -\-c +.Tp Fl c Print a specification for the tree to standard output. -.TP -\-d +.Tp Fl d Ignore everything except directory type files. -.TP -\-e +.Tp Fl e Don't object to files that are in the tree but not in the specification. -.TP -\-f +.Tp Fl f Read the specification from -.IR file , +.Ar file , instead of from standard input. -.TP -\-p +.Tp Fl p Traverse the tree rooted in -.IR path , +.Ar path , instead of the current directory. -.TP -\-r +.Tp Fl r Remove any files in the tree that are not described in the specification. -.TP -\-u +.Tp Fl u Modify the owner, group, and permissions of existing files to match the specification, as well as create any missing directories. Owner, group, and permissions must all be specified for missing directories to be created. -.TP -\-x +.Tp Fl x Don't descend below any mount points. -.PP +.Tp +.Pp Specifications are mostly composed of ``keywords'', i.e. strings that that specify values relating to files. No keywords have default values, and if a keyword has no set value no checks based on it are performed. -.PP +.Pp Currently supported keywords are as follows: -.TP -.B cksum +.Tw Cm +.Tp Cm cksum The checksum of the file using the algorithm specified by the program -.IR cksum (1). -.TP -.B ignore +.Xr cksum 1 . +.Tp Cm ignore Causes the hierarchy below the file to be ignored. -.TP -.B group +.Tp Cm group The group of the file; may be either numeric or symbolic. -.TP -.B mode +.Tp Cm mode The current file's permissions as an absolute (octal) or symbolic value (see -.IR chmod (1)). -.TP -.B nlink +.Xr chmod 1 ) . +.Tp Cm nlink The number of hard links the file is expected to have. -.TP -.B owner +.Tp Cm owner The owner of the file; may be either numeric or symbolic. -.TP -.B size +.Tp Cm size The size, in bytes, of the file. -.TP -.B link +.Tp Cm link The file a symbolic link is expected to reference. -.TP -.B time +.Tp Cm time The last modification time of the file. -.TP -.B type +.Tp Cm type The type of the file; may be set to any one of the following: -.RS -.TP -.B block +.Tw Cm +.Tp Tp Cm block block special device -.TP -.B char +.Tp Cm char character special device -.TP -.B dir +.Tp Cm dir directory -.TP -.B fifo +.Tp Cm fifo fifo -.TP -.B file +.Tp Cm file regular file -.TP -.B link +.Tp Cm link symbolic link -.TP -.B socket +.Tp Cm socket socket -.RE -.PP +.Tp +.Tp +.Pp There are four types of lines in a specification. -.PP +.Pp The first type of line sets a ``global'' value for a keyword, and consists of a leading ``/set'' followed by whitespace, followed by sets of keyword/value pairs, separated by whitespace. @@ -135,11 +114,11 @@ Keyword/value pairs consist of a keyword, followed by a equals sign (``=''), followed by a value, without intervening whitespace. Once a keyword has been set, its value remains unchanged until either set again or unset. -.PP +.Pp The second type of line unsets keywords and consists of a leading ``/unset'', followed by whitespace, followed by one or more keywords, separated by whitespace. -.PP +.Pp The third type of line is a file specification and consists of a file name, followed by whitespace, followed by zero or more whitespace separated keyword/value pairs. @@ -148,56 +127,73 @@ The file name may contain any of the standard file name matching characters (``['', ``]'', ``?'' or ``*''), in which case files in the hierarchy will be associated with the first pattern that they match. -.PP +.Pp Each of the keyword/value pairs consist of a keyword, followed by an equals sign (``=''), followed by the keyword's value, without intervening whitespace. These values override, without changing, the global value of the corresponding keyword. -.PP +.Pp All paths are relative. Specifying a directory will cause subsequent files to be searched for in that directory hierarchy. Which brings us to the last type of line in a specification: a line -containing only the string ``\fB..\fR'' causes the current directory +containing only the string +.Dq Nm \&.. +causes the current directory path to ascend one level. -.PP +.Pp Empty lines and lines whose first non-whitespace character is a hash mark (``#'') are ignored. -.PP -.I Mtree +.Pp +.Nm Mtree exits with a status of 0 on success and >0 if an error occurred or the tree did not match the specification. -.SH FILES -/etc/mtree system specification directory -.SH "SEE ALSO" -chmod(1), chown(1), chgrp(1), cksum(1), find(1), stat(2), fts(3), mkproto(8) -.SH BUGS +.Sh FILES +.Dw /etc/mtree +.Di L +.Dp Pa /etc/mtree +system specification directory +.Dp +.Sh SEE ALSO +.Xr chmod 1 , +.Xr chown 1 , +.Xr chgrp 1 , +.Xr cksum 1 , +.Xr find 1 , +.Xr stat 2 , +.Xr fts 3 , +.Xr mkproto 8 +.Sh BUGS The -.I cksum +.Cm cksum keyword is not yet implemented. -.br +.Pp The -.I time +.Cm time keyword should be specifiable in human readable terms. -.SH EXAMPLE -.nf +.Sh EXAMPLE +.Ds I # fs: /a/staff/rick/mybin # by: rick # date: Fri May 25 12:26:57 1990 - +.sp /set group=staff mode=0555 nlink=1 owner=rick type=file -[ nlink=2 size=6144 +[ nlink=2 size=6144 adb size=53248 df group=operator mode=02555 size=20480 ps group=kmem mode=02555 size=54272 rcp owner=root mode=04555 size=79872 test nlink=2 size=6144 - +.sp /set group=wheel mode=0444 nlink=1 owner=rick type=file manpages type=dir mode=0775 nlink=2 size=1024 - adb.man size=9473 - df.man size=5263 - tar.man size=3324 +adb.man size=9473 +df.man size=5263 +tar.man size=3324 \&.. -.fi +.De +.\" .Sh ENVIRONMENT +.Sh HISTORY +.Nm Mtree +debuts in 4.4 BSD. -- 2.20.1