Return to csh.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / bin / csh

Annotation of 43BSDReno/bin/csh/csh.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980, 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"     @(#)csh.1      6.14 (Berkeley) 7/24/90
        !            19: .\"
        !            20: .Dd July 24, 1990
        !            21: .Dt CSH 1
        !            22: .Os BSD 4
        !            23: .Sh NAME
        !            24: .Nm csh
        !            25: .Nd a shell (command interpreter) with C-like syntax
        !            26: .Sh SYNOPSIS
        !            27: .Nm csh
        !            28: .Op Fl cef\*(uainstvVxX
        !            29: .Op arg ...
        !            30: .Sh DESCRIPTION
        !            31: The
        !            32: .Nm Csh
        !            33: is a command language interpreter
        !            34: incorporating a history mechanism (see
        !            35: .Nm History Substitutions ) ,
        !            36: job control facilities (see
        !            37: .Nm Jobs ) ,
        !            38: interactive file name
        !            39: and user name completion (see
        !            40: .Nm File Name Completion ) ,
        !            41: and a C-like syntax. It is used both as an interactive
        !            42: login shell and a shell script command processor.
        !            43: .Ss Argument list processing
        !            44: If the first argument (argument 0) to the shell is
        !            45: .Sq Fl
        !            46: then this
        !            47: is a login shell.
        !            48: The flag arguments are interpreted as follows:
        !            49: .Tw 5n
        !            50: .Tp Fl b
        !            51: This flag forces a ``break'' from option processing, causing any further
        !            52: shell arguments to be treated as non-option arguments.
        !            53: The remaining arguments will not be interpreted as shell options.
        !            54: This may be used to pass options to a shell script without confusion
        !            55: or possible subterfuge.
        !            56: The shell will not run a set-user ID script without this option.
        !            57: .Tp Fl c
        !            58: Commands are read from the (single) following argument which must
        !            59: be present.
        !            60: Any remaining arguments are placed in
        !            61: .Ar argv .
        !            62: .Tp Fl e
        !            63: The shell exits if any invoked command terminates abnormally
        !            64: or yields a non-zero exit status.
        !            65: .Tp Fl f
        !            66: The shell will start faster, because it will neither search for nor
        !            67: execute commands from the file
        !            68: .Pa \&.cshrc
        !            69: in the invoker's home directory.
        !            70: .Tp Fl i
        !            71: The shell is interactive and prompts for its top-level input,
        !            72: even if it appears to not be a terminal.
        !            73: Shells are interactive without this option if their inputs
        !            74: and outputs are terminals.
        !            75: .Tp Fl n
        !            76: Commands are parsed, but not executed.
        !            77: This aids in syntactic checking of shell scripts.
        !            78: .Tp Fl s
        !            79: Command input is taken from the standard input.
        !            80: .Tp Fl t
        !            81: A single line of input is read and executed.
        !            82: A `\e' may be used to escape the newline at the end of this
        !            83: line and continue onto another line.
        !            84: .Tp Fl v
        !            85: Causes the
        !            86: .Ar verbose
        !            87: variable to be set, with the effect
        !            88: that command input is echoed after history substitution.
        !            89: .Tp Fl x
        !            90: Causes the
        !            91: .Ar echo
        !            92: variable to be set, so that commands are echoed immediately before execution.
        !            93: .Tp Fl V
        !            94: Causes the
        !            95: .Ar verbose
        !            96: variable to be set even before
        !            97: .Pa \&.cshrc is executed.
        !            98: .Tp Fl X
        !            99: Is to
        !           100: .Fl x
        !           101: as
        !           102: .Fl V
        !           103: is to
        !           104: .Fl v .
        !           105: .Tp
        !           106: .Pp
        !           107: After processing of flag arguments, if arguments remain but none of the
        !           108: .Fl c ,
        !           109: .Fl i ,
        !           110: .Fl s ,
        !           111: or
        !           112: .Fl t
        !           113: options were given, the first argument is taken as the name of a file of
        !           114: commands to be executed.
        !           115: The shell opens this file, and saves its name for possible resubstitution
        !           116: by `$0'.
        !           117: Since many systems use either the standard version 6 or version 7 shells
        !           118: whose shell scripts are not compatible with this shell, the shell will
        !           119: execute such a `standard' shell if the first character of a script
        !           120: is not a `#', i.e. if the script does not start with a comment.
        !           121: Remaining arguments initialize the variable
        !           122: .Ar argv .
        !           123: .Pp
        !           124: An instance of
        !           125: .Nm csh
        !           126: begins by executing commands from the file
        !           127: .Pa /etc/csh.cshrc
        !           128: and,
        !           129: if this is a login shell,
        !           130: .Pa \&/etc/csh.login .
        !           131: It then executes
        !           132: commands from
        !           133: .Pa \&.cshrc
        !           134: in the
        !           135: .Ar home
        !           136: directory of the invoker, and, if this is a login shell, the file
        !           137: .Pa \&.login
        !           138: in the same location.
        !           139: It is typical for users on crt's to put the command ``stty crt''
        !           140: in their
        !           141: .Pa \&.login
        !           142: file, and to also invoke
        !           143: .Xr tset  1
        !           144: there.
        !           145: .Pp
        !           146: In the normal case, the shell will then begin reading commands from the
        !           147: terminal, prompting with `% '.
        !           148: Processing of arguments and the use of the shell to process files
        !           149: containing command scripts will be described later.
        !           150: .Pp
        !           151: The shell then repeatedly performs the following actions:
        !           152: a line of command input is read and broken into
        !           153: .Ar words  .
        !           154: This sequence of words is placed on the command history list and then parsed.
        !           155: Finally each command in the current line is executed.
        !           156: .Pp
        !           157: When a login shell terminates it executes commands from the files
        !           158: .Pa .logout
        !           159: in the user's
        !           160: .Ar home
        !           161: directory and
        !           162: .Pa /etc/csh.logout .
        !           163: .Ss Lexical structure
        !           164: The shell splits input lines into words at blanks and tabs with the
        !           165: following exceptions.
        !           166: The characters
        !           167: `&' `\&|' `;' `<' `>' `(' `)'
        !           168: form separate words.
        !           169: If doubled in `&&', `\&|\&|', `<<' or `>>' these pairs form single words.
        !           170: These parser metacharacters may be made part of other words, or prevented their
        !           171: special meaning, by preceding them with `\e'.
        !           172: A newline preceded by a `\e' is equivalent to a blank.
        !           173: .Pp
        !           174: In addition strings enclosed in matched pairs of quotations,
        !           175: `\*(aa', `\*(ga' or `"',
        !           176: form parts of a word; metacharacters in these strings, including blanks
        !           177: and tabs, do not form separate words.
        !           178: These quotations have semantics to be described subsequently.
        !           179: Within pairs of `\'' or `"' characters a newline preceded by a `\e' gives
        !           180: a true newline character.
        !           181: .Pp
        !           182: When the shell's input is not a terminal,
        !           183: the character `#' introduces a comment which continues to the end of the
        !           184: input line.
        !           185: It is prevented this special meaning when preceded by `\e'
        !           186: and in quotations using `\`', `\'', and `"'.
        !           187: .Ss Commands
        !           188: A simple command is a sequence of words, the first of which
        !           189: specifies the command to be executed.
        !           190: A simple command or
        !           191: a sequence of simple commands separated by `\&|' characters
        !           192: forms a pipeline.
        !           193: The output of each command in a pipeline is connected to the input of the next.
        !           194: Sequences of pipelines may be separated by `;', and are then executed
        !           195: sequentially.
        !           196: A sequence of pipelines may be executed without immediately
        !           197: waiting for it to terminate by following it with an `&'.
        !           198: .Pp
        !           199: Any of the above may be placed in `(' `)' to form a simple command (which
        !           200: may be a component of a pipeline, etc.)
        !           201: It is also possible to separate pipelines with `\&|\&|' or `&&' indicating,
        !           202: as in the C language,
        !           203: that the second is to be executed only if the first fails or succeeds
        !           204: respectively. (See
        !           205: .Em Expressions . )
        !           206: .Ss Jobs
        !           207: The shell associates a
        !           208: .Ar job
        !           209: with each pipeline.  It keeps
        !           210: a table of current jobs, printed by the
        !           211: .Ar jobs
        !           212: command, and assigns them small integer numbers.  When
        !           213: a job is started asynchronously with `&', the shell prints a line which looks
        !           214: like:
        !           215: .Pp
        !           216: .Df I
        !           217: .Op 1
        !           218: 1234
        !           219: .De
        !           220: .Pp
        !           221: indicating that the job which was started asynchronously was job number
        !           222: 1 and had one (top-level) process, whose process id was 1234.
        !           223: .Pp
        !           224: If you are running a job and wish to do something else you may hit the key
        !           225: .Nm ^Z
        !           226: (control-Z) which sends a STOP signal to the current job.
        !           227: The shell will then normally indicate that the job has been `Stopped',
        !           228: and print another prompt.  You can then manipulate the state of this job,
        !           229: putting it in the background with the
        !           230: .Ar bg
        !           231: command, or run some other
        !           232: commands and then eventually bring the job back into the foreground with
        !           233: the foreground command
        !           234: .Ar fg  .
        !           235: A
        !           236: .Nm ^Z
        !           237: takes effect immediately and
        !           238: is like an interrupt in that pending output and unread input are discarded
        !           239: when it is typed.  There is another special key
        !           240: .Nm ^Y
        !           241: which does
        !           242: not generate a STOP signal until a program attempts to
        !           243: .Xr read  2
        !           244: it.
        !           245: This can usefully be typed ahead when you have prepared some commands
        !           246: for a job which you wish to stop after it has read them.
        !           247: .Pp
        !           248: A job being run in the background will stop if it tries to read
        !           249: from the terminal.  Background jobs are normally allowed to produce output,
        !           250: but this can be disabled by giving the command ``stty tostop''.
        !           251: If you set this
        !           252: tty option, then background jobs will stop when they try to produce
        !           253: output like they do when they try to read input.
        !           254: .Pp
        !           255: There are several ways to refer to jobs in the shell.  The character
        !           256: `%' introduces a job name.  If you wish to refer to job number 1, you can
        !           257: name it as `%1'.  Just naming a job brings it to the foreground; thus
        !           258: `%1' is a synonym for `fg %1', bringing job 1 back into the foreground.
        !           259: Similarly saying `%1 &' resumes job 1 in the background.
        !           260: Jobs can also be named by prefixes of the string typed in to start them,
        !           261: if these prefixes are unambiguous, thus `%ex' would normally restart
        !           262: a suspended
        !           263: .Xr ex  1
        !           264: job, if there were only one suspended job whose name began with
        !           265: the string `ex'.  It is also possible to say `%?string'
        !           266: which specifies a job whose text contains
        !           267: .Ar string ,
        !           268: if there is only one such job.
        !           269: .Pp
        !           270: The shell maintains a notion of the current and previous jobs.
        !           271: In output pertaining to jobs, the current job is marked with a `+'
        !           272: and the previous job with a `\-'.  The abbreviation `%+' refers
        !           273: to the current job and `%\-' refers to the previous job.  For close
        !           274: analogy with the syntax of the
        !           275: .Ar history
        !           276: mechanism (described below),
        !           277: `%%' is also a synonym for the current job.
        !           278: .Pp
        !           279: The job control mechanism requires that the
        !           280: .Xr stty 1
        !           281: option
        !           282: .Ic new
        !           283: be set. It is an artifact from a
        !           284: .Em new
        !           285: implementation
        !           286: of the
        !           287: tty driver which allows generation of interrupt characters from
        !           288: the keyboard to tell jobs to stop.  See stty(1) for details
        !           289: on setting options in the new tty driver.
        !           290: .Ss Status reporting
        !           291: This shell learns immediately whenever a process changes state.
        !           292: It normally informs you whenever a job becomes blocked so that
        !           293: no further progress is possible, but only just before it prints
        !           294: a prompt.  This is done so that it does not otherwise disturb your work.
        !           295: If, however, you set the shell variable
        !           296: .Ar notify ,
        !           297: the shell will notify you immediately of changes of status in background
        !           298: jobs.
        !           299: There is also a shell command
        !           300: .Ar notify
        !           301: which marks a single process so that its status changes will be immediately
        !           302: reported.  By default
        !           303: .Ar notify
        !           304: marks the current process;
        !           305: simply say `notify' after starting a background job to mark it.
        !           306: .Pp
        !           307: When you try to leave the shell while jobs are stopped, you will
        !           308: be warned that `You have stopped jobs.'  You may use the
        !           309: .Ar jobs
        !           310: command to see what they are.  If you do this or immediately try to
        !           311: exit again, the shell will not warn you a second time, and the suspended
        !           312: jobs will be terminated.
        !           313: .Ss File Name Completion
        !           314: When the file name completion feature is enabled by setting
        !           315: the shell variable
        !           316: .Ar filec
        !           317: (see
        !           318: .Ic set ) ,
        !           319: .Nm csh
        !           320: will
        !           321: interactively complete file names and user names from unique
        !           322: prefixes, when they are input from the terminal followed by
        !           323: the escape character (the escape key, or control-[)
        !           324: For example,
        !           325: if the current directory looks like
        !           326: .Ds I
        !           327: .Cw DSC.NEW chaosnet cmtest mbox
        !           328: .Cl DSC.OLD    bin     cmd     lib     xmpl.c
        !           329: .Cl DSC.NEW    chaosnet        cmtest  mail    xmpl.o
        !           330: .Cl bench      class   dev     mbox    xmpl.out
        !           331: .Cw
        !           332: .De
        !           333: .Pp
        !           334: and the input is
        !           335: .Pp
        !           336: .Dl \&% vi ch<escape>
        !           337: .Pp
        !           338: .Nm csh
        !           339: will complete the prefix ``ch''
        !           340: to the only matching file name ``chaosnet'', changing the input
        !           341: line to
        !           342: .Pp
        !           343: .Dl \&% vi chaosnet
        !           344: .Pp
        !           345: However, given
        !           346: .Pp
        !           347: .Dl % vi D<escape>
        !           348: .Pp
        !           349: .Nm csh
        !           350: will only expand the input to
        !           351: .Pp
        !           352: .Dl \&% vi DSC.
        !           353: .Pp
        !           354: and will sound the terminal bell to indicate that the expansion is
        !           355: incomplete, since there are two file names matching the prefix ``D''.
        !           356: .Pp
        !           357: If a partial file name is followed by the end-of-file character
        !           358: (usually control-D), then, instead of completing the name,
        !           359: .Nm csh
        !           360: will list all file names matching the prefix.  For example,
        !           361: the input
        !           362: .Pp
        !           363: .Dl \&% vi D<control-D>
        !           364: .Pp
        !           365: causes all files beginning with ``D'' to be listed:
        !           366: .Pp
        !           367: .Dl \&DSC.NEW  DSC.OLD
        !           368: .Pp
        !           369: while the input line remains unchanged.
        !           370: .Pp
        !           371: The same system of escape and end-of-file can also be used to
        !           372: expand partial user names, if the word to be completed
        !           373: (or listed) begins with the character ``~''.  For example,
        !           374: typing
        !           375: .Pp
        !           376: .Dl \&cd ~ro<escape>
        !           377: .Pp
        !           378: may produce the expansion
        !           379: .Pp
        !           380: .Dl \&cd ~root
        !           381: .Pp
        !           382: The use of the terminal bell to signal errors or multiple matches
        !           383: can be inhibited by setting the variable
        !           384: .Ar nobeep  .
        !           385: .Pp
        !           386: Normally, all files in the particular directory are candidates
        !           387: for name completion.  Files with certain suffixes can be excluded
        !           388: from consideration by setting the variable
        !           389: .Ar fignore
        !           390: to the
        !           391: list of suffixes to be ignored.  Thus, if
        !           392: .Ar fignore
        !           393: is set by
        !           394: the command
        !           395: .Pp
        !           396: .Dl \&% set fignore = (.o .out)
        !           397: .Pp
        !           398: then typing
        !           399: .Pp
        !           400: .Dl \&% vi x<escape>
        !           401: .Pp
        !           402: would result in the completion to
        !           403: .Pp
        !           404: .Dl \&% vi xmpl.c
        !           405: .Pp
        !           406: ignoring the files "xmpl.o" and "xmpl.out".
        !           407: However, if the only completion possible requires not ignoring these
        !           408: suffixes, then they are not ignored.  In addition,
        !           409: .Ar fignore
        !           410: does not affect the listing of file names by control-D.  All files
        !           411: are listed regardless of their suffixes.
        !           412: .Ss Substitutions
        !           413: We now describe the various transformations the shell performs on the
        !           414: input in the order in which they occur.
        !           415: .Ss History substitutions
        !           416: History substitutions place words from previous command input as portions
        !           417: of new commands, making it easy to repeat commands, repeat arguments
        !           418: of a previous command in the current command, or fix spelling mistakes
        !           419: in the previous command with little typing and a high degree of confidence.
        !           420: History substitutions begin with the character `!' and may begin
        !           421: .Ar anywhere
        !           422: in the input stream (with the proviso that they
        !           423: .Nm "do not"
        !           424: nest.)
        !           425: This `!' may be preceded by an `\e' to prevent its special meaning; for
        !           426: convenience, a `!' is passed unchanged when it is followed by a blank,
        !           427: tab, newline, `=' or `('.
        !           428: (History substitutions also occur when an input line begins with `\*(ua'.
        !           429: This special abbreviation will be described later.)
        !           430: Any input line which contains history substitution is echoed on the terminal
        !           431: before it is executed as it could have been typed without history substitution.
        !           432: .Pp
        !           433: Commands input from the terminal which consist of one or more words
        !           434: are saved on the history list.
        !           435: The history substitutions reintroduce sequences of words from these
        !           436: saved commands into the input stream.
        !           437: The size of which is controlled by the
        !           438: .Ar history
        !           439: variable; the previous command is always retained, regardless of its value.
        !           440: Commands are numbered sequentially from 1.
        !           441: .Pp
        !           442: For definiteness, consider the following output from the
        !           443: .Ar history
        !           444: command:
        !           445: .Pp
        !           446: .DT
        !           447: .Pp
        !           448: .Dl \&\09  write michael
        !           449: .Dl 10  ex write.c
        !           450: .Dl 11  cat oldwrite.c
        !           451: .Dl 12  diff *write.c
        !           452: .Pp
        !           453: The commands are shown with their event numbers.
        !           454: It is not usually necessary to use event numbers, but the current event
        !           455: number can be made part of the
        !           456: .Ar prompt
        !           457: by placing an `!' in the prompt string.
        !           458: .Pp
        !           459: With the current event 13 we can refer to previous events by event
        !           460: number `!11', relatively as in `!\-2' (referring to the same event),
        !           461: by a prefix of a command word
        !           462: as in `!d' for event 12 or `!wri' for event 9, or by a string contained in
        !           463: a word in the command as in `!?mic?' also referring to event 9.
        !           464: These forms, without further modification, simply reintroduce the words
        !           465: of the specified events, each separated by a single blank.
        !           466: As a special case `!!' refers to the previous command; thus `!!'
        !           467: alone is essentially a
        !           468: .Ar redo .
        !           469: .Pp
        !           470: To select words from an event we can follow the event specification by
        !           471: a `:' and a designator for the desired words.
        !           472: The words of an input line are numbered from 0,
        !           473: the first (usually command) word being 0, the second word (first argument)
        !           474: being 1, etc.
        !           475: The basic word designators are:
        !           476: .Pp
        !           477: .Dw Ds
        !           478: .Dp \&0
        !           479: first (command) word
        !           480: .Dp Ar n
        !           481: .Cx Ar n
        !           482: .Cx \'th
        !           483: .Cx
        !           484: argument
        !           485: .Dp \*(ua
        !           486: first argument,  i.e. `1'
        !           487: .Dp $
        !           488: last argument
        !           489: .Dp %
        !           490: word matched by (immediately preceding)
        !           491: .Cx \&?
        !           492: .Ar s
        !           493: .Cx \?
        !           494: .Cx
        !           495: search
        !           496: .Dp Ar \&x\-y
        !           497: range of words
        !           498: .Dp Ar \&\-y
        !           499: abbreviates
        !           500: .Ar `\&0\-y\'
        !           501: .Dp \&*
        !           502: abbreviates `\*(ua\-$', or nothing if only 1 word in event
        !           503: .Dp Ar x\&*
        !           504: abbreviates
        !           505: .Ar `x\-$\'
        !           506: .Dp Ar x\-
        !           507: like
        !           508: .Ar `x\&*\'
        !           509: but omitting word `$'
        !           510: .Dp
        !           511: .Pp
        !           512: The `:' separating the event specification from the word designator
        !           513: can be omitted if the argument selector begins with a `\*(ua', `$', `*'
        !           514: `\-' or `%'.
        !           515: After the optional word designator can be
        !           516: placed a sequence of modifiers, each preceded by a `:'.
        !           517: The following modifiers are defined:
        !           518: .Dw Ds
        !           519: .Dp h
        !           520: Remove a trailing pathname component, leaving the head.
        !           521: .Dp r
        !           522: Remove a trailing `.xxx' component, leaving the root name.
        !           523: .Dp e
        !           524: Remove all but the extension `.xxx' part.
        !           525: .Dp Cx s/
        !           526: .Ar l
        !           527: .Cx \/
        !           528: .Ar r
        !           529: .Cx \/
        !           530: .Cx
        !           531: Substitute
        !           532: .Ar l
        !           533: for
        !           534: .Ar r
        !           535: .Dp t
        !           536: Remove all leading pathname components, leaving the tail.
        !           537: .Dp \&&
        !           538: Repeat the previous substitution.
        !           539: .Dp g
        !           540: Apply the change globally, prefixing the above, e.g. `g&'.
        !           541: .Dp p
        !           542: Print the new command line but do not execute it.
        !           543: .Dp q
        !           544: Quote the substituted words, preventing further substitutions.
        !           545: .Dp x
        !           546: Like q, but break into words at blanks, tabs and newlines.
        !           547: .Dp
        !           548: .Pp
        !           549: Unless preceded by a `g' the modification is applied only to the first
        !           550: modifiable word.  With substitutions, it is an error for no word to be
        !           551: applicable.
        !           552: .Pp
        !           553: The left hand side of substitutions are not regular expressions in the sense
        !           554: of the editors, but rather strings.
        !           555: Any character may be used as the delimiter in place of `/';
        !           556: a `\e' quotes the delimiter into the
        !           557: .Ar l  " "
        !           558: and
        !           559: .Ar r  " "
        !           560: strings.
        !           561: The character `&' in the right hand side is replaced by the text from
        !           562: the left.
        !           563: A `\e' quotes `&' also.
        !           564: A null
        !           565: .Ar l  " "
        !           566: uses the previous string either from a
        !           567: .Ar l  " "
        !           568: or from a
        !           569: contextual scan string
        !           570: .Ar s  " "
        !           571: in `!?
        !           572: .Ar s
        !           573: \?'.
        !           574: The trailing delimiter in the substitution may be omitted if a newline
        !           575: follows immediately as may the trailing `?' in a contextual scan.
        !           576: .Pp
        !           577: A history reference may be given without an event specification, e.g. `!$'.
        !           578: In this case the reference is to the previous command unless a previous
        !           579: history reference occurred on the same line in which case this form repeats
        !           580: the previous reference.
        !           581: Thus `!?foo?\*(ua !$' gives the first and last arguments
        !           582: from the command matching `?foo?'.
        !           583: .Pp
        !           584: A special abbreviation of a history reference occurs when the first
        !           585: non-blank character of an input line is a `\*(ua'.
        !           586: This is equivalent to `!:s\*(ua' providing a convenient shorthand for substitutions
        !           587: on the text of the previous line.
        !           588: Thus `\*(ualb\*(ualib' fixes the spelling of
        !           589: `lib'
        !           590: in the previous command.
        !           591: Finally, a history substitution may be surrounded with `{' and `}'
        !           592: if necessary to insulate it from the characters which follow.
        !           593: Thus, after `ls \-ld ~paul' we might do `!{l}a' to do `ls \-ld ~paula',
        !           594: while `!la' would look for a command starting `la'.
        !           595: .Pp
        !           596: .Ss Quotations with \' and \&"
        !           597: The quotation of strings by `\'' and `"' can be used
        !           598: to prevent all or some of the remaining substitutions.
        !           599: Strings enclosed in `\'' are prevented any further interpretation.
        !           600: Strings enclosed in `"' may be expanded as described below.
        !           601: .Pp
        !           602: In both cases the resulting text becomes (all or part of) a single word;
        !           603: only in one special case (see
        !           604: .Em Command Substitition
        !           605: below) does a `"' quoted string yield parts of more than one word;
        !           606: `\'' quoted strings never do.
        !           607: .Ss Alias substitution
        !           608: The shell maintains a list of aliases which can be established, displayed
        !           609: and modified by the
        !           610: .Ar alias
        !           611: and
        !           612: .Ar unalias
        !           613: commands.
        !           614: After a command line is scanned, it is parsed into distinct commands and
        !           615: the first word of each command, left-to-right, is checked to see if it
        !           616: has an alias.
        !           617: If it does, then the text which is the alias for that command is reread
        !           618: with the history mechanism available
        !           619: as though that command were the previous input line.
        !           620: The resulting words replace the
        !           621: command and argument list.
        !           622: If no reference is made to the history list, then the argument list is
        !           623: left unchanged.
        !           624: .Pp
        !           625: Thus if the alias for `ls' is `ls \-l' the command `ls /usr' would map to
        !           626: `ls \-l /usr', the argument list here being undisturbed.
        !           627: Similarly if the alias for `lookup' was `grep !\*(ua /etc/passwd' then
        !           628: `lookup bill' would map to `grep bill /etc/passwd'.
        !           629: .Pp
        !           630: If an alias is found, the word transformation of the input text
        !           631: is performed and the aliasing process begins again on the reformed input line.
        !           632: Looping is prevented if the first word of the new text is the same as the old
        !           633: by flagging it to prevent further aliasing.
        !           634: Other loops are detected and cause an error.
        !           635: .Pp
        !           636: Note that the mechanism allows aliases to introduce parser metasyntax.
        !           637: Thus we can `alias print \'pr \e!* \&| lpr\'' to make a command which
        !           638: .Ar pr 's
        !           639: its arguments to the line printer.
        !           640: .Ss Variable substitution
        !           641: The shell maintains a set of variables, each of which has as value a list
        !           642: of zero or more words.
        !           643: Some of these variables are set by the shell or referred to by it.
        !           644: For instance, the
        !           645: .Ar argv
        !           646: variable is an image of the shell's argument list, and words of this
        !           647: variable's value are referred to in special ways.
        !           648: .Pp
        !           649: The values of variables may be displayed and changed by using the
        !           650: .Ar set
        !           651: and
        !           652: .Ar unset
        !           653: commands.
        !           654: Of the variables referred to by the shell a number are toggles;
        !           655: the shell does not care what their value is,
        !           656: only whether they are set or not.
        !           657: For instance, the
        !           658: .Ar verbose
        !           659: variable is a toggle which causes command input to be echoed.
        !           660: The setting of this variable results from the
        !           661: .Fl v
        !           662: command line option.
        !           663: .Pp
        !           664: Other operations treat variables numerically.
        !           665: The `@' command permits numeric calculations to be performed and the result
        !           666: assigned to a variable.
        !           667: Variable values are, however, always represented as (zero or more) strings.
        !           668: For the purposes of numeric operations, the null string is considered to be
        !           669: zero, and the second and subsequent words of multiword values are ignored.
        !           670: .Pp
        !           671: After the input line is aliased and parsed, and before each command
        !           672: is executed, variable substitution
        !           673: is performed keyed by `$' characters.
        !           674: This expansion can be prevented by preceding the `$' with a `\e' except
        !           675: within `"'s where it
        !           676: .Ar always
        !           677: occurs, and within `\''s where it
        !           678: .Ar never
        !           679: occurs.
        !           680: Strings quoted by `\*(ga' are interpreted later (see
        !           681: .Nm "Command substitution"
        !           682: below) so `$' substitution does not occur there until later, if at all.
        !           683: A `$' is passed unchanged if followed by a blank, tab, or end-of-line.
        !           684: .Pp
        !           685: Input/output redirections are recognized before variable expansion,
        !           686: and are variable expanded separately.
        !           687: Otherwise, the command name and entire argument list are expanded together.
        !           688: It is thus possible for the first (command) word to this point to generate
        !           689: more than one word, the first of which becomes the command name,
        !           690: and the rest of which become arguments.
        !           691: .Pp
        !           692: Unless enclosed in `"' or given the `:q' modifier the results of variable
        !           693: substitution may eventually be command and filename substituted.
        !           694: Within `"', a variable whose value consists of multiple words expands to a
        !           695: (portion of) a single word, with the words of the variables value
        !           696: separated by blanks.
        !           697: When the `:q' modifier is applied to a substitution
        !           698: the variable will expand to multiple words with each word separated
        !           699: by a blank and quoted to prevent later command or filename substitution.
        !           700: .Pp
        !           701: The following metasequences are provided for introducing variable values into
        !           702: the shell input.
        !           703: Except as noted, it is an error to reference a variable which is not set.
        !           704: .Dw Ds
        !           705: .Di L
        !           706: .Dp $name
        !           707: .Dp ${name}
        !           708: Are replaced by the words of the value of variable
        !           709: .Ar name ,
        !           710: each separated by a blank.
        !           711: Braces insulate
        !           712: .Ar name
        !           713: from following characters which would otherwise be part of it.
        !           714: Shell variables have names consisting of up to 20 letters and digits
        !           715: starting with a letter.  The underscore character is considered a letter.
        !           716: .br
        !           717: If
        !           718: .Ar name
        !           719: is not a shell variable, but is set in the environment, then
        !           720: that value is returned (but
        !           721: .Nm :
        !           722: modifiers and the other forms
        !           723: given below are not available in this case).
        !           724: .Pp
        !           725: .Dp Cx $name
        !           726: .Op selector
        !           727: .Cx
        !           728: .Dp Cx ${name
        !           729: .Op selector
        !           730: .Cx }
        !           731: .Cx
        !           732: May be used to select only some of the words from the value of
        !           733: .Ar name .
        !           734: The selector is subjected to `$' substitution and may consist of a single
        !           735: number or two numbers separated by a `\-'.
        !           736: The first word of a variables value is numbered `1'.
        !           737: If the first number of a range is omitted it defaults to `1'.
        !           738: If the last member of a range is omitted it defaults to `$#name'.
        !           739: The selector `*' selects all words.
        !           740: It is not an error for a range to be empty if the second argument is omitted
        !           741: or in range.
        !           742: .Pp
        !           743: .Dp $#name
        !           744: .Dp ${#name}
        !           745: Gives the number of words in the variable.
        !           746: This is useful for later use in a
        !           747: .Cx `$argv
        !           748: .Op selector
        !           749: .Cx \' .
        !           750: .Cx
        !           751: .Pp
        !           752: .Dp $0
        !           753: Substitutes the name of the file from which command input is being read.
        !           754: An error occurs if the name is not known.
        !           755: .Pp
        !           756: .Dp $number
        !           757: .Dp ${number}
        !           758: Equivalent to
        !           759: .Cx `$argv
        !           760: .Op number
        !           761: .Cx \' .
        !           762: .Cx
        !           763: .Pp
        !           764: .Dp $*
        !           765: Equivalent to
        !           766: .Cx `$argv
        !           767: .Op *
        !           768: .Cx \' .
        !           769: .Cx
        !           770: The modifiers `:e', `:h', `:t', `:r', `:q' and `:x' may be applied to
        !           771: the substitutions above as may `:gh', `:gt' and `:gr'.
        !           772: If braces `{' '}' appear in the command form then the modifiers
        !           773: must appear within the braces.
        !           774: The current implementation allows only one `:' modifier on each `$' expansion.
        !           775: .Dp
        !           776: .Pp
        !           777: The following substitutions may not be modified with `:' modifiers.
        !           778: .Pp
        !           779: .Dw Ds
        !           780: .Di L
        !           781: .Dp $?name
        !           782: .Dp ${?name}
        !           783: Substitutes the string `1' if name is set, `0' if it is not.
        !           784: .Pp
        !           785: .Dp $?0
        !           786: Substitutes `1' if the current input filename is known, `0' if it is not.
        !           787: .Pp
        !           788: .Dp $$
        !           789: Substitute the (decimal) process number of the (parent) shell.
        !           790: .Pp
        !           791: .Dp $<
        !           792: Substitutes a line from the standard
        !           793: input, with no further interpretation thereafter.  It can be used
        !           794: to read from the keyboard in a shell script.
        !           795: .Dp
        !           796: .Ss Command and filename substitution
        !           797: The remaining substitutions, command and filename substitution,
        !           798: are applied selectively to the arguments of builtin commands.
        !           799: This means that portions of expressions which are not evaluated are
        !           800: not subjected to these expansions.
        !           801: For commands which are not internal to the shell, the command
        !           802: name is substituted separately from the argument list.
        !           803: This occurs very late,
        !           804: after input-output redirection is performed, and in a child
        !           805: of the main shell.
        !           806: .Ss Command substitution
        !           807: Command substitution is indicated by a command enclosed in `\*(ga'.
        !           808: The output from such a command is normally broken into separate words
        !           809: at blanks, tabs and newlines, with null words being discarded,
        !           810: this text then replacing the original string.
        !           811: Within `"'s, only newlines force new words; blanks and tabs are preserved.
        !           812: .Pp
        !           813: In any case, the single final newline does not force a new word.
        !           814: Note that it is thus possible for a command substitution to yield
        !           815: only part of a word, even if the command outputs a complete line.
        !           816: .Ss Filename substitution
        !           817: If a word contains any of the characters `*', `?', `[' or `{'
        !           818: or begins with the character `~', then that word is a candidate for
        !           819: filename substitution, also known as `globbing'.
        !           820: This word is then regarded as a pattern, and replaced with an alphabetically
        !           821: sorted list of file names which match the pattern.
        !           822: In a list of words specifying filename substitution it is an error for
        !           823: no pattern to match an existing file name, but it is not required
        !           824: for each pattern to match.
        !           825: Only the metacharacters `*', `?' and `[' imply pattern matching,
        !           826: the characters `~' and `{' being more akin to abbreviations.
        !           827: .Pp
        !           828: In matching filenames, the character `.' at the beginning of a filename
        !           829: or immediately following a `/', as well as the character `/' must
        !           830: be matched explicitly.
        !           831: The character `*' matches any string of characters, including the null
        !           832: string.
        !           833: The character `?' matches any single character.
        !           834: The sequence
        !           835: .Sq Op ...
        !           836: matches any one of the characters enclosed.
        !           837: Within
        !           838: .Sq Op ... ,
        !           839: a pair of characters separated by `\-' matches any character lexically between
        !           840: the two.
        !           841: .Pp
        !           842: The character `~' at the beginning of a filename is used to refer to home
        !           843: directories.
        !           844: Standing alone, i.e. `~' it expands to the invokers home directory as reflected
        !           845: in the value of the variable
        !           846: .Ar home .
        !           847: When followed by a name consisting of letters, digits and `\-' characters
        !           848: the shell searches for a user with that name and substitutes their
        !           849: home directory;  thus `~ken' might expand to `/usr/ken' and `~ken/chmach'
        !           850: to `/usr/ken/chmach'.
        !           851: If the character `~' is followed by a character other than a letter or `/'
        !           852: or appears not at the beginning of a word,
        !           853: it is left undisturbed.
        !           854: .Pp
        !           855: The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
        !           856: Left to right order is preserved, with results of matches being sorted
        !           857: separately at a low level to preserve this order.
        !           858: This construct may be nested.
        !           859: Thus `~source/s1/{oldls,ls}.c' expands to
        !           860: `/usr/source/s1/oldls.c /usr/source/s1/ls.c'
        !           861: whether or not these files exist without any chance of error
        !           862: if the home directory for `source' is `/usr/source'.
        !           863: Similarly `../{memo,*box}' might expand to `../memo ../box ../mbox'.
        !           864: (Note that `memo' was not sorted with the results of matching `*box'.)
        !           865: As a special case `{', `}' and `{}' are passed undisturbed.
        !           866: .Ss Input/output
        !           867: The standard input and standard output of a command may be redirected
        !           868: with the following syntax:
        !           869: .Dw Ds
        !           870: .Di L
        !           871: .Dp < name
        !           872: Open file
        !           873: .Ar name
        !           874: (which is first variable, command and filename expanded) as the standard
        !           875: input.
        !           876: .Pp
        !           877: .Dp << word
        !           878: Read the shell input up to a line which is identical to
        !           879: .Ar word .
        !           880: .Ar Word
        !           881: is not subjected to variable, filename or command substitution,
        !           882: and each input line is compared to
        !           883: .Ar word
        !           884: before any substitutions are done on this input line.
        !           885: Unless a quoting `\e', `"', `\*(aa' or `\*(ga' appears in
        !           886: .Ar word
        !           887: variable and command substitution is performed on the intervening lines,
        !           888: allowing `\e' to quote `$', `\e' and `\*(ga'.
        !           889: Commands which are substituted have all blanks, tabs, and newlines
        !           890: preserved, except for the final newline which is dropped.
        !           891: The resultant text is placed in an anonymous temporary file which
        !           892: is given to the command as standard input.
        !           893: .Pp
        !           894: .Dp > name
        !           895: .Dp >! name
        !           896: .Dp >& name
        !           897: .Dp >&! name
        !           898: The file
        !           899: .Ar name
        !           900: is used as standard output.
        !           901: If the file does not exist then it is created;
        !           902: if the file exists, its is truncated, its previous contents being lost.
        !           903: .Pp
        !           904: If the variable
        !           905: .Ar noclobber
        !           906: is set, then the file must not exist or be a character special file (e.g. a
        !           907: terminal or `/dev/null') or an error results.
        !           908: This helps prevent accidental destruction of files.
        !           909: In this case the `!' forms can be used and suppress this check.
        !           910: .Pp
        !           911: The forms involving `&' route the diagnostic output into the specified
        !           912: file as well as the standard output.
        !           913: .Ar Name
        !           914: is expanded in the same way as `<' input filenames are.
        !           915: .Pp
        !           916: .Dp >> name
        !           917: .Dp >>& name
        !           918: .Dp >>! name
        !           919: .Dp >>&! name
        !           920: Uses file
        !           921: .Ar name
        !           922: as standard output like `>' but places output at the end of the file.
        !           923: If the variable
        !           924: .Ar noclobber
        !           925: is set, then it is an error for the file not to exist unless
        !           926: one of the `!' forms is given.
        !           927: Otherwise similar to `>'.
        !           928: .Dp
        !           929: .Pp
        !           930: A command receives the environment in which the shell was
        !           931: invoked as modified by the input-output parameters and
        !           932: the presence of the command in a pipeline.
        !           933: Thus, unlike some previous shells, commands run from a file of shell commands
        !           934: have no access to the text of the commands by default; rather
        !           935: they receive the original standard input of the shell.
        !           936: The `<<' mechanism should be used to present inline data.
        !           937: This permits shell command scripts to function as components of pipelines
        !           938: and allows the shell to block read its input.
        !           939: Note that the default standard input for a command run detached is
        !           940: .Ar not
        !           941: modified to be the empty file
        !           942: .Pa /dev/null ;
        !           943: rather the standard input
        !           944: remains as the original standard input of the shell.  If this is a terminal
        !           945: and if the process attempts to read from the terminal, then the process
        !           946: will block and the user will be notified (see
        !           947: .Ar Jobs
        !           948: above).
        !           949: .Pp
        !           950: Diagnostic output may be directed through a pipe with the standard output.
        !           951: Simply use the form `\&|&' rather than just `\&|'.
        !           952: .Ss Expressions
        !           953: A number of the builtin commands (to be described subsequently)
        !           954: take expressions, in which the operators are similar to those of C, with
        !           955: the same precedence.
        !           956: These expressions appear in the
        !           957: .Nm @,
        !           958: .Ar exit ,
        !           959: .Ar if ,
        !           960: and
        !           961: .Ar while
        !           962: commands.
        !           963: The following operators are available:
        !           964: .Pp
        !           965: .Ds I
        !           966: \&|\&|  &&  \&| *(ua  &  ==  !=  =~  !~  <=  >=  <  >
        !           967: <<  >>  +  \-  *  /  %  !  ~  (  )
        !           968: .De
        !           969: .Pp
        !           970: Here the precedence increases to the right,
        !           971: `==' `!=' `=~' and `!~', `<=' `>=' `<' and `>', `<<' and `>>', `+' and `\-',
        !           972: `*' `/' and `%' being, in groups, at the same level.
        !           973: The `==' `!=' `=~' and `!~' operators compare their arguments as strings;
        !           974: all others operate on numbers.
        !           975: The operators `=~' and `!~' are like `!=' and `==' except that the right
        !           976: hand side is a
        !           977: .Ar pattern
        !           978: (containing, e.g. `*'s, `?'s and instances of
        !           979: .Cx `
        !           980: .Op ...
        !           981: .Cx \' )
        !           982: .Cx
        !           983: against which the left hand operand is matched.  This reduces the
        !           984: need for use of the
        !           985: .Ar switch
        !           986: statement in shell scripts when all that is really needed is pattern matching.
        !           987: .Pp
        !           988: Strings which begin with `0' are considered octal numbers.
        !           989: Null or missing arguments are considered `0'.
        !           990: The result of all expressions are strings,
        !           991: which represent decimal numbers.
        !           992: It is important to note that no two components of an expression can appear
        !           993: in the same word; except when adjacent to components of expressions which
        !           994: are syntactically significant to the parser (`&' `\&|' `<' `>' `(' `)')
        !           995: they should be surrounded by spaces.
        !           996: .Pp
        !           997: Also available in expressions as primitive operands are command executions
        !           998: enclosed in `{' and `}'
        !           999: and file enquiries of the form
        !          1000: .Fl l
        !          1001: .Ar name
        !          1002: where
        !          1003: .Ic l
        !          1004: is one of:
        !          1005: .Pp
        !          1006: .Ds I
        !          1007: r      read access
        !          1008: w      write access
        !          1009: x      execute access
        !          1010: e      existence
        !          1011: o      ownership
        !          1012: z      zero size
        !          1013: f      plain file
        !          1014: d      directory
        !          1015: .De
        !          1016: .Pp
        !          1017: The specified name is command and filename expanded and then tested
        !          1018: to see if it has the specified relationship to the real user.
        !          1019: If the file does not exist or is inaccessible then all enquiries return
        !          1020: false, i.e. `0'.
        !          1021: Command executions succeed, returning true, i.e. `1',
        !          1022: if the command exits with status 0, otherwise they fail, returning
        !          1023: false, i.e. `0'.
        !          1024: If more detailed status information is required then the command
        !          1025: should be executed outside of an expression and the variable
        !          1026: .Ar status
        !          1027: examined.
        !          1028: .Ss Control flow
        !          1029: The shell contains a number of commands which can be used to regulate the
        !          1030: flow of control in command files (shell scripts) and
        !          1031: (in limited but useful ways) from terminal input.
        !          1032: These commands all operate by forcing the shell to reread or skip in its
        !          1033: input and, due to the implementation, restrict the placement of some
        !          1034: of the commands.
        !          1035: .Pp
        !          1036: The
        !          1037: .Ic foreach ,
        !          1038: .Ic switch ,
        !          1039: and
        !          1040: .Ic while
        !          1041: statements, as well as the
        !          1042: .Ic if\-then\-else
        !          1043: form of the
        !          1044: .Ic if
        !          1045: statement require that the major keywords appear in a single simple command
        !          1046: on an input line as shown below.
        !          1047: .Pp
        !          1048: If the shell's input is not seekable,
        !          1049: the shell buffers up input whenever a loop is being read
        !          1050: and performs seeks in this internal buffer to accomplish the rereading
        !          1051: implied by the loop.
        !          1052: (To the extent that this allows, backward goto's will succeed on
        !          1053: non-seekable inputs.)
        !          1054: .Ss Builtin commands
        !          1055: Builtin commands are executed within the shell.
        !          1056: If a builtin command occurs as any component of a pipeline
        !          1057: except the last then it is executed in a subshell.
        !          1058: .Dw Ds
        !          1059: .Di L
        !          1060: .Dp Ic alias
        !          1061: .Dp Cx Ic alias
        !          1062: .Cx \&\ \&
        !          1063: .Cx Ar name
        !          1064: .Cx
        !          1065: .Dp Cx Ic alias
        !          1066: .Cx \&\ \&
        !          1067: .Ar name wordlist
        !          1068: .Cx
        !          1069: The first form prints all aliases.
        !          1070: The second form prints the alias for name.
        !          1071: The final form assigns the specified
        !          1072: .Ar wordlist
        !          1073: as the alias of
        !          1074: .Ar name ;
        !          1075: .Ar wordlist
        !          1076: is command and filename substituted.
        !          1077: .Ar Name
        !          1078: is not allowed to be
        !          1079: .Ar alias
        !          1080: or
        !          1081: .Ar unalias .
        !          1082: .Pp
        !          1083: .Dp Ic alloc
        !          1084: Shows the amount of dynamic memory acquired, broken down into used and
        !          1085: free memory.
        !          1086: With an argument shows the number of free and used blocks in each size
        !          1087: category.  The categories start at size 8 and double at each step.
        !          1088: This command's output may vary across system types, since
        !          1089: systems other than the VAX may use a different memory allocator.
        !          1090: .Pp
        !          1091: .Dp Ic bg
        !          1092: .Dp Cx Ic bg \&%
        !          1093: .Ar job ...
        !          1094: .Cx
        !          1095: Puts the current or specified jobs into the background, continuing them
        !          1096: if they were stopped.
        !          1097: .Pp
        !          1098: .Dp Ic break
        !          1099: Causes execution to resume after the
        !          1100: .Ic end
        !          1101: of the nearest enclosing
        !          1102: .Ic foreach
        !          1103: or
        !          1104: .Ic while .
        !          1105: The remaining commands on the current line are executed.
        !          1106: Multi-level breaks are thus possible by writing them all on one line.
        !          1107: .Pp
        !          1108: .Dp Ic breaksw
        !          1109: Causes a break from a
        !          1110: .Ic switch ,
        !          1111: resuming after the
        !          1112: .Ic endsw .
        !          1113: .Pp
        !          1114: .Dp Cx Ic case
        !          1115: .Cx \&\ \&
        !          1116: .Ar label :
        !          1117: .Cx
        !          1118: A label in a
        !          1119: .Ic switch
        !          1120: statement as discussed below.
        !          1121: .Pp
        !          1122: .Dp Ic cd
        !          1123: .Dp Cx Ic cd
        !          1124: .Cx \&\ \&
        !          1125: .Ar name
        !          1126: .Cx
        !          1127: .Dp Ic chdir
        !          1128: .Dp Cx Ic chdir
        !          1129: .Cx \&\ \&
        !          1130: .Ar name
        !          1131: .Cx
        !          1132: Change the shell's working directory to directory
        !          1133: .Ar name .
        !          1134: If no argument is given then change to the home directory of the user.
        !          1135: If
        !          1136: .Ar name
        !          1137: is not found as a subdirectory of the current directory (and does not begin
        !          1138: with `/', `./' or `../'), then each
        !          1139: component of the variable
        !          1140: .Ic cdpath
        !          1141: is checked to see if it has a subdirectory
        !          1142: .Ar name .
        !          1143: Finally, if all else fails but
        !          1144: .Ar name
        !          1145: is a shell variable whose value begins with `/', then this
        !          1146: is tried to see if it is a directory.
        !          1147: .Pp
        !          1148: .Dp Ic continue
        !          1149: Continue execution of the nearest enclosing
        !          1150: .Ic while
        !          1151: or
        !          1152: .Ic foreach .
        !          1153: The rest of the commands on the current line are executed.
        !          1154: .Pp
        !          1155: .Dp Ic default :
        !          1156: Labels the default case in a
        !          1157: .Ic switch
        !          1158: statement.
        !          1159: The default should come after all
        !          1160: .Ic case
        !          1161: labels.
        !          1162: .Pp
        !          1163: .Dp Ic dirs
        !          1164: Prints the directory stack; the top of the stack is at the left,
        !          1165: the first directory in the stack being the current directory.
        !          1166: .Pp
        !          1167: .Dp Cx Ic echo
        !          1168: .Cx \&\ \&
        !          1169: .Ar  wordlist
        !          1170: .Cx
        !          1171: .Dp Cx Ic echo
        !          1172: .Cx \&\ \&
        !          1173: .Fl n
        !          1174: .Cx \&\ \&
        !          1175: .Ar wordlist
        !          1176: .Cx
        !          1177: The specified words are written to the shells standard output, separated
        !          1178: by spaces, and terminated with a newline unless the
        !          1179: .Fl n
        !          1180: option is specified.
        !          1181: .Pp
        !          1182: .Dp Ic else
        !          1183: .Dp Ic end
        !          1184: .Dp Ic endif
        !          1185: .Dp Ic endsw
        !          1186: See the description of the
        !          1187: .Ic foreach ,
        !          1188: .Ic if ,
        !          1189: .Ic switch ,
        !          1190: and
        !          1191: .Ic while
        !          1192: statements below.
        !          1193: .Pp
        !          1194: .Dp Cx Ic eval
        !          1195: .Cx \&\ \&
        !          1196: .Ar arg ...
        !          1197: .Cx
        !          1198: (As in
        !          1199: .Xr sh  1  . )
        !          1200: The arguments are read as input to the shell and the resulting
        !          1201: command(s) executed in the context of the current shell.
        !          1202: This is usually used to execute commands
        !          1203: generated as the result of command or variable substitution, since
        !          1204: parsing occurs before these substitutions.  See
        !          1205: .Xr tset  1
        !          1206: for an example of using
        !          1207: .Ic eval .
        !          1208: .Pp
        !          1209: .Dp Cx Ic exec
        !          1210: .Cx \&\ \&
        !          1211: .Ar command
        !          1212: .Cx
        !          1213: The specified command is executed in place of the current shell.
        !          1214: .Pp
        !          1215: .Dp Ic exit
        !          1216: .Dp Cx Ic exit
        !          1217: .Cx \&\ \&
        !          1218: .Ar (expr )
        !          1219: .Cx
        !          1220: The shell exits either with the value of the
        !          1221: .Ic status
        !          1222: variable (first form) or with the value of the specified
        !          1223: .Ic expr
        !          1224: (second form).
        !          1225: .Pp
        !          1226: .Dp Ic fg
        !          1227: .Dp Cx Ic fg \&%
        !          1228: .Ar job ...
        !          1229: .Cx
        !          1230: Brings the current or specified jobs into the foreground, continuing them if
        !          1231: they were stopped.
        !          1232: .Pp
        !          1233: .Dp Cx Ic foreach
        !          1234: .Cx \&\ \&
        !          1235: .Ar name (wordlist)
        !          1236: .Cx
        !          1237: .Dp ...
        !          1238: .Dp Ic end
        !          1239: The variable
        !          1240: .Ic name
        !          1241: is successively set to each member of
        !          1242: .Ic wordlist
        !          1243: and the sequence of commands between this command and the matching
        !          1244: .Ic end
        !          1245: are executed.
        !          1246: (Both
        !          1247: .Ic foreach
        !          1248: and
        !          1249: .Ic end
        !          1250: must appear alone on separate lines.)
        !          1251: The builtin command
        !          1252: .Ic continue
        !          1253: may be used to continue the loop prematurely and the builtin
        !          1254: command
        !          1255: .Ic break
        !          1256: to terminate it prematurely.
        !          1257: When this command is read from the terminal, the loop is read up once
        !          1258: prompting with `?' before any statements in the loop are executed.
        !          1259: If you make a mistake typing in a loop at the terminal you can rub it out.
        !          1260: .Pp
        !          1261: .Dp Cx Ic glob
        !          1262: .Cx \&\ \&
        !          1263: .Ar wordlist
        !          1264: .Cx
        !          1265: Like
        !          1266: .Ic echo
        !          1267: but no `\e' escapes are recognized and words are delimited
        !          1268: by null characters in the output.
        !          1269: Useful for programs which wish to use the shell to filename expand a list
        !          1270: of words.
        !          1271: .Pp
        !          1272: .Dp Cx Ic goto
        !          1273: .Cx \&\ \&
        !          1274: .Ar word
        !          1275: .Cx
        !          1276: The specified
        !          1277: .Ic word
        !          1278: is filename and command expanded to yield a string of the form `label'.
        !          1279: The shell rewinds its input as much as possible
        !          1280: and searches for a line of the form `label:'
        !          1281: possibly preceded by blanks or tabs.
        !          1282: Execution continues after the specified line.
        !          1283: .Pp
        !          1284: .Dp Ic hashstat
        !          1285: Print a statistics line indicating how effective the internal hash
        !          1286: table has been at locating commands (and avoiding
        !          1287: .Cx Ic exec
        !          1288: .Cx 's ) .
        !          1289: .Cx
        !          1290: An
        !          1291: .Ic exec
        !          1292: is attempted for each component of the
        !          1293: .Em path
        !          1294: where the hash function indicates a possible hit, and in each component
        !          1295: which does not begin with a `/'.
        !          1296: .Pp
        !          1297: .Dp Ic history
        !          1298: .Dp Cx Ic history
        !          1299: .Cx \&\ \&
        !          1300: .Ar n
        !          1301: .Cx
        !          1302: .Dp Cx Ic history
        !          1303: .Cx \&\ \&
        !          1304: .Fl r
        !          1305: .Cx \&\ \&
        !          1306: .Ar n
        !          1307: .Cx
        !          1308: .Dp Cx Ic history
        !          1309: .Cx \&\ \&
        !          1310: .Fl h
        !          1311: .Cx \&\ \&
        !          1312: .Ar n
        !          1313: .Cx
        !          1314: Displays the history event list; if
        !          1315: .Ar n
        !          1316: is given only the
        !          1317: .Ar n
        !          1318: most recent events are printed.
        !          1319: The
        !          1320: .Fl r
        !          1321: option reverses the order of printout to be most recent first
        !          1322: rather than oldest first.
        !          1323: The
        !          1324: .Fl h
        !          1325: option causes the history list to be printed without leading numbers.
        !          1326: This is used to produce files suitable for sourceing using the \-h
        !          1327: option to
        !          1328: .Ic source  .
        !          1329: .Pp
        !          1330: .Dp Cx Ic if
        !          1331: .Cx \&\ \&
        !          1332: .Cx \&(
        !          1333: .Ar expr
        !          1334: .Cx \&)
        !          1335: .Cx
        !          1336: .Ar command
        !          1337: If the specified expression evaluates true, then the single
        !          1338: .Ar command
        !          1339: with arguments is executed.
        !          1340: Variable substitution on
        !          1341: .Ar command
        !          1342: happens early, at the same
        !          1343: time it does for the rest of the
        !          1344: .Ic if
        !          1345: .Ar command .
        !          1346: .Ar Command
        !          1347: must be a simple command, not
        !          1348: a pipeline, a command list, or a parenthesized command list.
        !          1349: Input/output redirection occurs even if
        !          1350: .Ar expr
        !          1351: is false, when command is
        !          1352: .Sy not
        !          1353: executed (this is a bug).
        !          1354: .Pp
        !          1355: .Dp Cx Ic if
        !          1356: .Cx \&\ \&
        !          1357: .Cx \&(
        !          1358: .Ar expr
        !          1359: .Cx \&)
        !          1360: .Cx \&\ \&
        !          1361: .Ar then 
        !          1362: .Cx
        !          1363: .Dp ...
        !          1364: .Dp Cx Ic else if
        !          1365: .Cx \&\ \&
        !          1366: .Cx \&(
        !          1367: .Ar expr2
        !          1368: .Cx \&)
        !          1369: .Cx \&\ \&
        !          1370: .Ic then
        !          1371: .Cx
        !          1372: .Dp ...
        !          1373: .Dp Ic else
        !          1374: .Dp ...
        !          1375: .Dp Ic endif
        !          1376: If the specified
        !          1377: .Ar expr
        !          1378: is true then the commands to the first
        !          1379: .Ic else
        !          1380: are executed; otherwise if
        !          1381: .Ar expr2
        !          1382: is true then the commands to the
        !          1383: second
        !          1384: .Ic else
        !          1385: are executed, etc.
        !          1386: Any number of
        !          1387: .Ic else-if
        !          1388: pairs are possible; only one
        !          1389: .Ic endif
        !          1390: is needed.
        !          1391: The
        !          1392: .Ic else
        !          1393: part is likewise optional.
        !          1394: (The words
        !          1395: .Ic else
        !          1396: and
        !          1397: .Ic endif
        !          1398: must appear at the beginning of input lines;
        !          1399: the
        !          1400: .Ic if
        !          1401: must appear alone on its input line or after an
        !          1402: .Ic else . )
        !          1403: .Pp
        !          1404: .Dp Ic jobs
        !          1405: .Dp Cx Ic jobs
        !          1406: .Cx \&\ \&
        !          1407: .Fl l
        !          1408: .Cx
        !          1409: Lists the active jobs; given the
        !          1410: .Fl l
        !          1411: options lists process id's in addition to the normal information.
        !          1412: .Pp
        !          1413: .Dp Cx Ic kill  %
        !          1414: .Ar job
        !          1415: .Cx
        !          1416: .Dp Cx Ic kill
        !          1417: .Cx \&\ \&
        !          1418: .Ar pid
        !          1419: .Cx
        !          1420: .Dp Cx Ic kill
        !          1421: .Cx \&\ \&
        !          1422: .Fl sig
        !          1423: .Ar pid ...
        !          1424: .Cx
        !          1425: .Dp Cx Ic kill
        !          1426: .Cx \&\ \&
        !          1427: .Fl l
        !          1428: .Cx
        !          1429: Sends either the TERM (terminate) signal or the
        !          1430: specified signal to the specified jobs or processes.
        !          1431: Signals are either given by number or by names (as given in
        !          1432: .Pa /usr/include/signal.h,
        !          1433: stripped of the prefix ``SIG'').
        !          1434: The signal names are listed by ``kill \-l''.
        !          1435: There is no default, saying just `kill' does not
        !          1436: send a signal to the current job.
        !          1437: If the signal being sent is TERM (terminate) or HUP (hangup),
        !          1438: then the job or process will be sent a CONT (continue) signal as well.
        !          1439: .Pp
        !          1440: .Dp Ic limit
        !          1441: .Dp Cx Ic limit
        !          1442: .Cx \&\ \&
        !          1443: .Ar resource
        !          1444: .Cx
        !          1445: .Dp Cx Ic limit
        !          1446: .Cx \&\ \&
        !          1447: .Ar resource maximum-use
        !          1448: .Cx
        !          1449: .Dp Cx Ic limit
        !          1450: .Cx \&\ \&
        !          1451: .Fl h
        !          1452: .Cx
        !          1453: .Dp Cx Ic limit
        !          1454: .Cx \&\ \&
        !          1455: .Fl h
        !          1456: .Cx \&\ \&
        !          1457: .Ar resource
        !          1458: .Cx
        !          1459: .Dp Cx Ic limit
        !          1460: .Cx \&\ \&
        !          1461: .Fl h
        !          1462: .Cx \&\ \&
        !          1463: .Ar resource maximum-use
        !          1464: .Cx
        !          1465: Limits the consumption by the current process and each process
        !          1466: it creates to not individually exceed
        !          1467: .Ar maximum-use
        !          1468: on the
        !          1469: specified
        !          1470: .Ar resource  .
        !          1471: If no
        !          1472: .Ar maximum-use
        !          1473: is given, then
        !          1474: the current limit is printed; if no
        !          1475: .Ar resource
        !          1476: is given, then
        !          1477: all limitations are given.  If the
        !          1478: .Fl h
        !          1479: flag is given, the hard limits are used instead of the current
        !          1480: limits.  The hard limits impose a ceiling on the values of
        !          1481: the current limits.  Only the super-user may raise the hard limits,
        !          1482: but a user may lower or raise the current limits within the legal range.
        !          1483: .Pp
        !          1484: Resources controllable currently include
        !          1485: .Ar cputime
        !          1486: (the maximum
        !          1487: number of cpu-seconds to be used by each process),
        !          1488: .Ar filesize
        !          1489: (the largest single file which can be created),
        !          1490: .Ar datasize
        !          1491: (the maximum growth of the data+stack region via
        !          1492: .Xr sbrk  2
        !          1493: beyond the end of the program text),
        !          1494: .Ar stacksize
        !          1495: (the maximum
        !          1496: size of the automatically-extended stack region), and
        !          1497: .Ar coredumpsize
        !          1498: (the size of the largest core dump that will be created).
        !          1499: .Pp
        !          1500: The
        !          1501: .Ar maximum-use
        !          1502: may be given as a (floating point or integer)
        !          1503: number followed by a scale factor.  For all limits other than
        !          1504: .Ar cputime
        !          1505: the default scale is `k' or `kilobytes' (1024 bytes);
        !          1506: a scale factor of `m' or `megabytes' may also be used.
        !          1507: For
        !          1508: .Ar cputime
        !          1509: the default scaling is `seconds', while `m' for minutes
        !          1510: or `h' for hours, or a time of the form `mm:ss' giving minutes
        !          1511: and seconds may be used.
        !          1512: .Pp
        !          1513: For both
        !          1514: .Ar resource
        !          1515: names and scale factors, unambiguous prefixes
        !          1516: of the names suffice.
        !          1517: .Pp
        !          1518: .Dp Ic login
        !          1519: Terminate a login shell, replacing it with an instance of
        !          1520: .Pa /bin/login.
        !          1521: This is one way to log off, included for compatibility with
        !          1522: .Xr sh  1  .
        !          1523: .Pp
        !          1524: .Dp Ic logout
        !          1525: Terminate a login shell.
        !          1526: Especially useful if
        !          1527: .Ic ignoreeof
        !          1528: is set.
        !          1529: .Pp
        !          1530: .Dp Ic nice
        !          1531: .Dp Cx Ic nice
        !          1532: .Cx \&\ \&
        !          1533: .Ar +number
        !          1534: .Cx
        !          1535: .Dp Cx Ic nice
        !          1536: .Cx \&\ \&
        !          1537: .Ar command
        !          1538: .Cx
        !          1539: .Dp Cx Ic nice
        !          1540: .Cx \&\ \&
        !          1541: .Ar +number command
        !          1542: .Cx
        !          1543: The first form sets the
        !          1544: scheduling priority
        !          1545: for this shell to 4.
        !          1546: The second form sets the
        !          1547: priority
        !          1548: to the given
        !          1549: .Ar number .
        !          1550: The final two forms run command at priority 4 and
        !          1551: .Ar number
        !          1552: respectively.
        !          1553: The greater the number, the less cpu the process will get.
        !          1554: The super-user may specify negative priority by using `nice \-number ...'.
        !          1555: Command is always executed in a sub-shell, and the restrictions
        !          1556: placed on commands in simple
        !          1557: .Ic if
        !          1558: statements apply.
        !          1559: .Pp
        !          1560: .Dp Ic nohup
        !          1561: .Dp Cx Ic nohup
        !          1562: .Cx \&\ \&
        !          1563: .Ar command
        !          1564: .Cx
        !          1565: The first form can be used in shell scripts to cause hangups to be
        !          1566: ignored for the remainder of the script.
        !          1567: The second form causes the specified command to be run with hangups
        !          1568: ignored.
        !          1569: All processes detached with `&' are effectively
        !          1570: .Cx Ic nohup
        !          1571: .Cx \'ed .
        !          1572: .Cx
        !          1573: .Pp
        !          1574: .Dp Ic notify
        !          1575: .Dp Cx Ic notify %
        !          1576: .Cx \&\ \&
        !          1577: .Ar job ...
        !          1578: .Cx
        !          1579: Causes the shell to notify the user asynchronously when the status of the
        !          1580: current or specified jobs changes; normally notification is presented
        !          1581: before a prompt.  This is automatic if the shell variable
        !          1582: .Ic notify
        !          1583: is set.
        !          1584: .Pp
        !          1585: .Dp Ic onintr
        !          1586: .Dp Cx Ic onintr
        !          1587: .Cx \&\ \&
        !          1588: .Fl
        !          1589: .Cx
        !          1590: .Dp Cx Ic onintr
        !          1591: .Cx \&\ \&
        !          1592: .Ar label
        !          1593: .Cx
        !          1594: Control the action of the shell on interrupts.
        !          1595: The first form restores the default action of the shell on interrupts
        !          1596: which is to terminate shell scripts or to return to the terminal command
        !          1597: input level.
        !          1598: The second form `onintr \-' causes all interrupts to be ignored.
        !          1599: The final form causes the shell to execute a `goto label' when
        !          1600: an interrupt is received or a child process terminates because
        !          1601: it was interrupted.
        !          1602: .Pp
        !          1603: In any case, if the shell is running detached and interrupts are
        !          1604: being ignored, all forms of
        !          1605: .Ic onintr
        !          1606: have no meaning and interrupts
        !          1607: continue to be ignored by the shell and all invoked commands.
        !          1608: .Pp
        !          1609: .Dp Ic popd
        !          1610: .Dp Cx Ic popd
        !          1611: .Cx \&\ \&
        !          1612: .Ar +n
        !          1613: .Cx
        !          1614: Pops the directory stack, returning to the new top directory.
        !          1615: With an argument
        !          1616: .Cx `+
        !          1617: .Ar n
        !          1618: .Cx \'
        !          1619: .Cx
        !          1620: discards the
        !          1621: .Cx Ar n
        !          1622: .Cx \'
        !          1623: .Cx th
        !          1624: .Cx
        !          1625: entry in the stack.
        !          1626: The elements of the directory stack are numbered from 0 starting at the top.
        !          1627: .Pp
        !          1628: .Dp Ic pushd
        !          1629: .Dp Cx Ic pushd
        !          1630: .Cx \&\ \&
        !          1631: .Ar name
        !          1632: .Cx
        !          1633: .Dp Cx Ic pushd
        !          1634: .Cx \&\ \&
        !          1635: .Ar n
        !          1636: .Cx
        !          1637: With no arguments,
        !          1638: .Ic pushd
        !          1639: exchanges the top two elements of the directory stack.
        !          1640: Given a
        !          1641: .Ar name
        !          1642: argument,
        !          1643: .Ic pushd
        !          1644: changes to the new directory (ala
        !          1645: .Ic cd )
        !          1646: and pushes the old current working directory
        !          1647: (as in
        !          1648: .Ic csw )
        !          1649: onto the directory stack.
        !          1650: With a numeric argument, rotates the
        !          1651: .Cx Ar n
        !          1652: .Cx \'
        !          1653: .Cx th
        !          1654: .Cx
        !          1655: argument of the directory
        !          1656: stack around to be the top element and changes to it.  The members
        !          1657: of the directory stack are numbered from the top starting at 0.
        !          1658: .Pp
        !          1659: .Dp Ic rehash
        !          1660: Causes the internal hash table of the contents of the directories in
        !          1661: the
        !          1662: .Ic path
        !          1663: variable to be recomputed.  This is needed if new commands are added
        !          1664: to directories in the
        !          1665: .Ic path
        !          1666: while you are logged in.  This should only be necessary if you add
        !          1667: commands to one of your own directories, or if a systems programmer
        !          1668: changes the contents of one of the system directories.
        !          1669: .Pp
        !          1670: .Dp Cx Ic repeat
        !          1671: .Cx \&\ \&
        !          1672: .Ar count command
        !          1673: .Cx
        !          1674: The specified
        !          1675: .Ar command
        !          1676: which is subject to the same restrictions
        !          1677: as the
        !          1678: .Ar command
        !          1679: in the one line
        !          1680: .Ic if
        !          1681: statement above,
        !          1682: is executed
        !          1683: .Ar count
        !          1684: times.
        !          1685: I/O redirections occur exactly once, even if
        !          1686: .Ar count
        !          1687: is 0.
        !          1688: .Pp
        !          1689: .Dp Ic set
        !          1690: .Dp Cx Ic set
        !          1691: .Cx \&\ \&
        !          1692: .Ar name
        !          1693: .Cx
        !          1694: .Dp Cx Ic set
        !          1695: .Cx \&\ \&
        !          1696: .Ar name=word
        !          1697: .Cx
        !          1698: .Dp Cx Ic set
        !          1699: .Cx \&\ \&
        !          1700: .Ar name
        !          1701: .Op index
        !          1702: .Ar =word
        !          1703: .Cx
        !          1704: .Dp Cx Ic set
        !          1705: .Cx \&\ \&
        !          1706: .Ar name=(wordlist)
        !          1707: .Cx
        !          1708: The first form of the command shows the value of all shell variables.
        !          1709: Variables which have other than a single word as value print as a parenthesized
        !          1710: word list.
        !          1711: The second form sets
        !          1712: .Ic name
        !          1713: to the null string.
        !          1714: The third form sets
        !          1715: .Ic name
        !          1716: to the single
        !          1717: .Ic word .
        !          1718: The fourth form sets
        !          1719: the
        !          1720: .Cx Ar index
        !          1721: .Cx \'th
        !          1722: .Cx
        !          1723: component of name to word;
        !          1724: this component must already exist.
        !          1725: The final form sets
        !          1726: .Ar name
        !          1727: to the list of words in
        !          1728: .Ar wordlist .
        !          1729: In all cases the value is command and filename expanded.
        !          1730: .Pp
        !          1731: These arguments may be repeated to set multiple values in a single set command.
        !          1732: Note however, that variable expansion happens for all arguments before any
        !          1733: setting occurs.
        !          1734: .Pp
        !          1735: .Dp Ic setenv
        !          1736: .Dp Cx Ic setenv
        !          1737: .Cx \&\ \&
        !          1738: .Ar name value
        !          1739: .Cx
        !          1740: .Dp Cx Ic setenv
        !          1741: .Cx \&\ \&
        !          1742: .Ar name
        !          1743: .Cx
        !          1744: The first form lists all current environment variables.
        !          1745: The last form sets the value of environment variable
        !          1746: .Ar name
        !          1747: to be
        !          1748: .Ar value ,
        !          1749: a single string.  The second form sets
        !          1750: .Ar name
        !          1751: to an empty string.
        !          1752: The most commonly used environment variable
        !          1753: .Ev USER ,
        !          1754: .Ev TERM ,
        !          1755: and
        !          1756: .Ev PATH
        !          1757: are automatically imported to and exported from the
        !          1758: .Nm csh
        !          1759: variables
        !          1760: .Ar user ,
        !          1761: .Op Ar term ,
        !          1762: and
        !          1763: .Ar path ;
        !          1764: there is no need to use
        !          1765: .Ic setenv
        !          1766: for these.
        !          1767: .Pp
        !          1768: .Dp Ic shift
        !          1769: .Dp Cx Ic shift
        !          1770: .Cx \&\ \&
        !          1771: .Ar variable
        !          1772: .Cx
        !          1773: The members of
        !          1774: .Ic argv
        !          1775: are shifted to the left, discarding
        !          1776: .Cx Ic argv
        !          1777: .Op 1  .
        !          1778: .Cx
        !          1779: It is an error for
        !          1780: .Ic argv
        !          1781: not to be set or to have less than one word as value.
        !          1782: The second form performs the same function on the specified variable.
        !          1783: .Pp
        !          1784: .Dp Cx Ic source
        !          1785: .Cx \&\ \&
        !          1786: .Ar name
        !          1787: .Cx
        !          1788: .Dp Cx Ic source
        !          1789: .Cx \&\ \&
        !          1790: .Fl h
        !          1791: .Cx \&\ \&
        !          1792: .Ar name
        !          1793: .Cx
        !          1794: The shell reads commands from
        !          1795: .Ic name .
        !          1796: .Ic Source
        !          1797: commands may be nested; if they are nested too deeply the shell may
        !          1798: run out of file descriptors.
        !          1799: An error in a
        !          1800: .Ic source
        !          1801: at any level terminates all nested
        !          1802: .Ic source
        !          1803: commands.
        !          1804: Normally input during
        !          1805: .Ic source
        !          1806: commands is not placed on the history list;
        !          1807: the \-h option causes the commands to be placed in the
        !          1808: history list without being executed.
        !          1809: .Pp
        !          1810: .Dp Ic stop
        !          1811: .Dp Cx Ic stop %
        !          1812: .Ar job ...
        !          1813: .Cx
        !          1814: Stops the current or specified job which is executing in the background.
        !          1815: .Pp
        !          1816: .Dp Ic suspend
        !          1817: Causes the shell to stop in its tracks, much as if it had been sent a stop
        !          1818: signal with
        !          1819: .Ic ^Z .
        !          1820: This is most often used to stop shells started by
        !          1821: .Xr su  1 .
        !          1822: .Pp
        !          1823: .Dp Cx Ic switch
        !          1824: .Cx \&\ \&
        !          1825: .Ar (string)
        !          1826: .Cx
        !          1827: .Dp Cx Ic case
        !          1828: .Cx \&\ \&
        !          1829: .Ar str1 :
        !          1830: .Cx
        !          1831: .Dp \&...
        !          1832: .Dp Ic breaksw
        !          1833: .Dp \&...
        !          1834: .Dp Ic default :
        !          1835: .Dp \&...
        !          1836: .Dp Ic breaksw
        !          1837: .Dp Ic endsw
        !          1838: Each case label is successively matched, against the specified
        !          1839: .Ar string
        !          1840: which is first command and filename expanded.
        !          1841: The file metacharacters `*', `?' and `[...]'
        !          1842: may be used in the case labels,
        !          1843: which are variable expanded.
        !          1844: If none of the labels match before a `default' label is found, then
        !          1845: the execution begins after the default label.
        !          1846: Each case label and the default label must appear at the beginning of a line.
        !          1847: The command
        !          1848: .Ic breaksw
        !          1849: causes execution to continue after the
        !          1850: .Ic endsw .
        !          1851: Otherwise control may fall through case labels and default labels as in C.
        !          1852: If no label matches and there is no default, execution continues after
        !          1853: the
        !          1854: .Ic endsw .
        !          1855: .Pp
        !          1856: .Dp Ic time
        !          1857: .Dp Cx Ic time
        !          1858: .Cx \&\ \&
        !          1859: .Ar command
        !          1860: .Cx
        !          1861: With no argument, a summary of time used by this shell and its children
        !          1862: is printed.
        !          1863: If arguments are given
        !          1864: the specified simple command is timed and a time summary
        !          1865: as described under the
        !          1866: .Ic time
        !          1867: variable is printed.  If necessary, an extra shell is created to print the time
        !          1868: statistic when the command completes.
        !          1869: .Pp
        !          1870: .Dp Ic umask
        !          1871: .Dp Cx Ic umask
        !          1872: .Cx \&\ \&
        !          1873: .Ar value
        !          1874: .Cx
        !          1875: The file creation mask is displayed (first form) or set to the specified
        !          1876: value (second form).  The mask is given in octal.  Common values for
        !          1877: the mask are 002 giving all access to the group and read and execute
        !          1878: access to others or 022 giving all access except no write access for
        !          1879: users in the group or others.
        !          1880: .Pp
        !          1881: .Dp Cx Ic unalias
        !          1882: .Cx \&\ \&
        !          1883: .Ar pattern
        !          1884: .Cx
        !          1885: All aliases whose names match the specified pattern are discarded.
        !          1886: Thus all aliases are removed by `unalias *'.
        !          1887: It is not an error for nothing to be
        !          1888: .Ic unaliased .
        !          1889: .Pp
        !          1890: .Dp Ic unhash
        !          1891: Use of the internal hash table to speed location of executed programs
        !          1892: is disabled.
        !          1893: .Pp
        !          1894: .Dp Ic unlimit
        !          1895: .Dp Cx Ic unlimit
        !          1896: .Cx \&\ \&
        !          1897: .Ar  resource
        !          1898: .Cx
        !          1899: .Dp Cx Ic unlimit 
        !          1900: .Cx \&\ \&
        !          1901: .Fl h
        !          1902: .Cx
        !          1903: .Dp Cx Ic unlimit 
        !          1904: .Cx \&\ \&
        !          1905: .Fl h
        !          1906: .Cx \&\ \&
        !          1907: .Ar resource
        !          1908: .Cx
        !          1909: Removes the limitation on
        !          1910: .Ar resource  .
        !          1911: If no
        !          1912: .Ar resource
        !          1913: is specified, then all
        !          1914: .Ar resource
        !          1915: limitations are removed.  If
        !          1916: .Fl h
        !          1917: is given, the corresponding hard limits are removed.  Only the
        !          1918: super-user may do this.
        !          1919: .Pp
        !          1920: .Dp Cx Ic unset
        !          1921: .Cx \&\ \&
        !          1922: .Ar pattern 
        !          1923: .Cx
        !          1924: All variables whose names match the specified pattern are removed.
        !          1925: Thus all variables are removed by `unset *'; this has noticeably
        !          1926: distasteful side-effects.
        !          1927: It is not an error for nothing to be
        !          1928: .Ic unset .
        !          1929: .Pp
        !          1930: .Dp Cx Ic unsetenv
        !          1931: .Cx \&\ \&
        !          1932: .Ar pattern
        !          1933: .Cx
        !          1934: Removes all variables whose name match the specified pattern from the
        !          1935: environment.  See also the
        !          1936: .Ic setenv
        !          1937: command above and
        !          1938: .Xr printenv  1  .
        !          1939: .Pp
        !          1940: .Dp Ic wait
        !          1941: All background jobs are waited for.
        !          1942: It the shell is interactive, then an interrupt can disrupt the wait,
        !          1943: at which time the shell prints names and job numbers of all jobs
        !          1944: known to be outstanding.
        !          1945: .Pp
        !          1946: .Dp Cx Ic while
        !          1947: .Cx \&\ \&
        !          1948: .Ar (expr)
        !          1949: .Cx
        !          1950: .Dp \&...
        !          1951: .Dp Ic end
        !          1952: While the specified expression evaluates non-zero, the commands between
        !          1953: the
        !          1954: .Ic while
        !          1955: and the matching end are evaluated.
        !          1956: .Ic Break
        !          1957: and
        !          1958: .Ic continue
        !          1959: may be used to terminate or continue the loop prematurely.
        !          1960: (The
        !          1961: .Ic while
        !          1962: and
        !          1963: .Ic end
        !          1964: must appear alone on their input lines.)
        !          1965: Prompting occurs here the first time through the loop as for the
        !          1966: .Ic foreach
        !          1967: statement if the input is a terminal.
        !          1968: .Pp
        !          1969: .Dp Cx Ic %
        !          1970: .Cx \&\ \&
        !          1971: .Ar job
        !          1972: .Cx
        !          1973: Brings the specified job into the foreground.
        !          1974: .Pp
        !          1975: .Dp Cx Ic %
        !          1976: .Cx \&\ \&
        !          1977: .Ar job
        !          1978: .Cx \&\ \&
        !          1979: .Ic &
        !          1980: .Cx
        !          1981: Continues the specified job in the background.
        !          1982: .Pp
        !          1983: .Dp Ic @
        !          1984: .Dp Cx Ic @
        !          1985: .Cx \&\ \&
        !          1986: .Ar name = expr
        !          1987: .Cx
        !          1988: .Dp Cx Ic @
        !          1989: .Cx \&\ \&
        !          1990: .Ar name
        !          1991: .Op index
        !          1992: .Cx\&\ = expr
        !          1993: .Cx
        !          1994: The first form prints the values of all the shell variables.
        !          1995: The second form sets the specified
        !          1996: .Ar name
        !          1997: to the value of
        !          1998: .Ar expr .
        !          1999: If the expression contains `<', `>', `&' or `' then at least
        !          2000: this part of the expression must be placed within `(' `)'.
        !          2001: The third form assigns the value of
        !          2002: .Ar expr
        !          2003: to the
        !          2004: .Cx Ar index
        !          2005: .Cx \'th
        !          2006: .Cx
        !          2007: argument of
        !          2008: .Ar name .
        !          2009: Both
        !          2010: .Ar name
        !          2011: and its
        !          2012: .Cx Ar index
        !          2013: .Cx \'th
        !          2014: .Cx
        !          2015: component must already exist.
        !          2016: .Cx \&\ \&
        !          2017: .Dp
        !          2018: .Pp
        !          2019: The operators `*=', `+=', etc are available as in C.
        !          2020: The space separating the name from the assignment operator is optional.
        !          2021: Spaces are, however, mandatory in separating components of
        !          2022: .Ar expr
        !          2023: which would otherwise be single words.
        !          2024: .Pp
        !          2025: Special postfix `++' and `\-\-' operators increment and decrement
        !          2026: .Ar name
        !          2027: respectively, i.e. `@  i++'.
        !          2028: .Ss Pre-defined and environment variables
        !          2029: The following variables have special meaning to the shell.
        !          2030: Of these,
        !          2031: .Ar argv ,
        !          2032: .Ar cwd,
        !          2033: .Ar home ,
        !          2034: .Ar path,
        !          2035: .Ar prompt ,
        !          2036: .Ar shell
        !          2037: and
        !          2038: .Ar status
        !          2039: are always set by the shell.
        !          2040: Except for
        !          2041: .Ar cwd
        !          2042: and
        !          2043: .Ar status
        !          2044: this setting occurs only at initialization;
        !          2045: these variables will not then be modified unless this is done
        !          2046: explicitly by the user.
        !          2047: .Pp
        !          2048: This shell copies the environment variable
        !          2049: .Ev USER
        !          2050: into the variable
        !          2051: .Ar user ,
        !          2052: .Ev TERM
        !          2053: into
        !          2054: .Ar term ,
        !          2055: and
        !          2056: .Ev HOME
        !          2057: into
        !          2058: .Ar home ,
        !          2059: and copies these back into the environment whenever the normal
        !          2060: shell variables are reset.
        !          2061: The environment variable
        !          2062: .Ev PATH
        !          2063: is likewise handled; it is not
        !          2064: necessary to worry about its setting other than in the file
        !          2065: .Ar \&.cshrc
        !          2066: as inferior
        !          2067: .Nm csh
        !          2068: processes will import the definition of
        !          2069: .Ar path
        !          2070: from the environment, and re-export it if you then change it.
        !          2071: .Tp Ic argv
        !          2072: Set to the arguments to the shell, it is from this variable that
        !          2073: positional parameters are substituted, i.e. `$1' is replaced by
        !          2074: `$argv[1]',
        !          2075: etc.
        !          2076: .Tp Ic cdpath
        !          2077: Gives a list of alternate directories searched to find subdirectories
        !          2078: in
        !          2079: .Ar chdir
        !          2080: commands.
        !          2081: .Tp Ic cwd
        !          2082: The full pathname of the current directory.
        !          2083: .Tp Ic echo
        !          2084: Set when the
        !          2085: .Fl x
        !          2086: command line option is given.
        !          2087: Causes each command and its arguments
        !          2088: to be echoed just before it is executed.
        !          2089: For non-builtin commands all expansions occur before echoing.
        !          2090: Builtin commands are echoed before command and filename substitution,
        !          2091: since these substitutions are then done selectively.
        !          2092: .Tp Ic filec
        !          2093: Enable file name completion.
        !          2094: .Tp Ic histchars
        !          2095: Can be given a string value to change the characters used in history
        !          2096: substitution.  The first character of its value is used as the
        !          2097: history substitution character, replacing the default character `!'.
        !          2098: The second character of its value replaces the character `\(ua' in
        !          2099: quick substitutions.
        !          2100: .Tp Ic history
        !          2101: Can be given a numeric value to control the size of the history list.
        !          2102: Any command which has been referenced in this many events will not be
        !          2103: discarded.
        !          2104: Too large values of
        !          2105: .Ar history
        !          2106: may run the shell out of memory.
        !          2107: The last executed command is always saved on the history list.
        !          2108: .Tp Ic home
        !          2109: The home directory of the invoker, initialized from the environment.
        !          2110: The filename expansion of
        !          2111: .Cx `
        !          2112: .Pa ~
        !          2113: .Cx \'
        !          2114: .Cx
        !          2115: refers to this variable.
        !          2116: .Tp Ic ignoreeof
        !          2117: If set the shell ignores
        !          2118: end-of-file from input devices which are terminals.
        !          2119: This prevents shells from accidentally being killed by control-D's.
        !          2120: .Tp Ic mail
        !          2121: The files where the shell checks for mail.
        !          2122: This is done after each command completion which will result in a prompt,
        !          2123: if a specified interval has elapsed.
        !          2124: The shell says `You have new mail.'
        !          2125: if the file exists with an access time not greater than its modify time.
        !          2126: .Pp
        !          2127: If the first word of the value of
        !          2128: .Ar mail
        !          2129: is numeric it specifies a different mail checking interval, in seconds,
        !          2130: than the default, which is 10 minutes.
        !          2131: .Pp
        !          2132: If multiple mail files are specified, then the shell says
        !          2133: `New mail in
        !          2134: .Cx Ar name
        !          2135: .Cx \'
        !          2136: .Cx
        !          2137: when there is mail in the file
        !          2138: .Ar name .
        !          2139: .Tp Ic noclobber
        !          2140: As described in the section on
        !          2141: .Ar Input/output ,
        !          2142: restrictions are placed on output redirection to insure that
        !          2143: files are not accidentally destroyed, and that `>>' redirections
        !          2144: refer to existing files.
        !          2145: .Tp Ic noglob
        !          2146: If set, filename expansion is inhibited.
        !          2147: This is most useful in shell scripts which are not dealing with filenames,
        !          2148: or after a list of filenames has been obtained and further expansions
        !          2149: are not desirable.
        !          2150: .Tp Ic nonomatch
        !          2151: If set, it is not an error for a filename expansion to not match any
        !          2152: existing files; rather the primitive pattern is returned.
        !          2153: It is still an error for the primitive pattern to be malformed, i.e.
        !          2154: `echo ['
        !          2155: still gives an error.
        !          2156: .Tp Ic notify
        !          2157: If set, the shell notifies asynchronously of job completions.  The
        !          2158: default is to rather present job completions just before printing
        !          2159: a prompt.
        !          2160: .Tp Ic path
        !          2161: Each word of the path variable specifies a directory in which
        !          2162: commands are to be sought for execution.
        !          2163: A null word specifies the current directory.
        !          2164: If there is no
        !          2165: .Ar path
        !          2166: variable then only full path names will execute.
        !          2167: The usual search path is `.', `/bin' and `/usr/bin', but this
        !          2168: may vary from system to system.
        !          2169: For the super-user the default search path is `/etc', `/bin' and `/usr/bin'.
        !          2170: A shell which is given neither the
        !          2171: .Fl c
        !          2172: nor the
        !          2173: .Fl t
        !          2174: option will normally hash the contents of the directories in the
        !          2175: .Ar path
        !          2176: variable after reading
        !          2177: .Ar \&.cshrc ,
        !          2178: and each time the
        !          2179: .Ar path
        !          2180: variable is reset.  If new commands are added to these directories
        !          2181: while the shell is active, it may be necessary to give the
        !          2182: .Ar rehash
        !          2183: or the commands may not be found.
        !          2184: .Tp Ic prompt
        !          2185: The string which is printed before each command is read from
        !          2186: an interactive terminal input.
        !          2187: If a `!' appears in the string it will be replaced by the current event number
        !          2188: unless a preceding `\e' is given.
        !          2189: Default is `% ', or `# ' for the super-user.
        !          2190: .Tp Ic savehist
        !          2191: Is given a numeric value to control the number of entries of the
        !          2192: history list that are saved in ~/.history when the user logs out.
        !          2193: Any command which has been referenced in this many events will be saved.
        !          2194: During start up the shell sources ~/.history into the history list
        !          2195: enabling history to be saved across logins.
        !          2196: Too large values of
        !          2197: .Ar savehist
        !          2198: will slow down the shell during start up.
        !          2199: .Tp Ic shell
        !          2200: The file in which the shell resides.
        !          2201: This is used in forking shells to interpret files which have execute
        !          2202: bits set, but which are not executable by the system.
        !          2203: (See the description of
        !          2204: .Em Non-builtin Command Execution
        !          2205: below.)
        !          2206: Initialized to the (system-dependent) home of the shell.
        !          2207: .Tp Ic status
        !          2208: The status returned by the last command.
        !          2209: If it terminated abnormally, then 0200 is added to the status.
        !          2210: Builtin commands which fail return exit status `1',
        !          2211: all other builtin commands set status `0'.
        !          2212: .Tp Ic time
        !          2213: Controls automatic timing of commands.
        !          2214: If set, then any command which takes more than this many cpu seconds
        !          2215: will cause a line giving user, system, and real times and a utilization
        !          2216: percentage which is the ratio of user plus system times to real time
        !          2217: to be printed when it terminates.
        !          2218: .Tp Ic verbose
        !          2219: Set by the
        !          2220: .Fl v
        !          2221: command line option, causes the words of each command to be printed
        !          2222: after history substitution.
        !          2223: .Tp
        !          2224: .Ss Non-builtin command execution
        !          2225: When a command to be executed is found to not be a builtin command
        !          2226: the shell attempts to execute the command via
        !          2227: .Xr execve  2  .
        !          2228: Each word in the variable
        !          2229: .Ar path
        !          2230: names a directory from which the shell will attempt to execute the command.
        !          2231: If it is given neither a
        !          2232: .Fl c
        !          2233: nor a
        !          2234: .Fl t
        !          2235: option, the shell will hash the names in these directories into an internal
        !          2236: table so that it will only try an
        !          2237: .Ic exec
        !          2238: in a directory if there is a possibility that the command resides there.
        !          2239: This greatly speeds command location when a large number of directories
        !          2240: are present in the search path.
        !          2241: If this mechanism has been turned off (via
        !          2242: .Ic unhash ) ,
        !          2243: or if the shell was given a
        !          2244: .Fl c
        !          2245: or
        !          2246: .Fl t
        !          2247: argument, and in any case for each directory component of
        !          2248: .Ar path
        !          2249: which does not begin with a `/',
        !          2250: the shell concatenates with the given command name to form a path name
        !          2251: of a file which it then attempts to execute.
        !          2252: .Pp
        !          2253: Parenthesized commands are always executed in a subshell.
        !          2254: Thus
        !          2255: .Pp
        !          2256: .Dl (cd ; pwd) ; pwd
        !          2257: .Pp
        !          2258: prints the
        !          2259: .Ar home
        !          2260: directory; leaving you where you were (printing this after the home directory),
        !          2261: while
        !          2262: .Pp
        !          2263: .Dl cd ; pwd
        !          2264: .Pp
        !          2265: leaves you in the
        !          2266: .Ar home
        !          2267: directory.
        !          2268: Parenthesized commands are most often used to prevent
        !          2269: .Ic chdir
        !          2270: from affecting the current shell.
        !          2271: .Pp
        !          2272: If the file has execute permissions but is not an
        !          2273: executable binary to the system, then it is assumed to be a
        !          2274: file containing shell commands and a new shell is spawned to read it.
        !          2275: .Pp
        !          2276: If there is an
        !          2277: .Ic alias
        !          2278: for
        !          2279: .Ic shell
        !          2280: then the words of the alias will be prepended to the argument list to form
        !          2281: the shell command.
        !          2282: The first word of the
        !          2283: .Ic alias
        !          2284: should be the full path name of the shell
        !          2285: (e.g. `$shell').
        !          2286: Note that this is a special, late occurring, case of
        !          2287: .Ic alias
        !          2288: substitution,
        !          2289: and only allows words to be prepended to the argument list without modification.
        !          2290: .Ss Signal handling
        !          2291: The shell normally ignores
        !          2292: .Ar quit
        !          2293: signals.
        !          2294: Jobs running detached (either by
        !          2295: .Ic \&&
        !          2296: or the
        !          2297: .Ic bg
        !          2298: or
        !          2299: .Ic %... &
        !          2300: commands) are immune to signals generated from the keyboard, including
        !          2301: hangups.
        !          2302: Other signals have the values which the shell inherited from its parent.
        !          2303: The shell's handling of interrupts and terminate signals
        !          2304: in shell scripts can be controlled by
        !          2305: .Ic onintr .
        !          2306: Login shells catch the
        !          2307: .Ar terminate
        !          2308: signal; otherwise this signal is passed on to children from the state in the
        !          2309: shell's parent.
        !          2310: In no case are interrupts allowed when a login shell is reading the file
        !          2311: .Pa \&.logout .
        !          2312: .Sh AUTHOR
        !          2313: William Joy.
        !          2314: Job control and directory stack features first implemented by J.E. Kulp of
        !          2315: I.I.A.S.A, Laxenburg, Austria,
        !          2316: with different syntax than that used now.  File name completion
        !          2317: code written by Ken Greer, HP Labs.
        !          2318: .Sh FILES
        !          2319: .Dw /etc/passwd
        !          2320: .Di L
        !          2321: .Dp Pa ~/.cshrc
        !          2322: Read at beginning of execution by each shell.
        !          2323: .Dp Pa ~/.login
        !          2324: Read by login shell, after `.cshrc' at login.
        !          2325: .Dp Pa ~/.logout
        !          2326: Read by login shell, at logout.
        !          2327: .Dp Pa /bin/sh
        !          2328: Standard shell, for shell scripts not starting with a `#'.
        !          2329: .Dp Pa /tmp/sh*
        !          2330: Temporary file for `<<'.
        !          2331: .Dp Pa /etc/passwd
        !          2332: Source of home directories for `~name'.
        !          2333: .Dp
        !          2334: .Sh LIMITATIONS
        !          2335: Word lengths \-
        !          2336: Words can be no longer than 1024 characters.
        !          2337: The system limits argument lists to 10240 characters.
        !          2338: The number of arguments to a command which involves filename expansion
        !          2339: is limited to 1/6'th the number of characters allowed in an argument list.
        !          2340: Command substitutions may substitute no more characters than are
        !          2341: allowed in an argument list.
        !          2342: To detect looping, the shell restricts the number of
        !          2343: .Ic alias
        !          2344: substitutions on a single line to 20.
        !          2345: .Sh SEE ALSO
        !          2346: .Xr sh 1 ,
        !          2347: .Xr access 2 ,
        !          2348: .Xr execve 2 ,
        !          2349: .Xr fork 2 ,
        !          2350: .Xr killpg 2 ,
        !          2351: .Xr pipe 2 ,
        !          2352: .Xr sigvec 2 ,
        !          2353: .Xr umask 2 ,
        !          2354: .Xr setrlimit 2 ,
        !          2355: .Xr wait 2 ,
        !          2356: .Xr tty 4 ,
        !          2357: .Xr a.out 5 ,
        !          2358: .Xr environ 7 ,
        !          2359: .br
        !          2360: .Em An introduction to the C shell
        !          2361: .Sh HISTORY
        !          2362: .Nm Csh
        !          2363: Appeared in  3 BSD.  It
        !          2364: was a first implementation of a command language interpreter
        !          2365: incorporating a history mechanism (see
        !          2366: .Nm History Substitutions ) ,
        !          2367: job control facilities (see
        !          2368: .Nm Jobs ) ,
        !          2369: interactive file name
        !          2370: and user name completion (see
        !          2371: .Nm File Name Completion ) ,
        !          2372: and a C-like syntax.
        !          2373: There are now many shells which also have these mechanisms, plus
        !          2374: a few more (and maybe some bugs too), which are available thru
        !          2375: the internet, or as contributed software such as the
        !          2376: .Xr ksh korn\ shell .
        !          2377: .Sh BUGS
        !          2378: When a command is restarted from a stop,
        !          2379: the shell prints the directory it started in if this is different
        !          2380: from the current directory; this can be misleading (i.e. wrong)
        !          2381: as the job may have changed directories internally.
        !          2382: .Pp
        !          2383: Shell builtin functions are not stoppable/restartable.
        !          2384: Command sequences of the form `a ; b ; c' are also not handled gracefully
        !          2385: when stopping is attempted.  If you suspend `b', the shell will then
        !          2386: immediately execute `c'.  This is especially noticeable if this
        !          2387: expansion results from an
        !          2388: .Ar alias .
        !          2389: It suffices to place the sequence of commands in ()'s to force it to
        !          2390: a subshell, i.e. `( a ; b ; c )'.
        !          2391: .Pp
        !          2392: Control over tty output after processes are started is primitive;
        !          2393: perhaps this will inspire someone to work on a good virtual
        !          2394: terminal interface.  In a virtual terminal interface much more
        !          2395: interesting things could be done with output control.
        !          2396: .Pp
        !          2397: Alias substitution is most often used to clumsily simulate shell procedures;
        !          2398: shell procedures should be provided rather than aliases.
        !          2399: .Pp
        !          2400: Commands within loops, prompted for by `?', are not placed in the
        !          2401: .Ic history
        !          2402: list.
        !          2403: Control structure should be parsed rather than being recognized as built-in
        !          2404: commands.  This would allow control commands to be placed anywhere,
        !          2405: to be combined with `\&|', and to be used with `&' and `;' metasyntax.
        !          2406: .Pp
        !          2407: It should be possible to use the `:' modifiers on the output of command
        !          2408: substitutions.
        !          2409: All and more than one `:' modifier should be allowed on `$' substitutions.
        !          2410: .Pp
        !          2411: The way the
        !          2412: .Ic filec
        !          2413: facility is implemented is ugly and expensive.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.