new version from Rick Adams; rick@seismo.css.gov

[unix-history] / usr / src / bin / csh / csh.1

diff --git a/usr/src/bin/csh/csh.1 b/usr/src/bin/csh/csh.1
index c143934..463cbf6 100644 (file)
--- a/usr/src/bin/csh/csh.1
+++ b/usr/src/bin/csh/csh.1
@@ -2,9 +2,9 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)csh.1       5.1 (Berkeley) %G%
+.\"    @(#)csh.1       6.10 (Berkeley) %G%

 .\"
 .\"

-.TH CSH 1 "18 July 1983"
+.TH CSH 1 ""

 .UC 4
 .de sh
 .br
 .UC 4
 .de sh
 .br


@@ -13,7 +13,7 @@
 \fB\\$1\fR
 .PP
 ..
 \fB\\$1\fR
 .PP
 ..

-.if n .ds ua \o'^|'
+.if n .ds ua ^

 .if t .ds ua \(ua
 .if n .ds aa '
 .if t .ds aa \(aa
 .if t .ds ua \(ua
 .if n .ds aa '
 .if t .ds aa \(aa


@@ -32,10 +32,9 @@ arg ...
 .SH DESCRIPTION
 .I Csh
 is a first implementation of a command language interpreter
 .SH DESCRIPTION
 .I Csh
 is a first implementation of a command language interpreter

-incorporating a history mechanism (see
-.B "History Substitutions)"
-job control facilities (see
-.B Jobs)
+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
 and a C-like syntax.
 So as to be able to use its job control facilities, users of
 .I csh


@@ -125,7 +124,7 @@ like:
 .DT
        [1] 1234
 .PP
 .DT
        [1] 1234
 .PP

-indicating that the jobs which was started asynchronously was job number
+indicating that the job which was started asynchronously was job number

 1 and had one (top-level) process, whose process id was 1234.
 .PP
 If you are running a job and wish to do something else you may hit the key
 1 and had one (top-level) process, whose process id was 1234.
 .PP
 If you are running a job and wish to do something else you may hit the key


@@ -195,6 +194,88 @@ be warned that `You have stopped jobs.'  You may use the \fIjobs\fR
 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.
 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"
+When the file name completion feature is enabled by setting
+the shell variable \fIfilec\fP (see \fBset\fP), \fIcsh\fP 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,
+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
+and the input is
+.br
+       % vi ch<escape>
+.br
+\fIcsh\fP will complete the prefix ``ch''
+to the only matching file name ``chaosnet'', changing the input
+line to
+.br
+       % vi chaosnet
+.br
+However, given
+.br
+       % vi D<escape>
+.br
+\fIcsh\fP will only expand the input to
+.br
+       % vi DSC.
+.br
+and will sound the terminal bell to indicate that the expansion is
+incomplete, since there are two file names matching the prefix ``D''.
+.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
+will list all file names matching the prefix.  For example,
+the input
+.br
+       % vi D<control-D>
+.br
+causes all files beginning with ``D'' to be listed:
+.br
+       DSC.NEW DSC.OLD
+.br
+while the input line remains unchanged.
+.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<control-D>
+.br
+may produce the expansion
+.br
+       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
+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
+the command
+.br
+       % set fignore = (.o .out)
+.br
+then typing
+.br
+       % vi x<escape>
+.br
+would result in the completion to
+.br
+       % vi xmpl.c
+.br
+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
+does not affect the listing of file names by control-D.  All files
+are listed regardless of their suffixes.

 .sh Substitutions
 We now describe the various transformations the shell performs on the
 input in the order in which they occur.
 .sh Substitutions
 We now describe the various transformations the shell performs on the
 input in the order in which they occur.


@@ -258,7 +339,7 @@ alone is essentially a
 .PP
 To select words from an event we can follow the event specification by
 a `:' and a designator for the desired words.
 .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 a input line are numbered from 0,
+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:
 the first (usually command) word being 0, the second word (first argument)
 being 1, etc.
 The basic word designators are:


@@ -293,7 +374,7 @@ The following modifiers are defined:
        t       Remove all leading pathname components, leaving the tail.
        &       Repeat the previous substitution.
        g       Apply the change globally, prefixing the above, e.g. `g&'.
        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 but do not execute it.
+       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
        q       Quote the substituted words, preventing further substitutions.
        x       Like q, but break into words at blanks, tabs and newlines.
 .fi


@@ -443,7 +524,7 @@ and the rest of which become arguments.
 .PP
 Unless enclosed in `"' or given the `:q' modifier the results of variable
 substitution may eventually be command and filename substituted.
 .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
+Within `"', a variable whose value consists of multiple words expands to a

 (portion of) a single word, with the words of the variables value
 separated by blanks.
 When the `:q' modifier is applied to a substitution
 (portion of) a single word, with the words of the variables value
 separated by blanks.
 When the `:q' modifier is applied to a substitution


@@ -518,7 +599,7 @@ $*
 .br
 Equivalent to `$argv[*]'.
 .PP
 .br
 Equivalent to `$argv[*]'.
 .PP

-The modifiers `:h', `:t', `:r', `:q' and `:x' may be applied to
+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.
 the substitutions above as may `:gh', `:gt' and `:gr'.
 If braces `{' '}' appear in the command form then the modifiers
 must appear within the braces.


@@ -714,7 +795,7 @@ 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
 and if the process attempts to read from the terminal, then the process
 will block and the user will be notified (see
 .B Jobs

-above.)
+above).

 .PP
 Diagnostic output may be directed through a pipe with the standard output.
 Simply use the form `|\|&' rather than just `|'.
 .PP
 Diagnostic output may be directed through a pipe with the standard output.
 Simply use the form `|\|&' rather than just `|'.


@@ -843,12 +924,12 @@ or
 .HP 5
 .B  alloc
 .br
 .HP 5
 .B  alloc
 .br

-Shows the amount of dynamic core in use, broken down into used and
-free core, and address of the last location in the heap.
-With an argument shows each used and free block on the internal dynamic
-memory chain indicating its address, size, and whether it is used or free.
-This is a debugging command and may not work in production versions of the
-shell; it requires a modified version of the system memory allocator.
+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
 .HP 5
 .B bg
 .br


@@ -897,7 +978,7 @@ statement as discussed below.
 .HP 5
 .BR chdir " name"
 .br
 .HP 5
 .BR chdir " name"
 .br

-Change the shells working directory to directory
+Change the shell's working directory to directory

 .I name.
 If no argument is given then change to the home directory of the user.
 .br
 .I name.
 If no argument is given then change to the home directory of the user.
 .br


@@ -1149,10 +1230,10 @@ If the specified
 .IR expr ""
 is true then the commands to the first
 .I else
 .IR expr ""
 is true then the commands to the first
 .I else

-are executed; else if
+are executed; otherwise if

 .IR expr2 ""
 is true then the commands to the
 .IR expr2 ""
 is true then the commands to the

-second else are executed, etc.
+second \fIelse\fR are executed, etc.

 Any number of
 .I else-if
 pairs are possible; only one
 Any number of
 .I else-if
 pairs are possible; only one


@@ -1220,11 +1301,27 @@ then the job or process will be sent a CONT (continue) signal as well.
 .HP 5
 \fBlimit\fR \fIresource\fR \fImaximum-use\fR
 .br
 .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

 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
 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.
+all limitations are given.  If the \fB\-h\fR
+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
 .IP
 Resources controllable currently include \fIcputime\fR (the maximum
 number of cpu-seconds to be used by each process), \fIfilesize\fR


@@ -1266,7 +1363,7 @@ is set.
 .br
 .ns
 .HP 5
 .br
 .ns
 .HP 5

-.BR nice " \+number"
+.BR nice " +number"

 .br
 .ns
 .HP 5
 .br
 .ns
 .HP 5


@@ -1274,20 +1371,21 @@ is set.
 .br
 .ns
 .HP 5
 .br
 .ns
 .HP 5

-.BR nice " \+number command"
+.BR nice " +number command"

 .br
 The first form sets the
 .br
 The first form sets the

-.I nice
+scheduling priority

 for this shell to 4.
 The second form sets the
 for this shell to 4.
 The second form sets the

-.I nice
+priority

 to the given number.
 The final two forms run command at priority 4 and
 .I number
 respectively.
 to the given number.
 The final two forms run command at priority 4 and
 .I number
 respectively.

-The super-user may specify negative niceness by using `nice \-number ...'.
+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
 Command is always executed in a sub-shell, and the restrictions

-place on commands in simple
+placed on commands in simple

 .I if
 statements apply.
 .HP 5
 .I if
 statements apply.
 .HP 5


@@ -1348,7 +1446,7 @@ continue to be ignored by the shell and all invoked commands.
 .BR "popd" " +n"
 .br
 Pops the directory stack, returning to the new top directory.
 .BR "popd" " +n"
 .br
 Pops the directory stack, returning to the new top directory.

-With a argument `+\fIn\fR' discards the \fIn\fR\|th
+With an argument `+\fIn\fR' discards the \fIn\fR\|th

 entry in the stack.
 The elements of the directory stack are numbered from 0 starting at the top.
 .HP 5
 entry in the stack.
 The elements of the directory stack are numbered from 0 starting at the top.
 .HP 5


@@ -1451,13 +1549,24 @@ 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
 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
 .BR setenv " name value"
 .br

-Sets the value of environment variable
+.ns
+.HP 5
+.BR setenv " name"
+.br
+The first form lists all current environment variables.
+The last form sets the value of environment variable

 .I name
 to be
 .I value,
 .I name
 to be
 .I value,

-a single string.
+a single string.  The second form sets
+.I 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
 The most commonly used environment variable USER, TERM, and PATH
 are automatically imported to and exported from the
 .I csh


@@ -1614,14 +1723,24 @@ It is not an error for nothing to be
 Use of the internal hash table to speed location of executed programs
 is disabled.
 .HP 5
 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\fR \fIresource\fR
 .br
 .ns
 .HP 5

-\fBunlimit\fR
+\fBunlimit\ \-h\fR
+.br
+.ns
+.HP 5
+\fBunlimit\ \-h\fR \fIresource\fR

 .br
 Removes the limitation on \fIresource\fR.  If no \fIresource\fR
 .br
 Removes the limitation on \fIresource\fR.  If no \fIresource\fR

-is specified, then all \fIresource\fR limitations are removed.
+is specified, then all \fIresource\fR limitations are removed.  If
+\fB\-h\fR is given, the corresponding hard limits are removed.  Only the
+super-user may do this.

 .HP 5
 .BR unset " pattern"
 .br
 .HP 5
 .BR unset " pattern"
 .br


@@ -1784,6 +1903,10 @@ 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
 Builtin commands are echoed before command and filename substitution,
 since these substitutions are then done selectively.
 .TP 15

+.B filec
+Enable file name completion.
+\c
+.TP 15

 .B histchars
 \c
 Can be given a string value to change the characters used in history
 .B histchars
 \c
 Can be given a string value to change the characters used in history


@@ -1999,6 +2122,15 @@ If argument 0 to the shell is `\-' then this
 is a login shell.
 The flag arguments are interpreted as follows:
 .TP 5
 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
 .B  \-c
 \c
 Commands are read from the (single) following argument which must


@@ -2015,7 +2147,7 @@ or yields a non-zero exit status.
 \c
 The shell will start faster, because it will neither search for nor
 execute commands from the file
 \c
 The shell will start faster, because it will neither search for nor
 execute commands from the file

-`\&.cshrc' in the invokers home directory.
+`\&.cshrc' in the invoker's home directory.

 .TP 5
 .B  \-i
 \c
 .TP 5
 .B  \-i
 \c


@@ -2067,13 +2199,13 @@ as
 is to
 .B \-v.
 .PP
 is to
 .B \-v.
 .PP

-After processing of flag arguments if arguments remain but none of the
+After processing of flag arguments, if arguments remain but none of the

 .B \-c,
 .B \-i,
 .B \-s,
 or
 .B \-t
 .B \-c,
 .B \-i,
 .B \-s,
 or
 .B \-t

-options was given the first argument is taken as the name of a file of
+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'.
 commands to be executed.
 The shell opens this file, and saves its name for possible resubstitution
 by `$0'.


@@ -2104,7 +2236,8 @@ In no case are interrupts allowed when a login shell is reading the file
 William Joy.
 Job control and directory stack features first implemented by J.E. Kulp of
 I.I.A.S.A, Laxenburg, Austria,
 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.
+with different syntax than that used now.  File name completion
+code written by Ken Greer, HP Labs.

 .SH FILES
 .ta 1.75i
 .nf
 .SH FILES
 .ta 1.75i
 .nf


@@ -2163,7 +2296,6 @@ 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
 substitutions.
 All and more than one `:' modifier should be allowed on `$' substitutions.
 .PP

-Symbolic links fool the shell.  In particular,
-.I dirs
-and `cd ..' don't work properly once you've crossed through a symbolic
-link.
+The way the
+.B filec
+facility is implemented is ugly and expensive.