/share/doc/usd/04.csh/csh.2

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 1304 lines · 1303 code · 1 blank · 0 comment · 0 complexity · 8538b7d2d2568208f944d9a1423969be MD5 · raw file

  1. .\"-
  2. .\" Copyright (c) 1980, 1993
  3. .\" The Regents of the University of California. All rights reserved.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\" 4. Neither the name of the University nor the names of its contributors
  14. .\" may be used to endorse or promote products derived from this software
  15. .\" without specific prior written permission.
  16. .\"
  17. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27. .\" SUCH DAMAGE.
  28. .\"
  29. .\" @(#)csh.2 8.1 (Berkeley) 6/8/93
  30. .\" $FreeBSD$
  31. .\"
  32. .nr H1 1
  33. .NH
  34. Details on the shell for terminal users
  35. .NH 2
  36. Shell startup and termination
  37. .PP
  38. When you login, the shell is started by the system in your
  39. .I home
  40. directory and begins by reading commands from a file
  41. .I \&.cshrc
  42. in this directory.
  43. All shells which you may start during your terminal session will
  44. read from this file.
  45. We will later see what kinds of commands are usefully placed there.
  46. For now we need not have this file and the shell does not complain about
  47. its absence.
  48. .PP
  49. A
  50. .I "login shell" ,
  51. executed after you login to the system,
  52. will, after it reads commands from
  53. .I \&.cshrc,
  54. read commands from a file
  55. .I \&.login
  56. also in your home directory.
  57. This file contains commands which you wish to do each time you login
  58. to the \s-2UNIX\s0 system.
  59. My
  60. .I \&.login
  61. file looks something like:
  62. .DS
  63. set ignoreeof
  64. set mail=(/usr/spool/mail/bill)
  65. echo "${prompt}users" ; users
  66. alias ts \e
  67. \'set noglob ; eval \`tset \-s \-m dialup:c100rv4pna \-m plugboard:?hp2621nl \!*\`\';
  68. ts; stty intr ^C kill ^U crt
  69. set time=15 history=10
  70. msgs \-f
  71. if (\-e $mail) then
  72. echo "${prompt}mail"
  73. mail
  74. endif
  75. .DE
  76. .PP
  77. This file contains several commands to be executed by \s-2UNIX\s0
  78. each time I login.
  79. The first is a
  80. .I set
  81. command which is interpreted directly by the shell. It sets the shell
  82. variable
  83. .I ignoreeof
  84. which causes the shell to not log me off if I hit ^D. Rather,
  85. I use the
  86. .I logout
  87. command to log off of the system.
  88. By setting the
  89. .I mail
  90. variable, I ask the shell to watch for incoming mail to me. Every 5 minutes
  91. the shell looks for this file and tells me if more mail has arrived there.
  92. An alternative to this is to put the command
  93. .DS
  94. biff y
  95. .DE
  96. in place of this
  97. .I set;
  98. this will cause me to be notified immediately when mail arrives, and to
  99. be shown the first few lines of the new message.
  100. .PP
  101. Next I set the shell variable `time' to `15' causing the shell to automatically
  102. print out statistics lines for commands which execute for at least 15 seconds
  103. of \s-2CPU\s+2 time. The variable `history' is set to 10 indicating that
  104. I want the shell to remember the last 10 commands I type in its
  105. .I "history list" ,
  106. (described later).
  107. .PP
  108. I create an
  109. .I alias
  110. ``ts'' which executes a
  111. \fItset\fR\|(1) command setting up the modes of the terminal.
  112. The parameters to
  113. .I tset
  114. indicate the kinds of terminal which I usually use when not on a hardwired
  115. port. I then execute ``ts'' and also use the
  116. .I stty
  117. command to change the interrupt character to ^C and the line kill
  118. character to ^U.
  119. .PP
  120. I then run the `msgs' program, which provides me with any
  121. system messages which I have not seen before; the `\-f' option here prevents
  122. it from telling me anything if there are no new messages.
  123. Finally, if my mailbox file exists, then I run the `mail' program to
  124. process my mail.
  125. .PP
  126. When the `mail' and `msgs' programs finish, the shell will finish
  127. processing my
  128. .I \&.login
  129. file and begin reading commands from the terminal, prompting for each with
  130. `% '.
  131. When I log off (by giving the
  132. .I logout
  133. command) the shell
  134. will print `logout' and execute commands from the file `.logout'
  135. if it exists in my home directory.
  136. After that the shell will terminate and \s-2UNIX\s0 will log
  137. me off the system.
  138. If the system is not going down, I will receive a new login message.
  139. In any case, after the `logout' message the shell is committed to terminating
  140. and will take no further input from my terminal.
  141. .NH 2
  142. Shell variables
  143. .PP
  144. The shell maintains a set of
  145. .I variables.
  146. We saw above the variables
  147. .I history
  148. and
  149. .I time
  150. which had values `10' and `15'.
  151. In fact, each shell variable has as value an array of
  152. zero or more
  153. .I strings.
  154. Shell variables may be assigned values by the set command. It has
  155. several forms, the most useful of which was given above and is
  156. .DS
  157. set name=value
  158. .DE
  159. .PP
  160. Shell variables may be used to store values which are to
  161. be used in commands later through a substitution mechanism.
  162. The shell variables most commonly referenced are, however, those which the
  163. shell itself refers to.
  164. By changing the values of these variables one can directly affect the
  165. behavior of the shell.
  166. .PP
  167. One of the most important variables is the variable
  168. .I path.
  169. This variable contains a sequence of directory names where the shell
  170. searches for commands.
  171. The
  172. .I set
  173. command with no arguments
  174. shows the value of all variables currently defined (we usually say
  175. .I set)
  176. in the shell.
  177. The default value for path will be shown by
  178. .I set
  179. to be
  180. .DS
  181. % set
  182. .ta .75i
  183. argv ()
  184. cwd /usr/bill
  185. home /usr/bill
  186. path (. /usr/ucb /bin /usr/bin)
  187. prompt %
  188. shell /bin/csh
  189. status 0
  190. term c100rv4pna
  191. user bill
  192. %
  193. .so tabs
  194. .DE
  195. This output indicates that the variable path points to the current
  196. directory `.' and then `/usr/ucb', `/bin' and `/usr/bin'.
  197. Commands which you may write might be in `.' (usually one of
  198. your directories).
  199. Commands developed at Berkeley, live in `/usr/ucb'
  200. while commands developed at Bell Laboratories live in `/bin' and `/usr/bin'.
  201. .PP
  202. A number of locally developed programs on the system live in the directory
  203. `/usr/local'.
  204. If we wish that all shells which we invoke to have
  205. access to these new programs we can place the command
  206. .DS
  207. set path=(. /usr/ucb /bin /usr/bin /usr/local)
  208. .DE
  209. in our file
  210. .I \&.cshrc
  211. in our home directory.
  212. Try doing this and then logging out and back in and do
  213. .DS
  214. set
  215. .DE
  216. again to see that the value assigned to
  217. .I path
  218. has changed.
  219. .FS \(dg
  220. Another directory that might interest you is /usr/new, which contains
  221. many useful user-contributed programs provided with Berkeley Unix.
  222. .FE
  223. .PP
  224. One thing you should be aware of is that the shell examines each directory
  225. which you insert into your path and determines which commands are contained
  226. there. Except for the current directory `.', which the shell treats specially,
  227. this means that if commands are added to a directory in your search path after
  228. you have started the shell, they will not necessarily be found by the shell.
  229. If you wish to use a command which has been added in this way, you should
  230. give the command
  231. .DS
  232. rehash
  233. .DE
  234. to the shell, which will cause it to recompute its internal table of command
  235. locations, so that it will find the newly added command.
  236. Since the shell has to look in the current directory `.' on each command,
  237. placing it at the end of the path specification usually works equivalently
  238. and reduces overhead.
  239. .PP
  240. Other useful built in variables are the variable
  241. .I home
  242. which shows your home directory,
  243. .I cwd
  244. which contains your current working directory,
  245. the variable
  246. .I ignoreeof
  247. which can be set in your
  248. .I \&.login
  249. file to tell the shell not to exit when it receives an end-of-file from
  250. a terminal (as described above).
  251. The variable `ignoreeof'
  252. is one of several variables which the shell does not care about the
  253. value of, only whether they are
  254. .I set
  255. or
  256. .I unset.
  257. Thus to set this variable you simply do
  258. .DS
  259. set ignoreeof
  260. .DE
  261. and to unset it do
  262. .DS
  263. unset ignoreeof
  264. .DE
  265. These give the variable `ignoreeof' no value, but none is desired or required.
  266. .PP
  267. Finally, some other built-in shell variables of use are the
  268. variables
  269. .I noclobber
  270. and
  271. .I mail.
  272. The metasyntax
  273. .DS
  274. > filename
  275. .DE
  276. which redirects the standard output of a command
  277. will overwrite and destroy the previous contents of the named file.
  278. In this way you may accidentally overwrite a file which is valuable.
  279. If you would prefer that the shell not overwrite files in this
  280. way you can
  281. .DS
  282. set noclobber
  283. .DE
  284. in your
  285. .I \&.login
  286. file.
  287. Then trying to do
  288. .DS
  289. date > now
  290. .DE
  291. would cause a diagnostic if `now' existed already.
  292. You could type
  293. .DS
  294. date >! now
  295. .DE
  296. if you really wanted to overwrite the contents of `now'.
  297. The `>!' is a special metasyntax indicating that clobbering the
  298. file is ok.\(dg
  299. .FS
  300. \(dgThe space between the `!' and the word `now' is critical here, as `!now'
  301. would be an invocation of the
  302. .I history
  303. mechanism, and have a totally different effect.
  304. .FE
  305. .NH 2
  306. The shell's history list
  307. .PP
  308. The shell can maintain a
  309. .I "history list"
  310. into which it places the words
  311. of previous commands.
  312. It is possible to use a notation to reuse commands or words
  313. from commands in forming new commands.
  314. This mechanism can be used to repeat previous commands or to
  315. correct minor typing mistakes in commands.
  316. .PP
  317. The following figure gives a sample session involving typical usage of the
  318. history mechanism of the shell.
  319. .KF
  320. .DS
  321. % cat bug.c
  322. main()
  323. {
  324. printf("hello);
  325. }
  326. % cc !$
  327. cc bug.c
  328. "bug.c", line 4: newline in string or char constant
  329. "bug.c", line 5: syntax error
  330. % ed !$
  331. ed bug.c
  332. 29
  333. 4s/);/"&/p
  334. printf("hello");
  335. w
  336. 30
  337. q
  338. % !c
  339. cc bug.c
  340. % a.out
  341. hello% !e
  342. ed bug.c
  343. 30
  344. 4s/lo/lo\e\en/p
  345. printf("hello\en");
  346. w
  347. 32
  348. q
  349. % !c \-o bug
  350. cc bug.c \-o bug
  351. % size a.out bug
  352. a.out: 2784+364+1028 = 4176b = 0x1050b
  353. bug: 2784+364+1028 = 4176b = 0x1050b
  354. % ls \-l !*
  355. ls \-l a.out bug
  356. \(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:41 a.out
  357. \(mirwxr\(mixr\(mix 1 bill 3932 Dec 19 09:42 bug
  358. % bug
  359. hello
  360. % num bug.c | spp
  361. spp: Command not found.
  362. % ^spp^ssp
  363. num bug.c | ssp
  364. 1 main()
  365. 3 {
  366. 4 printf("hello\en");
  367. 5 }
  368. % !! | lpr
  369. num bug.c | ssp | lpr
  370. %
  371. .DE
  372. .KE
  373. In this example we have a very simple C program which has a bug (or two)
  374. in it in the file `bug.c', which we `cat' out on our terminal. We then
  375. try to run the C compiler on it, referring to the file again as `!$',
  376. meaning the last argument to the previous command. Here the `!' is the
  377. history mechanism invocation metacharacter, and the `$' stands for the last
  378. argument, by analogy to `$' in the editor which stands for the end of the line.
  379. The shell echoed the command, as it would have been typed without use of
  380. the history mechanism, and then executed it.
  381. The compilation yielded error diagnostics so we now run the editor on the
  382. file we were trying to compile, fix the bug, and run the C compiler again,
  383. this time referring to this command simply as `!c', which repeats the last
  384. command which started with the letter `c'. If there were other
  385. commands starting with `c' done recently we could have said `!cc' or even
  386. `!cc:p' which would have printed the last command starting with `cc'
  387. without executing it.
  388. .PP
  389. After this recompilation, we ran the resulting `a.out' file, and then
  390. noting that there still was a bug, ran the editor again. After fixing
  391. the program we ran the C compiler again, but tacked onto the command
  392. an extra `\-o bug' telling the compiler to place the resultant binary in
  393. the file `bug' rather than `a.out'. In general, the history mechanisms
  394. may be used anywhere in the formation of new commands and other characters
  395. may be placed before and after the substituted commands.
  396. .PP
  397. We then ran the `size' command to see how large the binary program images
  398. we have created were, and then an `ls \-l' command with the same argument
  399. list, denoting the argument list `\!*'.
  400. Finally we ran the program `bug' to see that its output is indeed correct.
  401. .PP
  402. To make a numbered listing of the program we ran the `num' command on the file `bug.c'.
  403. In order to compress out blank lines in the output of `num' we ran the
  404. output through the filter `ssp', but misspelled it as spp. To correct this
  405. we used a shell substitute, placing the old text and new text between `^'
  406. characters. This is similar to the substitute command in the editor.
  407. Finally, we repeated the same command with `!!', but sent its output to the
  408. line printer.
  409. .PP
  410. There are other mechanisms available for repeating commands. The
  411. .I history
  412. command prints out a number of previous commands with numbers by which
  413. they can be referenced. There is a way to refer to a previous command
  414. by searching for a string which appeared in it, and there are other,
  415. less useful, ways to select arguments to include in a new command.
  416. A complete description of all these mechanisms
  417. is given in the C shell manual pages in the \s-2UNIX\s0 Programmer's Manual.
  418. .NH 2
  419. Aliases
  420. .PP
  421. The shell has an
  422. .I alias
  423. mechanism which can be used to make transformations on input commands.
  424. This mechanism can be used to simplify the commands you type,
  425. to supply default arguments to commands,
  426. or to perform transformations on commands and their arguments.
  427. The alias facility is similar to a macro facility.
  428. Some of the features obtained by aliasing can be obtained also
  429. using shell command files, but these take place in another instance
  430. of the shell and cannot directly affect the current shells environment
  431. or involve commands such as
  432. .I cd
  433. which must be done in the current shell.
  434. .PP
  435. As an example, suppose that there is a new version of the mail program
  436. on the system called `newmail'
  437. you wish to use, rather than the standard mail program which is called
  438. `mail'.
  439. If you place the shell command
  440. .DS
  441. alias mail newmail
  442. .DE
  443. in your
  444. .I \&.cshrc
  445. file, the shell will transform an input line of the form
  446. .DS
  447. mail bill
  448. .DE
  449. into a call on `newmail'.
  450. More generally, suppose we wish the command `ls' to always show
  451. sizes of files, that is to always do `\-s'.
  452. We can do
  453. .DS
  454. alias ls ls \-s
  455. .DE
  456. or even
  457. .DS
  458. alias dir ls \-s
  459. .DE
  460. creating a new command syntax `dir'
  461. which does an `ls \-s'.
  462. If we say
  463. .DS
  464. dir ~bill
  465. .DE
  466. then the shell will translate this to
  467. .DS
  468. ls \-s /mnt/bill
  469. .DE
  470. .PP
  471. Thus the
  472. .I alias
  473. mechanism can be used to provide short names for commands,
  474. to provide default arguments,
  475. and to define new short commands in terms of other commands.
  476. It is also possible to define aliases which contain multiple
  477. commands or pipelines, showing where the arguments to the original
  478. command are to be substituted using the facilities of the
  479. history mechanism.
  480. Thus the definition
  481. .DS
  482. alias cd \'cd \e!* ; ls \'
  483. .DE
  484. would do an
  485. .I ls
  486. command after each change directory
  487. .I cd
  488. command.
  489. We enclosed the entire alias definition in `\'' characters to prevent
  490. most substitutions from occurring and the character `;' from being
  491. recognized as a metacharacter.
  492. The `!' here is escaped with a `\e' to prevent it from being interpreted
  493. when the alias command is typed in.
  494. The `\e!*' here substitutes the entire argument list to the pre-aliasing
  495. .I cd
  496. command, without giving an error if there were no arguments.
  497. The `;' separating commands is used here
  498. to indicate that one command is to be done and then the next.
  499. Similarly the definition
  500. .DS
  501. alias whois \'grep \e!^ /etc/passwd\'
  502. .DE
  503. defines a command which looks up its first argument in the password file.
  504. .PP
  505. .B Warning:
  506. The shell currently reads the
  507. .I \&.cshrc
  508. file each time it starts up. If you place a large number of commands
  509. there, shells will tend to start slowly. A mechanism for saving the shell
  510. environment after reading the \fI\&.cshrc\fR file and quickly restoring it is
  511. under development, but for now you should try to limit the number of
  512. aliases you have to a reasonable number... 10 or 15 is reasonable,
  513. 50 or 60 will cause a noticeable delay in starting up shells, and make
  514. the system seem sluggish when you execute commands from within the editor
  515. and other programs.
  516. .NH 2
  517. More redirection; >> and >&
  518. .PP
  519. There are a few more notations useful to the terminal user
  520. which have not been introduced yet.
  521. .PP
  522. In addition to the standard output, commands also have a
  523. .I "diagnostic output"
  524. which is normally directed to the terminal even when the standard output
  525. is redirected to a file or a pipe.
  526. It is occasionally desirable to direct the diagnostic output along with
  527. the standard output.
  528. For instance if you want to redirect the output of a long running command
  529. into a file and wish to have a record of any error diagnostic it produces
  530. you can do
  531. .DS
  532. command >& file
  533. .DE
  534. The `>&' here tells the shell to route both the diagnostic output and the
  535. standard output into `file'.
  536. Similarly you can give the command
  537. .DS
  538. command |\|& lpr
  539. .DE
  540. to route both standard and diagnostic output through the pipe
  541. to the line printer daemon
  542. .I lpr.\(dd
  543. .FS
  544. \(dd A command of the form
  545. .br
  546. .ti +5
  547. command >&! file
  548. .br
  549. exists, and is used when
  550. .I noclobber
  551. is set and
  552. .I file
  553. already exists.
  554. .FE
  555. .PP
  556. Finally, it is possible to use the form
  557. .DS
  558. command >> file
  559. .DE
  560. to place output at the end of an existing file.\(dg
  561. .FS
  562. \(dg If
  563. .I noclobber
  564. is set, then an error will result if
  565. .I file
  566. does not exist, otherwise the shell will create
  567. .I file
  568. if it doesn't exist.
  569. A form
  570. .br
  571. .ti +5
  572. command >>! file
  573. .br
  574. makes it not be an error for file to not exist when
  575. .I noclobber
  576. is set.
  577. .FE
  578. .NH 2
  579. Jobs; Background, Foreground, or Suspended
  580. .PP
  581. When one or more commands
  582. are typed together as a pipeline or as a sequence of commands separated by
  583. semicolons, a single
  584. .I job
  585. is created by the shell consisting of these commands together as a unit.
  586. Single commands without pipes or semicolons create the simplest jobs.
  587. Usually, every line typed to the shell creates a job.
  588. Some lines that create jobs (one per line) are
  589. .DS
  590. sort < data
  591. ls \-s | sort \-n | head \-5
  592. mail harold
  593. .DE
  594. .PP
  595. If the metacharacter `&' is typed
  596. at the end of the commands, then the job is started as a
  597. .I background
  598. job. This means that the shell does not wait for it to complete but
  599. immediately prompts and is ready for another command. The job runs
  600. .I "in the background"
  601. at the same time that normal jobs, called
  602. .I foreground
  603. jobs, continue to be read and executed by the shell one at a time.
  604. Thus
  605. .DS
  606. du > usage &
  607. .DE
  608. would run the
  609. .I du
  610. program, which reports on the disk usage of your working directory (as well as
  611. any directories below it), put the output into the file `usage' and return
  612. immediately with a prompt for the next command without out waiting for
  613. .I du
  614. to finish. The
  615. .I du
  616. program would continue executing in the background
  617. until it finished, even though you can type and execute more commands in the
  618. mean time.
  619. When a background
  620. job terminates, a message is typed by the shell just before the next prompt
  621. telling you that the job has completed.
  622. In the following example the
  623. .I du
  624. job finishes sometime during the
  625. execution of the
  626. .I mail
  627. command and its completion is reported just before
  628. the prompt after the
  629. .I mail
  630. job is finished.
  631. .DS
  632. % du > usage &
  633. [1] 503
  634. % mail bill
  635. How do you know when a background job is finished?
  636. EOT
  637. .ta 1.75i
  638. [1] \- Done du > usage
  639. %
  640. .so tabs
  641. .DE
  642. If the job did not terminate normally the `Done' message might say
  643. something else like `Killed'.
  644. If you want the
  645. terminations of background jobs to be reported at the time they occur
  646. (possibly interrupting the output of other foreground jobs), you can set
  647. the
  648. .I notify
  649. variable. In the previous example this would mean that the
  650. `Done' message might have come right in the middle of the message to
  651. Bill.
  652. Background jobs are unaffected by any signals from the keyboard like
  653. the \s-2STOP\s0, \s-2INTERRUPT\s0, or \s-2QUIT\s0 signals mentioned earlier.
  654. .PP
  655. Jobs are recorded in a table inside the shell until they terminate.
  656. In this table, the shell remembers the command names, arguments and the
  657. .I "process numbers"
  658. of all commands in the job as well as the working directory where the job was
  659. started.
  660. Each job in the table is either running
  661. .I "in the foreground"
  662. with the shell waiting for it to terminate, running
  663. .I "in the background,"
  664. or
  665. .I suspended.
  666. Only one job can be running in the foreground at one time, but several
  667. jobs can be suspended or running in the background at once. As each job
  668. is started, it is assigned a small identifying
  669. number called the
  670. .I "job number"
  671. which can be used later to refer to the job in the commands described below.
  672. Job numbers remain
  673. the same until the job terminates and then are re-used.
  674. .PP
  675. When a job is started in the background using `&', its number, as well
  676. as the process numbers of all its (top level) commands, is typed by the shell
  677. before prompting you for another command.
  678. For example,
  679. .DS
  680. % ls \-s | sort \-n > usage &
  681. [2] 2034 2035
  682. %
  683. .DE
  684. runs the `ls' program with the `\-s' options, pipes this output into
  685. the `sort' program with the `\-n' option which puts its output into the
  686. file `usage'.
  687. Since the `&' was at the end of the line, these two programs were started
  688. together as a background job. After starting the job, the shell prints
  689. the job number in brackets (2 in this case) followed by the process number
  690. of each program started in the job. Then the shell immediates prompts for
  691. a new command, leaving the job running simultaneously.
  692. .PP
  693. As mentioned in section 1.8, foreground jobs become
  694. .I suspended
  695. by typing ^Z
  696. which sends a \s-2STOP\s0 signal to the currently running
  697. foreground job. A background job can become suspended by using the
  698. .I stop
  699. command described below. When jobs are suspended they merely stop
  700. any further progress until started again, either in the foreground
  701. or the background. The shell notices when a job becomes stopped and
  702. reports this fact, much like it reports the termination of background jobs.
  703. For foreground jobs this looks like
  704. .DS
  705. % du > usage
  706. ^Z
  707. Stopped
  708. %
  709. .DE
  710. `Stopped' message is typed by the shell when it notices that the
  711. .I du
  712. program stopped.
  713. For background jobs, using the
  714. .I stop
  715. command, it is
  716. .DS
  717. % sort usage &
  718. [1] 2345
  719. % stop %1
  720. .ta 1.75i
  721. [1] + Stopped (signal) sort usage
  722. %
  723. .so tabs
  724. .DE
  725. Suspending foreground jobs can be very useful when you need to temporarily
  726. change what you are doing (execute other commands) and then return to
  727. the suspended job. Also, foreground jobs can be suspended and then
  728. continued as background jobs using the
  729. .I bg
  730. command, allowing you to continue other work and
  731. stop waiting for the foreground job to finish. Thus
  732. .DS
  733. % du > usage
  734. ^Z
  735. Stopped
  736. % bg
  737. [1] du > usage &
  738. %
  739. .DE
  740. starts `du' in the foreground, stops it before it finishes, then continues
  741. it in the background allowing more foreground commands to be executed.
  742. This is especially helpful
  743. when a foreground job ends up taking longer than you expected and you
  744. wish you had started it in the background in the beginning.
  745. .PP
  746. All
  747. .I "job control"
  748. commands can take an argument that identifies a particular
  749. job.
  750. All job name arguments begin with the character `%', since some of the
  751. job control commands also accept process numbers (printed by the
  752. .I ps
  753. command.)
  754. The default job (when no argument is given) is called the
  755. .I current
  756. job and is identified by a `+' in the output of the
  757. .I jobs
  758. command, which shows you which jobs you have.
  759. When only one job is stopped or running in the background (the usual case)
  760. it is always the current job thus no argument is needed.
  761. If a job is stopped while running in the foreground it becomes the
  762. .I current
  763. job and the existing current job becomes the
  764. .I previous
  765. job \- identified by a `\-' in the output of
  766. .I jobs.
  767. When the current job terminates, the previous job becomes the current job.
  768. When given, the argument is either `%\-' (indicating
  769. the previous job); `%#', where # is the job number;
  770. `%pref' where pref is some unique prefix of the command name
  771. and arguments of one of the jobs; or `%?' followed by some string found
  772. in only one of the jobs.
  773. .PP
  774. The
  775. .I jobs
  776. command types the table of jobs, giving the job number,
  777. commands and status (`Stopped' or `Running') of each background or
  778. suspended job. With the `\-l' option the process numbers are also
  779. typed.
  780. .DS
  781. % du > usage &
  782. [1] 3398
  783. % ls \-s | sort \-n > myfile &
  784. [2] 3405
  785. % mail bill
  786. ^Z
  787. Stopped
  788. % jobs
  789. .ta 1.75i
  790. [1] \(mi Running du > usage
  791. [2] Running ls \-s | sort \-n > myfile
  792. [3] \(pl Stopped mail bill
  793. % fg %ls
  794. ls \-s | sort \-n > myfile
  795. % more myfile
  796. .so tabs
  797. .DE
  798. .PP
  799. The
  800. .I fg
  801. command runs a suspended or background job in the foreground. It is
  802. used to restart a previously suspended job or change a background job
  803. to run in the foreground (allowing signals or input from the terminal).
  804. In the above example we used
  805. .I fg
  806. to change the `ls' job from the
  807. background to the foreground since we wanted to wait for it to
  808. finish before looking at its output file.
  809. The
  810. .I bg
  811. command runs a suspended job in the background. It is usually used
  812. after stopping the currently running foreground job with the
  813. \s-2STOP\s0 signal. The combination of the \s-2STOP\s0 signal and the
  814. .I bg
  815. command changes a foreground job into a background job.
  816. The
  817. .I stop
  818. command suspends a background job.
  819. .PP
  820. The
  821. .I kill
  822. command terminates a background or suspended job immediately.
  823. In addition to jobs, it may be given process numbers as arguments,
  824. as printed by
  825. .I ps.
  826. Thus, in the example above, the running
  827. .I du
  828. command could have been terminated by the command
  829. .DS
  830. % kill %1
  831. .ta 1.75i
  832. [1] Terminated du > usage
  833. %
  834. .so tabs
  835. .DE
  836. .PP
  837. The
  838. .I notify
  839. command (not the variable mentioned earlier) indicates that the termination
  840. of a specific job should be
  841. reported at the time it finishes instead of waiting for the next prompt.
  842. .PP
  843. If a job running in the background tries to read input from the terminal
  844. it is automatically stopped. When such a job is then run in the
  845. foreground, input can be given to the job. If desired, the job can
  846. be run in the background again until it requests input again.
  847. This is illustrated in the following sequence where the `s' command in the
  848. text editor might take a long time.
  849. .ID
  850. .nf
  851. % ed bigfile
  852. 120000
  853. 1,$s/thisword/thatword/
  854. ^Z
  855. Stopped
  856. % bg
  857. [1] ed bigfile &
  858. %
  859. . . . some foreground commands
  860. .ta 1.75i
  861. [1] Stopped (tty input) ed bigfile
  862. % fg
  863. ed bigfile
  864. w
  865. 120000
  866. q
  867. %
  868. .so tabs
  869. .DE
  870. So after the `s' command was issued, the `ed' job was stopped with ^Z
  871. and then put in the background using
  872. .I bg.
  873. Some time later when the `s' command was finished,
  874. .I ed
  875. tried to read another command and was stopped because jobs
  876. in the background cannot read from the terminal. The
  877. .I fg
  878. command returned the `ed' job to the foreground where it could once again
  879. accept commands from the terminal.
  880. .PP
  881. The command
  882. .DS
  883. stty tostop
  884. .DE
  885. causes all background jobs run on your terminal to stop
  886. when they are about to
  887. write output to the terminal. This prevents messages from background
  888. jobs from interrupting foreground job output and allows you to run
  889. a job in the background without losing terminal output. It also
  890. can be used for interactive programs that sometimes have long
  891. periods without interaction. Thus each time it outputs a prompt for more
  892. input it will stop before the prompt. It can then be run in the
  893. foreground using
  894. .I fg,
  895. more input can be given and, if necessary stopped and returned to
  896. the background. This
  897. .I stty
  898. command might be a good thing to put in your
  899. .I \&.login
  900. file if you do not like output from background jobs interrupting
  901. your work. It also can reduce the need for redirecting the output
  902. of background jobs if the output is not very big:
  903. .DS
  904. % stty tostop
  905. % wc hugefile &
  906. [1] 10387
  907. % ed text
  908. \&. . . some time later
  909. q
  910. .ta 1.75i
  911. [1] Stopped (tty output) wc hugefile
  912. % fg wc
  913. wc hugefile
  914. 13371 30123 302577
  915. % stty \-tostop
  916. .so tabs
  917. .DE
  918. Thus after some time the `wc' command, which counts the lines, words
  919. and characters in a file, had one line of output. When it tried to
  920. write this to the terminal it stopped. By restarting it in the
  921. foreground we allowed it to write on the terminal exactly when we were
  922. ready to look at its output.
  923. Programs which attempt to change the mode of the terminal will also
  924. block, whether or not
  925. .I tostop
  926. is set, when they are not in the foreground, as
  927. it would be very unpleasant to have a background job change the state
  928. of the terminal.
  929. .PP
  930. Since the
  931. .I jobs
  932. command only prints jobs started in the currently executing shell,
  933. it knows nothing about background jobs started in other login sessions
  934. or within shell files. The
  935. .I ps
  936. can be used in this case to find out about background jobs not started
  937. in the current shell.
  938. .NH 2
  939. Working Directories
  940. .PP
  941. As mentioned in section 1.6, the shell is always in a particular
  942. .I "working directory."
  943. The `change directory' command
  944. .I chdir
  945. (its
  946. short form
  947. .I cd
  948. may also be used)
  949. changes the working directory of the shell,
  950. that is, changes the directory you
  951. are located in.
  952. .PP
  953. It is useful to make a directory for each project you wish to work on
  954. and to place all files related to that project in that directory.
  955. The `make directory' command,
  956. .I mkdir,
  957. creates a new directory.
  958. The
  959. .I pwd
  960. (`print working directory') command
  961. reports the absolute pathname of the working directory of the shell,
  962. that is, the directory you are
  963. located in.
  964. Thus in the example below:
  965. .DS
  966. % pwd
  967. /usr/bill
  968. % mkdir newpaper
  969. % chdir newpaper
  970. % pwd
  971. /usr/bill/newpaper
  972. %
  973. .DE
  974. the user has created and moved to the
  975. directory
  976. .I newpaper.
  977. where, for example, he might
  978. place a group of related files.
  979. .PP
  980. No matter where you have moved to in a directory hierarchy,
  981. you can return to your `home' login directory by doing just
  982. .DS
  983. cd
  984. .DE
  985. with no arguments.
  986. The name `..' always means the directory above the current one in
  987. the hierarchy, thus
  988. .DS
  989. cd ..
  990. .DE
  991. changes the shell's working directory to the one directly above the
  992. current one.
  993. The name `..' can be used in any
  994. pathname, thus,
  995. .DS
  996. cd ../programs
  997. .DE
  998. means
  999. change to the directory `programs' contained in the directory
  1000. above the current one.
  1001. If you have several directories for different
  1002. projects under, say, your home directory,
  1003. this shorthand notation
  1004. permits you to switch easily between them.
  1005. .PP
  1006. The shell always remembers the pathname of its current working directory in
  1007. the variable
  1008. .I cwd.
  1009. The shell can also be requested to remember the previous directory when
  1010. you change to a new working directory. If the `push directory' command
  1011. .I pushd
  1012. is used in place of the
  1013. .I cd
  1014. command, the shell saves the name of the current working directory
  1015. on a
  1016. .I "directory stack"
  1017. before changing to the new one.
  1018. You can see this list at any time by typing the `directories'
  1019. command
  1020. .I dirs.
  1021. .ID
  1022. .nf
  1023. % pushd newpaper/references
  1024. ~/newpaper/references ~
  1025. % pushd /usr/lib/tmac
  1026. /usr/lib/tmac ~/newpaper/references ~
  1027. % dirs
  1028. /usr/lib/tmac ~/newpaper/references ~
  1029. % popd
  1030. ~/newpaper/references ~
  1031. % popd
  1032. ~
  1033. %
  1034. .DE
  1035. The list is printed in a horizontal line, reading left to right,
  1036. with a tilde (~) as
  1037. shorthand for your home directory\(emin this case `/usr/bill'.
  1038. The directory stack is printed whenever there is more than one
  1039. entry on it and it changes.
  1040. It is also printed by a
  1041. .I dirs
  1042. command.
  1043. .I Dirs
  1044. is usually faster and more informative than
  1045. .I pwd
  1046. since it shows the current working directory as well as any
  1047. other directories remembered in the stack.
  1048. .PP
  1049. The
  1050. .I pushd
  1051. command with no argument
  1052. alternates the current directory with the first directory in the
  1053. list.
  1054. The `pop directory'
  1055. .I popd
  1056. command without an argument returns you to the directory you were in prior to
  1057. the current one, discarding the previous current directory from the
  1058. stack (forgetting it).
  1059. Typing
  1060. .I popd
  1061. several times in a series takes you backward through the directories
  1062. you had been in (changed to) by
  1063. .I pushd
  1064. command.
  1065. There are other options to
  1066. .I pushd
  1067. and
  1068. .I popd
  1069. to manipulate the contents of the directory stack and to change
  1070. to directories not at the top of the stack; see the
  1071. .I csh
  1072. manual page for details.
  1073. .PP
  1074. Since the shell remembers the working directory in which each job
  1075. was started, it warns you when you might be confused by restarting
  1076. a job in the foreground which has a different working directory than the
  1077. current working directory of the shell. Thus if you start a background
  1078. job, then change the shell's working directory and then cause the
  1079. background job to run in the foreground, the shell warns you that the
  1080. working directory of the currently running foreground job is different
  1081. from that of the shell.
  1082. .DS
  1083. % dirs \-l
  1084. /mnt/bill
  1085. % cd myproject
  1086. % dirs
  1087. ~/myproject
  1088. % ed prog.c
  1089. 1143
  1090. ^Z
  1091. Stopped
  1092. % cd ..
  1093. % ls
  1094. myproject
  1095. textfile
  1096. % fg
  1097. ed prog.c (wd: ~/myproject)
  1098. .DE
  1099. This way the shell warns you when there
  1100. is an implied change of working directory, even though no cd command was
  1101. issued. In the above example the `ed' job was still in `/mnt/bill/project'
  1102. even though the shell had changed to `/mnt/bill'.
  1103. A similar warning is given when such a foreground job
  1104. terminates or is suspended (using the \s-2STOP\s0 signal) since
  1105. the return to the shell again implies a change of working directory.
  1106. .DS
  1107. % fg
  1108. ed prog.c (wd: ~/myproject)
  1109. . . . after some editing
  1110. q
  1111. (wd now: ~)
  1112. %
  1113. .DE
  1114. These messages are sometimes confusing if you use programs that change
  1115. their own working directories, since the shell only remembers which
  1116. directory a job is started in, and assumes it stays there.
  1117. The `\-l' option of
  1118. .I jobs
  1119. will type the working directory
  1120. of suspended or background jobs when it is different
  1121. from the current working directory of the shell.
  1122. .NH 2
  1123. Useful built-in commands
  1124. .PP
  1125. We now give a few of the useful built-in commands of the shell describing
  1126. how they are used.
  1127. .PP
  1128. The
  1129. .I alias
  1130. command described above is used to assign new aliases and to show the
  1131. existing aliases.
  1132. With no arguments it prints the current aliases.
  1133. It may also be given only one argument such as
  1134. .DS
  1135. alias ls
  1136. .DE
  1137. to show the current alias for, e.g., `ls'.
  1138. .PP
  1139. The
  1140. .I echo
  1141. command prints its arguments.
  1142. It is often used in
  1143. .I "shell scripts"
  1144. or as an interactive command
  1145. to see what filename expansions will produce.
  1146. .PP
  1147. The
  1148. .I history
  1149. command will show the contents of the history list.
  1150. The numbers given with the history events can be used to reference
  1151. previous events which are difficult to reference using the
  1152. contextual mechanisms introduced above.
  1153. There is also a shell variable called
  1154. .I prompt.
  1155. By placing a `!' character in its value the shell will there substitute
  1156. the number of the current command in the history list.
  1157. You can use this number to refer to this command in a history substitution.
  1158. Thus you could
  1159. .DS
  1160. set prompt=\'\e! % \'
  1161. .DE
  1162. Note that the `!' character had to be
  1163. .I escaped
  1164. here even within `\'' characters.
  1165. .PP
  1166. The
  1167. .I limit
  1168. command is used to restrict use of resources.
  1169. With no arguments it prints the current limitations:
  1170. .DS
  1171. .ta 1i
  1172. cputime unlimited
  1173. filesize unlimited
  1174. datasize 5616 kbytes
  1175. stacksize 512 kbytes
  1176. coredumpsize unlimited
  1177. .so tabs
  1178. .DE
  1179. Limits can be set, e.g.:
  1180. .DS
  1181. limit coredumpsize 128k
  1182. .DE
  1183. Most reasonable units abbreviations will work; see the
  1184. .I csh
  1185. manual page for more details.
  1186. .PP
  1187. The
  1188. .I logout
  1189. command can be used to terminate a login shell which has
  1190. .I ignoreeof
  1191. set.
  1192. .PP
  1193. The
  1194. .I rehash
  1195. command causes the shell to recompute a table of where commands are
  1196. located. This is necessary if you add a command to a directory
  1197. in the current shell's search path and wish the shell to find it,
  1198. since otherwise the hashing algorithm may tell the shell that the
  1199. command wasn't in that directory when the hash table was computed.
  1200. .PP
  1201. The
  1202. .I repeat
  1203. command can be used to repeat a command several times.
  1204. Thus to make 5 copies of the file
  1205. .I one
  1206. in the file
  1207. .I five
  1208. you could do
  1209. .DS
  1210. repeat 5 cat one >> five
  1211. .DE
  1212. .PP
  1213. The
  1214. .I setenv
  1215. command can be used
  1216. to set variables in the environment.
  1217. Thus
  1218. .DS
  1219. setenv TERM adm3a
  1220. .DE
  1221. will set the value of the environment variable \s-2TERM\s0
  1222. to
  1223. `adm3a'.
  1224. A user program
  1225. .I printenv
  1226. exists which will print out the environment.
  1227. It might then show:
  1228. .DS
  1229. % printenv
  1230. HOME=/usr/bill
  1231. SHELL=/bin/csh
  1232. PATH=:/usr/ucb:/bin:/usr/bin:/usr/local
  1233. TERM=adm3a
  1234. USER=bill
  1235. %
  1236. .DE
  1237. .PP
  1238. The
  1239. .I source
  1240. command can be used to force the current shell to read commands from
  1241. a file.
  1242. Thus
  1243. .DS
  1244. source .cshrc
  1245. .DE
  1246. can be used after editing in a change to the
  1247. .I \&.cshrc
  1248. file which you wish to take effect right away.
  1249. .PP
  1250. The
  1251. .I time
  1252. command can be used to cause a command to be timed no matter how much
  1253. \s-2CPU\s0 time it takes.
  1254. Thus
  1255. .DS
  1256. % time cp /etc/rc /usr/bill/rc
  1257. 0.0u 0.1s 0:01 8% 2+1k 3+2io 1pf+0w
  1258. % time wc /etc/rc /usr/bill/rc
  1259. 52 178 1347 /etc/rc
  1260. 52 178 1347 /usr/bill/rc
  1261. 104 356 2694 total
  1262. 0.1u 0.1s 0:00 13% 3+3k 5+3io 7pf+0w
  1263. %
  1264. .DE
  1265. indicates that the
  1266. .I cp
  1267. command used a negligible amount of user time (u)
  1268. and about 1/10th of a system time (s); the elapsed time was 1 second (0:01),
  1269. there was an average memory usage of 2k bytes of program space and 1k
  1270. bytes of data space over the cpu time involved (2+1k); the program
  1271. did three disk reads and two disk writes (3+2io), and took one page fault
  1272. and was not swapped (1pf+0w).
  1273. The word count command
  1274. .I wc
  1275. on the other hand used 0.1 seconds of user time and 0.1 seconds of system
  1276. time in less than a second of elapsed time.
  1277. The percentage `13%' indicates that over the period when it was active
  1278. the command `wc' used an average of 13 percent of the available \s-2CPU\s0
  1279. cycles of the machine.
  1280. .PP
  1281. The
  1282. .I unalias
  1283. and
  1284. .I unset
  1285. commands can be used
  1286. to remove aliases and variable definitions from the shell, and
  1287. .I unsetenv
  1288. removes variables from the environment.
  1289. .NH 2
  1290. What else?
  1291. .PP
  1292. This concludes the basic discussion of the shell for terminal users.
  1293. There are more features of the shell to be discussed here, and all
  1294. features of the shell are discussed in its manual pages.
  1295. One useful feature which is discussed later is the
  1296. .I foreach
  1297. built-in command which can be used to run the same command
  1298. sequence with a number of different arguments.
  1299. .PP
  1300. If you intend to use \s-2UNIX\s0 a lot you should look through
  1301. the rest of this document and the csh manual pages (section1) to become familiar
  1302. with the other facilities which are available to you.
  1303. .bp