diff options
Diffstat (limited to 'share/doc/usd')
-rw-r--r-- | share/doc/usd/04.csh/Makefile | 1 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.1 | 1012 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.2 | 1304 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.3 | 649 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.4 | 176 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.a | 93 | ||||
-rw-r--r-- | share/doc/usd/04.csh/csh.g | 1719 | ||||
-rw-r--r-- | share/doc/usd/04.csh/tabs | 32 | ||||
-rw-r--r-- | share/doc/usd/05.dc/Makefile | 1 | ||||
-rw-r--r-- | share/doc/usd/05.dc/dc | 753 | ||||
-rw-r--r-- | share/doc/usd/06.bc/Makefile | 1 | ||||
-rw-r--r-- | share/doc/usd/06.bc/bc | 1241 | ||||
-rw-r--r-- | share/doc/usd/07.mail/Makefile | 1 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail0.nr | 72 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail1.nr | 92 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail2.nr | 617 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail3.nr | 133 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail4.nr | 437 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail5.nr | 1042 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail6.nr | 125 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail7.nr | 107 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail8.nr | 75 | ||||
-rw-r--r-- | share/doc/usd/07.mail/mail9.nr | 203 | ||||
-rw-r--r-- | share/doc/usd/07.mail/maila.nr | 33 |
24 files changed, 9915 insertions, 4 deletions
diff --git a/share/doc/usd/04.csh/Makefile b/share/doc/usd/04.csh/Makefile index d22a7b9..5606b8f 100644 --- a/share/doc/usd/04.csh/Makefile +++ b/share/doc/usd/04.csh/Makefile @@ -5,6 +5,5 @@ VOLUME= usd/04.csh SRCS= tabs csh.1 csh.2 csh.3 csh.4 csh.a csh.g MACROS= -ms USE_SOELIM= -SRCDIR= ${.CURDIR}/../../../../bin/csh/USD.doc .include <bsd.doc.mk> diff --git a/share/doc/usd/04.csh/csh.1 b/share/doc/usd/04.csh/csh.1 new file mode 100644 index 0000000..915cb23 --- /dev/null +++ b/share/doc/usd/04.csh/csh.1 @@ -0,0 +1,1012 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.1 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.EH 'USD:4-%''An Introduction to the C shell' +.OH 'An Introduction to the C shell''USD:4-%' +.\".RP +.TL +An Introduction to the C shell +.AU +William Joy +(revised for 4.3BSD by Mark Seiden) +.AI +Computer Science Division +.br +Department of Electrical Engineering and Computer Science +.br +University of California, Berkeley +.br +Berkeley, California 94720 +.AB +.I Csh +is a new command language interpreter for +.UX +systems. +It incorporates good features of other shells and a +.I history +mechanism similar to the +.I redo +of \s-2INTERLISP\s0. +While incorporating many features of other shells which make +writing shell programs (shell scripts) easier, +most of the features unique to +.I csh +are designed more for the interactive \s-2UNIX\s0 user. +.PP +\s-2UNIX\s0 +users who have read a general introduction to the system +will find a valuable basic explanation of the shell here. +Simple terminal interaction with +.I csh +is possible after reading just the first section of this document. +The second section describes the shell's capabilities which you can +explore after you have begun to become acquainted with the shell. +Later sections introduce features which are useful, but not necessary +for all users of the shell. +.PP +Additional information includes an appendix listing special characters of the shell +and a glossary of terms and commands introduced in this manual. +.AE +.SH +.if n .ND +Introduction +.PP +A +.I shell +is a command language interpreter. +.I Csh +is the name of one particular command interpreter on +\s-2UNIX\s0. +The primary purpose of +.I csh +is to translate command lines typed at a terminal into +system actions, such as invocation of other programs. +.I Csh +is a user program just like any you might write. +Hopefully, +.I csh +will be a very useful program for you +in interacting with the \s-2UNIX\s0 system. +.PP +In addition to this document, you will want to refer to a copy +of the \s-2UNIX\s0 User Reference Manual. +The +.I csh +documentation in section 1 of the manual provides a full description of all +features of the shell and is the definitive reference for questions +about the shell. +.PP +Many words in this document are shown in +.I italics. +These are important words; +names of commands, and words which have special meaning in discussing +the shell and \s-2UNIX\s0. +Many of the words are defined in a glossary at the end of this document. +If you don't know what is meant by a word, you should look +for it in the glossary. +.SH +Acknowledgements +.PP +Numerous people have provided good input about previous versions +of +.I csh +and aided in its debugging and in the debugging of its documentation. +I would especially like to thank Michael Ubell +who made the crucial observation that history commands could be +done well over the word structure of input text, and implemented +a prototype history mechanism in an older version of the shell. +Eric Allman has also provided a large number of useful comments on the +shell, helping to unify those concepts which are present and to identify +and eliminate useless and marginally useful features. +Mike O'Brien suggested the pathname hashing +mechanism which speeds command execution. +Jim Kulp added the job control and directory stack primitives and +added their documentation to this introduction. +.br +.bp +.NH +Terminal usage of the shell +.NH 2 +The basic notion of commands +.PP +A +.I shell +in +\s-2UNIX\s0 +acts mostly as a medium through which other +.I programs +are invoked. +While it has a set of +.I builtin +functions which it performs directly, +most commands cause execution of programs that are, in fact, +external to the shell. +The shell is thus distinguished from the command interpreters of other +systems both by the fact that it is just a user program, and by the fact +that it is used almost exclusively as a mechanism for invoking other programs. +.PP +.I Commands +in the \s-2UNIX\s0 system consist of a list of strings or +.I words +interpreted as a +.I "command name" +followed by +.I arguments. +Thus the command +.DS +mail bill +.DE +consists of two words. +The first word +.I mail +names the command to be executed, in this case the +mail program which sends messages to other users. +The shell uses the name of the command in attempting to execute it for you. +It will look in a number of +.I directories +for a file with the name +.I mail +which is expected to contain the mail program. +.PP +The rest of the words of the command are given as +.I arguments +to the command itself when it is executed. +In this case we specified also the argument +.I bill +which is interpreted by the +.I mail +program to be the name of a user to whom mail is to be sent. +In normal terminal usage we might use the +.I mail +command as follows. +.DS +% mail bill +I have a question about the csh documentation. +My document seems to be missing page 5. +Does a page five exist? + Bill +EOT +% +.DE +.PP +Here we typed a message to send to +.I bill +and ended this message with a ^D which sent an end-of-file to +the mail program. +(Here and throughout this document, the notation ``^\fIx\fR'' +is to be read ``control-\fIx\fR'' and represents the striking of the \fIx\fR +key while the control key is held down.) +The mail program +then echoed the characters `EOT' and transmitted our message. +The characters `% ' were printed before and after the mail command +by the shell to indicate that input was needed. +.PP +After typing the `% ' prompt the shell was reading command input from +our terminal. +We typed a complete command `mail bill'. +The shell then executed the +.I mail +program with argument +.I bill +and went dormant waiting for it to complete. +The mail program then read input from our terminal until we signalled +an end-of-file via typing a ^D after which the shell noticed +that mail had completed +and signaled us that it was ready to read from the terminal again by +printing another `% ' prompt. +.PP +This is the essential pattern of all interaction with \s-2UNIX\s0 +through the shell. +A complete command is typed at the terminal, the shell executes +the command and when this execution completes, it prompts for a new command. +If you run the editor for an hour, the shell will patiently wait for +you to finish editing and obediently prompt you again whenever you finish +editing. +.PP +An example of a useful command you can execute now is the +.I tset +command, which sets the default +.I erase +and +.I kill +characters on your terminal \- the erase character erases the last +character you typed and the kill character erases the entire line you +have entered so far. +By default, the erase character is the delete key (equivalent to `^?') +and the kill character is `^U'. Some people prefer to make the erase character +the backspace key (equivalent to `^H'). +You can make this be true by typing +.DS +tset \-e +.DE +which tells the program +.I tset +to set the erase character to tset's default setting for this character +(a backspace). +.NH 2 +Flag arguments +.PP +A useful notion in \s-2UNIX\s0 is that of a +.I flag +argument. +While many arguments to commands specify file names or user names, +some arguments rather specify an optional capability of the command +which you wish to invoke. +By convention, such arguments begin with the character `\-' (hyphen). +Thus the command +.DS +ls +.DE +will produce a list of the files in the current +.I "working directory" . +The option +.I \-s +is the size option, and +.DS +ls \-s +.DE +causes +.I ls +to also give, for each file the size of the file in blocks of 512 +characters. +The manual section for each command in the \s-2UNIX\s0 reference manual +gives the available options for each command. +The +.I ls +command has a large number of useful and interesting options. +Most other commands have either no options or only one or two options. +It is hard to remember options of commands which are not used very +frequently, so most \s-2UNIX\s0 utilities perform only one or two functions +rather than having a large number of hard to remember options. +.NH 2 +Output to files +.PP +Commands that normally read input or write output on the terminal +can also be executed with this input and/or output done to +a file. +.PP +Thus suppose we wish to save the current date in a file called `now'. +The command +.DS +date +.DE +will print the current date on our terminal. +This is because our terminal is the default +.I "standard output" +for the date command and the date command prints the date on its +standard output. +The shell lets us +.I redirect +the +.I "standard output" +of a command through a +notation using the +.I metacharacter +`>' and the name of the file where output is to be placed. +Thus the command +.DS +date > now +.DE +runs the +.I date +command such that its standard output is +the file `now' rather than the terminal. +Thus this command places the current date and time into the file `now'. +It is important to know that the +.I date +command was unaware that its output was going to a file rather than +to the terminal. +The shell performed this +.I redirection +before the command began executing. +.PP +One other thing to note here is that the file `now' +need not have existed before the +.I date +command was executed; the shell would have created the file if it did +not exist. +And if the file did exist? +If it had existed previously these previous contents would have been discarded! +A shell option +.I noclobber +exists to prevent this from happening accidentally; +it is discussed in section 2.2. +.PP +The system normally keeps files which you create with `>' and all other files. +Thus the default is for files to be permanent. If you wish to create a file +which will be removed automatically, you can begin its name with a `#' +character, this `scratch' character denotes the fact that the file will +be a scratch file.* +.FS +*Note that if your erase character is a `#', you will have to precede the +`#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0) +standard erase character means that it seldom appears in a file name, and +allows this convention to be used for scratch files. If you are using a +\s-2CRT\s0, your erase character should be a ^H, as we demonstrated +in section 1.1 how this could be set up. +.FE +The system will remove such files after a couple of days, +or sooner if file space becomes very tight. +Thus, in running the +.I date +command above, we don't really want to save the output forever, so we +would more likely do +.DS +date > #now +.DE +.NH 2 +Metacharacters in the shell +.PP +The shell has a large number of +special characters (like `>') +which indicate special functions. +We say that these notations have +.I syntactic +and +.I semantic +meaning to the shell. +In general, most characters which are neither letters nor digits +have special meaning to the shell. +We shall shortly learn a means of +.I quotation +which allows us to use +.I metacharacters +without the shell treating them in any special way. +.PP +Metacharacters normally have effect only when the shell is reading +our input. +We need not worry about placing shell metacharacters in a letter +we are sending via +.I mail, +or when we are typing in text or data to some other program. +Note that the shell is only reading input when it has prompted with +`% ' (although we can type our input even before it prompts). +.NH 2 +Input from files; pipelines +.PP +We learned above how to +.I redirect +the +.I "standard output" +of a command +to a file. +It is also possible to redirect the +.I "standard input" +of a command from a file. +This is not often necessary since most commands will read from +a file whose name is given as an argument. +We can give the command +.DS +sort < data +.DE +to run the +.I sort +command with standard input, where the command normally +reads its input, from the file +`data'. +We would more likely say +.DS +sort data +.DE +letting the +.I sort +command open the file +`data' +for input itself since this is less to type. +.PP +We should note that if we just typed +.DS +sort +.DE +then the sort program would sort lines from its +.I "standard input." +Since we did not +.I redirect +the standard input, it would sort lines as we typed them on the terminal +until we typed a ^D to indicate an end-of-file. +.PP +A most useful capability is the ability to combine the standard output +of one command with the standard input of another, i.e. to run the +commands in a sequence known as a +.I pipeline. +For instance the command +.DS +ls \-s +.DE +normally produces a list of the files in our directory with the size +of each in blocks of 512 characters. +If we are interested in learning which of our files is largest we +may wish to have this sorted by size rather than by name, which is +the default way in which +.I ls +sorts. +We could look at the many options of +.I ls +to see if there was an option to do this but would eventually discover +that there is not. +Instead we can use a couple of simple options of the +.I sort +command, combining it with +.I ls +to get what we want. +.PP +The +.I \-n +option of sort specifies a numeric sort rather than an alphabetic sort. +Thus +.DS +ls \-s | sort \-n +.DE +specifies that the output of the +.I ls +command run with the option +.I \-s +is to be +.I piped +to the command +.I sort +run with the numeric sort option. +This would give us a sorted list of our files by size, but with the +smallest first. +We could then use the +.I \-r +reverse sort option and the +.I head +command in combination with the previous command doing +.DS +ls \-s | sort \-n \-r | head \-5 +.DE +Here we have taken a list of our files sorted alphabetically, +each with the size in blocks. +We have run this to the standard input of the +.I sort +command asking it to sort numerically in reverse order (largest first). +This output has then been run into the command +.I head +which gives us the first few lines. +In this case we have asked +.I head +for the first 5 lines. +Thus this command gives us the names and sizes of our 5 largest files. +.PP +The notation introduced above is called the +.I pipe +mechanism. +Commands separated by `\||\|' characters are connected together by the +shell and the standard output of each is run into the standard input of the +next. +The leftmost command in a pipeline will normally take its standard +input from the terminal and the rightmost will place its standard +output on the terminal. +Other examples of pipelines will be given later when we discuss the +history mechanism; +one important use of pipes which is illustrated there is in the +routing of information to the line printer. +.NH 2 +Filenames +.PP +Many commands to be executed will need the names of files as arguments. +\s-2UNIX\s0 +.I pathnames +consist of a number of +.I components +separated by `/'. +Each component except the last names a directory in which the next +component resides, in effect specifying the +.I path +of directories to follow to reach the file. +Thus the pathname +.DS +/etc/motd +.DE +specifies a file in the directory +`etc' +which is a subdirectory of the +.I root +directory `/'. +Within this directory the file named is `motd' which stands +for `message of the day'. +A +.I pathname +that begins with a slash is said to be an +.I absolute +pathname since it is specified from the absolute top of the entire +directory hierarchy of the system (the +.I root ). +.I Pathnames +which do not begin with `/' are interpreted as starting in the current +.I "working directory" , +which is, by default, your +.I home +directory and can be changed dynamically by the +.I cd +change directory command. +Such pathnames are said to be +.I relative +to the working directory since they are found by starting +in the working directory and descending to lower levels of directories +for each +.I component +of the pathname. If the pathname contains no slashes at all then the +file is contained in the working directory itself and the pathname is merely +the name of the file in this directory. +Absolute pathnames have no relation +to the working directory. +.PP +Most filenames consist of a number of alphanumeric characters and +`.'s (periods). +In fact, all printing characters except `/' (slash) may appear in filenames. +It is inconvenient to have most non-alphabetic characters in filenames +because many of these have special meaning to the shell. +The character `.' (period) is not a shell-metacharacter and is often used +to separate the +.I extension +of a file name from the base of the name. +Thus +.DS +prog.c prog.o prog.errs prog.output +.DE +are four related files. +They share a +.I base +portion of a name +(a base portion being that part of the name that is left when a trailing +`.' and following characters which are not `.' are stripped off). +The file +`prog.c' +might be the source for a C program, +the file `prog.o' the corresponding object file, +the file +`prog.errs' the errors resulting from a compilation of the program +and the file +`prog.output' the output of a run of the program. +.PP +If we wished to refer to all four of these files in a command, we could +use the notation +.DS +prog.* +.DE +This expression is expanded by the shell, before the command to which it is +an argument is executed, into a list of names which begin with `prog.'. +The character `*' here matches any sequence (including the empty sequence) +of characters in a file name. +The names which match are alphabetically sorted and placed in the +.I "argument list" +of the command. +Thus the command +.DS +echo prog.* +.DE +will echo the names +.DS +prog.c prog.errs prog.o prog.output +.DE +Note that the names are in sorted order here, and a different +order than we listed them above. +The +.I echo +command receives four words as arguments, even though we only typed +one word as an argument directly. +The four words were generated by +.I "filename expansion" +of the one input word. +.PP +Other notations for +.I "filename expansion" +are also available. +The character `?' matches any single character in a filename. +Thus +.DS +echo ? \|?? \|??? +.DE +will echo a line of filenames; first those with one character names, +then those with two character names, and finally those with three +character names. +The names of each length will be independently sorted. +.PP +Another mechanism consists of a sequence of characters between `[' and `]'. +This metasequence matches any single character from the enclosed set. +Thus +.DS +prog.[co] +.DE +will match +.DS +prog.c prog.o +.DE +in the example above. +We can also place two characters around a `\-' in this notation to denote +a range. +Thus +.DS +chap.[1\-5] +.DE +might match files +.DS +chap.1 chap.2 chap.3 chap.4 chap.5 +.DE +if they existed. +This is shorthand for +.DS +chap.[12345] +.DE +and otherwise equivalent. +.PP +An important point to note is that if a list of argument words to +a command (an +.I "argument list)" +contains filename expansion syntax, and if this filename expansion syntax +fails to match any existing file names, then the shell considers this +to be an error and prints a diagnostic +.DS +No match. +.DE +and does not execute the command. +.PP +Another very important point is that files with the character `.' at the +beginning are treated specially. +Neither `*' or `?' or the `[' `]' mechanism will match it. +This prevents accidental matching of the filenames `.' and `..' +in the working directory which have special meaning to the system, +as well as other files such as +.I \&.cshrc +which are not normally +visible. +We will discuss the special role of the file +.I \&.cshrc +later. +.PP +Another filename expansion mechanism gives access to the pathname of +the +.I home +directory of other users. +This notation consists of the character `~' (tilde) followed by another user's +login name. +For instance the word `~bill' would map to the pathname `/usr/bill' +if the home directory for `bill' was `/usr/bill'. +Since, on large systems, users may have login directories scattered over +many different disk volumes with different prefix directory names, +this notation provides a convenient way of accessing the files +of other users. +.PP +A special case of this notation consists of a `~' alone, e.g. `~/mbox'. +This notation is expanded by the shell into the file `mbox' in your +.I home +directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB +Computer Science Department VAX machine, where this document was prepared. +This can be very useful if you have used +.I cd +to change to another directory and have found a file you wish to +copy using +.I cp. +If I give the command +.DS +cp thatfile ~ +.DE +the shell will expand this command to +.DS +cp thatfile /usr/bill +.DE +since my home directory is /usr/bill. +.PP +There also exists a mechanism using the characters `{' and `}' for +abbreviating a set of words which have common parts but cannot +be abbreviated by the above mechanisms because they are not files, +are the names of files which do not yet exist, +are not thus conveniently described. +This mechanism will be described much later, +in section 4.2, +as it is used less frequently. +.NH 2 +Quotation +.PP +We have already seen a number of metacharacters used by the shell. +These metacharacters pose a problem in that we cannot use them directly +as parts of words. +Thus the command +.DS +echo * +.DE +will not echo the character `*'. +It will either echo a sorted list of filenames in the +current +.I "working directory," +or print the message `No match' if there are +no files in the working directory. +.PP +The recommended mechanism for placing characters which are neither numbers, +digits, `/', `.' or `\-' in an argument word to a command is to enclose +it with single quotation characters `\'', i.e. +.DS +echo \'*\' +.DE +There is one special character `!' which is used by the +.I history +mechanism of the shell and which cannot be +.I escaped +by placing it within `\'' characters. +It and the character `\'' itself can be preceded by a single `\e' +to prevent their special meaning. +Thus +.DS +echo \e\'\e! +.DE +prints +.DS +\'! +.DE +These two mechanisms suffice to place any printing character into a word +which is an argument to a shell command. They can be combined, as in +.DS +echo \e\'\'*\' +.DE +which prints +.DS +\'* +.DE +since the first `\e' escaped the first `\'' and the `*' was enclosed +between `\'' characters. +.NH 2 +Terminating commands +.PP +When you are executing a command and the shell is +waiting for it to complete there are several ways +to force it to stop. +For instance if you type the command +.DS +cat /etc/passwd +.DE +the system will print a copy of a list of all users of the system +on your terminal. +This is likely to continue for several minutes unless you stop it. +You can send an +\s-2INTERRUPT\s0 +.I signal +to the +.I cat +command by typing ^C on your terminal.* +.FS +*On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key +has the same effect. "stty all" will tell you the INTR key value. +.FE +Since +.I cat +does not take any precautions to avoid or otherwise handle this signal +the +\s-2INTERRUPT\s0 +will cause it to terminate. +The shell notices that +.I cat +has terminated and prompts you again with `% '. +If you hit \s-2INTERRUPT\s0 again, the shell will just +repeat its prompt since it handles \s-2INTERRUPT\s0 signals +and chooses to continue to execute commands rather than terminating +like +.I cat +did, which would have the effect of logging you out. +.PP +Another way in which many programs terminate is when they get an end-of-file +from their standard input. +Thus the +.I mail +program in the first example above was terminated when we typed a ^D +which generates an end-of-file from the standard input. +The shell also terminates when it gets an end-of-file printing `logout'; +\s-2UNIX\s0 then logs you off the system. +Since this means that typing too many ^D's can accidentally log us off, +the shell has a mechanism for preventing this. +This +.I ignoreeof +option will be discussed in section 2.2. +.PP +If a command has its standard input redirected from a file, then it will +normally terminate when it reaches the end of this file. +Thus if we execute +.DS +mail bill < prepared.text +.DE +the mail command will terminate without our typing a ^D. +This is because it read to the end-of-file of our file +`prepared.text' in which we placed a message for `bill' with an editor program. +We could also have done +.DS +cat prepared.text \||\| mail bill +.DE +since the +.I cat +command would then have written the text through the pipe to the +standard input of the mail command. +When the +.I cat +command completed it would have terminated, +closing down the pipeline +and the +.I mail +command would have received an end-of-file from it and terminated. +Using a pipe here is more complicated than redirecting input +so we would more likely use the first form. +These commands could also have been stopped by sending an \s-2INTERRUPT\s0. +.PP +Another possibility for stopping a command is to suspend its execution +temporarily, with the possibility of continuing execution later. This is +done by sending a \s-2STOP\s0 signal via typing a ^Z. +This signal causes all commands running on the terminal +(usually one but more if a pipeline is executing) to become suspended. +The shell notices that the command(s) have been suspended, types +`Stopped' and then prompts for a new command. +The previously executing command has been suspended, but otherwise +unaffected by the \s-2STOP\s0 signal. Any other commands can be executed +while the original command remains suspended. The suspended command can +be continued using the +.I fg +command with no arguments. The shell will then retype the command +to remind you which command is being continued, and cause the command +to resume execution. Unless any input files in use by the suspended +command have been changed in the meantime, the suspension has no effect +whatsoever on the execution of the command. This feature can be very useful +during editing, when you need to look at another file before continuing. +An +example of command suspension follows. +.DS +% mail harold +Someone just copied a big file into my directory and its name is +^Z +Stopped +% ls +funnyfile +prog.c +prog.o +% jobs +.ta 1.75i +[1] + Stopped mail harold +% fg +mail harold +funnyfile. Do you know who did it? +EOT +% +.so tabs +.DE +In this example someone was sending a message to Harold and forgot the +name of the file he wanted to mention. The mail command was suspended +by typing ^Z. When the shell noticed that the mail program was +suspended, it typed `Stopped' and prompted for a new command. Then the +.I ls +command was typed to find out the name of the file. The +.I jobs +command was run to find out which command was suspended. +At this time the +.I fg +command was typed to continue execution of the mail program. Input +to the mail program was then continued and ended with a ^D +which indicated the end of the message at which time the mail +program typed EOT. The +.I jobs +command will show which commands are suspended. +The ^Z should only be typed at the beginning of a line since +everything typed on the current line is discarded when a signal is sent +from the keyboard. This also happens on \s-2INTERRUPT\s0, and \s-2QUIT\s0 +signals. More information on +suspending jobs and controlling them is given in +section 2.6. +.PP +If you write or run programs which are not fully debugged then it may +be necessary to stop them somewhat ungracefully. +This can be done by sending them a \s-2QUIT\s0 +signal, sent by typing a ^\e. +This will usually provoke the shell to produce a message like: +.DS +Quit (Core dumped) +.DE +indicating that a file +`core' has been created containing information about the running program's +state when it terminated due to the \s-2QUIT\s0 signal. +You can examine this file yourself, or forward information to the +maintainer of the program telling him/her where the +.I "core file" +is. +.PP +If you run background commands (as explained in section 2.6) then these +commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the +terminal. To stop them you must use the +.I kill +command. See section 2.6 for an example. +.PP +If you want to examine the output of a command without having it move +off the screen as the output of the +.DS +cat /etc/passwd +.DE +command will, you can use the command +.DS +more /etc/passwd +.DE +The +.I more +program pauses after each complete screenful and types `\-\-More\-\-' +at which point you can hit a space to get another screenful, a return +to get another line, a `?' to get some help on other commands, or a `q' to end the +.I more +program. You can also use more as a filter, i.e. +.DS +cat /etc/passwd | more +.DE +works just like the more simple more command above. +.PP +For stopping output of commands not involving +.I more +you can use the +^S key to stop the typeout. The typeout will resume when you +hit ^Q or any other key, but ^Q is normally used because +it only restarts the output and does not become input to the program +which is running. This works well on low-speed terminals, but at 9600 +baud it is hard to type ^S and ^Q fast enough to paginate +the output nicely, and a program like +.I more +is usually used. +.PP +An additional possibility is to use the ^O flush output +character; when this character is typed, all output from the current +command is thrown away (quickly) until the next input read occurs +or until the next shell prompt. This can be used to allow a command +to complete without having to suffer through the output on a slow +terminal; ^O is a toggle, so flushing can be turned off by +typing ^O again while output is being flushed. +.NH 2 +What now? +.PP +We have so far seen a number of mechanisms of the shell and learned a lot +about the way in which it operates. +The remaining sections will go yet further into the internals of the +shell, but you will surely want to try using the +shell before you go any further. +To try it you can log in to \s-2UNIX\s0 and type the following +command to the system: +.DS +chsh myname /bin/csh +.DE +Here `myname' should be replaced by the name you typed to +the system prompt of `login:' to get onto the system. +Thus I would use `chsh bill /bin/csh'. +.B +You only have to do this once; it takes effect at next login. +.R +You are now ready to try using +.I csh. +.PP +Before you do the `chsh' command, the shell you are using when +you log into the system is `/bin/sh'. +In fact, much of the above discussion is applicable to `/bin/sh'. +The next section will introduce many features particular to +.I csh +so you should change your shell to +.I csh +before you begin reading it. +.bp diff --git a/share/doc/usd/04.csh/csh.2 b/share/doc/usd/04.csh/csh.2 new file mode 100644 index 0000000..5fbf43c --- /dev/null +++ b/share/doc/usd/04.csh/csh.2 @@ -0,0 +1,1304 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.2 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.nr H1 1 +.NH +Details on the shell for terminal users +.NH 2 +Shell startup and termination +.PP +When you login, the shell is started by the system in your +.I home +directory and begins by reading commands from a file +.I \&.cshrc +in this directory. +All shells which you may start during your terminal session will +read from this file. +We will later see what kinds of commands are usefully placed there. +For now we need not have this file and the shell does not complain about +its absence. +.PP +A +.I "login shell" , +executed after you login to the system, +will, after it reads commands from +.I \&.cshrc, +read commands from a file +.I \&.login +also in your home directory. +This file contains commands which you wish to do each time you login +to the \s-2UNIX\s0 system. +My +.I \&.login +file looks something like: +.DS +set ignoreeof +set mail=(/usr/spool/mail/bill) +echo "${prompt}users" ; users +alias ts \e + \'set noglob ; eval \`tset \-s \-m dialup:c100rv4pna \-m plugboard:?hp2621nl \!*\`\'; +ts; stty intr ^C kill ^U crt +set time=15 history=10 +msgs \-f +if (\-e $mail) then + echo "${prompt}mail" + mail +endif +.DE +.PP +This file contains several commands to be executed by \s-2UNIX\s0 +each time I login. +The first is a +.I set +command which is interpreted directly by the shell. It sets the shell +variable +.I ignoreeof +which causes the shell to not log me off if I hit ^D. Rather, +I use the +.I logout +command to log off of the system. +By setting the +.I mail +variable, I ask the shell to watch for incoming mail to me. Every 5 minutes +the shell looks for this file and tells me if more mail has arrived there. +An alternative to this is to put the command +.DS +biff y +.DE +in place of this +.I set; +this will cause me to be notified immediately when mail arrives, and to +be shown the first few lines of the new message. +.PP +Next I set the shell variable `time' to `15' causing the shell to automatically +print out statistics lines for commands which execute for at least 15 seconds +of \s-2CPU\s+2 time. The variable `history' is set to 10 indicating that +I want the shell to remember the last 10 commands I type in its +.I "history list" , +(described later). +.PP +I create an +.I alias +``ts'' which executes a +\fItset\fR\|(1) command setting up the modes of the terminal. +The parameters to +.I tset +indicate the kinds of terminal which I usually use when not on a hardwired +port. I then execute ``ts'' and also use the +.I stty +command to change the interrupt character to ^C and the line kill +character to ^U. +.PP +I then run the `msgs' program, which provides me with any +system messages which I have not seen before; the `\-f' option here prevents +it from telling me anything if there are no new messages. +Finally, if my mailbox file exists, then I run the `mail' program to +process my mail. +.PP +When the `mail' and `msgs' programs finish, the shell will finish +processing my +.I \&.login +file and begin reading commands from the terminal, prompting for each with +`% '. +When I log off (by giving the +.I logout +command) the shell +will print `logout' and execute commands from the file `.logout' +if it exists in my home directory. +After that the shell will terminate and \s-2UNIX\s0 will log +me off the system. +If the system is not going down, I will receive a new login message. +In any case, after the `logout' message the shell is committed to terminating +and will take no further input from my terminal. +.NH 2 +Shell variables +.PP +The shell maintains a set of +.I variables. +We saw above the variables +.I history +and +.I time +which had values `10' and `15'. +In fact, each shell variable has as value an array of +zero or more +.I strings. +Shell variables may be assigned values by the set command. It has +several forms, the most useful of which was given above and is +.DS +set name=value +.DE +.PP +Shell variables may be used to store values which are to +be used in commands later through a substitution mechanism. +The shell variables most commonly referenced are, however, those which the +shell itself refers to. +By changing the values of these variables one can directly affect the +behavior of the shell. +.PP +One of the most important variables is the variable +.I path. +This variable contains a sequence of directory names where the shell +searches for commands. +The +.I set +command with no arguments +shows the value of all variables currently defined (we usually say +.I set) +in the shell. +The default value for path will be shown by +.I set +to be +.DS +% set +.ta .75i +argv () +cwd /usr/bill +home /usr/bill +path (. /usr/ucb /bin /usr/bin) +prompt % +shell /bin/csh +status 0 +term c100rv4pna +user bill +% +.so tabs +.DE +This output indicates that the variable path points to the current +directory `.' and then `/usr/ucb', `/bin' and `/usr/bin'. +Commands which you may write might be in `.' (usually one of +your directories). +Commands developed at Berkeley, live in `/usr/ucb' +while commands developed at Bell Laboratories live in `/bin' and `/usr/bin'. +.PP +A number of locally developed programs on the system live in the directory +`/usr/local'. +If we wish that all shells which we invoke to have +access to these new programs we can place the command +.DS +set path=(. /usr/ucb /bin /usr/bin /usr/local) +.DE +in our file +.I \&.cshrc +in our home directory. +Try doing this and then logging out and back in and do +.DS +set +.DE +again to see that the value assigned to +.I path +has changed. +.FS \(dg +Another directory that might interest you is /usr/new, which contains +many useful user-contributed programs provided with Berkeley Unix. +.FE +.PP +One thing you should be aware of is that the shell examines each directory +which you insert into your path and determines which commands are contained +there. Except for the current directory `.', which the shell treats specially, +this means that if commands are added to a directory in your search path after +you have started the shell, they will not necessarily be found by the shell. +If you wish to use a command which has been added in this way, you should +give the command +.DS +rehash +.DE +to the shell, which will cause it to recompute its internal table of command +locations, so that it will find the newly added command. +Since the shell has to look in the current directory `.' on each command, +placing it at the end of the path specification usually works equivalently +and reduces overhead. +.PP +Other useful built in variables are the variable +.I home +which shows your home directory, +.I cwd +which contains your current working directory, +the variable +.I ignoreeof +which can be set in your +.I \&.login +file to tell the shell not to exit when it receives an end-of-file from +a terminal (as described above). +The variable `ignoreeof' +is one of several variables which the shell does not care about the +value of, only whether they are +.I set +or +.I unset. +Thus to set this variable you simply do +.DS +set ignoreeof +.DE +and to unset it do +.DS +unset ignoreeof +.DE +These give the variable `ignoreeof' no value, but none is desired or required. +.PP +Finally, some other built-in shell variables of use are the +variables +.I noclobber +and +.I mail. +The metasyntax +.DS +> filename +.DE +which redirects the standard output of a command +will overwrite and destroy the previous contents of the named file. +In this way you may accidentally overwrite a file which is valuable. +If you would prefer that the shell not overwrite files in this +way you can +.DS +set noclobber +.DE +in your +.I \&.login +file. +Then trying to do +.DS +date > now +.DE +would cause a diagnostic if `now' existed already. +You could type +.DS +date >! now +.DE +if you really wanted to overwrite the contents of `now'. +The `>!' is a special metasyntax indicating that clobbering the +file is ok.\(dg +.FS +\(dgThe space between the `!' and the word `now' is critical here, as `!now' +would be an invocation of the +.I history +mechanism, and have a totally different effect. +.FE +.NH 2 +The shell's history list +.PP +The shell can maintain a +.I "history list" +into which it places the words +of previous commands. +It is possible to use a notation to reuse commands or words +from commands in forming new commands. +This mechanism can be used to repeat previous commands or to +correct minor typing mistakes in commands. +.PP +The following figure gives a sample session involving typical usage of the +history mechanism of the shell. +.KF +.DS +% cat bug.c +main() + +{ + printf("hello); +} +% cc !$ +cc bug.c +"bug.c", line 4: newline in string or char constant +"bug.c", line 5: syntax error +% ed !$ +ed bug.c +29 +4s/);/"&/p + printf("hello"); +w +30 +q +% !c +cc bug.c +% a.out +hello% !e +ed bug.c +30 +4s/lo/lo\e\en/p + printf("hello\en"); +w +32 +q +% !c \-o bug +cc bug.c \-o bug +% size a.out bug +a.out: 2784+364+1028 = 4176b = 0x1050b +bug: 2784+364+1028 = 4176b = 0x1050b +% ls \-l !* +ls \-l a.out bug +\(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:41 a.out +\(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:42 bug +% bug +hello +% num bug.c | spp +spp: Command not found. +% ^spp^ssp +num bug.c | ssp + 1 main() + 3 { + 4 printf("hello\en"); + 5 } +% !! | lpr +num bug.c | ssp | lpr +% +.DE +.KE +In this example we have a very simple C program which has a bug (or two) +in it in the file `bug.c', which we `cat' out on our terminal. We then +try to run the C compiler on it, referring to the file again as `!$', +meaning the last argument to the previous command. Here the `!' is the +history mechanism invocation metacharacter, and the `$' stands for the last +argument, by analogy to `$' in the editor which stands for the end of the line. +The shell echoed the command, as it would have been typed without use of +the history mechanism, and then executed it. +The compilation yielded error diagnostics so we now run the editor on the +file we were trying to compile, fix the bug, and run the C compiler again, +this time referring to this command simply as `!c', which repeats the last +command which started with the letter `c'. If there were other +commands starting with `c' done recently we could have said `!cc' or even +`!cc:p' which would have printed the last command starting with `cc' +without executing it. +.PP +After this recompilation, we ran the resulting `a.out' file, and then +noting that there still was a bug, ran the editor again. After fixing +the program we ran the C compiler again, but tacked onto the command +an extra `\-o bug' telling the compiler to place the resultant binary in +the file `bug' rather than `a.out'. In general, the history mechanisms +may be used anywhere in the formation of new commands and other characters +may be placed before and after the substituted commands. +.PP +We then ran the `size' command to see how large the binary program images +we have created were, and then an `ls \-l' command with the same argument +list, denoting the argument list `\!*'. +Finally we ran the program `bug' to see that its output is indeed correct. +.PP +To make a numbered listing of the program we ran the `num' command on the file `bug.c'. +In order to compress out blank lines in the output of `num' we ran the +output through the filter `ssp', but misspelled it as spp. To correct this +we used a shell substitute, placing the old text and new text between `^' +characters. This is similar to the substitute command in the editor. +Finally, we repeated the same command with `!!', but sent its output to the +line printer. +.PP +There are other mechanisms available for repeating commands. The +.I history +command prints out a number of previous commands with numbers by which +they can be referenced. There is a way to refer to a previous command +by searching for a string which appeared in it, and there are other, +less useful, ways to select arguments to include in a new command. +A complete description of all these mechanisms +is given in the C shell manual pages in the \s-2UNIX\s0 Programmer's Manual. +.NH 2 +Aliases +.PP +The shell has an +.I alias +mechanism which can be used to make transformations on input commands. +This mechanism can be used to simplify the commands you type, +to supply default arguments to commands, +or to perform transformations on commands and their arguments. +The alias facility is similar to a macro facility. +Some of the features obtained by aliasing can be obtained also +using shell command files, but these take place in another instance +of the shell and cannot directly affect the current shells environment +or involve commands such as +.I cd +which must be done in the current shell. +.PP +As an example, suppose that there is a new version of the mail program +on the system called `newmail' +you wish to use, rather than the standard mail program which is called +`mail'. +If you place the shell command +.DS +alias mail newmail +.DE +in your +.I \&.cshrc +file, the shell will transform an input line of the form +.DS +mail bill +.DE +into a call on `newmail'. +More generally, suppose we wish the command `ls' to always show +sizes of files, that is to always do `\-s'. +We can do +.DS +alias ls ls \-s +.DE +or even +.DS +alias dir ls \-s +.DE +creating a new command syntax `dir' +which does an `ls \-s'. +If we say +.DS +dir ~bill +.DE +then the shell will translate this to +.DS +ls \-s /mnt/bill +.DE +.PP +Thus the +.I alias +mechanism can be used to provide short names for commands, +to provide default arguments, +and to define new short commands in terms of other commands. +It is also possible to define aliases which contain multiple +commands or pipelines, showing where the arguments to the original +command are to be substituted using the facilities of the +history mechanism. +Thus the definition +.DS +alias cd \'cd \e!* ; ls \' +.DE +would do an +.I ls +command after each change directory +.I cd +command. +We enclosed the entire alias definition in `\'' characters to prevent +most substitutions from occurring and the character `;' from being +recognized as a metacharacter. +The `!' here is escaped with a `\e' to prevent it from being interpreted +when the alias command is typed in. +The `\e!*' here substitutes the entire argument list to the pre-aliasing +.I cd +command, without giving an error if there were no arguments. +The `;' separating commands is used here +to indicate that one command is to be done and then the next. +Similarly the definition +.DS +alias whois \'grep \e!^ /etc/passwd\' +.DE +defines a command which looks up its first argument in the password file. +.PP +.B Warning: +The shell currently reads the +.I \&.cshrc +file each time it starts up. If you place a large number of commands +there, shells will tend to start slowly. A mechanism for saving the shell +environment after reading the \fI\&.cshrc\fR file and quickly restoring it is +under development, but for now you should try to limit the number of +aliases you have to a reasonable number... 10 or 15 is reasonable, +50 or 60 will cause a noticeable delay in starting up shells, and make +the system seem sluggish when you execute commands from within the editor +and other programs. +.NH 2 +More redirection; >> and >& +.PP +There are a few more notations useful to the terminal user +which have not been introduced yet. +.PP +In addition to the standard output, commands also have a +.I "diagnostic output" +which is normally directed to the terminal even when the standard output +is redirected to a file or a pipe. +It is occasionally desirable to direct the diagnostic output along with +the standard output. +For instance if you want to redirect the output of a long running command +into a file and wish to have a record of any error diagnostic it produces +you can do +.DS +command >& file +.DE +The `>&' here tells the shell to route both the diagnostic output and the +standard output into `file'. +Similarly you can give the command +.DS +command |\|& lpr +.DE +to route both standard and diagnostic output through the pipe +to the line printer daemon +.I lpr.\(dd +.FS +\(dd A command of the form +.br +.ti +5 +command >&! file +.br +exists, and is used when +.I noclobber +is set and +.I file +already exists. +.FE +.PP +Finally, it is possible to use the form +.DS +command >> file +.DE +to place output at the end of an existing file.\(dg +.FS +\(dg If +.I noclobber +is set, then an error will result if +.I file +does not exist, otherwise the shell will create +.I file +if it doesn't exist. +A form +.br +.ti +5 +command >>! file +.br +makes it not be an error for file to not exist when +.I noclobber +is set. +.FE +.NH 2 +Jobs; Background, Foreground, or Suspended +.PP +When one or more commands +are typed together as a pipeline or as a sequence of commands separated by +semicolons, a single +.I job +is created by the shell consisting of these commands together as a unit. +Single commands without pipes or semicolons create the simplest jobs. +Usually, every line typed to the shell creates a job. +Some lines that create jobs (one per line) are +.DS +sort < data +ls \-s | sort \-n | head \-5 +mail harold +.DE +.PP +If the metacharacter `&' is typed +at the end of the commands, then the job is started as a +.I background +job. This means that the shell does not wait for it to complete but +immediately prompts and is ready for another command. The job runs +.I "in the background" +at the same time that normal jobs, called +.I foreground +jobs, continue to be read and executed by the shell one at a time. +Thus +.DS +du > usage & +.DE +would run the +.I du +program, which reports on the disk usage of your working directory (as well as +any directories below it), put the output into the file `usage' and return +immediately with a prompt for the next command without out waiting for +.I du +to finish. The +.I du +program would continue executing in the background +until it finished, even though you can type and execute more commands in the +mean time. +When a background +job terminates, a message is typed by the shell just before the next prompt +telling you that the job has completed. +In the following example the +.I du +job finishes sometime during the +execution of the +.I mail +command and its completion is reported just before +the prompt after the +.I mail +job is finished. +.DS +% du > usage & +[1] 503 +% mail bill +How do you know when a background job is finished? +EOT +.ta 1.75i +[1] \- Done du > usage +% +.so tabs +.DE +If the job did not terminate normally the `Done' message might say +something else like `Killed'. +If you want the +terminations of background jobs to be reported at the time they occur +(possibly interrupting the output of other foreground jobs), you can set +the +.I notify +variable. In the previous example this would mean that the +`Done' message might have come right in the middle of the message to +Bill. +Background jobs are unaffected by any signals from the keyboard like +the \s-2STOP\s0, \s-2INTERRUPT\s0, or \s-2QUIT\s0 signals mentioned earlier. +.PP +Jobs are recorded in a table inside the shell until they terminate. +In this table, the shell remembers the command names, arguments and the +.I "process numbers" +of all commands in the job as well as the working directory where the job was +started. +Each job in the table is either running +.I "in the foreground" +with the shell waiting for it to terminate, running +.I "in the background," +or +.I suspended. +Only one job can be running in the foreground at one time, but several +jobs can be suspended or running in the background at once. As each job +is started, it is assigned a small identifying +number called the +.I "job number" +which can be used later to refer to the job in the commands described below. +Job numbers remain +the same until the job terminates and then are re-used. +.PP +When a job is started in the background using `&', its number, as well +as the process numbers of all its (top level) commands, is typed by the shell +before prompting you for another command. +For example, +.DS +% ls \-s | sort \-n > usage & +[2] 2034 2035 +% +.DE +runs the `ls' program with the `\-s' options, pipes this output into +the `sort' program with the `\-n' option which puts its output into the +file `usage'. +Since the `&' was at the end of the line, these two programs were started +together as a background job. After starting the job, the shell prints +the job number in brackets (2 in this case) followed by the process number +of each program started in the job. Then the shell immediates prompts for +a new command, leaving the job running simultaneously. +.PP +As mentioned in section 1.8, foreground jobs become +.I suspended +by typing ^Z +which sends a \s-2STOP\s0 signal to the currently running +foreground job. A background job can become suspended by using the +.I stop +command described below. When jobs are suspended they merely stop +any further progress until started again, either in the foreground +or the background. The shell notices when a job becomes stopped and +reports this fact, much like it reports the termination of background jobs. +For foreground jobs this looks like +.DS +% du > usage +^Z +Stopped +% +.DE +`Stopped' message is typed by the shell when it notices that the +.I du +program stopped. +For background jobs, using the +.I stop +command, it is +.DS +% sort usage & +[1] 2345 +% stop %1 +.ta 1.75i +[1] + Stopped (signal) sort usage +% +.so tabs +.DE +Suspending foreground jobs can be very useful when you need to temporarily +change what you are doing (execute other commands) and then return to +the suspended job. Also, foreground jobs can be suspended and then +continued as background jobs using the +.I bg +command, allowing you to continue other work and +stop waiting for the foreground job to finish. Thus +.DS +% du > usage +^Z +Stopped +% bg +[1] du > usage & +% +.DE +starts `du' in the foreground, stops it before it finishes, then continues +it in the background allowing more foreground commands to be executed. +This is especially helpful +when a foreground job ends up taking longer than you expected and you +wish you had started it in the background in the beginning. +.PP +All +.I "job control" +commands can take an argument that identifies a particular +job. +All job name arguments begin with the character `%', since some of the +job control commands also accept process numbers (printed by the +.I ps +command.) +The default job (when no argument is given) is called the +.I current +job and is identified by a `+' in the output of the +.I jobs +command, which shows you which jobs you have. +When only one job is stopped or running in the background (the usual case) +it is always the current job thus no argument is needed. +If a job is stopped while running in the foreground it becomes the +.I current +job and the existing current job becomes the +.I previous +job \- identified by a `\-' in the output of +.I jobs. +When the current job terminates, the previous job becomes the current job. +When given, the argument is either `%\-' (indicating +the previous job); `%#', where # is the job number; +`%pref' where pref is some unique prefix of the command name +and arguments of one of the jobs; or `%?' followed by some string found +in only one of the jobs. +.PP +The +.I jobs +command types the table of jobs, giving the job number, +commands and status (`Stopped' or `Running') of each background or +suspended job. With the `\-l' option the process numbers are also +typed. +.DS +% du > usage & +[1] 3398 +% ls \-s | sort \-n > myfile & +[2] 3405 +% mail bill +^Z +Stopped +% jobs +.ta 1.75i +[1] \(mi Running du > usage +[2] Running ls \-s | sort \-n > myfile +[3] \(pl Stopped mail bill +% fg %ls +ls \-s | sort \-n > myfile +% more myfile +.so tabs +.DE +.PP +The +.I fg +command runs a suspended or background job in the foreground. It is +used to restart a previously suspended job or change a background job +to run in the foreground (allowing signals or input from the terminal). +In the above example we used +.I fg +to change the `ls' job from the +background to the foreground since we wanted to wait for it to +finish before looking at its output file. +The +.I bg +command runs a suspended job in the background. It is usually used +after stopping the currently running foreground job with the +\s-2STOP\s0 signal. The combination of the \s-2STOP\s0 signal and the +.I bg +command changes a foreground job into a background job. +The +.I stop +command suspends a background job. +.PP +The +.I kill +command terminates a background or suspended job immediately. +In addition to jobs, it may be given process numbers as arguments, +as printed by +.I ps. +Thus, in the example above, the running +.I du +command could have been terminated by the command +.DS +% kill %1 +.ta 1.75i +[1] Terminated du > usage +% +.so tabs +.DE +.PP +The +.I notify +command (not the variable mentioned earlier) indicates that the termination +of a specific job should be +reported at the time it finishes instead of waiting for the next prompt. +.PP +If a job running in the background tries to read input from the terminal +it is automatically stopped. When such a job is then run in the +foreground, input can be given to the job. If desired, the job can +be run in the background again until it requests input again. +This is illustrated in the following sequence where the `s' command in the +text editor might take a long time. +.ID +.nf +% ed bigfile +120000 +1,$s/thisword/thatword/ +^Z +Stopped +% bg +[1] ed bigfile & +% + . . . some foreground commands +.ta 1.75i +[1] Stopped (tty input) ed bigfile +% fg +ed bigfile +w +120000 +q +% +.so tabs +.DE +So after the `s' command was issued, the `ed' job was stopped with ^Z +and then put in the background using +.I bg. +Some time later when the `s' command was finished, +.I ed +tried to read another command and was stopped because jobs +in the background cannot read from the terminal. The +.I fg +command returned the `ed' job to the foreground where it could once again +accept commands from the terminal. +.PP +The command +.DS +stty tostop +.DE +causes all background jobs run on your terminal to stop +when they are about to +write output to the terminal. This prevents messages from background +jobs from interrupting foreground job output and allows you to run +a job in the background without losing terminal output. It also +can be used for interactive programs that sometimes have long +periods without interaction. Thus each time it outputs a prompt for more +input it will stop before the prompt. It can then be run in the +foreground using +.I fg, +more input can be given and, if necessary stopped and returned to +the background. This +.I stty +command might be a good thing to put in your +.I \&.login +file if you do not like output from background jobs interrupting +your work. It also can reduce the need for redirecting the output +of background jobs if the output is not very big: +.DS +% stty tostop +% wc hugefile & +[1] 10387 +% ed text +\&. . . some time later +q +.ta 1.75i +[1] Stopped (tty output) wc hugefile +% fg wc +wc hugefile + 13371 30123 302577 +% stty \-tostop +.so tabs +.DE +Thus after some time the `wc' command, which counts the lines, words +and characters in a file, had one line of output. When it tried to +write this to the terminal it stopped. By restarting it in the +foreground we allowed it to write on the terminal exactly when we were +ready to look at its output. +Programs which attempt to change the mode of the terminal will also +block, whether or not +.I tostop +is set, when they are not in the foreground, as +it would be very unpleasant to have a background job change the state +of the terminal. +.PP +Since the +.I jobs +command only prints jobs started in the currently executing shell, +it knows nothing about background jobs started in other login sessions +or within shell files. The +.I ps +can be used in this case to find out about background jobs not started +in the current shell. +.NH 2 +Working Directories +.PP +As mentioned in section 1.6, the shell is always in a particular +.I "working directory." +The `change directory' command +.I chdir +(its +short form +.I cd +may also be used) +changes the working directory of the shell, +that is, changes the directory you +are located in. +.PP +It is useful to make a directory for each project you wish to work on +and to place all files related to that project in that directory. +The `make directory' command, +.I mkdir, +creates a new directory. +The +.I pwd +(`print working directory') command +reports the absolute pathname of the working directory of the shell, +that is, the directory you are +located in. +Thus in the example below: +.DS +% pwd +/usr/bill +% mkdir newpaper +% chdir newpaper +% pwd +/usr/bill/newpaper +% +.DE +the user has created and moved to the +directory +.I newpaper. +where, for example, he might +place a group of related files. +.PP +No matter where you have moved to in a directory hierarchy, +you can return to your `home' login directory by doing just +.DS +cd +.DE +with no arguments. +The name `..' always means the directory above the current one in +the hierarchy, thus +.DS +cd .. +.DE +changes the shell's working directory to the one directly above the +current one. +The name `..' can be used in any +pathname, thus, +.DS +cd ../programs +.DE +means +change to the directory `programs' contained in the directory +above the current one. +If you have several directories for different +projects under, say, your home directory, +this shorthand notation +permits you to switch easily between them. +.PP +The shell always remembers the pathname of its current working directory in +the variable +.I cwd. +The shell can also be requested to remember the previous directory when +you change to a new working directory. If the `push directory' command +.I pushd +is used in place of the +.I cd +command, the shell saves the name of the current working directory +on a +.I "directory stack" +before changing to the new one. +You can see this list at any time by typing the `directories' +command +.I dirs. +.ID +.nf +% pushd newpaper/references +~/newpaper/references ~ +% pushd /usr/lib/tmac +/usr/lib/tmac ~/newpaper/references ~ +% dirs +/usr/lib/tmac ~/newpaper/references ~ +% popd +~/newpaper/references ~ +% popd +~ +% +.DE +The list is printed in a horizontal line, reading left to right, +with a tilde (~) as +shorthand for your home directory\(emin this case `/usr/bill'. +The directory stack is printed whenever there is more than one +entry on it and it changes. +It is also printed by a +.I dirs +command. +.I Dirs +is usually faster and more informative than +.I pwd +since it shows the current working directory as well as any +other directories remembered in the stack. +.PP +The +.I pushd +command with no argument +alternates the current directory with the first directory in the +list. +The `pop directory' +.I popd +command without an argument returns you to the directory you were in prior to +the current one, discarding the previous current directory from the +stack (forgetting it). +Typing +.I popd +several times in a series takes you backward through the directories +you had been in (changed to) by +.I pushd +command. +There are other options to +.I pushd +and +.I popd +to manipulate the contents of the directory stack and to change +to directories not at the top of the stack; see the +.I csh +manual page for details. +.PP +Since the shell remembers the working directory in which each job +was started, it warns you when you might be confused by restarting +a job in the foreground which has a different working directory than the +current working directory of the shell. Thus if you start a background +job, then change the shell's working directory and then cause the +background job to run in the foreground, the shell warns you that the +working directory of the currently running foreground job is different +from that of the shell. +.DS +% dirs \-l +/mnt/bill +% cd myproject +% dirs +~/myproject +% ed prog.c +1143 +^Z +Stopped +% cd .. +% ls +myproject +textfile +% fg +ed prog.c (wd: ~/myproject) +.DE +This way the shell warns you when there +is an implied change of working directory, even though no cd command was +issued. In the above example the `ed' job was still in `/mnt/bill/project' +even though the shell had changed to `/mnt/bill'. +A similar warning is given when such a foreground job +terminates or is suspended (using the \s-2STOP\s0 signal) since +the return to the shell again implies a change of working directory. +.DS +% fg +ed prog.c (wd: ~/myproject) + . . . after some editing +q +(wd now: ~) +% +.DE +These messages are sometimes confusing if you use programs that change +their own working directories, since the shell only remembers which +directory a job is started in, and assumes it stays there. +The `\-l' option of +.I jobs +will type the working directory +of suspended or background jobs when it is different +from the current working directory of the shell. +.NH 2 +Useful built-in commands +.PP +We now give a few of the useful built-in commands of the shell describing +how they are used. +.PP +The +.I alias +command described above is used to assign new aliases and to show the +existing aliases. +With no arguments it prints the current aliases. +It may also be given only one argument such as +.DS +alias ls +.DE +to show the current alias for, e.g., `ls'. +.PP +The +.I echo +command prints its arguments. +It is often used in +.I "shell scripts" +or as an interactive command +to see what filename expansions will produce. +.PP +The +.I history +command will show the contents of the history list. +The numbers given with the history events can be used to reference +previous events which are difficult to reference using the +contextual mechanisms introduced above. +There is also a shell variable called +.I prompt. +By placing a `!' character in its value the shell will there substitute +the number of the current command in the history list. +You can use this number to refer to this command in a history substitution. +Thus you could +.DS +set prompt=\'\e! % \' +.DE +Note that the `!' character had to be +.I escaped +here even within `\'' characters. +.PP +The +.I limit +command is used to restrict use of resources. +With no arguments it prints the current limitations: +.DS +.ta 1i +cputime unlimited +filesize unlimited +datasize 5616 kbytes +stacksize 512 kbytes +coredumpsize unlimited +.so tabs +.DE +Limits can be set, e.g.: +.DS +limit coredumpsize 128k +.DE +Most reasonable units abbreviations will work; see the +.I csh +manual page for more details. +.PP +The +.I logout +command can be used to terminate a login shell which has +.I ignoreeof +set. +.PP +The +.I rehash +command causes the shell to recompute a table of where commands are +located. This is necessary if you add a command to a directory +in the current shell's search path and wish the shell to find it, +since otherwise the hashing algorithm may tell the shell that the +command wasn't in that directory when the hash table was computed. +.PP +The +.I repeat +command can be used to repeat a command several times. +Thus to make 5 copies of the file +.I one +in the file +.I five +you could do +.DS +repeat 5 cat one >> five +.DE +.PP +The +.I setenv +command can be used +to set variables in the environment. +Thus +.DS +setenv TERM adm3a +.DE +will set the value of the environment variable \s-2TERM\s0 +to +`adm3a'. +A user program +.I printenv +exists which will print out the environment. +It might then show: +.DS +% printenv +HOME=/usr/bill +SHELL=/bin/csh +PATH=:/usr/ucb:/bin:/usr/bin:/usr/local +TERM=adm3a +USER=bill +% +.DE +.PP +The +.I source +command can be used to force the current shell to read commands from +a file. +Thus +.DS +source .cshrc +.DE +can be used after editing in a change to the +.I \&.cshrc +file which you wish to take effect right away. +.PP +The +.I time +command can be used to cause a command to be timed no matter how much +\s-2CPU\s0 time it takes. +Thus +.DS +% time cp /etc/rc /usr/bill/rc +0.0u 0.1s 0:01 8% 2+1k 3+2io 1pf+0w +% time wc /etc/rc /usr/bill/rc + 52 178 1347 /etc/rc + 52 178 1347 /usr/bill/rc + 104 356 2694 total +0.1u 0.1s 0:00 13% 3+3k 5+3io 7pf+0w +% +.DE +indicates that the +.I cp +command used a negligible amount of user time (u) +and about 1/10th of a system time (s); the elapsed time was 1 second (0:01), +there was an average memory usage of 2k bytes of program space and 1k +bytes of data space over the cpu time involved (2+1k); the program +did three disk reads and two disk writes (3+2io), and took one page fault +and was not swapped (1pf+0w). +The word count command +.I wc +on the other hand used 0.1 seconds of user time and 0.1 seconds of system +time in less than a second of elapsed time. +The percentage `13%' indicates that over the period when it was active +the command `wc' used an average of 13 percent of the available \s-2CPU\s0 +cycles of the machine. +.PP +The +.I unalias +and +.I unset +commands can be used +to remove aliases and variable definitions from the shell, and +.I unsetenv +removes variables from the environment. +.NH 2 +What else? +.PP +This concludes the basic discussion of the shell for terminal users. +There are more features of the shell to be discussed here, and all +features of the shell are discussed in its manual pages. +One useful feature which is discussed later is the +.I foreach +built-in command which can be used to run the same command +sequence with a number of different arguments. +.PP +If you intend to use \s-2UNIX\s0 a lot you should look through +the rest of this document and the csh manual pages (section1) to become familiar +with the other facilities which are available to you. +.bp diff --git a/share/doc/usd/04.csh/csh.3 b/share/doc/usd/04.csh/csh.3 new file mode 100644 index 0000000..76ee1eb --- /dev/null +++ b/share/doc/usd/04.csh/csh.3 @@ -0,0 +1,649 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.3 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.nr H1 2 +.NH +Shell control structures and command scripts +.NH 2 +Introduction +.PP +It is possible to place commands in files and to cause shells to be +invoked to read and execute commands from these files, +which are called +.I "shell scripts." +We here detail those features of the shell useful to the writers of such +scripts. +.NH 2 +Make +.PP +It is important to first note what shell scripts are +.I not +useful for. +There is a program called +.I make +which is very useful for maintaining a group of related files +or performing sets of operations on related files. +For instance a large program consisting of one or more files +can have its dependencies described in a +.I makefile +which contains definitions of the commands used to create these +different files when changes occur. +Definitions of the means for printing listings, cleaning up the directory +in which the files reside, and installing the resultant programs +are easily, and most appropriately placed in this +.I makefile. +This format is superior and preferable to maintaining a group of shell +procedures to maintain these files. +.PP +Similarly when working on a document a +.I makefile +may be created which defines how different versions of the document +are to be created and which options of +.I nroff +or +.I troff +are appropriate. +.NH 2 +Invocation and the argv variable +.PP +A +.I csh +command script may be interpreted by saying +.DS +% csh script ... +.DE +where +.I script +is the name of the file containing a group of +.I csh +commands and +`\&...' is replaced by a sequence of arguments. +The shell places these arguments in the variable +.I argv +and then begins to read commands from the script. +These parameters are then available through the same mechanisms +which are used to reference any other shell variables. +.PP +If you make the file +`script' +executable by doing +.DS +chmod 755 script +.DE +and place a shell comment at the beginning of the shell script +(i.e. begin the file with a `#' character) +then a `/bin/csh' will automatically be invoked to execute `script' when +you type +.DS +script +.DE +If the file does not begin with a `#' then the standard shell +`/bin/sh' will be used to execute it. +This allows you to convert your older shell scripts to use +.I csh +at your convenience. +.NH 2 +Variable substitution +.PP +After each input line is broken into words and history substitutions +are done on it, the input line is parsed into distinct commands. +Before each command is executed a mechanism know as +.I "variable substitution" +is done on these words. +Keyed by the character `$' this substitution replaces the names +of variables by their values. +Thus +.DS +echo $argv +.DE +when placed in a command script would cause the current value of the +variable +.I argv +to be echoed to the output of the shell script. +It is an error for +.I argv +to be unset at this point. +.PP +A number of notations are provided for accessing components and attributes +of variables. +The notation +.DS +$?name +.DE +expands to `1' if name is +.I set +or to `0' +if name is not +.I set. +It is the fundamental mechanism used for checking whether particular +variables have been assigned values. +All other forms of reference to undefined variables cause errors. +.PP +The notation +.DS +$#name +.DE +expands to the number of elements in the variable +.I name. +Thus +.DS +% set argv=(a b c) +% echo $?argv +1 +% echo $#argv +3 +% unset argv +% echo $?argv +0 +% echo $argv +Undefined variable: argv. +% +.DE +.PP +It is also possible to access the components of a variable +which has several values. +Thus +.DS +$argv[1] +.DE +gives the first component of +.I argv +or in the example above `a'. +Similarly +.DS +$argv[$#argv] +.DE +would give `c', +and +.DS +$argv[1\-2] +.DE +would give `a b'. Other notations useful in shell scripts are +.DS +$\fIn\fR +.DE +where +.I n +is an integer as a shorthand for +.DS +$argv[\fIn\fR\|] +.DE +the +.I n\|th +parameter and +.DS +$* +.DE +which is a shorthand for +.DS +$argv +.DE +The form +.DS +$$ +.DE +expands to the process number of the current shell. +Since this process number is unique in the system it can +be used in generation of unique temporary file names. +The form +.DS +$< +.DE +is quite special and is replaced by the next line of input read from +the shell's standard input (not the script it is reading). This is +useful for writing shell scripts that are interactive, reading +commands from the terminal, or even writing a shell script that +acts as a filter, reading lines from its input file. +Thus the sequence +.DS +echo 'yes or no?\ec' +set a=($<) +.DE +would write out the prompt `yes or no?' without a newline and then +read the answer into the variable `a'. In this case `$#a' would be +`0' if either a blank line or end-of-file (^D) was typed. +.PP +One minor difference between `$\fIn\fR\|' and `$argv[\fIn\fR\|]' +should be noted here. +The form +`$argv[\fIn\fR\|]' +will yield an error if +.I n +is not in the range +`1\-$#argv' +while `$n' +will never yield an out of range subscript error. +This is for compatibility with the way older shells handled parameters. +.PP +Another important point is that it is never an error to give a subrange +of the form `n\-'; if there are less than +.I n +components of the given variable then no words are substituted. +A range of the form `m\-n' likewise returns an empty vector without giving +an error when \fIm\fR exceeds the number of elements of the given variable, +provided the subscript \fIn\fR is in range. +.NH 2 +Expressions +.PP +In order for interesting shell scripts to be constructed it +must be possible to evaluate expressions in the shell based on the +values of variables. +In fact, all the arithmetic operations of the language C are available +in the shell +with the same precedence that they have in C. +In particular, the operations `==' and `!=' compare strings +and the operators `&&' and `|\|\||' implement the boolean and/or operations. +The special operators `=~' and `!~' are similar to `==' and `!=' except +that the string on the right side can have pattern matching characters +(like *, ? or []) and the test is whether the string on the left matches +the pattern on the right. +.PP +The shell also allows file enquiries of the form +.DS +\-? filename +.DE +where `?' is replace by a number of single characters. +For instance the expression primitive +.DS +\-e filename +.DE +tell whether the file +`filename' +exists. +Other primitives test for read, write and execute access to the file, +whether it is a directory, or has non-zero length. +.PP +It is possible to test whether a command terminates normally, +by a primitive of the +form `{ command }' which returns true, i.e. `1' if the command +succeeds exiting normally with exit status 0, or `0' if the command +terminates abnormally or with exit status non-zero. +If more detailed information about the execution status of a command +is required, it can be executed and the variable `$status' examined +in the next command. +Since `$status' is set by every command, it is very transient. +It can be saved if it is inconvenient to use it only in the single +immediately following command. +.PP +For a full list of expression components available see the manual +section for the shell. +.NH 2 +Sample shell script +.PP +A sample shell script which makes use of the expression mechanism +of the shell and some of its control structure follows: +.DS +% cat copyc +# +# Copyc copies those C programs in the specified list +# to the directory ~/backup if they differ from the files +# already in ~/backup +# +set noglob +foreach i ($argv) + + if ($i !~ *.c) continue # not a .c file so do nothing + + if (! \-r ~/backup/$i:t) then + echo $i:t not in backup... not cp\e\'ed + continue + endif + + cmp \-s $i ~/backup/$i:t # to set $status + + if ($status != 0) then + echo new backup of $i + cp $i ~/backup/$i:t + endif +end +.DE +.PP +This script makes use of the +.I foreach +command, which causes the shell to execute the commands between the +.I foreach +and the matching +.I end +for each of the values given between `(' and `)' with the named +variable, in this case `i' set to successive values in the list. +Within this loop we may use the command +.I break +to stop executing the loop +and +.I continue +to prematurely terminate one iteration +and begin the next. +After the +.I foreach +loop the iteration variable +(\fIi\fR in this case) +has the value at the last iteration. +.PP +We set the variable +.I noglob +here to prevent filename expansion of the members of +.I argv. +This is a good idea, in general, if the arguments to a shell script +are filenames which have already been expanded or if the arguments +may contain filename expansion metacharacters. +It is also possible to quote each use of a `$' variable expansion, +but this is harder and less reliable. +.PP +The other control construct used here is a statement of the form +.DS +\fBif\fR ( expression ) \fBthen\fR + command + ... +\fBendif\fR +.DE +The placement of the keywords here is +.B not +flexible due to the current implementation of the shell.\(dg +.FS +\(dgThe following two formats are not currently acceptable to the shell: +.sp +.in +5 +.nf +\fBif\fR ( expression ) # \fBWon't work!\fR +\fBthen\fR + command + ... +\fBendif\fR +.fi +.in -5 +.sp +and +.sp +.in +5 +.nf +\fBif\fR ( expression ) \fBthen\fR command \fBendif\fR # \fBWon't work\fR +.in -5 +.fi +.FE +.PP +The shell does have another form of the if statement of the form +.DS +\fBif\fR ( expression ) \fBcommand\fR +.DE +which can be written +.DS +\fBif\fR ( expression ) \e + command +.DE +Here we have escaped the newline for the sake of appearance. +The command must not involve `\||\|', `&' or `;' +and must not be another control command. +The second form requires the final `\e' to +.B immediately +precede the end-of-line. +.PP +The more general +.I if +statements above also admit a sequence of +.I else\-if +pairs followed by a single +.I else +and an +.I endif, +e.g.: +.DS +\fBif\fR ( expression ) \fBthen\fR + commands +\fBelse\fR \fBif\fR (expression ) \fBthen\fR + commands +\&... + +\fBelse\fR + commands +\fBendif\fR +.DE +.PP +Another important mechanism used in shell scripts is the `:' modifier. +We can use the modifier `:r' here to extract a root of a filename or +`:e' to extract the +.I extension. +Thus if the variable +.I i +has the value +`/mnt/foo.bar' +then +.sp +.in +5 +.nf +% echo $i $i:r $i:e +/mnt/foo.bar /mnt/foo bar +% +.sp +.in -5 +.fi +shows how the `:r' modifier strips off the trailing `.bar' and the +the `:e' modifier leaves only the `bar'. +Other modifiers will take off the last component of a pathname leaving +the head `:h' or all but the last component of a pathname leaving the +tail `:t'. +These modifiers are fully described in the +.I csh +manual pages in the User's Reference Manual. +It is also possible to use the +.I "command substitution" +mechanism described in the next major section to perform modifications +on strings to then reenter the shell's environment. +Since each usage of this mechanism involves the creation of a new process, +it is much more expensive to use than the `:' modification mechanism.\(dd +.FS +\(dd It is also important to note that +the current implementation of the shell limits the number of `:' modifiers +on a `$' substitution to 1. +Thus +.sp +.nf +.in +5 +% echo $i $i:h:t +/a/b/c /a/b:t +% +.in -5 +.fi +.sp +does not do what one would expect. +.FE +Finally, we note that the character `#' lexically introduces a shell +comment in shell scripts (but not from the terminal). +All subsequent characters on the input line after a `#' are discarded +by the shell. +This character can be quoted using `\'' or `\e' to place it in +an argument word. +.NH 2 +Other control structures +.PP +The shell also has control structures +.I while +and +.I switch +similar to those of C. +These take the forms +.DS +\fBwhile\fR ( expression ) + commands +\fBend\fR +.DE +and +.DS +\fBswitch\fR ( word ) + +\fBcase\fR str1: + commands + \fBbreaksw\fR + +\& ... + +\fBcase\fR strn: + commands + \fBbreaksw\fR + +\fBdefault:\fR + commands + \fBbreaksw\fR + +\fBendsw\fR +.DE +For details see the manual section for +.I csh. +C programmers should note that we use +.I breaksw +to exit from a +.I switch +while +.I break +exits a +.I while +or +.I foreach +loop. +A common mistake to make in +.I csh +scripts is to use +.I break +rather than +.I breaksw +in switches. +.PP +Finally, +.I csh +allows a +.I goto +statement, with labels looking like they do in C, i.e.: +.DS +loop: + commands + \fBgoto\fR loop +.DE +.NH 2 +Supplying input to commands +.PP +Commands run from shell scripts receive by default the standard +input of the shell which is running the script. +This is different from previous shells running +under \s-2UNIX\s0. It allows shell scripts to fully participate +in pipelines, but mandates extra notation for commands which are to take +inline data. +.PP +Thus we need a metanotation for supplying inline data to commands in +shell scripts. +As an example, consider this script which runs the editor to +delete leading blanks from the lines in each argument file: +.DS +% cat deblank +# deblank \-\- remove leading blanks +foreach i ($argv) +ed \- $i << \'EOF\' +1,$s/^[ ]*// +w +q +\&\'EOF\' +end +% +.DE +The notation `<< \'EOF\'' +means that the standard input for the +.I ed +command is to come from the text in the shell script file +up to the next line consisting of exactly `\'EOF\''. +The fact that the `EOF' is enclosed in `\'' characters, i.e. quoted, +causes the shell to not perform variable substitution on the +intervening lines. +In general, if any part of the word following the `<<' which the +shell uses to terminate the text to be given to the command is quoted +then these substitutions will not be performed. +In this case since we used the form `1,$' in our editor script +we needed to insure that this `$' was not variable substituted. +We could also have insured this by preceding the `$' here with a `\e', +i.e.: +.DS +1,\e$s/^[ ]*// +.DE +but quoting the `EOF' terminator is a more reliable way of achieving the +same thing. +.NH 2 +Catching interrupts +.PP +If our shell script creates temporary files, we may wish to catch +interruptions of the shell script so that we can clean up +these files. +We can then do +.DS +onintr label +.DE +where +.I label +is a label in our program. +If an interrupt is received the shell will do a +`goto label' +and we can remove the temporary files and then do an +.I exit +command (which is built in to the shell) +to exit from the shell script. +If we wish to exit with a non-zero status we can do +.DS +exit(1) +.DE +e.g. to exit with status `1'. +.NH 2 +What else? +.PP +There are other features of the shell useful to writers of shell +procedures. +The +.I verbose +and +.I echo +options and the related +.I \-v +and +.I \-x +command line options can be used to help trace the actions of the shell. +The +.I \-n +option causes the shell only to read commands and not to execute +them and may sometimes be of use. +.PP +One other thing to note is that +.I csh +will not execute shell scripts which do not begin with the +character `#', that is shell scripts that do not begin with a comment. +Similarly, the `/bin/sh' on your system may well defer to `csh' +to interpret shell scripts which begin with `#'. +This allows shell scripts for both shells to live in harmony. +.PP +There is also another quotation mechanism using `"' which allows +only some of the expansion mechanisms we have so far discussed to occur +on the quoted string and serves to make this string into a single word +as `\'' does. +.bp diff --git a/share/doc/usd/04.csh/csh.4 b/share/doc/usd/04.csh/csh.4 new file mode 100644 index 0000000..7ef24dc --- /dev/null +++ b/share/doc/usd/04.csh/csh.4 @@ -0,0 +1,176 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.4 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.nr H1 3 +.NH +Other, less commonly used, shell features +.NH 2 +Loops at the terminal; variables as vectors +.PP +It is occasionally useful to use the +.I foreach +control structure at the terminal to aid in performing a number +of similar commands. +For instance, there were at one point three shells in use on the Cory \s-2UNIX\s0 +system at Cory Hall, +`/bin/sh', +`/bin/nsh', +and +`/bin/csh'. +To count the number of persons using each shell one could have issued +the commands +.DS +% grep \-c csh$ /etc/passwd +27 +% grep \-c nsh$ /etc/passwd +128 +% grep \-c \-v sh$ /etc/passwd +430 +% +.DE +Since these commands are very similar we can use +.I foreach +to do this more easily. +.DS +% foreach i (\'sh$\' \'csh$\' \'\-v sh$\') +? grep \-c $i /etc/passwd +? end +27 +128 +430 +% +.DE +Note here that the shell prompts for +input with `? ' when reading the body of the loop. +.PP +Very useful with loops are variables which contain lists of filenames +or other words. +You can, for example, do +.DS +% set a=(\`ls\`) +% echo $a +csh.n csh.rm +% ls +csh.n +csh.rm +% echo $#a +2 +% +.DE +The +.I set +command here gave the variable +.I a +a list of all the filenames in the current directory as value. +We can then iterate over these names to perform any chosen function. +.PP +The output of a command within `\`' characters is converted by +the shell to a list of words. +You can also place the `\`' quoted string within `"' characters +to take each (non-empty) line as a component of the variable; +preventing the lines from being split into words at blanks and tabs. +A modifier `:x' exists which can be used later to expand each component +of the variable into another variable splitting it into separate words +at embedded blanks and tabs. +.NH 2 +Braces { ... } in argument expansion +.PP +Another form of filename expansion, alluded +to before involves the characters `{' and `}'. +These characters specify that the contained strings, separated by `,' +are to be consecutively substituted into the containing characters +and the results expanded left to right. +Thus +.DS +A{str1,str2,...strn}B +.DE +expands to +.DS +Astr1B Astr2B ... AstrnB +.DE +This expansion occurs before the other filename expansions, and may +be applied recursively (i.e. nested). +The results of each expanded string are sorted separately, left +to right order being preserved. +The resulting filenames are not required to exist if no other expansion +mechanisms are used. +This means that this mechanism can be used to generate arguments which are +not filenames, but which have common parts. +.PP +A typical use of this would be +.DS +mkdir ~/{hdrs,retrofit,csh} +.DE +to make subdirectories `hdrs', `retrofit' and `csh' +in your home directory. +This mechanism is most useful when the common prefix is longer +than in this example, i.e. +.DS +chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +.DE +.NH 2 +Command substitution +.PP +A command enclosed in `\`' characters is replaced, just before +filenames are expanded, by the output from that command. +Thus it is possible to do +.DS +set pwd=\`pwd\` +.DE +to save the current directory in the variable +.I pwd +or to do +.DS +ex \`grep \-l TRACE *.c\` +.DE +to run the editor +.I ex +supplying as arguments those files whose names end in `.c' +which have the string `TRACE' in them.* +.FS +*Command expansion also occurs in input redirected with `<<' +and within `"' quotations. +Refer to the shell manual section for full details. +.FE +.NH 2 +Other details not covered here +.PP +In particular circumstances it may be necessary to know the exact +nature and order of different substitutions performed by the shell. +The exact meaning of certain combinations of quotations is also +occasionally important. +These are detailed fully in its manual section. +.PP +The shell has a number of command line option flags mostly of use +in writing \s-2UNIX\s0 programs, +and debugging shell scripts. +See the csh(1) manual section for a list of these options. +.bp diff --git a/share/doc/usd/04.csh/csh.a b/share/doc/usd/04.csh/csh.a new file mode 100644 index 0000000..22c8f76 --- /dev/null +++ b/share/doc/usd/04.csh/csh.a @@ -0,0 +1,93 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.a 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.SH +Appendix \- Special characters +.LP +The following table lists the special characters of +.I csh +and the \s-2UNIX\s0 system, giving for each the section(s) in which it +is discussed. +A number of these characters also have special meaning in expressions. +See the +.I csh +manual section +for a complete list. +.ta .75i 1.5i 2.25i +.LP +Syntactic metacharacters +.DS +; 2.4 separates commands to be executed sequentially +| 1.5 separates commands in a pipeline +( ) 2.2,3.6 brackets expressions and variable values +& 2.5 follows commands to be executed without waiting for completion +.DE +.LP +Filename metacharacters +.DS +/ 1.6 separates components of a file's pathname +\&. 1.6 separates root parts of a file name from extensions +? 1.6 expansion character matching any single character +* 1.6 expansion character matching any sequence of characters +[ ] 1.6 expansion sequence matching any single character from a set +~ 1.6 used at the beginning of a filename to indicate home directories +{ } 4.2 used to specify groups of arguments with common parts +.DE +.LP +Quotation metacharacters +.DS +\e 1.7 prevents meta-meaning of following single character +\' 1.7 prevents meta-meaning of a group of characters +" 4.3 like \', but allows variable and command expansion +.DE +.LP +Input/output metacharacters +.DS +< 1.5 indicates redirected input +> 1.3 indicates redirected output +.DE +.LP +Expansion/substitution metacharacters +.DS +$ 3.4 indicates variable substitution +! 2.3 indicates history substitution +: 3.6 precedes substitution modifiers +^ 2.3 used in special forms of history substitution +\` 4.3 indicates command substitution +.DE +.LP +Other metacharacters +.DS +# 1.3,3.6 begins scratch file names; indicates shell comments +\- 1.2 prefixes option (flag) arguments to commands +% 2.6 prefixes job name specifications +.DE +.bp diff --git a/share/doc/usd/04.csh/csh.g b/share/doc/usd/04.csh/csh.g new file mode 100644 index 0000000..ba1b161 --- /dev/null +++ b/share/doc/usd/04.csh/csh.g @@ -0,0 +1,1719 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.g 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.SH +Glossary +.PP +This glossary lists the most important terms introduced in the +introduction to the +shell and gives references to sections of the shell +document for further information about them. +References of the form +`pr (1)' +indicate that the command +.I pr +is in the \s-2UNIX\s0 User Reference manual in section 1. +You can look at an online copy of its manual page by doing +.DS +man 1 pr +.DE +References of the form (2.5) +indicate that more information can be found in section 2.5 of this +manual. +.IP \&\fB.\fR 15n +Your current directory has the name `.' as well as the name printed +by the command +.I pwd; +see also +.I dirs. +The current directory `.' is usually the first +.I component +of the search path contained in the variable +.I path , +thus commands which are in `.' are found first (2.2). +The character `.' is also used in separating +.I components +of filenames +(1.6). +The character `.' at the beginning of a +.I component +of a +.I pathname +is treated specially and not matched by the +.I "filename expansion" +metacharacters `?', `*', and `[' `]' pairs (1.6). +.IP \&\fB..\fR +Each directory has a file `..' in it which is a reference to its +parent directory. +After changing into the directory with +.I chdir , +i.e. +.DS +chdir paper +.DE +you can return to the parent directory by doing +.DS +chdir .. +.DE +The current directory is printed by +.I pwd +(2.7). +.IP a.out +Compilers which create executable images create them, by default, in the +file +.I a.out. +for historical reasons (2.3). +.IP "absolute pathname" +.br +A +.I pathname +which begins with a `/' is +.I absolute +since it specifies the +.I path +of directories from the beginning +of the entire directory system \- called the +.I root +directory. +.I Pathname s +which are not +.I absolute +are called +.I relative +(see definition of +.I "relative pathname" ) +(1.6). +.IP alias +An +.I alias +specifies a shorter or different name for a \s-2UNIX\s0 +command, or a transformation on a command to be performed in +the shell. +The shell has a command +.I alias +which establishes +.I aliases +and can print their current values. +The command +.I unalias +is used to remove +.I aliases +(2.4). +.IP argument +Commands in \s-2UNIX\s0 receive a list of +.I argument +words. +Thus the command +.DS +echo a b c +.DE +consists of the +.I "command name" +`echo' and three +.I argument +words `a', `b' and `c'. +The set of +.I arguments +after the +.I "command name" +is said to be the +.I "argument list" +of the command (1.1). +.IP argv +The list of arguments to a command written in the shell language +(a shell script or shell procedure) is stored in a variable called +.I argv +within the shell. +This name is taken from the conventional name in the +C programming language (3.4). +.IP background +Commands started without waiting for them to complete are called +.I background +commands (2.6). +.IP base +A filename is sometimes thought of as consisting of a +.I base +part, before any `.' character, and an +.I extension +\- the part after +the `.'. See +.I filename +and +.I extension +(1.6) and basename (1). +.IP bg +The +.I bg +command causes a +.I suspended +job to continue execution in the +.I background +(2.6). +.IP bin +A directory containing binaries of programs and shell scripts to be +executed is typically called a +.I bin +directory. +The standard system +.I bin +directories are `/bin' containing the most +heavily used commands and `/usr/bin' which contains most other user +programs. +Programs developed at UC Berkeley live in `/usr/ucb', while locally +written programs live in `/usr/local'. Games are kept in the directory +`/usr/games'. +You can place binaries in any directory. +If you wish to execute them often, the name of the directories +should be a +.I component +of the variable +.I path . +.IP break +.I Break +is a builtin command used to exit from loops within the control +structure of the shell (3.7). +.IP breaksw +The +.I breaksw +builtin command is used to exit from a +.I switch +control structure, like a +.I break +exits from loops (3.7). +.IP builtin +A command executed directly by the shell is called a +.I builtin +command. +Most commands in \s-2UNIX\s0 are not built into the shell, +but rather exist as files in +.I bin +directories. +These commands are accessible because the directories in which +they reside are named in the +.I path +variable. +.IP case +A +.I case +command is used as a label in a +.I switch +statement in the shell's control structure, similar to that of the +language C. +Details are given in the shell documentation `csh (1)' (3.7). +.IP cat +The +.I cat +program catenates a list of specified files on the +.I "standard output" . +It is usually used to look at the contents of a single file on the terminal, +to `cat a file' (1.8, 2.3). +.IP cd +The +.I cd +command is used to change the +.I "working directory" . +With no arguments, +.I cd +changes your +.I "working directory" +to be your +.I home +directory (2.4, 2.7). +.IP chdir +The +.I chdir +command is a synonym for +.I cd . +.I Cd +is usually used because it is easier to type. +.IP chsh +The +.I chsh +command is used to change the shell which you use on \s-2UNIX\s0. +By default, you use a different version of the shell +which resides in `/bin/sh'. +You can change your shell to `/bin/csh' by doing +.DS +chsh your-login-name /bin/csh +.DE +Thus I would do +.DS +chsh bill /bin/csh +.DE +It is only necessary to do this once. +The next time you log in to \s-2UNIX\s0 after doing this command, +you will be using +.I csh +rather than the shell in `/bin/sh' (1.9). +.IP cmp +.I Cmp +is a program which compares files. +It is usually used on binary files, or to see if two files are identical (3.6). +For comparing text files the program +.I diff , +described in `diff (1)' is used. +.IP command +A function performed by the system, either by the shell +(a builtin +.I command ) +or by a program residing in a file in +a directory within the \s-2UNIX\s0 system, is called a +.I command +(1.1). +.IP "command name" +.br +When a command is issued, it consists of a +.I "command name" , +which is the first word of the command, +followed by arguments. +The convention on \s-2UNIX\s0 is that the first word of a +command names the function to be performed (1.1). +.IP "command substitution" +.br +The replacement of a command enclosed in `\`' characters +by the text output by that command +is called +.I "command substitution" +(4.3). +.IP component +A part of a +.I pathname +between `/' characters is called a +.I component +of that +.I pathname . +A variable +which has multiple strings as value is said to have +several +.I component s; +each string is a +.I component +of the variable. +.IP continue +A builtin command which causes execution of the enclosing +.I foreach +or +.I while +loop to cycle prematurely. +Similar to the +.I continue +command in the programming language C (3.6). +.IP control- +Certain special characters, called +.I control +characters, are produced by holding down the \s-2CONTROL\s0 key +on your terminal and simultaneously pressing another character, much like +the \s-2SHIFT\s0 key is used to produce upper case characters. Thus +.I control- c +is produced by holding down the \s-2CONTROL\s0 key while pressing the +`c' key. Usually \s-2UNIX\s0 prints a caret (^) followed by the +corresponding letter when you type a +.I control +character (e.g. `^C' for +.I control- c +(1.8). +.IP "core\ dump" +When a program terminates abnormally, the system places an image +of its current state in a file named `core'. +This +.I "core dump" +can be examined with the system debugger `adb (1)' +or `sdb (1)' in order to determine what went wrong with the program (1.8). +If the shell produces a message of the form +.DS +Illegal instruction (core dumped) +.DE +(where `Illegal instruction' is only one of several possible +messages), you should report this to the author of the program +or a system administrator, +saving the `core' file. +.IP cp +The +.I cp +(copy) program is used to copy the contents of one file into another +file. +It is one of the most commonly used \s-2UNIX\s0 commands (1.6). +.IP csh +The name of the shell +program that this document describes. +.IP \&.cshrc +The file +.I \&.cshrc +in your +.I home +directory is read by each shell as it begins execution. +It is usually used to change the setting of the variable +.I path +and to set +.I alias +parameters which are to take effect globally (2.1). +.IP cwd +The +.I cwd +variable in the shell holds the +.I "absolute pathname" +of the current +.I "working directory" \&. +It is changed by the shell whenever your current +.I "working directory" +changes and should not be changed otherwise (2.2). +.IP date +The +.I date +command prints the current date and time (1.3). +.IP debugging +.I Debugging +is the process of correcting mistakes in programs and shell scripts. +The shell has several options and variables which may be used +to aid in shell +.I debugging +(4.4). +.IP default: +The label +.I default: +is used within shell +.I switch +statements, as it is in the C language +to label the code to be executed if none of the +.I case +labels matches the value switched on (3.7). +.IP \s-2DELETE\s0 +The +\s-2DELETE\s0 +or +\s-2RUBOUT\s0 +key on the terminal normally causes an interrupt to be sent to the current job. +Many users change the interrupt character to be ^C. +.IP detached +A command that continues running in the +.I background +after you logout is said to be +.I detached . +.IP diagnostic +An error message produced by a program is often referred to as a +.I diagnostic . +Most error messages are not written to the +.I "standard output" , +since that is often directed away from the terminal (1.3, 1.5). +Error messsages are instead written to the +.I "diagnostic output" +which may be directed away from the terminal, but usually is not. +Thus +.I diagnostics +will usually appear on the terminal (2.5). +.IP directory +A structure which contains files. +At any time you are in one particular +.I directory +whose names can be printed by the command +.I pwd . +The +.I chdir +command will change you to another +.I directory , +and make the files +in that +.I directory +visible. The +.I directory +in which you are when you first login is your +.I home +directory (1.1, 2.7). +.IP "directory\ stack" +The shell saves the names of previous +.I "working directories" +in the +.I "directory stack" +when you change your current +.I "working directory" +via the +.I pushd +command. The +.I "directory stack" +can be printed by using the +.I dirs +command, which includes your current +.I "working directory" +as the first directory name on the left (2.7). +.IP dirs +The +.I dirs +command prints the shell's +.I "directory stack" +(2.7). +.IP du +The +.I du +command is a program (described in `du (1)') which +prints the number of disk blocks is all directories below +and including your current +.I "working directory" +(2.6). +.IP echo +The +.I echo +command prints its arguments (1.6, 3.6). +.IP else +The +.I else +command is part of the `if-then-else-endif' control +command construct (3.6). +.IP endif +If an +.I if +statement is ended with the word +.I then , +all lines following the +.I if +up to a line starting with the word +.I endif +or +.I else +are executed if the condition between parentheses after the +.I if +is true (3.6). +.IP \s-2EOF\s0 +An +.I "end\f1-\fPof\f1-\fPfile" +is generated by the terminal by a control-d, +and whenever a command reads to the end of a file which +it has been given as input. +Commands receiving input from a +.I pipe +receive an +.I "end\f1-\fPof\f1-\fPfile" +when the command sending them input completes. +Most commands terminate when they receive an +.I "end\f1-\fPof\f1-\fPfile" . +The shell has an option to ignore +.I "end\f1-\fPof\f1-\fPfile" +from a terminal +input which may help you keep from logging out accidentally +by typing too many control-d's (1.1, 1.8, 3.8). +.IP escape +A character `\e' used to prevent the special meaning of a metacharacter +is said to +.I escape +the character from its special meaning. +Thus +.DS +echo \e* +.DE +will echo the character `*' while just +.DS +echo * +.DE +will echo the names of the file in the current directory. +In this example, \e +.I escape s +`*' (1.7). +There is also a non-printing character called +.I escape , +usually labelled +\s-2ESC\s0 +or +\s-2ALTMODE\s0 +on terminal keyboards. +Some older \s-2UNIX\s0 systems use this character to indicate that +output is to be +.I suspended . +Most systems use control-s to stop the output and control-q to start it. +.IP /etc/passwd +This file contains information about the accounts currently on the +system. +It consists of a line for each account with fields separated by +`:' characters (1.8). +You can look at this file by saying +.DS +cat /etc/passwd +.DE +The commands +.I finger +and +.I grep +are often used to search for information in this file. +See `finger (1)', `passwd(5)', and `grep (1)' for more details. +.IP exit +The +.I exit +command is used to force termination of a shell script, +and is built into the shell (3.9). +.IP "exit\ status" +A command which discovers a problem may reflect this back to the command +(such as a shell) which invoked (executed) it. +It does this by returning a non-zero number as its +.I "exit status" , +a status of zero being considered +`normal termination'. +The +.I exit +command can be used to force a shell command script to give a non-zero +.I "exit status" +(3.6). +.IP expansion +The replacement of strings in the shell input which contain metacharacters +by other strings is referred to as the process of +.I expansion . +Thus the replacement of the word `*' by a sorted list of files +in the current directory is a `filename expansion'. +Similarly the replacement of the characters `!!' by the text of +the last command is a `history expansion'. +.I Expansions +are also referred to as +.I substitutions +(1.6, 3.4, 4.2). +.IP expressions +.I Expressions +are used in the shell +to control the conditional structures used in the writing of shell +scripts and in calculating values for these scripts. +The operators available in shell +.I expressions +are those of the language +C (3.5). +.IP extension +Filenames often consist of a +.I base +name and an +.I extension +separated by the character `.'. +By convention, groups of related files often share the same +.I root +name. +Thus if `prog.c' were a C program, then the object file for this +program would be stored in `prog.o'. +Similarly a paper written with the +`\-me' +nroff macro package might be stored in +`paper.me' +while a formatted version of this paper might be kept in +`paper.out' and a list of spelling errors in +`paper.errs' (1.6). +.IP fg +The +.I "job control" +command +.I fg +is used to run a +.I background +or +.I suspended +job in the +.I foreground +(1.8, 2.6). +.IP filename +Each file in \s-2UNIX\s0 has a name consisting of up to 14 characters +and not including the character `/' which is used in +.I pathname +building. Most +.I filenames +do not begin with the character `.', and contain +only letters and digits with perhaps a `.' separating the +.I base +portion of the +.I filename +from an +.I extension +(1.6). +.IP "filename expansion" +.br +.I "Filename expansion" +uses the metacharacters `*', `?' and `[' and `]' +to provide a convenient mechanism for naming files. +Using +.I "filename expansion" +it is easy to name all the files in +the current directory, or all files which have a common +.I root +name. Other +.I "filename expansion" +mechanisms use the metacharacter `~' and allow +files in other users' directories to be named easily (1.6, 4.2). +.IP flag +Many \s-2UNIX\s0 commands accept arguments which are not the names +of files or other users but are used to modify the action of the commands. +These are referred to as +.I flag +options, and by convention consist of one or more letters preceded by +the character `\-' (1.2). +Thus the +.I ls +(list files) command has an option +`\-s' to list the sizes of files. +This is specified +.DS +ls \-s +.DE +.IP foreach +The +.I foreach +command is used in shell scripts and at the terminal to specify +repetition of a sequence of commands while the value of a certain +shell variable ranges through a specified list (3.6, 4.1). +.IP foreground +When commands are executing in the normal way such that the +shell is waiting for them to finish before prompting for another +command they are said to be +.I "foreground jobs" +or +.I "running in the foreground" \&. +This is as opposed to +.I background . +.I Foreground +jobs can be stopped by signals +from the terminal caused by typing different +control characters at the keyboard (1.8, 2.6). +.IP goto +The shell has a command +.I goto +used in shell scripts to transfer control to a given label (3.7). +.IP grep +The +.I grep +command searches through a list of argument files for a specified string. +Thus +.DS +grep bill /etc/passwd +.DE +will print each line in the file +.I "/etc/passwd" +which contains the string `bill'. +Actually, +.I grep +scans for +.I "regular expressions" +in the sense of the editors +`ed (1)' and `ex (1)'. +.I Grep +stands for +`globally find +.I "regular expression" +and print' (2.4). +.IP head +The +.I head +command prints the first few lines of one or more files. +If you have a bunch of files containing text which you are wondering +about it is sometimes useful to run +.I head +with these files as arguments. +This will usually show enough of what is in these files to let you decide +which you are interested in (1.5). +.br +.I Head +is also used to describe the part of a +.I pathname +before and including the last `/' character. The +.I tail +of a +.I pathname +is the part after the last `/'. The `:h' and `:t' modifiers allow the +.I head +or +.I tail +of a +.I pathname +stored in a shell variable to be used (3.6). +.IP history +The +.I history +mechanism of the shell allows previous commands to be repeated, +possibly after modification to correct typing mistakes or to change +the meaning of the command. +The shell has a +.I "history list" +where these commands are kept, and a +.I history +variable which controls how large this list is (2.3). +.IP "home\ directory" +.br +Each user has a +.I "home directory" , +which is given in your entry +in the password file, +.I /etc/passwd . +This is the directory which you are placed in when you first login. +The +.I cd +or +.I chdir +command with no arguments takes you back to this directory, whose +name is recorded in the shell variable +.I home . +You can also access the +.I "home directories" +of other users in forming +filenames using a +.I "filename expansion" +notation and the character `~' (1.6). +.IP if +A conditional command within the shell, the +.I if +command is used in shell command scripts to make decisions +about what course of action to take next (3.6). +.IP ignoreeof +Normally, your shell will exit, printing +`logout' +if you type a control-d at a prompt of `% '. +This is the way you usually log off the system. +You can +.I set +the +.I ignoreeof +variable if you wish in your +.I \&.login +file and then use the command +.I logout +to logout. +This is useful if you sometimes accidentally type too many control-d +characters, logging yourself off +(2.2). +.IP input +Many commands on \s-2UNIX\s0 take information from the terminal or from +files which they then act on. +This information is called +.I input . +Commands normally read for +.I input +from their +.I "standard input" +which is, by default, the terminal. +This +.I "standard input" +can be redirected from a file using a shell metanotation +with the character `<'. +Many commands will also read from a file specified as argument. +Commands placed in +.I pipelines +will read from the output of the previous +command in the +.I pipeline . +The leftmost command in a +.I pipeline +reads from the terminal if +you neither redirect its +.I input +nor give it a filename to use as +.I "standard input" . +Special mechanisms exist for supplying input to commands in shell +scripts (1.5, 3.8). +.IP interrupt +An +.I interrupt +is a signal to a program that is generated by typing ^C. (On older versions +of UNIX the \s-2RUBOUT\s0 or \s-2DELETE\s0 key were used for this purpose.) +It causes most programs to stop execution. +Certain programs, such as the shell and the editors, +handle an +.I interrupt +in special ways, usually by stopping what they +are doing and prompting for another command. +While the shell is executing another command and waiting for it +to finish, the shell does not listen to +.I interrupts. +The shell often wakes up when you hit +.I interrupt +because many commands +die when they receive an +.I interrupt +(1.8, 3.9). +.IP job +One or more commands +typed on the same input line separated by `|' or `;' characters +are run together and are called a +.I job \&. +Simple commands run by themselves without any `|' or `;' characters +are the simplest +.I jobs. +.I Jobs +are classified as +.I foreground , +.I background , +or +.I suspended +(2.6). +.IP "job\ control" +The builtin functions that control the execution of +jobs are called +.I "job control" +commands. These are +.I "bg, fg, stop, kill" +(2.6). +.IP "job\ number" +When each job +is started it is assigned a small number called a +.I "job number" +which is printed next to the job in the output of the +.I jobs +command. This number, preceded by a `%' character, can be used as an argument +to +.I "job control" +commands to indicate +a specific job (2.6). +.IP jobs +The +.I jobs +command prints a table showing +jobs that are either running in the +.I background +or are +.I suspended +(2.6). +.IP kill +A command which sends a +signal +to a job causing it to terminate (2.6). +.IP \&.login +The file +.I \&.login +in your +.I home +directory is read by the shell each time you login to \s-2UNIX\s0 +and the commands there are executed. +There are a number of commands which are usefully placed here, +especially +.I set +commands to the shell itself (2.1). +.IP "login\ shell" +The shell that is started on your terminal when you login is called +your +.I "login shell" . +It is different from other shells which you may run (e.g. on +shell scripts) +in that it reads the +.I \&.login +file before reading commands from the terminal and it reads the +.I \&.logout +file after you logout +(2.1). +.IP logout +The +.I logout +command causes a login shell to exit. +Normally, a login shell will exit when you hit control-d +generating an +.I end\f1-\fPof\f1-\fPfile, +but if you have set +.I ignoreeof +in you +.I \&.login +file then this will not work and you must use +.I logout +to log off the \s-2UNIX\s0 system (2.8). +.IP \&.logout +When you log off of \s-2UNIX\s0 the shell will execute commands from +the file +.I \&.logout +in your +.I home +directory after it prints `logout'. +.IP lpr +The command +.I lpr +is the line printer daemon. +The standard input of +.I lpr +spooled and printed on the \s-2UNIX\s0 line printer. +You can also give +.I lpr +a list of filenames as arguments to be printed. +It is most common to use +.I lpr +as the last component of a +.I pipeline +(2.3). +.IP ls +The +.I ls +(list files) command is one of the most commonly used \s-2UNIX\s0 +commands. +With no argument filenames it prints the names of the files in the +current directory. +It has a number of useful +.I flag +arguments, and can also be given the names of directories +as arguments, in which case it lists the names of the files in these +directories (1.2). +.IP mail +The +.I mail +program is used to send and receive messages from other \s-2UNIX\s0 +users (1.1, 2.1), whether they are logged on or not. +.IP make +The +.I make +command is used to maintain one or more related files and to +organize functions to be performed on these files. +In many ways +.I make +is easier to use, and more helpful than +shell command scripts (3.2). +.IP makefile +The file containing commands for +.I make +is called +.I makefile +or +.I Makefile +(3.2). +.IP manual +The +.I manual +often referred to is the +`\s-2UNIX\s0 manual'. +It contains 8 numbered sections with a description of each \s-2UNIX\s0 +program (section 1), system call (section 2), subroutine (section 3), +device (section 4), special data structure (section 5), game (section 6), +miscellaneous item (section 7) and system administration program (section 8). +There are also supplementary documents (tutorials and reference guides) +for individual programs which require explanation in more detail. +An online version of the +.I manual +is accessible through the +.I man +command. +Its documentation can be obtained online via +.DS +man man +.DE +If you can't decide what manual page to look in, try the +.I apropos (1) +command. +The supplementary documents are in subdirectories of /usr/doc. +.IP metacharacter +.br +Many characters which are neither letters nor digits have special meaning +either to the shell or to \s-2UNIX\s0. +These characters are called +.I metacharacters . +If it is necessary to place these characters in arguments to commands +without them having their special meaning then they must be +.I quoted . +An example of a +.I metacharacter +is the character `>' which is used +to indicate placement of output into a file. +For the purposes of the +.I history +mechanism, +most unquoted +.I metacharacters +form separate words (1.4). +The appendix to this user's manual lists the +.I metacharacters +in groups by their function. +.IP mkdir +The +.I mkdir +command is used to create a new directory. +.IP modifier +Substitutions with the +.I history +mechanism, keyed by the character `!' +or of variables using the metacharacter `$', are often subjected +to modifications, indicated by placing the character `:' after the +substitution and following this with the +.I modifier +itself. +The +.I "command substitution" +mechanism can also be used to perform modification in a similar way, +but this notation is less clear (3.6). +.IP more +The program +.I more +writes a file on your terminal allowing you to control how much text +is displayed at a time. +.I More +can move through the file screenful by screenful, line by line, +search forward for a string, or start again at the beginning of the file. +It is generally the easiest way of viewing a file (1.8). +.IP noclobber +The shell has a variable +.I noclobber +which may be set in the file +.I \&.login +to prevent accidental destruction of files by the `>' output redirection +metasyntax of the shell (2.2, 2.5). +.IP noglob +The shell variable +.I noglob +is set to suppress the +.I "filename expansion" +of arguments containing the metacharacters `~', `*', `?', `[' and `]' (3.6). +.IP notify +The +.I notify +command tells the shell to report on the termination of a specific +.I "background job" +at the exact time it occurs as opposed to waiting +until just before the next prompt to report the termination. +The +.I notify +variable, if set, causes the shell to always report the termination +of +.I background +jobs exactly when they occur (2.6). +.IP onintr +The +.I onintr +command is built into the shell and is used to control the action +of a shell command script when an +.I interrupt +signal is received (3.9). +.IP output +Many commands in \s-2UNIX\s0 result in some lines of text which are +called their +.I output. +This +.I output +is usually placed on what is known as the +.I "standard output" +which is normally connected to the user's terminal. +The shell has a syntax using the metacharacter `>' for redirecting +the +.I "standard output" +of a command to a file (1.3). +Using the +.I pipe +mechanism and the metacharacter `|' it is also possible for +the +.I "standard output" +of one command to become the +.I "standard input" +of another command (1.5). +Certain commands such as the line printer daemon +.I p +do not place their results on the +.I "standard output" +but rather in more +useful places such as on the line printer (2.3). +Similarly the +.I write +command places its output on another user's terminal rather than its +.I "standard output" +(2.3). +Commands also have a +.I "diagnostic output" +where they write their error messages. +Normally these go to the terminal even if the +.I "standard output" +has been sent to a file or another command, but it is possible +to direct error diagnostics along with +.I "standard output" +using a special metanotation (2.5). +.IP path +The shell has a variable +.I path +which gives the names of the directories in which it searches for +the commands which it is given. +It always checks first to see if the command it is given is +built into the shell. +If it is, then it need not search for the command as it can do it internally. +If the command is not builtin, then the shell searches for a file +with the name given in each of the directories in the +.I path +variable, left to right. +Since the normal definition of the +.I path +variable is +.DS +path (. /usr/ucb /bin /usr/bin) +.DE +the shell normally looks in the current directory, and then in +the standard system directories `/usr/ucb', `/bin' and `/usr/bin' for the named +command (2.2). +If the command cannot be found the shell will print an error diagnostic. +Scripts of shell commands will be executed using another shell to interpret +them if they have `execute' permission set. +This is normally true because a command of the form +.DS +chmod 755 script +.DE +was executed to turn this execute permission on (3.3). +If you add new commands to a directory in the +.I path , +you should issue +the command +.I rehash +(2.2). +.IP pathname +A list of names, separated by `/' characters, forms a +.I pathname. +Each +.I component, +between successive `/' characters, names a directory +in which the next +.I component +file resides. +.I Pathnames +which begin with the character `/' are interpreted relative +to the +.I root +directory in the file system. +Other +.I pathnames +are interpreted relative to the current directory +as reported by +.I pwd. +The last component of a +.I pathname +may name a directory, but +usually names a file. +.IP pipeline +A group of commands which are connected together, the +.I "standard output" +of each connected to the +.I "standard input" +of the next, +is called a +.I pipeline. +The +.I pipe +mechanism used to connect these commands is indicated by +the shell metacharacter `|' (1.5, 2.3). +.IP popd +The +.I popd +command changes the shell's +.I "working directory" +to the directory you most recently left using the +.I pushd +command. It returns to the directory without having to type its name, +forgetting the name of the current +.I "working directory" +before doing so (2.7). +.IP port +The part of a computer system to which each terminal is +connected is called a +.I port . +Usually the system has a fixed number of +.I ports , +some of which are connected to telephone lines +for dial-up access, and some of which are permanently +wired directly to specific terminals. +.IP pr +The +.I pr +command is used to prepare listings of the contents of files +with headers giving the name of the file and the date and +time at which the file was last modified (2.3). +.IP printenv +The +.I printenv +command is used +to print the current setting of variables in the environment +(2.8). +.IP process +An instance of a running program is called a +.I process +(2.6). +\s-2UNIX\s0 assigns each +.I process +a unique number when it is +started \- called the +.I "process number" . +.I "Process numbers" +can be used to stop individual +.I processes +using the +.I kill +or +.I stop +commands when the +.I processes +are part of a detached +.I background +job. +.IP program +Usually synonymous with +.I command ; +a binary file or shell command script +which performs a useful function is often +called a +.I program . +.IP prompt +Many programs will print a +.I prompt +on the terminal when they expect input. +Thus the editor +`ex (1)' will print a `:' when it expects input. +The shell +.I prompts +for input with `% ' and occasionally with `? ' when +reading commands from the terminal (1.1). +The shell has a variable +.I prompt +which may be set to a different value to change the shell's main +.I prompt . +This is mostly used when debugging the shell (2.8). +.IP pushd +The +.I pushd +command, which means `push directory', changes the shell's +.I "working directory" +and also remembers the current +.I "working directory" +before the change is made, allowing you to return to the same +directory via the +.I popd +command later without retyping its name (2.7). +.IP ps +The +.I ps +command is used to show the processes you are currently running. +Each process is shown with its unique process number, +an indication of the terminal name it is attached to, +an indication of the state of the process (whether it is running, +stopped, awaiting some event (sleeping), and whether it is swapped out), +and the amount of \s-2CPU\s0 time it has used so far. +The command is identified by printing some of the words used +when it was invoked (2.6). +Shells, such as the +.I csh +you use to run the +.I ps +command, are not normally shown in the output. +.IP pwd +The +.I pwd +command prints the full +.I pathname +of the current +.I "working directory" \&. +The +.I dirs +builtin command is usually a better and faster choice. +.IP quit +The +.I quit +signal, generated by a control-\e, +is used to terminate programs which are behaving unreasonably. +It normally produces a core image file (1.8). +.IP quotation +The process by which metacharacters are prevented their special +meaning, usually by using the character `\' in pairs, or by +using the character `\e', is referred to as +.I quotation +(1.7). +.IP redirection +The routing of input or output from or to a file is known +as +.I redirection +of input or output (1.3). +.IP rehash +The +.I rehash +command tells the shell to rebuild its internal table of which commands +are found in which directories in your +.I path . +This is necessary when a new program is installed in one of these +directories (2.8). +.IP "relative pathname" +.br +A +.I pathname +which does not begin with a `/' is called a +.I "relative pathname" +since it is interpreted +.I relative +to the current +.I "working directory" . +The first +.I component +of such a +.I pathname +refers to some file or directory in the +.I "working directory" , +and subsequent +.I components +between `/' characters refer to directories below the +.I "working directory" . +.I Pathnames +that are not +.I relative +are called +.I "absolute pathnames" +(1.6). +.IP repeat +The +.I repeat +command iterates another command a specified number of times. +.IP root +The directory +that is at the top of the entire directory structure is called the +.I root +directory since it is the `root' of the entire tree structure of +directories. The name used in +.I pathnames +to indicate the +.I root +is `/'. +.I Pathnames +starting with `/' are said to be +.I absolute +since they start at the +.I root +directory. +.I Root +is also used as the part of a +.I pathname +that is left after removing +the +.I extension . +See +.I filename +for a further explanation (1.6). +.IP \s-2RUBOUT\s0 +The \s-2RUBOUT\s0 or \s-2DELETE\s0 +key is often used to erase the previously typed character; some users +prefer the \s-2BACKSPACE\s0 for this purpose. On older versions of \s-2UNIX\s0 +this key served as the \s-2INTR\s0 character. +.IP "scratch file" +Files whose names begin with a `#' are referred to as +.I "scratch files" , +since they are automatically removed by the system after a couple of +days of non-use, or more frequently if disk space becomes tight (1.3). +.IP script +Sequences of shell commands placed in a file are called shell command +.I scripts . +It is often possible to perform simple tasks using these +.I scripts +without writing a program in a language such as C, by +using the shell to selectively run other programs (3.3, 3.10). +.IP set +The builtin +.I set +command is used to assign new values to shell variables +and to show the values of the current variables. +Many shell variables have special meaning to the shell itself. +Thus by using the +.I set +command the behavior of the shell can be affected (2.1). +.IP setenv +Variables in the environment `environ (5)' +can be changed by using the +.I setenv +builtin command (2.8). +The +.I printenv +command can be used to print the value of the variables in the environment. +.IP shell +A +.I shell +is a command language interpreter. +It is possible to write and run your own +.I shell , +as +.I shells +are no different than any other programs as far as the +system is concerned. +This manual deals with the details of one particular +.I shell , +called +.I csh. +.IP "shell script" +See +.I script +(3.3, 3.10). +.IP signal +A +.I signal +in \s-2UNIX\s0 is a short message that is sent to a running program +which causes something to happen to that process. +.I Signals +are sent either by typing special +.I control +characters on the keyboard or by using the +.I kill +or +.I stop +commands (1.8, 2.6). +.IP sort +The +.I sort +program sorts a sequence of lines in ways that can be controlled +by argument +.I flags +(1.5). +.IP source +The +.I source +command causes the shell to read commands from a specified file. +It is most useful for reading files such as +.I \&.cshrc +after changing them (2.8). +.IP "special character" +.br +See +.I metacharacters +and the +appendix to this manual. +.IP standard +We refer often to the +.I "standard input" +and +.I "standard output" +of commands. +See +.I input +and +.I output +(1.3, 3.8). +.IP status +A command normally returns a +.I status +when it finishes. +By convention a +.I status +of zero indicates that the command succeeded. +Commands may return non-zero +.I status +to indicate that some abnormal event has occurred. +The shell variable +.I status +is set to the +.I status +returned by the last command. +It is most useful in shell commmand scripts (3.6). +.IP stop +The +.I stop +command causes a +.I background +job to become +.I suspended +(2.6). +.IP string +A sequential group of characters taken together is called a +.I string \&. +.I Strings +can contain any printable characters (2.2). +.IP stty +The +.I stty +program changes certain parameters inside \s-2UNIX\s0 which determine +how your terminal is handled. See `stty (1)' for a complete description (2.6). +.IP substitution +The shell implements a number of +.I substitutions +where sequences indicated by metacharacters are replaced by other sequences. +Notable examples of this are history +.I substitution +keyed by the +metacharacter `!' and variable +.I substitution +indicated by `$'. +We also refer to +.I substitutions +as +.I expansions +(3.4). +.IP suspended +A job becomes +.I suspended +after a \s-2STOP\s0 signal is sent to it, either by typing a +.I control -z +at the terminal (for +.I foreground +jobs) or by using the +.I stop +command (for +.I background +jobs). When +.I suspended , +a job temporarily stops running until it is restarted by either the +.I fg +or +.I bg +command (2.6). +.IP switch +The +.I switch +command of the shell allows the shell +to select one of a number of sequences of commands based on an +argument string. +It is similar to the +.I switch +statement in the language C (3.7). +.IP termination +When a command which is being executed finishes we say it undergoes +.I termination +or +.I terminates. +Commands normally terminate when they read an +.I end\f1-\fPof\f1-\fPfile +from their +.I "standard input" . +It is also possible to terminate commands by sending them +an +.I interrupt +or +.I quit +signal (1.8). +The +.I kill +program terminates specified jobs (2.6). +.IP then +The +.I then +command is part of the shell's +`if-then-else-endif' control construct used in command scripts (3.6). +.IP time +The +.I time +command can be used to measure the amount of \s-2CPU\s0 +and real time consumed by a specified command as well +as the amount of disk i/o, memory utilized, and number +of page faults and swaps taken by the command (2.1, 2.8). +.IP tset +The +.I tset +program is used to set standard erase and kill characters +and to tell the system what kind of terminal you are using. +It is often invoked in a +.I \&.login +file (2.1). +.IP tty +The word +.I tty +is a historical abbreviation for `teletype' which is frequently used +in \s-2UNIX\s0 to indicate the +.I port +to which a given terminal is connected. The +.I tty +command will print the name of the +.I tty +or +.I port +to which your terminal is presently connected. +.IP unalias +The +.I unalias +command removes aliases (2.8). +.IP \s-2UNIX\s0 +\s-2UNIX\s0 is an operating system on which +.I csh +runs. +\s-2UNIX\s0 provides facilities which allow +.I csh +to invoke other programs such as editors and text formatters which +you may wish to use. +.IP unset +The +.I unset +command removes the definitions of shell variables (2.2, 2.8). +.IP "variable expansion" +.br +See +.I variables +and +.I expansion +(2.2, 3.4). +.IP variables +.I Variables +in +.I csh +hold one or more strings as value. +The most common use of +.I variables +is in controlling the behavior +of the shell. +See +.I path , +.I noclobber , +and +.I ignoreeof +for examples. +.I Variables +such as +.I argv +are also used in writing shell programs (shell command scripts) +(2.2). +.IP verbose +The +.I verbose +shell variable can be set to cause commands to be echoed +after they are history expanded. +This is often useful in debugging shell scripts. +The +.I verbose +variable is set by the shell's +.I \-v +command line option (3.10). +.IP wc +The +.I wc +program calculates the number of characters, words, and lines in the +files whose names are given as arguments (2.6). +.IP while +The +.I while +builtin control construct is used in shell command scripts (3.7). +.IP word +A sequence of characters which forms an argument to a command is called +a +.I word . +Many characters which are neither letters, digits, `\-', `.' nor `/' +form +.I words +all by themselves even if they are not surrounded +by blanks. +Any sequence of characters may be made into a +.I word +by surrounding it +with `\'' characters +except for the characters `\'' and `!' which require special treatment +(1.1). +This process of placing special characters in +.I words +without their special meaning is called +.I quoting . +.IP "working directory" +.br +At any given time you are in one particular directory, called +your +.I "working directory" . +This directory's name is printed by the +.I pwd +command and the files listed by +.I ls +are the ones in this directory. +You can change +.I "working directories" +using +.I chdir . +.IP write +The +.I write +command is an obsolete way of communicating with other users who are logged in to +\s-2UNIX\s0 (you have to take turns typing). If you are both using display +terminals, use \fItalk\fP(1), which is much more pleasant. diff --git a/share/doc/usd/04.csh/tabs b/share/doc/usd/04.csh/tabs new file mode 100644 index 0000000..196d437 --- /dev/null +++ b/share/doc/usd/04.csh/tabs @@ -0,0 +1,32 @@ +.\"- +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tabs 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n diff --git a/share/doc/usd/05.dc/Makefile b/share/doc/usd/05.dc/Makefile index 2b01e0c..fd1cffc 100644 --- a/share/doc/usd/05.dc/Makefile +++ b/share/doc/usd/05.dc/Makefile @@ -4,6 +4,5 @@ VOLUME= usd/05.dc SRCS= dc MACROS= -ms -SRCDIR= ${.CURDIR}/../../../../usr.bin/dc/USD.doc .include <bsd.doc.mk> diff --git a/share/doc/usd/05.dc/dc b/share/doc/usd/05.dc/dc new file mode 100644 index 0000000..4caa0f4 --- /dev/null +++ b/share/doc/usd/05.dc/dc @@ -0,0 +1,753 @@ +.\" $FreeBSD$ +.\" $OpenBSD: dc,v 1.2 2003/09/22 19:08:27 otto Exp $ +.\" +.\" Copyright (C) Caldera International Inc. 2001-2002. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed or owned by Caldera +.\" International, Inc. +.\" 4. Neither the name of Caldera International, Inc. nor the names of other +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA +.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, +.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" @(#)dc 8.1 (Berkeley) 6/8/93 +.\" +.EH 'USD:5-%''DC \- An Interactive Desk Calculator' +.OH 'DC \- An Interactive Desk Calculator''USD:5-%' +.\".RP +.\" ....TM 75-1271-8 39199 39199-11 +.ND +.TL +DC \- An Interactive Desk Calculator +.AU "MH 2C-524" 3878 +Robert Morris +.AU +Lorinda Cherry +.AI +.\" .MH +.AB +DC is an interactive desk calculator program implemented +on the +.UX +time-sharing system to do arbitrary-precision +integer arithmetic. +It has provision for manipulating scaled fixed-point numbers and +for input and output in bases other than decimal. +.PP +The size of numbers that can be manipulated is limited +only by available core storage. +On typical implementations of +.UX , +the size of numbers that +can be handled varies from several hundred digits on the smallest +systems to several thousand on the largest. +.AE +.PP +.SH +.PP +.ft I +Editor's note: the description of the implementation details of DC in this +paper is only valid for the original version of DC. +The current version of DC uses a different approach. +.ft +.PP +DC is an arbitrary precision arithmetic package implemented +on the +.UX +time-sharing system +in the form of an interactive desk calculator. +It works like a stacking calculator using reverse Polish notation. +Ordinarily DC operates on decimal integers, but one may +specify an input base, output base, and a number of fractional +digits to be maintained. +.PP +A language called BC [1] has been developed which accepts +programs written in the familiar style of higher-level +programming languages and compiles output which is +interpreted by DC. +Some of the commands described below were designed +for the compiler interface and are not easy for a human user +to manipulate. +.PP +Numbers that are typed into DC are put on a push-down +stack. +DC commands work by taking the top number or two +off the stack, performing the desired operation, and pushing the result +on the stack. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +.SH +SYNOPTIC DESCRIPTION +.PP +Here we describe the DC commands that are intended +for use by people. The additional commands that are +intended to be invoked by compiled output are +described in the detailed description. +.PP +Any number of commands are permitted on a line. +Blanks and new-line characters are ignored except within numbers +and in places where a register name is expected. +.PP +The following constructions are recognized: +.SH +number +.IP +The value of the number is pushed onto the main stack. +A number is an unbroken string of the digits 0-9 +and the capital letters A\-F which are treated as digits +with values 10\-15 respectively. +The number may be preceded by an underscore _ to input a +negative number. +Numbers may contain decimal points. +.SH ++ \- * % ^ +.IP +The +top two values on the stack are added +(\fB+\fP), +subtracted +(\fB\-\fP), +multiplied (\fB*\fP), +divided (\fB/\fP), +remaindered (\fB%\fP), +or exponentiated (^). +The two entries are popped off the stack; +the result is pushed on the stack in their place. +The result of a division is an integer truncated toward zero. +See the detailed description below for the treatment of +numbers with decimal points. +An exponent must not have any digits after the decimal point. +.SH +s\fIx\fP +.IP +The +top of the main stack is popped and stored into +a register named \fIx\fP, where \fIx\fP may be any character. +If +the +.ft B +s +.ft +is capitalized, +.ft I +x +.ft +is treated as a stack and the value is pushed onto it. +Any character, even blank or new-line, is a valid register name. +.SH +l\fIx\fP +.IP +The +value in register +.ft I +x +.ft +is pushed onto the stack. +The register +.ft I +x +.ft +is not altered. +If the +.ft B +l +.ft +is capitalized, +register +.ft I +x +.ft +is treated as a stack and its top value is popped onto the main stack. +.LP +All registers start with empty value which is treated as a zero +by the command \fBl\fP and is treated as an error by the command \fBL\fP. +.SH +d +.IP +The +top value on the stack is duplicated. +.SH +p +.IP +The top value on the stack is printed. +The top value remains unchanged. +.SH +f +.IP +All values on the stack and in registers are printed. +.SH +x +.IP +treats the top element of the stack as a character string, +removes it from the stack, and +executes it as a string of DC commands. +.SH +[ ... ] +.IP +puts the bracketed character string onto the top of the stack. +.SH +q +.IP +exits the program. +If executing a string, the recursion level is +popped by two. +If +.ft B +q +.ft +is capitalized, +the top value on the stack is popped and the string execution level is popped +by that value. +.SH +<\fIx\fP >\fIx\fP =\fIx\fP !<\fIx\fP !>\fIx\fP !=\fIx\fP +.IP +The +top two elements of the stack are popped and compared. +Register +.ft I +x +.ft +is executed if they obey the stated +relation. +Exclamation point is negation. +.SH +v +.IP +replaces the top element on the stack by its square root. +The square root of an integer is truncated to an integer. +For the treatment of numbers with decimal points, see +the detailed description below. +.SH +! +.IP +interprets the rest of the line as a +.UX +command. +Control returns to DC when the +.UX +command terminates. +.SH +c +.IP +All values on the stack are popped; the stack becomes empty. +.SH +i +.IP +The top value on the stack is popped and used as the +number radix for further input. +If \fBi\fP is capitalized, the value of +the input base is pushed onto the stack. +No mechanism has been provided for the input of arbitrary +numbers in bases less than 1 or greater than 16. +.SH +o +.IP +The top value on the stack is popped and used as the +number radix for further output. +If \fBo\fP is capitalized, the value of the output +base is pushed onto the stack. +.SH +k +.IP +The top of the stack is popped, and that value is used as +a scale factor +that influences the number of decimal places +that are maintained during multiplication, division, and exponentiation. +The scale factor must be greater than or equal to zero and +less than 100. +If \fBk\fP is capitalized, the value of the scale factor +is pushed onto the stack. +.SH +z +.IP +The value of the stack level is pushed onto the stack. +.SH +? +.IP +A line of input is taken from the input source (usually the console) +and executed. +.SH +DETAILED DESCRIPTION +.SH +Internal Representation of Numbers +.PP +Numbers are stored internally using a dynamic storage allocator. +Numbers are kept in the form of a string +of digits to the base 100 stored one digit per byte +(centennial digits). +The string is stored with the low-order digit at the +beginning of the string. +For example, the representation of 157 +is 57,1. +After any arithmetic operation on a number, care is taken +that all digits are in the range 0\-99 and that +the number has no leading zeros. +The number zero is represented by the empty string. +.PP +Negative numbers are represented in the 100's complement +notation, which is analogous to two's complement notation for binary +numbers. +The high order digit of a negative number is always \-1 +and all other digits are in the range 0\-99. +The digit preceding the high order \-1 digit is never a 99. +The representation of \-157 is 43,98,\-1. +We shall call this the canonical form of a number. +The advantage of this kind of representation of negative +numbers is ease of addition. When addition is performed digit +by digit, the result is formally correct. The result need only +be modified, if necessary, to put it into canonical form. +.PP +Because the largest valid digit is 99 and the byte can +hold numbers twice that large, addition can be carried out +and the handling of carries done later when +that is convenient, as it sometimes is. +.PP +An additional byte is stored with each number beyond +the high order digit to indicate the number of +assumed decimal digits after the decimal point. The representation +of .001 is 1,\fI3\fP +where the scale has been italicized to emphasize the fact that it +is not the high order digit. +The value of this extra byte is called the +.ft B +scale factor +.ft +of the number. +.SH +The Allocator +.PP +DC uses a dynamic string storage allocator +for all of its internal storage. +All reading and writing of numbers internally is done through +the allocator. +Associated with each string in the allocator is a four-word header containing pointers +to the beginning of the string, the end of the string, +the next place to write, and the next place to read. +Communication between the allocator and DC +is done via pointers to these headers. +.PP +The allocator initially has one large string on a list +of free strings. All headers except the one pointing +to this string are on a list of free headers. +Requests for strings are made by size. +The size of the string actually supplied is the next higher +power of 2. +When a request for a string is made, the allocator +first checks the free list to see if there is +a string of the desired size. +If none is found, the allocator finds the next larger free string and splits it repeatedly until +it has a string of the right size. +Left-over strings are put on the free list. +If there are no larger strings, +the allocator tries to coalesce smaller free strings into +larger ones. +Since all strings are the result +of splitting large strings, +each string has a neighbor that is next to it in core +and, if free, can be combined with it to make a string twice as long. +This is an implementation of the `buddy system' of allocation +described in [2]. +.PP +Failing to find a string of the proper length after coalescing, +the allocator asks the system for more space. +The amount of space on the system is the only limitation +on the size and number of strings in DC. +If at any time in the process of trying to allocate a string, the allocator runs out of +headers, it also asks the system for more space. +.PP +There are routines in the allocator for reading, writing, copying, rewinding, +forward-spacing, and backspacing strings. +All string manipulation is done using these routines. +.PP +The reading and writing routines +increment the read pointer or write pointer so that +the characters of a string are read or written in +succession by a series of read or write calls. +The write pointer is interpreted as the end of the +information-containing portion of a string and a call +to read beyond that point returns an end-of-string indication. +An attempt to write beyond the end of a string +causes the allocator to +allocate a larger space and then copy +the old string into the larger block. +.SH +Internal Arithmetic +.PP +All arithmetic operations are done on integers. +The operands (or operand) needed for the operation are popped +from the main stack and their scale factors stripped off. +Zeros are added or digits removed as necessary to get +a properly scaled result from the internal arithmetic routine. +For example, if the scale of the operands is different and decimal +alignment is required, as it is for +addition, zeros are appended to the operand with the smaller +scale. +After performing the required arithmetic operation, +the proper scale factor is appended to the end of the number before +it is pushed on the stack. +.PP +A register called \fBscale\fP plays a part +in the results of most arithmetic operations. +\fBscale\fP is the bound on the number of decimal places retained in +arithmetic computations. +\fBscale\fP may be set to the number on the top of the stack +truncated to an integer with the \fBk\fP command. +\fBK\fP may be used to push the value of \fBscale\fP on the stack. +\fBscale\fP must be greater than or equal to 0 and less than 100. +The descriptions of the individual arithmetic operations will +include the exact effect of \fBscale\fP on the computations. +.SH +Addition and Subtraction +.PP +The scales of the two numbers are compared and trailing +zeros are supplied to the number with the lower scale to give both +numbers the same scale. The number with the smaller scale is +multiplied by 10 if the difference of the scales is odd. +The scale of the result is then set to the larger of the scales +of the two operands. +.PP +Subtraction is performed by negating the number +to be subtracted and proceeding as in addition. +.PP +Finally, the addition is performed digit by digit from the +low order end of the number. The carries are propagated +in the usual way. +The resulting number is brought into canonical form, which may +require stripping of leading zeros, or for negative numbers +replacing the high-order configuration 99,\-1 by the digit \-1. +In any case, digits which are not in the range 0\-99 must +be brought into that range, propagating any carries or borrows +that result. +.SH +Multiplication +.PP +The scales are removed from the two operands and saved. +The operands are both made positive. +Then multiplication is performed in +a digit by digit manner that exactly mimics the hand method +of multiplying. +The first number is multiplied by each digit of the second +number, beginning with its low order digit. The intermediate +products are accumulated into a partial sum which becomes the +final product. +The product is put into the canonical form and its sign is +computed from the signs of the original operands. +.PP +The scale of the result is set equal to the sum +of the scales of the two operands. +If that scale is larger than the internal register +.ft B +scale +.ft +and also larger than both of the scales of the two operands, +then the scale of the result is set equal to the largest +of these three last quantities. +.SH +Division +.PP +The scales are removed from the two operands. +Zeros are appended or digits removed from the dividend to make +the scale of the result of the integer division equal to +the internal quantity +\fBscale\fP. +The signs are removed and saved. +.PP +Division is performed much as it would be done by hand. +The difference of the lengths of the two numbers +is computed. +If the divisor is longer than the dividend, +zero is returned. +Otherwise the top digit of the divisor is divided into the top +two digits of the dividend. +The result is used as the first (high-order) digit of the +quotient. +It may turn out be one unit too low, but if it is, the next +trial quotient will be larger than 99 and this will be +adjusted at the end of the process. +The trial digit is multiplied by the divisor and the result subtracted +from the dividend and the process is repeated to get +additional quotient digits until the remaining +dividend is smaller than the divisor. +At the end, the digits of the quotient are put into +the canonical form, with propagation of carry as needed. +The sign is set from the sign of the operands. +.SH +Remainder +.PP +The division routine is called and division is performed +exactly as described. The quantity returned is the remains of the +dividend at the end of the divide process. +Since division truncates toward zero, remainders have the same +sign as the dividend. +The scale of the remainder is set to +the maximum of the scale of the dividend and +the scale of the quotient plus the scale of the divisor. +.SH +Square Root +.PP +The scale is stripped from the operand. +Zeros are added if necessary to make the +integer result have a scale that is the larger of +the internal quantity +\fBscale\fP +and the scale of the operand. +.PP +The method used to compute sqrt(y) is Newton's method +with successive approximations by the rule +.EQ +x sub {n+1} ~=~ half ( x sub n + y over x sub n ) +.EN +The initial guess is found by taking the integer square root +of the top two digits. +.SH +Exponentiation +.PP +Only exponents with zero scale factor are handled. If the exponent is +zero, then the result is 1. If the exponent is negative, then +it is made positive and the base is divided into one. The scale +of the base is removed. +.PP +The integer exponent is viewed as a binary number. +The base is repeatedly squared and the result is +obtained as a product of those powers of the base that +correspond to the positions of the one-bits in the binary +representation of the exponent. +Enough digits of the result +are removed to make the scale of the result the same as if the +indicated multiplication had been performed. +.SH +Input Conversion and Base +.PP +Numbers are converted to the internal representation as they are read +in. +The scale stored with a number is simply the number of fractional digits input. +Negative numbers are indicated by preceding the number with a \fB\_\fP (an +underscore). +The hexadecimal digits A\-F correspond to the numbers 10\-15 regardless of input base. +The \fBi\fP command can be used to change the base of the input numbers. +This command pops the stack, truncates the resulting number to an integer, +and uses it as the input base for all further input. +The input base is initialized to 10 but may, for example be changed to +8 or 16 to do octal or hexadecimal to decimal conversions. +The command \fBI\fP will push the value of the input base on the stack. +.SH +Output Commands +.PP +The command \fBp\fP causes the top of the stack to be printed. +It does not remove the top of the stack. +All of the stack and internal registers can be output +by typing the command \fBf\fP. +The \fBo\fP command can be used to change the output base. +This command uses the top of the stack, truncated to an integer as +the base for all further output. +The output base in initialized to 10. +It will work correctly for any base. +The command \fBO\fP pushes the value of the output base on the stack. +.SH +Output Format and Base +.PP +The input and output bases only affect +the interpretation of numbers on input and output; they have no +effect on arithmetic computations. +Large numbers are output with 70 characters per line; +a \\ indicates a continued line. +All choices of input and output bases work correctly, although not all are +useful. +A particularly useful output base is 100000, which has the effect of +grouping digits in fives. +Bases of 8 and 16 can be used for decimal-octal or decimal-hexadecimal +conversions. +.SH +Internal Registers +.PP +Numbers or strings may be stored in internal registers or loaded on the stack +from registers with the commands \fBs\fP and \fBl\fP. +The command \fBs\fIx\fR pops the top of the stack and +stores the result in register \fBx\fP. +\fIx\fP can be any character. +\fBl\fIx\fR puts the contents of register \fBx\fP on the top of the stack. +The \fBl\fP command has no effect on the contents of register \fIx\fP. +The \fBs\fP command, however, is destructive. +.SH +Stack Commands +.PP +The command \fBc\fP clears the stack. +The command \fBd\fP pushes a duplicate of the number on the top of the stack +on the stack. +The command \fBz\fP pushes the stack size on the stack. +The command \fBX\fP replaces the number on the top of the stack +with its scale factor. +The command \fBZ\fP replaces the top of the stack +with its length. +.SH +Subroutine Definitions and Calls +.PP +Enclosing a string in \fB[ ]\fP pushes the ascii string on the stack. +The \fBq\fP command quits or in executing a string, pops the recursion levels by two. +.SH +Internal Registers \- Programming DC +.PP +The load and store +commands together with \fB[ ]\fP to store strings, \fBx\fP to execute +and the testing commands `<', `>', `=', `!<', `!>', `!=' can be used to program +DC. +The \fBx\fP command assumes the top of the stack is an string of DC commands +and executes it. +The testing commands compare the top two elements on the stack and if the relation holds, execute the register +that follows the relation. +For example, to print the numbers 0-9, +.DS +[lip1+ si li10>a]sa +0si lax +.DE +.SH +Push-Down Registers and Arrays +.PP +These commands were designed for used by a compiler, not by +people. +They involve push-down registers and arrays. +In addition to the stack that commands work on, DC can be thought +of as having individual stacks for each register. +These registers are operated on by the commands \fBS\fP and \fBL\fP. +\fBS\fIx\fR pushes the top value of the main stack onto the stack for +the register \fIx\fP. +\fBL\fIx\fR pops the stack for register \fIx\fP and puts the result on the main +stack. +The commands \fBs\fP and \fBl\fP also work on registers but not as push-down +stacks. +\fBl\fP doesn't effect the top of the +register stack, and \fBs\fP destroys what was there before. +.PP +The commands to work on arrays are \fB:\fP and \fB;\fP. +\fB:\fIx\fR pops the stack and uses this value as an index into +the array \fIx\fP. +The next element on the stack is stored at this index in \fIx\fP. +An index must be greater than or equal to 0 and +less than 2048. +\fB;\fIx\fR is the command to load the main stack from the array \fIx\fP. +The value on the top of the stack is the index +into the array \fIx\fP of the value to be loaded. +.SH +Miscellaneous Commands +.PP +The command \fB!\fP interprets the rest of the line as a +.UX +command and passes it to +.UX +to execute. +One other compiler command is \fBQ\fP. +This command uses the top of the stack as the number of levels of recursion to skip. +.SH +DESIGN CHOICES +.PP +The real reason for the use of a dynamic storage allocator was +that a general purpose program could be (and in fact has been) +used for a variety of other tasks. +The allocator has some value for input and for compiling (i.e. +the bracket [...] commands) where it cannot be known in advance +how long a string will be. +The result was that at a modest +cost in execution time, all considerations of string allocation +and sizes of strings were removed from the remainder of the program +and debugging was made easier. The allocation method +used wastes approximately 25% of available space. +.PP +The choice of 100 as a base for internal arithmetic +seemingly has no compelling advantage. Yet the base cannot +exceed 127 because of hardware limitations and at the cost +of 5% in space, debugging was made a great deal easier and +decimal output was made much faster. +.PP +The reason for a stack-type arithmetic design was +to permit all DC commands from addition to subroutine execution +to be implemented in essentially the same way. The result +was a considerable degree of logical separation of the final +program into modules with very little communication between +modules. +.PP +The rationale for the lack of interaction between the scale and the bases +was to provide an understandable means of proceeding after +a change of base or scale when numbers had already been entered. +An earlier implementation which had global notions of +scale and base did not work out well. +If the value of +.ft B +scale +.ft +were to be interpreted in the current +input or output base, +then a change of base or scale in the midst of a +computation would cause great confusion in the interpretation +of the results. +The current scheme has the advantage that the value of +the input and output bases +are only used for input and output, respectively, and they +are ignored in all other operations. +The value of +scale +is not used for any essential purpose by any part of the program +and it is used only to prevent the number of +decimal places resulting from the arithmetic operations from +growing beyond all bounds. +.PP +The design rationale for the choices for the scales of +the results of arithmetic were that in no case should +any significant digits be thrown away if, on appearances, the +user actually wanted them. Thus, if the user wants +to add the numbers 1.5 and 3.517, it seemed reasonable to give +him the result 5.017 without requiring him to unnecessarily +specify his rather obvious requirements for precision. +.PP +On the other hand, multiplication and exponentiation produce +results with many more digits than their operands and it +seemed reasonable to give as a minimum the number of decimal +places in the operands but not to give more than that +number of digits +unless the user asked for them by specifying a value for \fBscale\fP. +Square root can be handled in just the same way as multiplication. +The operation of division gives arbitrarily many decimal places +and there is simply no way to guess how many places the user +wants. +In this case only, the user must +specify a \fBscale\fP to get any decimal places at all. +.PP +The scale of remainder was chosen to make it possible +to recreate the dividend from the quotient and remainder. +This is easy to implement; no digits are thrown away. +.SH +References +.IP [1] +L. L. Cherry, R. Morris, +.ft I +BC \- An Arbitrary Precision Desk-Calculator Language. +.ft +.IP [2] +K. C. Knowlton, +.ft I +A Fast Storage Allocator, +.ft +Comm. ACM \fB8\fP, pp. 623-625 (Oct. 1965). diff --git a/share/doc/usd/06.bc/Makefile b/share/doc/usd/06.bc/Makefile index 12dfedd..b4f340c 100644 --- a/share/doc/usd/06.bc/Makefile +++ b/share/doc/usd/06.bc/Makefile @@ -4,6 +4,5 @@ VOLUME= usd/06.bc SRCS= bc MACROS= -ms -SRCDIR= ${.CURDIR}/../../../../usr.bin/bc/USD.doc .include <bsd.doc.mk> diff --git a/share/doc/usd/06.bc/bc b/share/doc/usd/06.bc/bc new file mode 100644 index 0000000..c4e68c6 --- /dev/null +++ b/share/doc/usd/06.bc/bc @@ -0,0 +1,1241 @@ +.\" $FreeBSD$ +.\" $OpenBSD: bc,v 1.9 2004/07/09 10:23:05 jmc Exp $ +.\" +.\" Copyright (C) Caldera International Inc. 2001-2002. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed or owned by Caldera +.\" International, Inc. +.\" 4. Neither the name of Caldera International, Inc. nor the names of other +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA +.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, +.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" @(#)bc 6.2 (Berkeley) 4/17/91 +.\" +.if n \{\ +.po 5n +.ll 70n +.\} +.EH 'USD:6-%''BC \- An Arbitrary Precision Desk-Calculator Language' +.OH 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6-%' +.\".RP +.TL +BC \- An Arbitrary Precision Desk-Calculator Language +.AU +Lorinda Cherry +.AU +Robert Morris +.AI +.\" .MH +.AB +BC is a language and a compiler for doing arbitrary precision arithmetic +on the PDP-11 under the +.UX +time-sharing +system. The output of the compiler is interpreted and executed by +a collection of routines which can input, output, and do +arithmetic on indefinitely large integers and on scaled fixed-point +numbers. +.PP +These routines are themselves based on a dynamic storage allocator. +Overflow does not occur until all available core storage +is exhausted. +.PP +The language has a complete control structure as well as immediate-mode +operation. Functions can be defined and saved for later execution. +.PP +Two five hundred-digit numbers can be multiplied to give a +thousand digit result in about ten seconds. +.PP +A small collection of library functions is also available, +including sin, cos, arctan, log, exponential, and Bessel functions of +integer order. +.PP +Some of the uses of this compiler are +.IP \- +to do computation with large integers, +.IP \- +to do computation accurate to many decimal places, +.IP \- +conversion of numbers from one base to another base. +.AE +.PP +.SH +Introduction +.PP +BC is a language and a compiler for doing arbitrary precision +arithmetic on the +.UX +time-sharing system [1]. +The compiler was written to make conveniently available a +collection of routines (called DC [5]) which are capable of doing +arithmetic on integers of arbitrary size. The compiler +is by no means intended to provide a complete programming +language. +It is a minimal language facility. +.PP +There is a scaling provision that permits the +use of decimal point notation. +Provision is made for input and output in bases other than +decimal. Numbers can be converted from decimal to octal by +simply setting the output base to equal 8. +.PP +The actual limit on the number of digits that can +be handled depends on the amount of storage available on the machine. +Manipulation of numbers with many hundreds of digits +is possible even on the smallest versions of +.UX . +.PP +The syntax of BC has been deliberately selected to agree +substantially with the C language [2]. Those who +are familiar with C will find few surprises in this language. +.SH +Simple Computations with Integers +.PP +The simplest kind of statement is an arithmetic expression +on a line by itself. +For instance, if you type in the line: +.DS +.ft B +142857 + 285714 +.ft P +.DE +the program responds immediately with the line +.DS +.ft B +428571 +.ft P +.DE +The operators \-, *, /, %, and ^ can also be used; they +indicate subtraction, multiplication, division, remaindering, and +exponentiation, respectively. Division of integers produces an +integer result truncated toward zero. +Division by zero produces an error +comment. +.PP +Any term in an expression may be prefixed by a minus sign to +indicate that it is to be negated (the `unary' minus sign). +The expression +.DS +.ft B +7+\-3 +.ft P +.DE +is interpreted to mean that \-3 is to be added to 7. +.PP +More complex expressions with several operators and with +parentheses are interpreted just as in +Fortran, with ^ having the greatest binding +power, then * and % and /, and finally + and \-. +Contents of parentheses are evaluated before material +outside the parentheses. +Exponentiations are +performed from right to left and the other operators +from left to right. +The two expressions +.DS +.ft B +a^b^c and a^(b^c) +.ft P +.DE +are equivalent, as are the two expressions +.DS +.ft B +a*b*c and (a*b)*c +.ft P +.DE +BC shares with Fortran and C the undesirable convention that +.DS +\fBa/b*c\fP is equivalent to \fB(a/b)*c\fP +.ft P +.DE +.PP +Internal storage registers to hold numbers have single lower-case +letter names. The value of an expression can be assigned to +a register in the usual way. The statement +.DS +.ft B +x = x + 3 +.ft P +.DE +has the effect of increasing by three the value of the contents of the +register named x. +When, as in this case, the outermost operator is an =, the +assignment is performed but the result is not printed. +Only 26 of these named storage registers are available. +.PP +There is a built-in square root function whose +result is truncated to an integer (but see scaling below). +The lines +.DS +.ft B +x = sqrt(191) +x +.ft P +.DE +produce the printed result +.DS +.ft B +13 +.ft P +.DE +.SH +Bases +.PP +There are special internal quantities, called `ibase' and `obase'. +The contents of `ibase', initially set to 10, +determines the base used for interpreting numbers read in. +For example, the lines +.DS +.ft B +ibase = 8 +11 +.ft P +.DE +will produce the output line +.DS +.ft B +9 +.ft P +.DE +and you are all set up to do octal to decimal conversions. +Beware, however of trying to change the input base back +to decimal by typing +.DS +.ft B +ibase = 10 +.ft P +.DE +Because the number 10 is interpreted as octal, this statement will +have no effect. +For those who deal in hexadecimal notation, +the characters A\-F are permitted in numbers +(no matter what base is in effect) +and are +interpreted as digits having values 10\-15 respectively. +The statement +.DS +.ft B +ibase = A +.ft P +.DE +will change you back to decimal input base no matter what the +current input base is. +Negative and large positive input bases are +permitted but useless. +No mechanism has been provided for the input of arbitrary +numbers in bases less than 1 and greater than 16. +.PP +The contents of `obase', initially set to 10, are used as the base for output +numbers. The lines +.DS +.ft B +obase = 16 +1000 +.ft P +.DE +will produce the output line +.DS +.ft B +3E8 +.ft P +.DE +which is to be interpreted as a 3-digit hexadecimal number. +Very large output bases are permitted, and they are sometimes useful. +For example, large numbers can be output in groups of five digits +by setting `obase' to 100000. +Strange (i.e. 1, 0, or negative) output bases are +handled appropriately. +.PP +Very large numbers are split across lines with 70 characters per line. +Lines which are continued end with \\. +Decimal output conversion is practically instantaneous, but output +of very large numbers (i.e., more than 100 digits) with other bases +is rather slow. +Non-decimal output conversion of +a one hundred digit number takes about +three seconds. +.PP +It is best to remember that `ibase' and `obase' have no effect +whatever on the course of internal computation or +on the evaluation of expressions, but only affect input and +output conversion, respectively. +.SH +Scaling +.PP +A third special internal quantity called `scale' is +used to determine the scale of calculated +quantities. +Numbers may have +up to a specific number of decimal digits after the decimal point. +This fractional part is retained in further computations. +We refer to the number of digits after the decimal point of +a number as its scale. +The current implementation allows scales to be as large as can be +represented by a 32-bit unsigned number minus one. +This is a non-portable extension. +The original implementation allowed for a maximum scale of 99. +.PP +When two scaled numbers are combined by +means of one of the arithmetic operations, the result +has a scale determined by the following rules. For +addition and subtraction, the scale of the result is the larger +of the scales of the two operands. In this case, +there is never any truncation of the result. +For multiplications, the scale of the result is never +less than the maximum of the two scales of the operands, +never more than the sum of the scales of the operands +and, subject to those two restrictions, +the scale of the result is set equal to the contents of the internal +quantity `scale'. +The scale of a quotient is the contents of the internal +quantity `scale'. The scale of a remainder is +the sum of the scales of the quotient and the divisor. +The result of an exponentiation is scaled as if +the implied multiplications were performed. +An exponent must be an integer. +The scale of a square root is set to the maximum of the scale +of the argument and the contents of `scale'. +.PP +All of the internal operations are actually carried out in terms +of integers, with digits being discarded when necessary. +In every case where digits are discarded, truncation and +not rounding is performed. +.PP +The contents of +`scale' must be no greater than +4294967294 and no less than 0. It is initially set to 0. +.PP +The internal quantities `scale', `ibase', and `obase' can be +used in expressions just like other variables. +The line +.DS +.ft B +scale = scale + 1 +.ft P +.DE +increases the value of `scale' by one, and the line +.DS +.ft B +scale +.ft P +.DE +causes the current value of `scale' to be printed. +.PP +The value of `scale' retains its meaning as a +number of decimal digits to be retained in internal +computation even when `ibase' or `obase' are not equal to 10. +The internal computations (which are still conducted in decimal, +regardless of the bases) are performed to the specified number +of decimal digits, never hexadecimal or octal or any +other kind of digits. +.SH +Functions +.PP +The name of a function is a single lower-case letter. +Function names are permitted to collide with simple +variable names. +Twenty-six different defined functions are permitted +in addition to the twenty-six variable names. +The line +.DS +.ft B + define a(x){ +.ft P +.DE +begins the definition of a function with one argument. +This line must be followed by one or more statements, +which make up the body of the function, ending +with a right brace }. +Return of control from a function occurs when a return +statement is executed or when the end of the function is reached. +The return statement can take either +of the two forms +.DS +.ft B +return +return(x) +.ft P +.DE +In the first case, the value of the function is 0, and in +the second, the value of the expression in parentheses. +.PP +Variables used in the function can be declared as automatic +by a statement of the form +.DS +.ft B +auto x,y,z +.ft P +.DE +There can be only one `auto' statement in a function and it must +be the first statement in the definition. +These automatic variables are allocated space and initialized +to zero on entry to the function and thrown away on return. The +values of any variables with the same names outside the function +are not disturbed. +Functions may be called recursively and the automatic variables +at each level of call are protected. +The parameters named in a function definition are treated in +the same way as the automatic variables of that function +with the single exception that they are given a value +on entry to the function. +An example of a function definition is +.DS +.ft B + define a(x,y){ + auto z + z = x*y + return(z) + } +.ft P +.DE +The value of this function, when called, will be the +product of its +two arguments. +.PP +A function is called by the appearance of its name +followed by a string of arguments enclosed in +parentheses and separated by commas. +The result +is unpredictable if the wrong number of arguments is used. +.PP +Functions with no arguments are defined and called using +parentheses with nothing between them: b(). +.PP +If the function +.ft I +a +.ft +above has been defined, then the line +.DS +.ft B +a(7,3.14) +.ft P +.DE +would cause the result 21.98 to be printed and the line +.DS +.ft B +x = a(a(3,4),5) +.ft P +.DE +would cause the value of x to become 60. +.SH +Subscripted Variables +.PP +A single lower-case letter variable name +followed by an expression in brackets is called a subscripted +variable (an array element). +The variable name is called the array name and the expression +in brackets is called the subscript. +Only one-dimensional arrays are +permitted. The names of arrays are permitted to +collide with the names of simple variables and function names. +Any fractional +part of a subscript is discarded before use. +Subscripts must be greater than or equal to zero and +less than or equal to 2047. +.PP +Subscripted variables may be freely used in expressions, in +function calls, and in return statements. +.PP +An array name may be used as an argument to a function, +or may be declared as automatic in +a function definition by the use of empty brackets: +.DS +.ft B +f(a[\|]) +define f(a[\|]) +auto a[\|] +.ft P +.DE +When an array name is so used, the whole contents of the array +are copied for the use of the function, and thrown away on exit +from the function. +Array names which refer to whole arrays cannot be used +in any other contexts. +.SH +Control Statements +.PP +The `if', the `while', and the `for' statements +may be used to alter the flow within programs or to cause iteration. +The range of each of them is a statement or +a compound statement consisting of a collection of +statements enclosed in braces. +They are written in the following way +.DS +.ft B +if(relation) statement +if(relation) statement else statement +while(relation) statement +for(expression1; relation; expression2) statement +.ft P +.DE +or +.DS +.ft B +if(relation) {statements} +if(relation) {statements} else {statements} +while(relation) {statements} +for(expression1; relation; expression2) {statements} +.ft P +.DE +.PP +A relation in one of the control statements is an expression of the form +.DS +.ft B +x>y +.ft P +.DE +where two expressions are related by one of the six relational +operators `<', `>', `<=', `>=', `==', or `!='. +The relation `==' +stands for `equal to' and `!=' stands for `not equal to'. +The meaning of the remaining relational operators is +clear. +.PP +BEWARE of using `=' instead of `==' in a relational. Unfortunately, +both of them are legal, so you will not get a diagnostic +message, but `=' really will not do a comparison. +.PP +The `if' statement causes execution of its range +if and only if the relation is true. +Then control passes to the next statement in sequence. +If an `else' branch is present, the statements in this branch are +executed if the relation is false. +The `else' keyword is a non-portable extension. +.PP +The `while' statement causes execution of its range +repeatedly as long as the relation +is true. The relation is tested before each execution +of its range and if the relation +is false, control passes to the next statement beyond the range +of the while. +.PP +The `for' statement begins +by executing `expression1'. Then the relation is tested +and, if true, the statements in the range of the `for' are executed. +Then `expression2' is executed. The relation is tested, and so on. +The typical use of the `for' statement is for a controlled iteration, +as in the statement +.DS +.ft B +for(i=1; i<=10; i=i+1) i +.ft P +.DE +which will print the integers from 1 to 10. +Here are some examples of the use of the control statements. +.DS +.ft B +define f(n){ +auto i, x +x=1 +for(i=1; i<=n; i=i+1) x=x*i +return(x) +} +.ft P +.DE +The line +.DS +.ft B + f(a) +.ft P +.DE +will print +.ft I +a +.ft +factorial if +.ft I +a +.ft +is a positive integer. +Here is the definition of a function which will +compute values of the binomial coefficient +(m and n are assumed to be positive integers). +.DS +.ft B +define b(n,m){ +auto x, j +x=1 +for(j=1; j<=m; j=j+1) x=x*(n\-j+1)/j +return(x) +} +.ft P +.DE +The following function computes values of the exponential function +by summing the appropriate series +without regard for possible truncation errors: +.DS +.ft B +scale = 20 +define e(x){ + auto a, b, c, d, n + a = 1 + b = 1 + c = 1 + d = 0 + n = 1 + while(1==1){ + a = a*x + b = b*n + c = c + a/b + n = n + 1 + if(c==d) return(c) + d = c + } +} +.ft P +.DE +.SH +Some Details +.PP +There are some language features that every user should know +about even if he will not use them. +.PP +Normally statements are typed one to a line. It is also permissible +to type several statements on a line separated by semicolons. +.PP +If an assignment statement is parenthesized, it then has +a value and it can be used anywhere that an expression can. +For example, the line +.DS +.ft B +(x=y+17) +.ft P +.DE +not only makes the indicated assignment, but also prints the +resulting value. +.PP +Here is an example of a use of the value of an +assignment statement even when it is not parenthesized. +.DS +.ft B +x = a[i=i+1] +.ft P +.DE +causes a value to be assigned to x and also increments i +before it is used as a subscript. +.PP +The following constructs work in BC in exactly the same manner +as they do in the C language. Consult the appendix or the +C manuals [2] for their exact workings. +.DS +.ft B +.ta 2i +x=y=z is the same as x=(y=z) +x += y x = x+y +x \-= y x = x\-y +x *= y x = x*y +x /= y x = x/y +x %= y x = x%y +x ^= y x = x^y +x++ (x=x+1)\-1 +x\-\- (x=x\-1)+1 +++x x = x+1 +\-\-x x = x\-1 +.ft P +.DE +Even if you don't intend to use the constructs, +if you type one inadvertently, something correct but unexpected +may happen. +.SH +Three Important Things +.PP +1. To exit a BC program, type `quit'. +.PP +2. There is a comment convention identical to that of C and +of PL/I. Comments begin with `/*' and end with `*/'. +As a non-portable extension, comments may also start with a `#' and end with +a newline. +The newline is not part of the comment. +.PP +3. There is a library of math functions which may be obtained by +typing at command level +.DS +.ft B +bc \-l +.ft P +.DE +This command will load a set of library functions +which, at the time of writing, consists of sine (named `s'), +cosine (`c'), arctangent (`a'), natural logarithm (`l'), +exponential (`e') and Bessel functions of integer order (`j(n,x)'). Doubtless more functions will be added +in time. +The library sets the scale to 20. You can reset it to something +else if you like. +The design of these mathematical library routines +is discussed elsewhere [3]. +.PP +If you type +.DS +.ft B +bc file ... +.ft P +.DE +BC will read and execute the named file or files before accepting +commands from the keyboard. In this way, you may load your +favorite programs and function definitions. +.SH +Acknowledgement +.PP +The compiler is written in YACC [4]; its original +version was written by S. C. Johnson. +.SH +References +.IP [1] +K. Thompson and D. M. Ritchie, +.ft I +UNIX Programmer's Manual, +.ft +Bell Laboratories, +1978. +.IP [2] +B. W. Kernighan and +D. M. Ritchie, +.ft I +The C Programming Language, +.ft +Prentice-Hall, 1978. +.IP [3] +R. Morris, +.ft I +A Library of Reference Standard Mathematical Subroutines, +.ft +Bell Laboratories internal memorandum, 1975. +.IP [4] +S. C. Johnson, +.ft I +YACC \(em Yet Another Compiler-Compiler. +.ft +Bell Laboratories Computing Science Technical Report #32, 1978. +.IP [5] +R. Morris and L. L. Cherry, +.ft I +DC \- An Interactive Desk Calculator. +.ft +.LP +.bp +.ft B +.DS C +Appendix +.DE +.ft +.NH +Notation +.PP +In the following pages syntactic categories are in \fIitalics\fP; +literals are in \fBbold\fP; material in brackets [\|] is optional. +.NH +Tokens +.PP +Tokens consist of keywords, identifiers, constants, operators, +and separators. +Token separators may be blanks, tabs or comments. +Newline characters or semicolons separate statements. +.NH 2 +Comments +.PP +Comments are introduced by the characters /* and terminated by +*/. +As a non-portable extension, comments may also start with a # and +end with a newline. +The newline is not part of the comment. +.NH 2 +Identifiers +.PP +There are three kinds of identifiers \- ordinary identifiers, array identifiers +and function identifiers. +All three types consist of single lower-case letters. +Array identifiers are followed by square brackets, possibly +enclosing an expression describing a subscript. +Arrays are singly dimensioned and may contain up to 2048 +elements. +Indexing begins at zero so an array may be indexed from 0 to 2047. +Subscripts are truncated to integers. +Function identifiers are followed by parentheses, possibly enclosing arguments. +The three types of identifiers do not conflict; +a program can have a variable named \fBx\fP, +an array named \fBx\fP and a function named \fBx\fP, all of which are separate and +distinct. +.NH 2 +Keywords +.PP +The following are reserved keywords: +.ft B +.ta .5i 1.0i +.nf + ibase if + obase break + scale define + sqrt auto + length return + while quit + for continue + else last + print +.fi +.ft +.NH 2 +Constants +.PP +Constants consist of arbitrarily long numbers +with an optional decimal point. +The hexadecimal digits \fBA\fP\-\fBF\fP are also recognized as digits with +values 10\-15, respectively. +.NH 1 +Expressions +.PP +The value of an expression is printed unless the main +operator is an assignment. +The value printed is assigned to the special variable \fBlast\fP. +A single dot may be used as a synonym for \fBlast\fP. +This is a non-portable extension. +Precedence is the same as the order +of presentation here, with highest appearing first. +Left or right associativity, where applicable, is +discussed with each operator. +.bp +.NH 2 +Primitive expressions +.NH 3 +Named expressions +.PP +Named expressions are +places where values are stored. +Simply stated, +named expressions are legal on the left +side of an assignment. +The value of a named expression is the value stored in the place named. +.NH 4 +\fIidentifiers\fR +.PP +Simple identifiers are named expressions. +They have an initial value of zero. +.NH 4 +\fIarray-name\fP\|[\|\fIexpression\fP\|] +.PP +Array elements are named expressions. +They have an initial value of zero. +.NH 4 +\fBscale\fR, \fBibase\fR and \fBobase\fR +.PP +The internal registers +\fBscale\fP, \fBibase\fP and \fBobase\fP are all named expressions. +\fBscale\fP is the number of digits after the decimal point to be +retained in arithmetic operations. +\fBscale\fR has an initial value of zero. +\fBibase\fP and \fBobase\fP are the input and output number +radix respectively. +Both \fBibase\fR and \fBobase\fR have initial values of 10. +.NH 3 +Function calls +.NH 4 +\fIfunction-name\fB\|(\fR[\fIexpression\fR\|[\fB,\|\fIexpression\|\fR.\|.\|.\|]\|]\fB) +.PP +A function call consists of a function name followed by parentheses +containing a comma-separated list of +expressions, which are the function arguments. +A whole array passed as an argument is specified by the +array name followed by empty square brackets. +All function arguments are passed by +value. +As a result, changes made to the formal parameters have +no effect on the actual arguments. +If the function terminates by executing a return +statement, the value of the function is +the value of the expression in the parentheses of the return +statement or is zero if no expression is provided +or if there is no return statement. +.NH 4 +sqrt\|(\|\fIexpression\fP\|) +.PP +The result is the square root of the expression. +The result is truncated in the least significant decimal place. +The scale of the result is +the scale of the expression or the +value of +.ft B +scale, +.ft +whichever is larger. +.NH 4 +length\|(\|\fIexpression\fP\|) +.PP +The result is the total number of significant decimal digits in the expression. +The scale of the result is zero. +.NH 4 +scale\|(\|\fIexpression\fP\|) +.PP +The result is the scale of the expression. +The scale of the result is zero. +.NH 3 +Constants +.PP +Constants are primitive expressions. +.NH 3 +Parentheses +.PP +An expression surrounded by parentheses is +a primitive expression. +The parentheses are used to alter the +normal precedence. +.NH 2 +Unary operators +.PP +The unary operators +bind right to left. +.NH 3 +\-\|\fIexpression\fP +.PP +The result is the negative of the expression. +.NH 3 +++\|\fInamed-expression\fP +.PP +The named expression is +incremented by one. +The result is the value of the named expression after +incrementing. +.NH 3 +\-\-\|\fInamed-expression\fP +.PP +The named expression is +decremented by one. +The result is the value of the named expression after +decrementing. +.NH 3 +\fInamed-expression\fP\|++ +.PP +The named expression is +incremented by one. +The result is the value of the named expression before +incrementing. +.NH 3 +\fInamed-expression\fP\|\-\- +.PP +The named expression is +decremented by one. +The result is the value of the named expression before +decrementing. +.NH 2 +Exponentiation operator +.PP +The exponentiation operator binds right to left. +.NH 3 +\fIexpression\fP ^ \fIexpression\fP +.PP +The result is the first +expression raised to the power of the +second expression. +The second expression must be an integer. +If \fIa\fP +is the scale of the left expression +and \fIb\fP is the absolute value +of the right expression, +then the scale of the result is: +.PP +min\|(\|\fIa\(mub\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP\|)\|) +.NH 2 +Multiplicative operators +.PP +The operators *, /, % bind left to right. +.NH 3 +\fIexpression\fP * \fIexpression\fP +.PP +The result is the product +of the two expressions. +If \fIa\fP and \fIb\fP are the +scales of the two expressions, +then the scale of the result is: +.PP +min\|(\|\fIa+b\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP,\|\fIb\fP\|)\|) +.NH 3 +\fIexpression\fP / \fIexpression\fP +.PP +The result is the quotient of the two expressions. +The scale of the result is the value of \fBscale\fR. +.NH 3 +\fIexpression\fP % \fIexpression\fP +.PP +The % operator produces the remainder of the division +of the two expressions. +More precisely, +\fIa\fP%\fIb\fP is \fIa\fP\-\fIa\fP/\fIb\fP*\fIb\fP. +.PP +The scale of the result is the sum of the scale of +the divisor and the value of +.ft B +scale +.ft +.NH 2 +Additive operators +.PP +The additive operators bind left to right. +.NH 3 +\fIexpression\fP + \fIexpression\fP +.PP +The result is the sum of the two expressions. +The scale of the result is +the maximum of the scales of the expressions. +.NH 3 +\fIexpression\fP \- \fIexpression\fP +.PP +The result is the difference of the two expressions. +The scale of the result is the +maximum of the scales of the expressions. +.NH 2 +assignment operators +.PP +The assignment operators bind right to left. +.NH 3 +\fInamed-expression\fP = \fIexpression\fP +.PP +This expression results in assigning the value of the expression +on the right +to the named expression on the left. +.NH 3 +\fInamed-expression\fP += \fIexpression\fP +.NH 3 +\fInamed-expression\fP \-= \fIexpression\fP +.NH 3 +\fInamed-expression\fP *= \fIexpression\fP +.NH 3 +\fInamed-expression\fP /= \fIexpression\fP +.NH 3 +\fInamed-expression\fP %= \fIexpression\fP +.NH 3 +\fInamed-expression\fP ^= \fIexpression\fP +.PP +The result of the above expressions is equivalent +to ``named expression = named expression OP expression'', +where OP is the operator after the = sign. +.NH 1 +Relations +.PP +Unlike all other operators, the relational operators +are only valid as the object of an \fBif\fP, \fBwhile\fP, +or inside a \fBfor\fP statement. +.NH 2 +\fIexpression\fP < \fIexpression\fP +.NH 2 +\fIexpression\fP > \fIexpression\fP +.NH 2 +\fIexpression\fP <= \fIexpression\fP +.NH 2 +\fIexpression\fP >= \fIexpression\fP +.NH 2 +\fIexpression\fP == \fIexpression\fP +.NH 2 +\fIexpression\fP != \fIexpression\fP +.NH 1 +Storage classes +.PP +There are only two storage classes in BC, global and automatic +(local). +Only identifiers that are to be local to a function need be +declared with the \fBauto\fP command. +The arguments to a function +are local to the function. +All other identifiers are assumed to be global +and available to all functions. +All identifiers, global and local, have initial values +of zero. +Identifiers declared as \fBauto\fP are allocated on entry to the function +and released on returning from the function. +They therefore do not retain values between function calls. +\fBauto\fP arrays are specified by the array name followed by empty square brackets. +.PP +Automatic variables in BC do not work in exactly the same way +as in either C or PL/I. On entry to a function, the old values of +the names that appear as parameters and as automatic +variables are pushed onto a stack. +Until return is made from the function, reference to these +names refers only to the new values. +.NH 1 +Statements +.PP +Statements must be separated by semicolon or newline. +Except where altered by control statements, execution +is sequential. +.NH 2 +Expression statements +.PP +When a statement is an expression, unless +the main operator is an assignment, the value +of the expression is printed, followed by a newline character. +.NH 2 +Compound statements +.PP +Statements may be grouped together and used when one statement is expected +by surrounding them with { }. +.NH 2 +Quoted string statements +.PP +"any string" +.sp .5 +This statement prints the string inside the quotes. +.NH 2 +If statements +.sp .5 +\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fR +.PP +The substatement is executed if the relation is true. +.NH 2 +If-else statements +.sp .5 +\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fB\|else\|\fIstatement\fR +.PP +The first substatement is executed if the relation is true, the second +substatement if the relation is false. +The \fBif-else\fR statement is a non-portable extension. +.NH 2 +While statements +.sp .5 +\fBwhile\|(\|\fIrelation\fB\|)\|\fIstatement\fR +.PP +The statement is executed while the relation +is true. +The test occurs before each execution of the statement. +.NH 2 +For statements +.sp .5 +\fBfor\|(\|\fIexpression\fB; \fIrelation\fB; \fIexpression\fB\|)\|\fIstatement\fR +.PP +The \fBfor\fR statement is the same as +.nf +.ft I + first-expression + \fBwhile\|(\fPrelation\|\fB) {\fP + statement + last-expression + } +.ft R +.fi +.PP +All three expressions may be left out. +This is a non-portable extension. +.NH 2 +Break statements +.sp .5 +\fBbreak\fP +.PP +\fBbreak\fP causes termination of a \fBfor\fP or \fBwhile\fP statement. +.NH 2 +Continue statements +.sp .5 +\fBcontinue\fP +.PP +\fBcontinue\fP causes the next iteration of a \fBfor\fP or \fBwhile\fP +statement to start, skipping the remainder of the loop. +For a \fBwhile\fP statement, execution continues with the evaluation +of the condition. +For a \fBfor\fP statement, execution continues with evaluation of +the last-expression. +The \fBcontinue\fP statement is a non-portable extension. +.NH 2 +Auto statements +.sp .5 +\fBauto \fIidentifier\fR\|[\|\fB,\fIidentifier\fR\|] +.PP +The \fBauto\fR statement causes the values of the identifiers to be pushed down. +The identifiers can be ordinary identifiers or array identifiers. +Array identifiers are specified by following the array name by empty square +brackets. +The auto statement must be the first statement +in a function definition. +.NH 2 +Define statements +.sp .5 +.nf +\fBdefine(\|\fR[\fIparameter\|\fR[\fB\|,\|\fIparameter\|.\|.\|.\|\fR]\|]\|\fB)\|{\fI + statements\|\fB}\fR +.fi +.PP +The \fBdefine\fR statement defines a function. +The parameters may +be ordinary identifiers or array names. +Array names must be followed by empty square brackets. +As a non-portable extension, the opening brace may also appear on the +next line. +.NH 2 +Return statements +.sp .5 +\fBreturn\fP +.sp .5 +\fBreturn(\fI\|expression\|\fB)\fR +.PP +The \fBreturn\fR statement causes termination of a function, +popping of its auto variables, and +specifies the result of the function. +The first form is equivalent to \fBreturn(0)\fR. +The result of the function is the result of the expression +in parentheses. +Leaving out the expression between parentheses is equivalent to +\fBreturn(0)\fR. +As a non-portable extension, the parentheses may be left out. +.NH 2 +Print +.PP +The \fBprint\fR statement takes a list of comma-separated expressions. +Each expression in the list is evaluated and the computed +value is printed and assigned to the variable `last'. +No trailing newline is printed. +The expression may also be a string enclosed in double quotes. +Within these strings the following escape sequences may be used: +\ea +for bell (alert), +`\eb' +for backspace, +`\ef' +for formfeed, +`\en' +for newline, +`\er' +for carriage return, +`\et' +`for tab, +`\eq' +for double quote and +`\e\e' +for backslash. +Any other character following a backslash will be ignored. +Strings will not be assigned to `last'. +The \fBprint\fR statement is a non-portable extension. +.NH 2 +Quit +.PP +The \fBquit\fR statement stops execution of a BC program and returns +control to UNIX when it is first encountered. +Because it is not treated as an executable statement, +it cannot be used +in a function definition or in an +.ft B +if, for, +.ft +or +.ft B +while +.ft +statement. diff --git a/share/doc/usd/07.mail/Makefile b/share/doc/usd/07.mail/Makefile index d5a6d3c..790aa96 100644 --- a/share/doc/usd/07.mail/Makefile +++ b/share/doc/usd/07.mail/Makefile @@ -6,6 +6,5 @@ SRCS= mail0.nr mail1.nr mail2.nr mail3.nr mail4.nr mail5.nr mail6.nr \ mail7.nr mail8.nr mail9.nr maila.nr MACROS= -me USE_TBL= -SRCDIR= ${.CURDIR}/../../../../usr.bin/mail/USD.doc .include <bsd.doc.mk> diff --git a/share/doc/usd/07.mail/mail0.nr b/share/doc/usd/07.mail/mail0.nr new file mode 100644 index 0000000..e569a5f --- /dev/null +++ b/share/doc/usd/07.mail/mail0.nr @@ -0,0 +1,72 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail0.nr 8.1 (Berkeley) 6/8/93 +.\" +.\" $FreeBSD$ +.\" +.eh 'USD:7-%''Mail Reference Manual' +.oh 'Mail Reference Manual''USD:7-%' +.if n \ +.nr fs .5v +.\".he 'Mail Reference Manual'\n(mo/\n(dy/\n(yr'%' +.tp +.sp 1.0i +.sz 12 +.rb +.(l C +MAIL REFERENCE MANUAL +.)l +.sz 10 +.sp 2 +.i +.(l C +Kurt Shoens +.)l +.r +.(l C +Revised by +.)l +.(l C +.i +Craig Leres\ \c +.r +and\ \c +.i +Mark Andrews +.)l +.r +.(l C +Version 5.5 + + +.)l +.pn 2 diff --git a/share/doc/usd/07.mail/mail1.nr b/share/doc/usd/07.mail/mail1.nr new file mode 100644 index 0000000..50e7883 --- /dev/null +++ b/share/doc/usd/07.mail/mail1.nr @@ -0,0 +1,92 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail1.nr 8.1 (Berkeley) 6/8/93 +.\" +.sh 1 Introduction +.pp +.i Mail +provides a simple and friendly environment for sending and receiving mail. +It divides incoming mail into +its constituent messages and allows the user to deal with them +in any order. In addition, it provides a set of +.i ed -\c +like commands for manipulating messages and sending mail. +.i Mail +offers the user simple editing capabilities to ease the composition +of outgoing messages, as well as providing the ability to define and send +to names which address groups of users. Finally, +.i Mail +is able to send and receive messages across such networks as the +ARPANET, UUCP, and Berkeley network. +.pp +This document describes how to use the +.i Mail +program to send and receive messages. The reader is not assumed to +be familiar with other message handling systems, but should be +familiar with the \s-2UNIX\s0\** +.(f +\** \s-1UNIX\s0 is a trademark of Bell Laboratories. +.)f +shell, the text editor, and some of the common \s-2UNIX\s0 commands. +.q "The \s-2UNIX\s0 Programmer's Manual," +.q "An Introduction to Csh," +and +.q "Text Editing with Ex and Vi" +can be consulted for more information on these topics. +.pp +Here is how messages are handled: +the mail system accepts incoming +.i messages +for you from other people +and collects them in a file, called your +.i "system mailbox" . +When you login, the system notifies you if there are any messages +waiting in your system mailbox. If you are a +.i csh +user, you will be notified when new mail arrives if you inform +the shell of the location of your mailbox. On version 7 systems, +your system mailbox is located in the directory /var/mail +in a file with your login name. If your login name is +.q sam, +then you can make +.i csh +notify you of new mail by including the following line in your .cshrc +file: +.(l +set mail=/var/mail/sam +.)l +When you read your mail using +.i Mail , +it reads your system mailbox and separates that file into the +individual messages that have been sent to you. You can then +read, reply to, delete, or save these messages. +Each message is marked with its author and the date they sent it. diff --git a/share/doc/usd/07.mail/mail2.nr b/share/doc/usd/07.mail/mail2.nr new file mode 100644 index 0000000..0419859 --- /dev/null +++ b/share/doc/usd/07.mail/mail2.nr @@ -0,0 +1,617 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail2.nr 8.1 (Berkeley) 6/8/93 +.\" +.bp +.sh 1 "Common usage" +.pp +The +.i Mail +command has two distinct usages, according to whether one +wants to send or receive mail. Sending mail is simple: to send a +message to a user whose login name is, say, +\*(lqroot,\*(rq +use the shell +command: +.(l +% Mail root +.)l +then type your message. When you reach the end of the message, type +an EOT (control\-d) at the beginning of a line, which will cause +.i Mail +to echo \*(lqEOT\*(rq and return you to the Shell. When the user you sent mail +to next logs in, he will receive the message: +.(l +You have mail. +.)l +to alert him to the existence of your message. +.pp +If, while you are composing the message +you decide that you do not wish to send it after all, you can +abort the letter with a \s-2RUBOUT\s0. Typing a single \s-2RUBOUT\s0 +causes +.i Mail +to print +.(l +(Interrupt -- one more to kill letter) +.)l +Typing a second +\s-2RUBOUT\s0 causes +.i Mail +to save your partial letter on the file +.q dead.letter +in your home directory and abort the letter. +Once you have +sent mail to someone, there is no way to undo the act, so be +careful. +.pp +The message your recipient reads will consist of the message you +typed, preceded by a line telling who sent the message (your login name) +and the date and time it +was sent. +.pp +If you want to send the same message to several other people, you can list +their login names on the command line. +Thus, +.(l +% Mail sam bob john +Tuition fees are due next Friday. Don't forget!! +<Control\-d> +EOT +% +.)l +will send the reminder to sam, bob, and john. +.pp +If, when you log in, you see the message, +.(l +You have mail. +.)l +you can read the mail by typing simply: +.(l +% Mail +.)l +.i Mail +will respond by typing its version number and date and then listing +the messages you have waiting. Then it will type a prompt and await +your command. The messages are assigned numbers starting with 1 \*- you +refer to the messages with these numbers. +.i Mail +keeps track of which messages are +.i new +(have been sent since you last read your mail) and +.i read +(have been read by you). New messages have an +.b N +next to them in the header listing and old, but unread messages have +a +.b U +next to them. +.i Mail +keeps track of new/old and read/unread messages by putting a +header field called +.q Status +into your messages. +.pp +To look at a specific message, use the +.b type +command, which may be abbreviated to simply +.b t . +For example, if you had the following messages: +.(l +N 1 root Wed Sep 21 09:21 "Tuition fees" +N 2 sam Tue Sep 20 22:55 +.)l +you could examine the first message by giving the command: +.(l +type 1 +.)l +which might cause +.i Mail +to respond with, for example: +.(l +Message 1: +From root Wed Sep 21 09:21:45 1978 +Subject: Tuition fees +Status: R + +Tuition fees are due next Wednesday. Don't forget!! + +.)l +Many +.i Mail +commands that operate on messages take a message number as an +argument like the +.b type +command. For these commands, there is a notion of a current +message. When you enter the +.i Mail +program, the current message is initially the first one. Thus, +you can often omit the message number and use, for example, +.(l +t +.)l +to type the current message. As a further shorthand, you can type a message +by simply giving its message number. Hence, +.(l +1 +.)l +would type the first message. +.pp +Frequently, it is useful to read the messages in your mailbox in order, +one after another. You can read the next message in +.i Mail +by simply typing a newline. As a special case, you can type a newline +as your first command to +.i Mail +to type the first message. +.pp +If, after typing a message, you wish to immediately send a reply, +you can do so with the +.b reply +command. +.b Reply , +like +.b type , +takes a message number as an argument. +.i Mail +then begins a message addressed to the user who sent you the message. +You may then type in your letter in reply, followed by a <control-d> +at the beginning of a line, as before. +.i Mail +will type EOT, then type the ampersand prompt to indicate its readiness +to accept another command. In our example, if, after typing the +first message, you wished to reply to it, you might give the command: +.(l +reply +.)l +.i Mail +responds by typing: +.(l +To: root +Subject: Re: Tuition fees +.)l +and waiting for you to enter your letter. +You are now in the message collection mode described at the beginning +of this section and +.i Mail +will gather up your message up to a control\-d. +Note that it copies the subject +header from the original message. This is useful in that correspondence +about a particular matter will tend to retain the same subject heading, +making it easy to recognize. If there are other header fields in +the message, the information found will also be used. +For example, if the letter had a +.q "To:" +header listing several recipients, +.i Mail +would arrange to send your replay to the same people as well. +Similarly, if the original message contained a +.q "Cc:" +(carbon copies to) field, +.i Mail +would send your reply to +.i those +users, too. +.i Mail +is careful, though, not too send the message to +.i you , +even if you appear in the +.q "To:" +or +.q "Cc:" +field, unless you ask to be included explicitly. See section 4 for more +details. +.pp +After typing in your letter, the dialog with +.i Mail +might look like the following: +.(l +reply +To: root +Subject: Tuition fees + +Thanks for the reminder +EOT +& +.)l +.pp +The +.b reply +command is especially useful for sustaining extended conversations +over the message system, with other +.q listening +users receiving copies of the conversation. The +.b reply +command can be abbreviated to +.b r . +.pp +Sometimes you will receive a message that has been sent to +several people and wish to reply +.i only +to the person who sent it. +.b Reply +with a capital +.b R +replies to a message, but sends a copy to the sender only. +.pp +If you wish, while reading your mail, to send a message to someone, +but not as a reply to one of your messages, you can send the message +directly with the +.b mail +command, which takes as arguments the names of the recipients you wish +to send to. For example, to send a message to +.q frank, +you would do: +.(l +mail frank +This is to confirm our meeting next Friday at 4. +EOT +& +.)l +The +.b mail +command can be abbreviated to +.b m . +.pp +Normally, each message you receive is saved in the file +.i mbox +in your login directory at the time you leave +.i Mail . +Often, +however, you will not want to save a particular message you +have received because it is only of passing interest. To avoid +saving a message in +.i mbox +you can delete it using the +.b delete +command. In our example, +.(l +delete 1 +.)l +will prevent +.i Mail +from saving message 1 (from root) in +.i mbox . +In addition to not saving deleted messages, +.i Mail +will not let +you type them, either. The effect is to make the message disappear +altogether, along with its number. The +.b delete +command can be abbreviated to simply +.b d . +.pp +Many features of +.i Mail +can be tailored to your liking with the +.b set +command. The +.b set +command has two forms, depending on whether you are setting +a +.i binary +option or a +.i valued +option. +Binary options are either on or off. For example, the +.q ask +option informs +.i Mail +that each time you send a message, you want it to prompt you for +a subject header, to be included in the message. +To set the +.q ask +option, you would type +.(l +set ask +.)l +.pp +Another useful +.i Mail +option is +.q hold. +Unless told otherwise, +.i Mail +moves the messages from your system mailbox to the file +.i mbox +in your home directory when you leave +.i Mail . +If you want +.i Mail +to keep your letters in the system mailbox instead, you can set the +.q hold +option. +.pp +Valued options are values which +.i Mail +uses to adapt to your tastes. For example, the +.q SHELL +option tells +.i Mail +which shell you like to use, and is specified by +.(l +set SHELL=/bin/csh +.)l +for example. Note that no spaces are allowed in +.q "SHELL=/bin/csh." +A complete list of the +.i Mail +options appears in section 5. +.pp +Another important valued option is +.q crt. +If you use a fast video terminal, you will find that when you +print long messages, they fly by too quickly for you to read them. +With the +.q crt +option, you can make +.i Mail +print any message larger than a given number of lines by sending +it through a paging program. This program is specified by the +valued option \fBPAGER\fP. +If \fBPAGER\fP is not set, a default paginator is used. +For example, most CRT users with 24-line screens should do: +.(l +set crt=24 +.)l +to paginate messages that will not fit on their screens. +In the default state, \fImore\fP (default paginator) prints a screenful of +information, then types --More--. Type a space to see the next screenful. +.pp +Another adaptation to user needs that +.i Mail +provides is that of +.i aliases . +An alias is simply a name which stands for one or more +real user names. +.i Mail +sent to an alias is really sent to the list of real users +associated with it. For example, an alias can be defined for the +members of a project, so that you can send mail to the whole project +by sending mail to just a single name. The +.b alias +command in +.i Mail +defines an alias. Suppose that the users in a project are +named Sam, Sally, Steve, and Susan. To define an alias called +.q project +for them, you would use the +.i Mail +command: +.(l +alias project sam sally steve susan +.)l +The +.b alias +command can also be used to provide a convenient name for someone +whose user name is inconvenient. For example, if a user named +.q "Bob Anderson" +had the login name +.q anderson," +you might want to use: +.(l +alias bob anderson +.)l +so that you could send mail to the shorter name, +.q bob. +.pp +While the +.b alias +and +.b set +commands allow you to customize +.i Mail , +they have the drawback that they must be retyped each time you enter +.i Mail . +To make them more convenient to use, +.i Mail +always looks for two files when it is invoked. It first reads +a system wide file +.q /etc/mail.rc, +then a user specific file, +.q .mailrc, +which is found in the user's home directory. +The system wide file +is maintained by the system administrator and +contains +.b set +commands that are applicable to all users of the system. +The +.q .mailrc +file is usually used by each user to set options the way he likes +and define individual aliases. +For example, my .mailrc file looks like this: +.(l +set ask nosave SHELL=/bin/csh +.)l +As you can see, it is possible to set many options in the +same +.b set +command. The +.q nosave +option is described in section 5. +.pp +Mail aliasing is implemented +at the system-wide level +by the mail delivery +system +.i sendmail . +These aliases are stored in the file /usr/lib/aliases and are +accessible to all users of the system. +The lines in /usr/lib/aliases are of +the form: +.(l +alias: name\*<1\*>, name\*<2\*>, name\*<3\*> +.)l +where +.i alias +is the mailing list name and the +.i name\*<i\*> +are the members of the list. Long lists can be continued onto the next +line by starting the next line with a space or tab. Remember that you +must execute the shell command +.i newaliases +after editing /usr/lib/aliases since the delivery system +uses an indexed file created by +.i newaliases . +.pp +We have seen that +.i Mail +can be invoked with command line arguments which are people +to send the message to, or with no arguments to read mail. +Specifying the +.rb \-f +flag on the command line causes +.i Mail +to read messages from a file other than your system mailbox. +For example, if you have a collection of messages in +the file +.q letters +you can use +.i Mail +to read them with: +.(l +% Mail \-f letters +.)l +You can use all +the +.i Mail +commands described in this document to examine, modify, or delete +messages from your +.q letters +file, which will be rewritten when you leave +.i Mail +with the +.b quit +command described below. +.pp +Since mail that you read is saved in the file +.i mbox +in your home directory by default, you can read +.i mbox +in your home directory by using simply +.(l +% Mail \-f +.)l +.pp +Normally, messages that you examine using the +.b type +command are saved in the file +.q mbox +in your home directory if you leave +.i Mail +with the +.b quit +command described below. +If you wish to retain a message in your system mailbox +you can use the +.b preserve +command to tell +.i Mail +to leave it there. +The +.b preserve +command accepts a list of message numbers, just like +.b type +and may be abbreviated to +.b pre . +.pp +Messages in your system mailbox that you do not examine are +normally retained in your system mailbox automatically. +If you wish to have such a message saved in +.i mbox +without reading it, you may use the +.b mbox +command to have them so saved. For example, +.(l +mbox 2 +.)l +in our example would cause the second message (from sam) +to be saved in +.i mbox +when the +.b quit +command is executed. +.b Mbox +is also the way to direct messages to your +.i mbox +file if you have set the +.q hold +option described above. +.b Mbox +can be abbreviated to +.b mb . +.pp +When you have perused all the messages of interest, you can leave +.i Mail +with the +.b quit +command, which saves the messages you have typed but not +deleted in the file +.i mbox +in your login directory. Deleted messages are discarded irretrievably, +and messages left untouched are preserved in your system mailbox so +that you will see them the next time you type: +.(l +% Mail +.)l +The +.b quit +command can be abbreviated to simply +.b q . +.pp +If you wish for some reason to leave +.i Mail +quickly without altering either your system mailbox or +.i mbox , +you can type the +.b x +command (short for +.b exit ), +which will immediately return you to the Shell without changing anything. +.pp +If, instead, you want to execute a Shell command without leaving +.i Mail , +you +can type the command preceded by an exclamation point, just as in the +text editor. Thus, for instance: +.(l +!date +.)l +will print the current date without leaving +.i Mail . +.pp +Finally, the +.b help +command is available to print out a brief summary of the +.i Mail +commands, using only the single character command abbreviations. diff --git a/share/doc/usd/07.mail/mail3.nr b/share/doc/usd/07.mail/mail3.nr new file mode 100644 index 0000000..8b133ef --- /dev/null +++ b/share/doc/usd/07.mail/mail3.nr @@ -0,0 +1,133 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail3.nr 8.1 (Berkeley) 6/8/93 +.\" +.sh 1 "Maintaining folders" +.pp +.i Mail +includes a simple facility for maintaining groups of messages together +in folders. This section describes this facility. +.pp +To use the folder facility, you must tell +.i Mail +where you wish to keep your folders. Each folder of messages will +be a single file. For convenience, all of your folders are kept in +a single directory of your choosing. To tell +.i Mail +where your folder directory is, put a line of the form +.(l +set folder=letters +.)l +in your +.i .mailrc +file. If, as in the example above, your folder directory does not +begin with a `/,' +.i Mail +will assume that your folder directory is to be found starting from +your home directory. Thus, if your home directory is +.b /home/person +the above example told +.i Mail +to find your folder directory in +.b /home/person/letters . +.pp +Anywhere a file name is expected, you can use a folder name, preceded +with `+.' For example, to put a message into a folder with the +.b save +command, you can use: +.(l +save +classwork +.)l +to save the current message in the +.i classwork +folder. If the +.i classwork +folder does not yet exist, it will be created. Note that messages +which are saved with the +.b save +command are automatically removed from your system mailbox. +.pp +In order to make a copy of a message in a folder without causing +that message to be removed from your system mailbox, use the +.b copy +command, which is identical in all other respects to the +.b save +command. For example, +.(l +copy +classwork +.)l +copies the current message into the +.i classwork +folder and leaves a copy in your system mailbox. +.pp +The +.b folder +command +can be used to direct +.i Mail +to the contents of a different folder. +For example, +.(l +folder +classwork +.)l +directs +.i Mail +to read the contents of the +.i classwork +folder. All of the commands that you can use on your system +mailbox are also applicable to folders, including +.b type , +.b delete , +and +.b reply . +To inquire which folder you are currently editing, use simply: +.(l +folder +.)l +.pp +To list your current set of folders, use the +.b folders +command. +.pp +To start +.i Mail +reading one of your folders, you can use the +.b \-f +option described in section 2. For example: +.(l +% Mail \-f +classwork +.)l +will cause +.i Mail +to read your +.i classwork +folder without looking at your system mailbox. diff --git a/share/doc/usd/07.mail/mail4.nr b/share/doc/usd/07.mail/mail4.nr new file mode 100644 index 0000000..1a1e046 --- /dev/null +++ b/share/doc/usd/07.mail/mail4.nr @@ -0,0 +1,437 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail4.nr 8.1 (Berkeley) 6/8/93 +.\" +.bp +.sh 1 "More about sending mail" +.sh 2 "Tilde escapes" +.pp +While typing in a message to be sent to others, it is often +useful to be able to invoke the text editor on the partial message, +print the message, execute a shell command, or do some other +auxiliary function. +.i Mail +provides these capabilities through +.i "tilde escapes" , +which consist of a tilde (~) at the beginning of a line, followed by +a single character which indicates the function to be performed. For +example, to print the text of the message so far, use: +.(l +~p +.)l +which will print a line of dashes, the recipients of your message, and +the text of the message so far. +Since +.i Mail +requires two consecutive \s-2RUBOUT\s0's to abort a letter, you +can use a single \s-2RUBOUT\s0 to abort the output of ~p or any other +~ escape without killing your letter. +.pp +If you are dissatisfied with the message as +it stands, you can invoke the text editor on it using the escape +.(l +~e +.)l +which causes the message to be copied into a temporary file and an +instance of the editor to be spawned. After modifying the message to +your satisfaction, write it out and quit the editor. +.i Mail +will respond +by typing +.(l +(continue) +.)l +after which you may continue typing text which will be appended to your +message, or type <control-d> to end the message. +A standard text editor is provided by +.i Mail . +You can override this default by setting the valued option +.q EDITOR +to something else. For example, you might prefer: +.(l +set EDITOR=/usr/bin/ex +.)l +.pp +Many systems offer a screen editor as an alternative to the standard +text editor, such as the +.i vi +editor from UC Berkeley. +To use the screen, or +.i visual +editor, on your current message, you can use the escape, +.(l +~v +.)l +~v works like ~e, except that the screen editor is invoked instead. +A default screen editor is defined by +.i Mail . +If it does not suit you, you can set the valued option +.q VISUAL +to the path name of a different editor. +.pp +It is often useful to be able to include the contents of some +file in your message; the escape +.(l +~r filename +.)l +is provided for this purpose, and causes the named file to be appended +to your current message. +.i Mail +complains if the file doesn't exist +or can't be read. If the read is successful, the number of lines and +characters appended to your message is printed, after which you may continue +appending text. The filename may contain shell metacharacters like * and ? +which are expanded according to the conventions of your shell. +.pp +As a special case of ~r, the escape +.(l +~d +.)l +reads in the file +.q dead.letter +in your home directory. This is often useful since +.i Mail +copies the text +of your message there when you abort a message with \s-2RUBOUT\s0. +.pp +To save the current text of your message on a file you may use the +.(l +~w filename +.)l +escape. +.i Mail +will print out the number of lines and characters written +to the file, after which you may continue appending text to your message. +Shell metacharacters may be used in the filename, as in ~r and are expanded +with the conventions of your shell. +.pp +If you are sending mail from within +.i Mail's +command mode +you can read a message sent to you into the message +you are constructing with the escape: +.(l +~m 4 +.)l +which will read message 4 into the current message, shifted right by +one tab stop. You can name any non-deleted message, or list of messages. +Messages can also be forwarded without shifting by a tab stop with ~f. +This is the usual way to forward a message. +.pp +If, in the process of composing a message, you decide to add additional +people to the list of message recipients, you can do so with the escape +.(l +~t name1 name2 ... +.)l +You may name as few or many additional recipients as you wish. Note +that the users originally on the recipient list will still receive +the message; you cannot remove someone from the recipient +list with ~t. +.pp +If you wish, you can associate a subject with your message by using the +escape +.(l +~s Arbitrary string of text +.)l +which replaces any previous subject with +.q "Arbitrary string of text." +The subject, if given, is sent near the +top of the message prefixed with +.q "Subject:" +You can see what the message will look like by using ~p. +.pp +For political reasons, one occasionally prefers to list certain +people as recipients of carbon copies of a message rather than +direct recipients. The escape +.(l +~c name1 name2 ... +.)l +adds the named people to the +.q "Cc:" +list, similar to ~t. +Again, you can execute ~p to see what the message will look like. +.pp +The escape +.(l +~b name1 name2 ... +.)l +adds the named people to the +.q "Cc:" +list, but does not make the names visible in the +.q "Cc:" +line ("blind" carbon copy). +.pp +The recipients of the message together constitute the +.q "To:" +field, the subject the +.q "Subject:" +field, and the carbon copies the +.q "Cc:" +field. If you wish to edit these in ways impossible with the ~t, ~s, ~c +and ~b escapes, you can use the escape +.(l +~h +.)l +which prints +.q "To:" +followed by the current list of recipients and leaves the cursor +(or printhead) at the end of the line. If you type in ordinary +characters, they are appended to the end of the current list of +recipients. You can also use your erase character to erase back into +the list of recipients, or your kill character to erase them altogether. +Thus, for example, if your erase and kill characters are the standard +(on printing terminals) # and @ symbols, +.(l +~h +To: root kurt####bill +.)l +would change the initial recipients +.q "root kurt" +to +.q "root bill." +When you type a newline, +.i Mail +advances to the +.q "Subject:" +field, where the same rules apply. Another newline brings you to +the +.q "Cc:" +field, which may be edited in the same fashion. Another newline +brings you to the +.q "Bcc:" +("blind" carbon copy) field, which follows the same rules as the "Cc:" +field. Another newline +leaves you appending text to the end of your message. You can use +~p to print the current text of the header fields and the body +of the message. +.pp +To effect a temporary escape to the shell, the escape +.(l +~!command +.)l +is used, which executes +.i command +and returns you to mailing mode without altering the text of +your message. If you wish, instead, to filter the body of your +message through a shell command, then you can use +.(l +~|command +.)l +which pipes your message through the command and uses the output +as the new text of your message. If the command produces no output, +.i Mail +assumes that something is amiss and retains the old version +of your message. A frequently-used filter is the command +.i fmt , +designed to format outgoing mail. +.pp +To effect a temporary escape to +.i Mail +command mode instead, you can use the +.(l +~:\fIMail command\fP +.)l +escape. This is especially useful for retyping the message you are +replying to, using, for example: +.(l +~:t +.)l +It is also useful for setting options and modifying aliases. +.pp +If you wish abort the current message, you can use the escape +.(l +~q +.)l +This will terminate the current message and return you to the +shell (or \fIMail\fP if you were using the \fBmail\fP command). +If the \fBsave\fP option is set, the message will be copied +to the file +.q dead.letter +in your home directory. +.pp +If you wish (for some reason) to send a message that contains +a line beginning with a tilde, you must double it. Thus, for example, +.(l +~~This line begins with a tilde. +.)l +sends the line +.(l +~This line begins with a tilde. +.)l +.pp +Finally, the escape +.(l +~? +.)l +prints out a brief summary of the available tilde escapes. +.pp +On some terminals (particularly ones with no lower case) +tilde's are difficult to type. +.i Mail +allows you to change the escape character with the +.q escape +option. For example, I set +.(l +set escape=] +.)l +and use a right bracket instead of a tilde. If I ever need to +send a line beginning with right bracket, I double it, just as for ~. +Changing the escape character removes the special meaning of ~. +.sh 2 "Network access" +.pp +This section describes how to send mail to people on other machines. +Recall that sending to a plain login name sends mail to that person +on your machine. If your machine is directly (or sometimes, even, +indirectly) connected to the Arpanet, you can send messages to people +on the Arpanet using a name of the form +.(l +name@host.domain +.)l +where +.i name +is the login name of the person you're trying to reach, +.i host +is the name of the machine on the Arpanet, +and +.i domain +is the higher-level scope within which the hostname is known, e.g. EDU (for educational +institutions), COM (for commercial entities), GOV (for governmental agencies), +ARPA for many other things, BITNET or CSNET for those networks. +.pp +If your recipient logs in on a machine connected to yours by +UUCP (the Bell Laboratories supplied network that communicates +over telephone lines), sending mail can be a bit more complicated. +You must know the list of machines through which your message must +travel to arrive at his site. So, if his machine is directly connected +to yours, you can send mail to him using the syntax: +.(l +host!name +.)l +where, again, +.i host +is the name of the machine and +.i name +is the login name. +If your message must go through an intermediary machine first, you +must use the syntax: +.(l +intermediary!host!name +.)l +and so on. It is actually a feature of UUCP that the map of all +the systems in the network is not known anywhere (except where people +decide to write it down for convenience). Talk to your system administrator +about good ways to get places; the +.i uuname +command will tell you systems whose names are recognized, but not which +ones are frequently called or well-connected. +.pp +When you use the +.b reply +command to respond to a letter, there is a problem of figuring out the +names of the users in the +.q "To:" +and +.q "Cc:" +lists +.i "relative to the current machine" . +If the original letter was sent to you by someone on the local machine, +then this problem does not exist, but if the message came from a remote +machine, the problem must be dealt with. +.i Mail +uses a heuristic to build the correct name for each user relative +to the local machine. So, when you +.b reply +to remote mail, the names in the +.q "To:" +and +.q "Cc:" +lists may change somewhat. +.sh 2 "Special recipients" +.pp +As described previously, you can send mail to either user names or +.b alias +names. It is also possible to send messages directly to files or to +programs, using special conventions. If a recipient name has a +`/' in it or begins with a `+', it is assumed to be the +path name of a file into which +to send the message. If the file already exists, the message is +appended to the end of the file. If you want to name a file in +your current directory (ie, one for which a `/' would not usually +be needed) you can precede the name with `./' +So, to send mail to the file +.q memo +in the current directory, you can give the command: +.(l +% Mail ./memo +.)l +If the name begins with a `+,' it is expanded into the full path name +of the folder name in your folder directory. +This ability to send mail to files can be used for a variety of +purposes, such as maintaining a journal and keeping a record of +mail sent to a certain group of users. The second example can be +done automatically by including the full pathname of the record +file in the +.b alias +command for the group. Using our previous +.b alias +example, you might give the command: +.(l +alias project sam sally steve susan /usr/project/mail_record +.)l +Then, all mail sent to "project" would be saved on the file +.q /usr/project/mail_record +as well as being sent to the members of the project. This file +can be examined using +.i "Mail \-f" . +.pp +It is sometimes useful to send mail directly to a program, for +example one might write a project billboard program and want to access +it using +.i Mail . +To send messages to the billboard program, one can send mail +to the special name `|billboard' for example. +.i Mail +treats recipient names that begin with a `|' as a program to send +the mail to. An +.b alias +can be set up to reference a `|' prefaced name if desired. +.i Caveats : +the shell treats `|' specially, so it must be quoted on the command +line. Also, the `| program' must be presented as a single argument to +mail. The safest course is to surround the entire name with double +quotes. This also applies to usage in the +.b alias +command. For example, if we wanted to alias `rmsgs' to `rmsgs \-s' +we would need to say: +.(l +alias rmsgs "| rmsgs -s" +.)l diff --git a/share/doc/usd/07.mail/mail5.nr b/share/doc/usd/07.mail/mail5.nr new file mode 100644 index 0000000..10e707c --- /dev/null +++ b/share/doc/usd/07.mail/mail5.nr @@ -0,0 +1,1042 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail5.nr 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.bp +.sh 1 "Additional features" +.pp +This section describes some additional commands useful for +reading your mail, setting options, and handling lists of messages. +.sh 2 "Message lists" +.pp +Several +.i Mail +commands accept a list of messages as an argument. +Along with +.b type +and +.b delete , +described in section 2, +there is the +.b from +command, which prints the message headers associated with the +message list passed to it. +The +.b from +command is particularly useful in conjunction with some of the +message list features described below. +.pp +A +.i "message list" +consists of a list of message numbers, ranges, and names, +separated by spaces or tabs. Message numbers may be either +decimal numbers, which directly specify messages, or one of the +special characters +.q \(ua +.q "." +or +.q "$" +to specify the first relevant, current, or last +relevant message, respectively. +.i Relevant +here means, for most commands +.q "not deleted" +and +.q "deleted" +for the +.b undelete +command. +.pp +A range of messages consists of two message numbers (of the form +described in the previous paragraph) separated by a dash. +Thus, to print the first four messages, use +.(l +type 1\-4 +.)l +and to print all the messages from the current message to the last +message, use +.(l +type .\-$ +.)l +.pp +A +.i name +is a user name. The user names given in the message list are +collected together and each message selected by other means +is checked to make sure it was sent by one of the named users. +If the message consists entirely of user names, then every +message sent by one of those users that is +.i relevant +(in the sense described earlier) +is selected. Thus, to print every message sent to you by +.q root, +do +.(l +type root +.)l +.pp +As a shorthand notation, you can specify simply +.q * +to get every +.i relevant +(same sense) +message. Thus, +.(l +type * +.)l +prints all undeleted messages, +.(l +delete * +.)l +deletes all undeleted messages, and +.(l +undelete * +.)l +undeletes all deleted messages. +.pp +You can search for the presence of a word in subject lines with +.b / . +For example, to print the headers of all messages that contain the +word +.q PASCAL, +do: +.(l +from /pascal +.)l +Note that subject searching ignores upper/lower case differences. +.sh 2 "List of commands" +.pp +This section describes all the +.i Mail +commands available when +receiving mail. +.ip "\fB\-\fP\ \ " +The +.rb \- +command goes to the previous message and prints it. The +.rb \- +command may be given a decimal number +.i n +as an argument, in which case the +.i n th +previous message is gone to and printed. +.ip "\fB?\fP\ \ " +Prints a brief summary of commands. +.ip "\fB!\fP\ \ " +Used to preface a command to be executed by the shell. +.ip "\fBPrint\fP\ \ " +Like +.b print , +but also print out ignored header fields. See also +\fBprint\fP, \fBignore\fP and \fBretain\fP. +\fBPrint\fP can be abbreviated to \fBP\fP. +.ip "\fBReply\fP or \fBRespond\fP\ \ " +Note the capital \fBR\fP in the name. +Frame a reply to a one or more messages. +The reply (or replies if you are using this on multiple messages) +will be sent ONLY to the person who sent you the message +(respectively, the set of people who sent the messages you are +replying to). +You can +add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP +tilde escapes. The subject in your reply is formed by prefacing the +subject in the original message with +.q "Re:" +unless it already began thus. +If the original message included a +.q "reply-to" +header field, the reply will go +.i only +to the recipient named by +.q "reply-to." +You type in your message using the same conventions available to you +through the +.b mail +command. +The +.b Reply +command is especially useful for replying to messages that were sent +to enormous distribution groups when you really just want to +send a message to the originator. Use it often. +\fBReply\fP (and \fBRespond\fP) can be abbreviated to \fBR\fP. +.ip "\fBType\fP\ \ " +Identical to the +.b Print +command. +\fBType\fP can be abbreviated to \fBT\fP. +.ip "\fBalias\fP\ \ " +Define a name to stand for a set of other names. +This is used when you want to send messages to a certain +group of people and want to avoid retyping their names. +For example +.(l +alias project john sue willie kathryn +.)l +creates an alias +.i project +which expands to the four people John, Sue, Willie, and Kathryn. +If no arguments are given, all currently-defined aliases are printed. +If one argument is given, that alias is printed (if it exists). +\fBAlias\fP can be abbreviated to \fBa\fP. +.ip "\fBalternates\fP\ \ " +If you have accounts on several machines, you may find it convenient +to use the /usr/lib/aliases on all the machines except one to direct +your mail to a single account. +The +.b alternates +command is used to inform +.i Mail +that each of these other addresses is really +.i you . +.i Alternates +takes a list of user names and remembers that they are all actually you. +When you +.b reply +to messages that were sent to one of these alternate names, +.i Mail +will not bother to send a copy of the message to this other address (which +would simply be directed back to you by the alias mechanism). +If +.i alternates +is given no argument, it lists the current set of alternate names. +.b Alternates +is usually used in the .mailrc file. +\fBAlternates\fP can be abbreviated to \fBalt\fP. +.ip "\fBchdir\fP\ \ " +The +.b chdir +command allows you to change your current directory. +.b Chdir +takes a single argument, which is taken to be the pathname of +the directory to change to. If no argument is given, +.b chdir +changes to your home directory. +\fBChdir\fP can be abbreviated to \fBc\fP. +.ip "\fBcopy\fP\ \ " +The +.b copy +command does the same thing that +.b save +does, except that it does not mark the messages it is used on +for deletion when you quit. +\fBCopy\fP can be abbreviated to \fBco\fP. +.ip "\fBdelete\fP\ \ " +Deletes a list of messages. Deleted messages can be reclaimed +with the +.b undelete +command. +\fBDelete\fP can be abbreviated to \fBd\fP. +.ip "\fBdp\fP or \fBdt\fP\ \ " +These +commands delete the current message and print the next message. +They are useful for quickly reading and disposing of mail. +If there is no next message, \fImail\fP says ``at EOF.'' +.ip "\fBedit\fP\ \ " +To edit individual messages using the text editor, the +.b edit +command is provided. The +.b edit +command takes a list of messages as described under the +.b type +command and processes each by writing it into the file +Message\c +.i x +where +.i x +is the message number being edited and executing the text editor on it. +When you have edited the message to your satisfaction, write the message +out and quit, upon which +.i Mail +will read the message back and remove the file. +.b Edit +can be abbreviated to +.b e . +.ip "\fBelse\fP\ \ " +Marks the end of the then-part of an +.b if +statement and the beginning of the +part to take effect if the condition of the +.b if +statement is false. +.ip "\fBendif\fP\ \ " +Marks the end of an +.b if +statement. +.ip "\fBexit\fP or \fBxit\fP\ \ " +Leave +.i Mail +without updating the system mailbox or the file your were reading. +Thus, if you accidentally delete several messages, you can use +.b exit +to avoid scrambling your mailbox. +\fBExit\fP can be abbreviated to \fBex\fP or \fBx\fP. +.ip "\fBfile\fP\ \ " +The same as +.b folder . +\fBFile\fP can be abbreviated to \fBfi\fP. +.ip "\fBfolders\fP\ \ " +List the names of the folders in your folder directory. +.ip "\fBfolder\fP\ \ " +The +.b folder +command switches to a new mail file or folder. With no arguments, it +tells you which file you are currently reading. If you give +it an argument, it will write out changes (such as deletions) +you have made in the current file and read the new file. +Some special conventions are recognized for the name: +.(b +.TS +center; +c c +l a. +Name Meaning +_ +# Previous file read +% Your system mailbox +%name \fIName\fP's system mailbox +& Your ~/mbox file ++folder A file in your folder directory +.TE +.)b +\fBFolder\fP can be abbreviated to \fBfo\fP. +.ip "\fBfrom\fP\ \ " +The +.b from +command takes a list of messages and prints out the header lines for each one; +hence +.(l +from joe +.)l +is the easy way to display all the message headers from \*(lqjoe.\*(rq +\fBFrom\fP can be abbreviated to \fBf\fP. +.ip "\fBheaders\fP\ \ " +When you start up +.i Mail +to read your mail, it lists the message headers that you have. +These headers tell you who each message is from, when they were +received, how many lines and characters each message is, and the +.q "Subject:" +header field of each message, if present. In addition, +.i Mail +tags the message header of each message that has been the object +of the +.b preserve +command with a +.q P. +Messages that have been +.b saved +or +.b written +are flagged with a +.q *. +Finally, +.b deleted +messages are not printed at all. If you wish to reprint the current +list of message headers, you can do so with the +.b headers +command. The +.b headers +command (and thus the initial header listing) +only lists the first so many message headers. +The number of headers listed depends on the speed of your +terminal. +This can be overridden by specifying the number of headers you +want with the +.i window +option. +.i Mail +maintains a notion of the current +.q window +into your messages for the purposes of printing headers. +Use the +.b z +command to move forward and back a window. +You can move +.i Mail's +notion of the current window directly to a particular message by +using, for example, +.(l +headers 40 +.)l +to move +.i Mail's +attention to the messages around message 40. +If a ``+'' argument is given, then the next screenful of message headers is +printed, and if a ``\-'' argument is given, the previous screenful of message +headers is printed. +\fBHeaders\fP can be abbreviated to \fBh\fP. +.ip "\fBhelp\fP\ \ " +Print a brief and usually out of date help message about the commands +in +.i Mail . +The +.i man +page for +.i mail +is usually more up-to-date than either the help message or this manual. +It is also a synonym for \fB?\fP. +.ip "\fBhold\fP\ \ " +Arrange to hold a list of messages in the system mailbox, instead +of moving them to the file +.i mbox +in your home directory. If you set the binary option +.i hold , +this will happen by default. +It does not override the \fBdelete\fP command. +\fBHold\fP can be abbreviated to \fBho\fP. +.ip "\fBif\fP\ \ " +Commands in your +.q .mailrc +file can be executed conditionally depending on whether you are +sending or receiving mail with the +.b if +command. For example, you can do: +.(l +if receive + \fIcommands\fP... +endif +.)l +An +.b else +form is also available: +.(l +if send + \fIcommands\fP... +else + \fIcommands\fP... +endif +.)l +Note that the only allowed conditions are +.b receive +and +.b send . +.ip "\fBignore\fP \ \ " +.b N.B.: +.i Ignore +has been superseded by +.i retain. +.br +Add the list of header fields named to the +.i "ignore list" . +Header fields in the ignore list are not printed on your +terminal when you print a message. This allows you to suppress +printing of certain machine-generated header fields, such as +.i Via +which are not usually of interest. The +.b Type +and +.b Print +commands can be used to print a message in its entirety, including +ignored fields. +If +.b ignore +is executed with no arguments, it lists the current set of ignored fields. +.ip "\fBlist\fP\ \ " +List the valid +.i Mail +commands. +\fBList\fP can be abbreviated to \fBl\fP. +.\".ip \fBlocal\fP +.\"Define a list of local names for this host. This command is useful +.\"when the host is known by more than one name. Names in the list +.\"may be qualified be the domain of the host. The first name on the local +.\"list is the +.\".i distinguished +.\"name of the host. +.\"The names on the local list are used by +.\".i Mail +.\"to decide which addresses are local to the host. +.\"For example: +.\".(l +.\"local ucbarpa.BERKELEY.ARPA arpa.BERKELEY.ARPA \\ +.\" arpavax.BERKELEY.ARPA r.BERKELEY.ARPA \\ +.\" ucb-arpa.ARPA +.\".)l +.\"From this list we see that +.\".i "fred@ucbarpa.BERKELEY.ARPA", +.\".i "harold@arpa.BERKELEY", +.\"and +.\".i "larry@r" +.\"are all addresses of users on the local host. +.\"The +.\".b local +.\"command is usually not used be general users since it is designed for +.\"local configuration; it is usually found in the file /etc/mail.rc. +.ip "\fBmail\fP\ \ " +Send mail to one or more people. If you have the +.i ask +option set, +.i Mail +will prompt you for a subject to your message. Then you +can type in your message, using tilde escapes as described in +section 4 to edit, print, or modify your message. To signal your +satisfaction with the message and send it, type control-d at the +beginning of a line, or a . alone on a line if you set the option +.i dot . +To abort the message, type two interrupt characters (\s-2RUBOUT\s0 +by default) in a row or use the +.b ~q +escape. +The \fBmail\fP command can be abbreviated to \fBm\fP. +.ip "\fBmbox\fP\ \ " +Indicate that a list of messages be sent to +.i mbox +in your home directory when you quit. This is the default +action for messages if you do +.i not +have the +.i hold +option set. +.ip "\fBnext\fP or \fB+\fP\ \ " +The +.b next +command goes to the next message and types it. If given a message list, +.b next +goes to the first such message and types it. Thus, +.(l +next root +.)l +goes to the next message sent by +.q root +and types it. The +.b next +command can be abbreviated to simply a newline, which means that one +can go to and type a message by simply giving its message number or +one of the magic characters +.q "^" +.q "." +or +.q "$". +Thus, +.(l +\&. +.)l +prints the current message and +.(l +4 +.)l +prints message 4, as described previously. +\fBNext\fP can be abbreviated to \fBn\fP. +.ip "\fBpreserve\fP\ \ " +Same as +.b hold . +Cause a list of messages to be held in your system mailbox when you quit. +\fBPreserve\fP can be abbreviated to \fBpre\fP. +.ip "\fBprint\fP\ \ " +Print the specified messages. If the +.b crt +variable is set, messages longer than the number of lines it indicates +are paged through the command specified by the \fBPAGER\fP variable. +The \fBprint\fP command can be abbreviated to \fBp\fP. +.ip "\fBquit\fP\ \ " +Terminates the session, saving all undeleted, unsaved and unwritten messages +in the user's \fImbox\fP file in their login directory +(messages marked as having been read), preserving all +messages marked with \fBhold\fP or \fBpreserve\fP or never referenced +in their system mailbox. +Any messages that were deleted, saved, written or saved to \fImbox\fP are +removed from their system mailbox. +If new mail has arrived during the session, the message +``You have new mail'' is given. If given while editing a mailbox file +with the \fB\-f\fP flag, then the edit file is rewritten. +A return to the Shell is effected, unless the rewrite of edit file fails, +in which case the user can escape with the \fBexit\fP command. +\fBQuit\fP can be abbreviated to \fBq\fP. +.ip "\fBreply\fP or \fBrespond\fP\ \ " +Frame a reply to a single message. +The reply will be sent to the +person who sent you the message (to which you are replying), plus all +the people who received the original message, except you. You can +add people using the \fB~t\fP, \fB~c\fP and \fB~b\fP +tilde escapes. The subject in your reply is formed by prefacing the +subject in the original message with +.q "Re:" +unless it already began thus. +If the original message included a +.q "reply-to" +header field, the reply will go +.i only +to the recipient named by +.q "reply-to." +You type in your message using the same conventions available to you +through the +.b mail +command. +The \fBreply\fP (and \fBrespond\fP) command can be abbreviated to \fBr\fP. +.ip "\fBretain\fP\ \ " +Add the list of header fields named to the \fIretained list\fP. +Only the header fields in the retain list +are shown on your terminal when you print a message. +All other header fields are suppressed. +The +.b Type +and +.b Print +commands can be used to print a message in its entirety. +If +.b retain +is executed with no arguments, it lists the current set of +retained fields. +.ip "\fBsave\fP\ \ " +It is often useful to be able to save messages on related topics +in a file. The +.b save +command gives you the ability to do this. The +.b save +command takes as an argument a list of message numbers, followed by +the name of the file in which to save the messages. The messages +are appended to the named file, thus allowing one to keep several +messages in the file, stored in the order they were put there. +The filename in quotes, followed by the line +count and character count is echoed on the user's terminal. +An example of the +.b save +command relative to our running example is: +.(l +s 1 2 tuitionmail +.)l +.b Saved +messages are not automatically saved in +.i mbox +at quit time, nor are they selected by the +.b next +command described above, unless explicitly specified. +\fBSave\fP can be abbreviated to \fBs\fP. +.ip "\fBset\fP\ \ " +Set an option or give an option a value. Used to customize +.i Mail . +Section 5.3 contains a list of the options. Options can be +.i binary , +in which case they are +.i on +or +.i off , +or +.i valued . +To set a binary option +.i option +.i on , +do +.(l +set option +.)l +To give the valued option +.i option +the value +.i value , +do +.(l +set option=value +.)l +There must be no space before or after the ``='' sign. +If no arguments are given, all variable values are printed. +Several options can be specified in a single +.b set +command. +\fBSet\fP can be abbreviated to \fBse\fP. +.ip "\fBshell\fP\ \ " +The +.b shell +command allows you to +escape to the shell. +.b Shell +invokes an interactive shell and allows you to type commands to it. +When you leave the shell, you will return to +.i Mail . +The shell used is a default assumed by +.i Mail ; +you can override this default by setting the valued option +.q SHELL, +eg: +.(l +set SHELL=/bin/csh +.)l +\fBShell\fP can be abbreviated to \fBsh\fP. +.ip "\fBsize\fP\ \ " +Takes a message list and prints out the size in characters of each +message. +.ip "\fBsource\fP\ \ " +The +.b source +command reads +.i mail +commands from a file. It is useful when you are trying to fix your +.q .mailrc +file and you need to re-read it. +\fBSource\fP can be abbreviated to \fBso\fP. +.ip "\fBtop\fP\ \ " +The +.b top +command takes a message list and prints the first five lines +of each addressed message. +If you wish, you can change the number of lines that +.b top +prints out by setting the valued option +.q "toplines." +On a CRT terminal, +.(l +set toplines=10 +.)l +might be preferred. +\fBTop\fP can be abbreviated to \fBto\fP. +.ip "\fBtype\fP\ \ " +Same as \fBprint\fP. +Takes a message list and types out each message on the terminal. +The \fBtype\fP command can be abbreviated to \fBt\fP. +.ip "\fBundelete\fP \ \" +Takes a message list and marks each message as \fInot\fP +being deleted. +\fBUndelete\fP can be abbreviated to \fBu\fP. +.ip "\fBunread\fP\ \ " +Takes a message list and marks each message as +.i not +having been read. +\fBUnread\fP can be abbreviated to \fBU\fP. +.ip "\fBunset\fP\ \ " +Takes a list of option names and discards their remembered values; +the inverse of \fBset\fP . +.ip "\fBvisual\fP\ \ " +It is often useful to be able to invoke one of two editors, +based on the type of terminal one is using. To invoke +a display oriented editor, you can use the +.b visual +command. The operation of the +.b visual +command is otherwise identical to that of the +.b edit +command. +.ne 2v+\n(psu +.sp \n(psu +Both the +.b edit +and +.b visual +commands assume some default text editors. These default editors +can be overridden by the valued options +.q EDITOR +and +.q VISUAL +for the standard and screen editors. You might want to do: +.(l +set EDITOR=/usr/bin/ex VISUAL=/usr/bin/vi +.)l +\fBVisual\fP can be abbreviated to \fBv\fP. +.ip "\fBwrite\fP\ \ " +The +.b save +command always writes the entire message, including the headers, +into the file. If you want to write just the message itself, you +can use the +.b write +command. The +.b write +command has the same syntax as the +.b save +command, and can be abbreviated to simply +.b w . +Thus, we could write the second message by doing: +.(l +w 2 file.c +.)l +As suggested by this example, the +.b write +command is useful for such tasks as sending and receiving +source program text over the message system. +The filename in quotes, followed by the line +count and character count is echoed on the user's terminal. +.ip "\fBz\fP\ \ " +.i Mail +presents message headers in windowfuls as described under +the +.b headers +command. +You can move +.i Mail's +attention forward to the next window by giving the +.(l +z+ +.)l +command. Analogously, you can move to the previous window with: +.(l +z\- +.)l +.sh 2 "Custom options" +.pp +Throughout this manual, we have seen examples of binary and valued options. +This section describes each of the options in alphabetical order, including +some that you have not seen yet. +To avoid confusion, please note that the options are either +all lower case letters or all upper case letters. When I start a sentence +such as: +.q "Ask" +causes +.i Mail +to prompt you for a subject header, +I am only capitalizing +.q ask +as a courtesy to English. +.ip "\fBEDITOR\fP\ \ " +The valued option +.q EDITOR +defines the pathname of the text editor to be used in the +.b edit +command and ~e. If not defined, a standard editor is used. +.ip "\fBPAGER\fP\ \ " +Pathname of the program to use for paginating output when +it exceeds \fIcrt\fP lines. +A default paginator is used if this option is not defined. +.ip "\fBSHELL\fP\ \ " +The valued option +.q SHELL +gives the path name of your shell. This shell is used for the +.b ! +command and ~! escape. In addition, this shell expands +file names with shell metacharacters like * and ? in them. +.ip "\fBVISUAL\fP\ \ " +The valued option +.q VISUAL +defines the pathname of the screen editor to be used in the +.b visual +command +and ~v escape. A standard screen editor is used if you do not define one. +.ip "\fBappend\fP\ \ " +The +.q append +option is binary and +causes messages saved in +.i mbox +to be appended to the end rather than prepended. +Normally, \fIMail\fP will put messages in \fImbox\fP +in the same order that the system puts messages in your system mailbox. +By setting +.q append, +you are requesting that +.i mbox +be appended to regardless. It is in any event quicker to append. +.ip "\fBask\fP\ \ " +.q "Ask" +is a binary option which +causes +.i Mail +to prompt you for the subject of each message you send. +If you respond with simply a newline, no subject field will be sent. +.ip "\fBaskcc\fP\ \ " +.q Askcc +is a binary option which +causes you to be prompted for additional carbon copy recipients at the +end of each message. Responding with a newline shows your +satisfaction with the current list. +.ip "\fBautoprint\fP\ \ " +.q Autoprint +is a binary option which +causes the +.b delete +command to behave like +.b dp +\*- thus, after deleting a message, the next one will be typed +automatically. This is useful when quickly scanning and deleting +messages in your mailbox. +.ip "\fBcrt\fP \ \ " +The valued option +.q crt +is used as a threshold to determine how long a message must +be before +.b PAGER +is used to read it. +.ip "\fBdebug\fP \ \ " +The binary option +.q debug +causes debugging information to be displayed. Use of this +option is the same as using the \fB\-d\fP command line flag. +.ip "\fBdot\fP\ \ " +.q Dot +is a binary option which, if set, causes +.i Mail +to interpret a period alone on a line as the terminator +of the message you are sending. +.ip "\fBescape\fP\ \ " +To allow you to change the escape character used when sending +mail, you can set the valued option +.q escape. +Only the first character of the +.q escape +option is used, and it must be doubled if it is to appear as +the first character of a line of your message. If you change your escape +character, then ~ loses all its special meaning, and need no longer be doubled +at the beginning of a line. +.ip "\fBfolder\fP\ \ " +The name of the directory to use for storing folders of messages. +If this name begins with a `/' +.i Mail +considers it to be an absolute pathname; otherwise, the folder directory +is found relative to your home directory. +.ip "\fBhold\fP\ \ " +The binary option +.q hold +causes messages that have been read but not manually dealt with +to be held in the system mailbox. This prevents such messages from +being automatically swept into your \fImbox\fP file. +.ip "\fBignore\fP\ \ " +The binary option +.q ignore +causes \s-2RUBOUT\s0 characters from your terminal to be ignored and echoed +as @'s while you are sending mail. \s-2RUBOUT\s0 characters retain their +original meaning in +.i Mail +command mode. +Setting the +.q ignore +option is equivalent to supplying the +.b \-i +flag on the command line as described in section 6. +.ip "\fBignoreeof\fP\ \ " +An option related to +.q dot +is +.q ignoreeof +which makes +.i Mail +refuse to accept a control\-d as the end of a message. +.q Ignoreeof +also applies to +.i Mail +command mode. +.ip "\fBkeep\fP\ \ " +The +.q keep +option causes +.i Mail +to truncate your system mailbox instead of deleting it when it +is empty. This is useful if you elect to protect your mailbox, which +you would do with the shell command: +.(l +chmod 600 /var/mail/yourname +.)l +where +.i yourname +is your login name. If you do not do this, anyone can probably read +your mail, although people usually don't. +.ip "\fBkeepsave\fP\ \ " +When you +.b save +a message, +.i Mail +usually discards it when you +.b quit . +To retain all saved messages, set the +.q keepsave +option. +.ip "\fBmetoo\fP\ \ " +When sending mail to an alias, +.i Mail +makes sure that if you are included in the alias, that mail will not +be sent to you. This is useful if a single alias is being used by +all members of the group. If however, you wish to receive a copy of +all the messages you send to the alias, you can set the binary option +.q metoo. +.ip "\fBnoheader\fP\ \ " +The binary option +.q noheader +suppresses the printing of the version and headers when +.i Mail +is first invoked. Setting this option is the same as using +.b \-N +on the command line. +.ip "\fBnosave\fP\ \ " +Normally, +when you abort a message with two \s-2RUBOUTs\s0, +.i Mail +copies the partial letter to the file +.q dead.letter +in your home directory. Setting the binary option +.q nosave +prevents this. +.ip "\fBReplyall\fP\ \ " +Reverses the sense of +.i reply +and +.i Reply +commands. +.ip "\fBquiet\fP\ \ " +The binary option +.q quiet +suppresses the printing of the version when +.i Mail +is first invoked, +as well as printing the for example +.q "Message 4:" +from the +.b type +command. +.ip "\fBrecord\fP\ \ " +If you love to keep records, then the +valued option +.q record +can be set to the name of a file to save your outgoing mail. +Each new message you send is appended to the end of the file. +.ip "\fBscreen\fP\ \ " +When +.i Mail +initially prints the message headers, it determines the number to +print by looking at the speed of your terminal. The faster your +terminal, the more it prints. +The valued option +.q screen +overrides this calculation and +specifies how many message headers you want printed. +This number is also used for scrolling with the +.b z +command. +.ip "\fBsendmail\fP\ \ " +To use an alternate mail delivery system, set the +.q sendmail +option to the full pathname of the program to use. Note: this is not +for everyone! Most people should use the default delivery system. +.ip "\fBtoplines\fP\ \ " +The valued option +.q toplines +defines the number of lines that the +.q top +command will print out instead of the default five lines. +.ip "\fBverbose\fP\ \ " +The binary option "verbose" causes +.i Mail +to invoke sendmail with the +.b \-v +flag, which causes it to go into verbose mode and announce expansion +of aliases, etc. Setting the "verbose" option is equivalent to +invoking +.i Mail +with the +.b \-v +flag as described in section 6. diff --git a/share/doc/usd/07.mail/mail6.nr b/share/doc/usd/07.mail/mail6.nr new file mode 100644 index 0000000..0465a94 --- /dev/null +++ b/share/doc/usd/07.mail/mail6.nr @@ -0,0 +1,125 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail6.nr 8.1 (Berkeley) 6/8/93 +.\" +.bp +.sh 1 "Command line options" +.pp +This section describes command line options for +.i Mail +and what they are used for. +.ip \-N +Suppress the initial printing of headers. +.ip \-d +Turn on debugging information. Not of general interest. +.ip "\-f file\ \ " +Show the messages in +.i file +instead of your system mailbox. If +.i file +is omitted, +.i Mail +reads +.i mbox +in your home directory. +.ip \-i +Ignore tty interrupt signals. Useful on noisy phone lines, which +generate spurious RUBOUT or DELETE characters. It's usually +more effective to change your interrupt character to control\-c, +for which see the +.i stty +shell command. +.ip \-n +Inhibit reading of /etc/mail.rc. Not generally useful, since +/etc/mail.rc is usually empty. +.ip "\-s string" +Used for sending mail. +.i String +is used as the subject of the message being composed. If +.i string +contains blanks, you must surround it with quote marks. +.ip "\-u name" +Read +.i names's +mail instead of your own. Unwitting others often neglect to protect +their mailboxes, but discretion is advised. Essentially, +.b "\-u user" +is a shorthand way of doing +.b "\-f /var/mail/user". +.ip "\-v" +Use the +.b \-v +flag when invoking sendmail. This feature may also be enabled +by setting the the option "verbose". +.pp +The following command line flags are also recognized, but are +intended for use by programs invoking +.i Mail +and not for people. +.ip "\-T file" +Arrange to print on +.i file +the contents of the +.i article-id +fields of all messages that were either read or deleted. +.b \-T +is for the +.i readnews +program and should NOT be used for reading your mail. +.ip "\-h number" +Pass on hop count information. +.i Mail +will take the number, increment it, and pass it with +.b \-h +to the mail delivery system. +.b \-h +only has effect when sending mail and is used for network mail +forwarding. +.ip "\-r name" +Used for network mail forwarding: interpret +.i name +as the sender of the message. The +.i name +and +.b \-r +are simply sent along to the mail delivery system. Also, +.i Mail +will wait for the message to be sent and return the exit status. +Also restricts formatting of message. +.pp +Note that +.b \-h +and +.b \-r , +which are for network mail forwarding, are not used in practice +since mail forwarding is now handled separately. They may +disappear soon. diff --git a/share/doc/usd/07.mail/mail7.nr b/share/doc/usd/07.mail/mail7.nr new file mode 100644 index 0000000..0b2590b --- /dev/null +++ b/share/doc/usd/07.mail/mail7.nr @@ -0,0 +1,107 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail7.nr 8.1 (Berkeley) 6/8/93 +.\" +.sh 1 "Format of messages" +.pp +This section describes the format of messages. +Messages begin with a +.i from +line, which consists of the word +.q From +followed by a user name, followed by anything, followed by +a date in the format returned by the +.i ctime +library routine described in section 3 of the Unix Programmer's +Manual. A possible +.i ctime +format date is: +.(l +Tue Dec 1 10:58:23 1981 +.)l +The +.i ctime +date may be optionally followed by a single space and a +time zone indication, which +should be three capital letters, such as PDT. +.pp +Following the +.i from +line are zero or more +.i "header field" +lines. +Each header field line is of the form: +.(l +name: information +.)l +.i Name +can be anything, but only certain header fields are recognized as +having any meaning. The recognized header fields are: +.i article-id , +.i bcc , +.i cc , +.i from , +.i reply-to , +.i sender , +.i subject , +and +.i to . +Other header fields are also significant to other systems; see, +for example, the current Arpanet message standard for much more +information on this topic. +A header field can be continued onto following lines by making the +first character on the following line a space or tab character. +.pp +If any headers are present, they must be followed by a blank line. +The part that follows is called the +.i body +of the message, and must be ASCII text, not containing null characters. +Each line in the message body must be no longer than 512 characters and +terminated with an ASCII newline character. +If binary data must be passed through the mail system, it is suggested +that this data be encoded in a system which encodes six bits into +a printable character (i.e.: uuencode). +For example, one could use the upper and lower case letters, the digits, +and the characters comma and period to make up the 64 characters. +Then, one can send a 16-bit binary number +as three characters. These characters should be packed into lines, +preferably lines about 70 characters long as long lines are transmitted +more efficiently. +.pp +The message delivery system always adds a blank line to the end of +each message. This blank line must not be deleted. +.pp +The UUCP message delivery system sometimes adds a blank line to +the end of a message each time it is forwarded through a machine. +.pp +It should be noted that some network transport protocols enforce +limits to the lengths of messages. diff --git a/share/doc/usd/07.mail/mail8.nr b/share/doc/usd/07.mail/mail8.nr new file mode 100644 index 0000000..b09afbd --- /dev/null +++ b/share/doc/usd/07.mail/mail8.nr @@ -0,0 +1,75 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail8.nr 8.1 (Berkeley) 6/8/93 +.\" +.bp +.sh 1 "Glossary" +.pp +This section contains the definitions of a few phrases +peculiar to +.i Mail . +.ip "\fIalias\fP" +An alternative name for a person or list of people. +.ip "\fIflag\fP" +An option, given on the command line of +.i Mail , +prefaced with a \-. For example, +.b \-f +is a flag. +.ip "\fIheader field\fP" +At the beginning of a message, a line which contains information +that is part of the structure of the message. Popular header fields +include +.i to , +.i cc , +and +.i subject . +.ip "\fImail\ \ \fP" +A collection of messages. Often used in the phrase, +.q "Have you read your mail?" +.ip "\fImailbox\fP" +The place where your mail is stored, typically in the directory +/var/mail. +.ip "\fImessage\fP" +A single letter from someone, initially stored in your +.i mailbox . +.ip "\fImessage list\fP" +A string used in +.i Mail +command mode to describe a sequence of messages. +.ip "\fIoption\fP" +A piece of special purpose information used to tailor +.i Mail +to your taste. +Options are specified with the +.b set +command. diff --git a/share/doc/usd/07.mail/mail9.nr b/share/doc/usd/07.mail/mail9.nr new file mode 100644 index 0000000..271548e --- /dev/null +++ b/share/doc/usd/07.mail/mail9.nr @@ -0,0 +1,203 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mail9.nr 8.1 (Berkeley) 6/8/93 +.\" +.bp +.sh 1 "Summary of commands, options, and escapes" +.pp +This section gives a quick summary of the +.i Mail +commands, binary and valued options, and tilde escapes. +.pp +The following table describes the commands: +.TS +center ; +c ci +lb l. +Command Description +_ ++ Same as \fBnext\fP +- Back up to previous message +? Print brief summary of \fIMail\fP commands +! Single command escape to shell +Print Type message with ignored fields +Reply Reply to author of message only +Respond Same as \fBReply\fP +Type Type message with ignored fields +alias Define an alias as a set of user names +alternates List other names you are known by +chdir Change working directory, home by default +copy Copy a message to a file or folder +delete Delete a list of messages +dp Same as \fBdt\fP +dt Delete current message, type next message +edit Edit a list of messages +else Start of else part of conditional; see \fBif\fP +endif End of conditional statement; see \fBif\fP +exit Leave mail without changing anything +file Interrogate/change current mail file +folder Same as \fBfile\fP +folders List the folders in your folder directory +from List headers of a list of messages +headers List current window of messages +help Same as \fB?\fP +hold Same as \fBpreserve\fP +if Conditional execution of \fIMail\fP commands +ignore Set/examine list of ignored header fields +list List valid \fIMail\fP commands +local List other names for the local host +mail Send mail to specified names +mbox Arrange to save a list of messages in \fImbox\fP +next Go to next message and type it +preserve Arrange to leave list of messages in system mailbox +print Print messages +quit Leave \fIMail\fP; update system mailbox, \fImbox\fP as appropriate +reply Compose a reply to a message +respond Same as \fBreply\fP +retain Supersedes \fBignore\fP +save Append messages, headers included, on a file +set Set binary or valued options +shell Invoke an interactive shell +size Prints out size of message list +source Read \fImail\fP commands from a file +top Print first so many (5 by default) lines of list of messages +type Same as \fBprint\fP +undelete Undelete list of messages +unread Marks list of messages as not been read +unset Undo the operation of a \fBset\fP +visual Invoke visual editor on a list of messages +write Append messages to a file, don't include headers +xit Same as \fBexit\fP +z Scroll to next/previous screenful of headers +.TE +.bp +.(b +.pp +The following table describes the options. Each option is +shown as being either a binary or valued option. +.TS +center; +c ci ci +l ci l. +Option Type Description +_ +EDITOR valued Pathname of editor for ~e and \fBedit\fP +PAGER valued Pathname of paginator for \fBPrint\fP, \fBprint\fP, \fBType\fP and \fBtype\fP +SHELL valued Pathname of shell for \fBshell\fP, ~! and \fB!\fP +VISUAL valued Pathname of screen editor for ~v, \fBvisual\fP +append binary Always append messages to end of \fImbox\fP +ask binary Prompt user for Subject: field when sending +askcc binary Prompt user for additional Cc's at end of message +autoprint binary Print next message after \fBdelete\fP +crt valued Minimum number of lines before using \fBPAGER\fP +debug binary Print out debugging information +dot binary Accept . alone on line to terminate message input +escape valued Escape character to be used instead of\ \ ~ +folder valued Directory to store folders in +hold binary Hold messages in system mailbox by default +ignore binary Ignore \s-2RUBOUT\s0 while sending mail +ignoreeof binary Don't terminate letters/command input with \fB\(uaD\fP +keep binary Don't unlink system mailbox when empty +keepsave binary Don't delete \fBsave\fPd messages by default +metoo binary Include sending user in aliases +noheader binary Suppress initial printing of version and headers +nosave binary Don't save partial letter in \fIdead.letter\fP +quiet binary Suppress printing of \fIMail\fP version and message numbers +record valued File to save all outgoing mail in +screen valued Size of window of message headers for \fBz\fP, etc. +sendmail valued Choose alternate mail delivery system +toplines valued Number of lines to print in \fBtop\fP +verbose binary Invoke sendmail with the \fB\-v\fP flag +.TE +.)b +.(b +.pp +The following table summarizes the tilde escapes available +while sending mail. +.TS +center; +c ci ci +l li l. +Escape Arguments Description +_ +~! command Execute shell command +~b name ... Add names to "blind" Cc: list +~c name ... Add names to Cc: field +~d Read \fIdead.letter\fP into message +~e Invoke text editor on partial message +~f messages Read named messages +~h Edit the header fields +~m messages Read named messages, right shift by tab +~p Print message entered so far +~q Abort entry of letter; like \s-2RUBOUT\s0 +~r filename Read file into message +~s string Set Subject: field to \fIstring\fP +~t name ... Add names to To: field +~v Invoke screen editor on message +~w filename Write message on file +~| command Pipe message through \fIcommand\fP +~: Mail command Execute a \fIMail\fP command +~~ string Quote a ~ in front of \fIstring\fP +.TE +.)b +.(b +.pp +The following table shows the command line flags that +.i Mail +accepts: +.TS +center; +c c +l a. +Flag Description +_ +\-N Suppress the initial printing of headers +\-T \fIfile\fP Article-id's of read/deleted messages to \fIfile\fP +\-d Turn on debugging +\-f \fIfile\fP Show messages in \fIfile\fP or \fI~/mbox\fP +\-h \fInumber\fP Pass on hop count for mail forwarding +\-i Ignore tty interrupt signals +\-n Inhibit reading of /etc/mail.rc +\-r \fIname\fP Pass on \fIname\fP for mail forwarding +\-s \fIstring\fP Use \fIstring\fP as subject in outgoing mail +\-u \fIname\fP Read \fIname's\fP mail instead of your own +\-v Invoke sendmail with the \fB\-v\fP flag +.TE +.)b +.lp +Notes: +.b \-T , +.b \-d , +.b \-h , +and +.b \-r +are not for human use. diff --git a/share/doc/usd/07.mail/maila.nr b/share/doc/usd/07.mail/maila.nr new file mode 100644 index 0000000..84b01fe --- /dev/null +++ b/share/doc/usd/07.mail/maila.nr @@ -0,0 +1,33 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)maila.nr 8.1 (Berkeley) 6/8/93 +.\" |