rc.html 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668
  1. <html>
  2. <title>
  3. data
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>Rc &#173; The Plan 9 Shell
  7. </H1>
  8. <DL><DD><I>Tom Duff<br>
  9. td@plan9.bell-labs.com<br>
  10. </I></DL>
  11. <DL><DD><H4>ABSTRACT</H4>
  12. <I>Rc</I>
  13. is a command interpreter for Plan 9 that
  14. provides similar facilities to UNIX's
  15. Bourne shell,
  16. with some small additions and less idiosyncratic syntax.
  17. This paper uses numerous examples to describe
  18. <I>rc</I>'s
  19. features, and contrasts
  20. <I>rc</I>
  21. with the Bourne shell, a model that many readers will be familiar with.
  22. </DL>
  23. <H4>1 Introduction
  24. </H4>
  25. <P>
  26. <I>Rc</I>
  27. is similar in spirit but different in detail from UNIX's
  28. Bourne shell. This paper describes
  29. <I>rc</I>'s
  30. principal features with many small examples and a few larger ones.
  31. It assumes familiarity with the Bourne shell.
  32. </P>
  33. <H4>2 Simple commands
  34. </H4>
  35. <P>
  36. For the simplest uses
  37. <I>rc</I>
  38. has syntax familiar to Bourne-shell users.
  39. All of the following behave as expected:
  40. <DL><DT><DD><TT><PRE>
  41. date
  42. cat /lib/news/build
  43. who &gt;user.names
  44. who &gt;&gt;user.names
  45. wc &lt;file
  46. echo [a-f]*.c
  47. who | wc
  48. who; date
  49. vc *.c &amp;
  50. mk &amp;&amp; v.out /*/bin/fb/*
  51. rm -r junk || echo rm failed!
  52. </PRE></TT></DL>
  53. </P>
  54. <H4>3 Quotation
  55. </H4>
  56. <P>
  57. An argument that contains a space or one of
  58. <I>rc</I>'s
  59. other syntax characters must be enclosed in apostrophes
  60. (<TT>'</TT>):
  61. <DL><DT><DD><TT><PRE>
  62. rm 'odd file name'
  63. </PRE></TT></DL>
  64. An apostrophe in a quoted argument must be doubled:
  65. <DL><DT><DD><TT><PRE>
  66. echo 'How''s your father?'
  67. </PRE></TT></DL>
  68. </P>
  69. <H4>4 Patterns
  70. </H4>
  71. <P>
  72. An unquoted argument that contains any of the characters
  73. <TT>*</TT>
  74. <TT>?</TT>
  75. <TT>[</TT>
  76. is a pattern to be matched against file names.
  77. A
  78. <TT>*</TT>
  79. character matches any sequence of characters,
  80. <TT>?</TT>
  81. matches any single character, and
  82. <TT>[</TT><I>class</I><TT>]</TT><I>
  83. matches any character in the
  84. </I><TT>class</TT><I>,
  85. unless the first character of
  86. </I><I>class</I><I>
  87. is
  88. </I><TT>~</TT><I>,
  89. in which case the class is complemented.
  90. The
  91. </I><I>class</I><I>
  92. may also contain pairs of characters separated by
  93. </I><TT>-</TT><I>,
  94. standing for all characters lexically between the two.
  95. The character
  96. </I><TT>/</TT><I>
  97. must appear explicitly in a pattern, as must the path name components
  98. </I><TT>.</TT><I>
  99. and
  100. </I><TT>..</TT><I>.
  101. A pattern is replaced by a list of arguments, one for each path name matched,
  102. except that a pattern matching no names is not replaced by the empty list;
  103. rather it stands for itself.
  104. </P>
  105. </I><H4>5 Variables
  106. </H4>
  107. <P>
  108. UNIX's Bourne shell offers string-valued variables.
  109. <I>Rc</I>
  110. provides variables whose values are lists of arguments &#173;
  111. that is, arrays of strings. This is the principal difference
  112. between
  113. <I>rc</I>
  114. and traditional UNIX command interpreters.
  115. Variables may be given values by typing, for example:
  116. <DL><DT><DD><TT><PRE>
  117. path=(. /bin)
  118. user=td
  119. font=/lib/font/bit/pelm/ascii.9.font
  120. </PRE></TT></DL>
  121. The parentheses indicate that the value assigned to
  122. <TT>path</TT>
  123. is a list of two strings. The variables
  124. <TT>user</TT>
  125. and
  126. <TT>font</TT>
  127. are assigned lists containing a single string.
  128. </P>
  129. <P>
  130. The value of a variable can be substituted into a command by
  131. preceding its name with a
  132. <TT></TT><I></I><TT>,
  133. like this:
  134. <DL><DT><DD><TT><PRE>
  135. echo </TT>path
  136. </PRE></TT></DL>
  137. If
  138. <TT>path</TT>
  139. had been set as above, this would be equivalent to
  140. <DL><DT><DD><TT><PRE>
  141. echo . /bin
  142. </PRE></TT></DL>
  143. Variables may be subscripted by numbers or lists of numbers,
  144. like this:
  145. <DL><DT><DD><TT><PRE>
  146. echo <I>path(2)
  147. echo </I>path(2 1 2)
  148. </PRE></TT></DL>
  149. These are equivalent to
  150. <DL><DT><DD><TT><PRE>
  151. echo /bin
  152. echo /bin . /bin
  153. </PRE></TT></DL>
  154. There can be no space separating the variable's name from the
  155. left parenthesis; otherwise, the subscript would be considered
  156. a separate parenthesized list.
  157. </P>
  158. <P>
  159. The number of strings in a variable can be determined by the
  160. <TT></TT><I>#</I><TT>
  161. operator. For example,
  162. <DL><DT><DD><TT><PRE>
  163. echo </TT>#path
  164. </PRE></TT></DL>
  165. would print 2 for this example.
  166. </P>
  167. <P>
  168. The following two assignments are subtly different:
  169. <DL><DT><DD><TT><PRE>
  170. empty=()
  171. null=''
  172. </PRE></TT></DL>
  173. The first sets
  174. <TT>empty</TT>
  175. to a list containing no strings.
  176. The second sets
  177. <TT>null</TT>
  178. to a list containing a single string,
  179. but the string contains no characters.
  180. </P>
  181. <P>
  182. Although these may seem like more or less
  183. the same thing (in Bourne's shell, they are
  184. indistinguishable), they behave differently
  185. in almost all circumstances.
  186. Among other things
  187. <DL><DT><DD><TT><PRE>
  188. echo <I>#empty
  189. </PRE></TT></DL>
  190. prints 0, whereas
  191. <DL><DT><DD><TT><PRE>
  192. echo </I>#null
  193. </PRE></TT></DL>
  194. prints 1.
  195. </P>
  196. <P>
  197. All variables that have never been set have the value
  198. <TT>()</TT>.
  199. </P>
  200. <P>
  201. Occasionally, it is convenient to treat a variable's value
  202. as a single string. The elements of a string are concatenated
  203. into a single string, with spaces between the elements, by
  204. the
  205. <TT></TT><I>"</I><TT>
  206. operator.
  207. Thus, if we set
  208. <DL><DT><DD><TT><PRE>
  209. list=(How now brown cow)
  210. string=</TT>"list
  211. </PRE></TT></DL>
  212. then both
  213. <DL><DT><DD><TT><PRE>
  214. echo <I>list
  215. </PRE></TT></DL>
  216. and
  217. <DL><DT><DD><TT><PRE>
  218. echo </I>string
  219. </PRE></TT></DL>
  220. cause the same output, viz:
  221. <DL><DT><DD><TT><PRE>
  222. How now brown cow
  223. </PRE></TT></DL>
  224. but
  225. <DL><DT><DD><TT><PRE>
  226. echo <I>#list </I>#string
  227. </PRE></TT></DL>
  228. will output
  229. <DL><DT><DD><TT><PRE>
  230. 4 1
  231. </PRE></TT></DL>
  232. because
  233. <TT></TT><I>list</I><TT>
  234. has four members, but
  235. </TT><TT></TT><TT>string</TT><TT>
  236. has a single member, with three spaces separating its words.
  237. </P>
  238. </TT><H4>6 Arguments
  239. </H4>
  240. <P>
  241. When
  242. <I>rc</I>
  243. is reading its input from a file, the file has access
  244. to the arguments supplied on
  245. <I>rc</I>'s
  246. command line. The variable
  247. <TT></TT><I>*</I><TT>
  248. initially has the list of arguments assigned to it.
  249. The names
  250. </TT><TT></TT><TT>1</TT><TT>,
  251. </TT><TT></TT><I>2</I><TT>,
  252. etc. are synonyms for
  253. </TT><TT></TT><TT>*(1)</TT><TT>,
  254. </TT><TT></TT><I>*(2)</I><TT>,
  255. etc.
  256. In addition,
  257. </TT><TT></TT><TT>0</TT><TT>
  258. is the name of the file from which
  259. </TT><I>rc</I><TT>'s
  260. input is being read.
  261. </P>
  262. </TT><H4>7 Concatenation
  263. </H4>
  264. <P>
  265. <I>Rc</I>
  266. has a string concatenation operator, the caret
  267. <TT>^</TT>,
  268. to build arguments out of pieces.
  269. <DL><DT><DD><TT><PRE>
  270. echo hully^gully
  271. </PRE></TT></DL>
  272. is exactly equivalent to
  273. <DL><DT><DD><TT><PRE>
  274. echo hullygully
  275. </PRE></TT></DL>
  276. Suppose variable
  277. <TT>i</TT>
  278. contains the name of a command.
  279. Then
  280. <DL><DT><DD><TT><PRE>
  281. vc <I>i^.c
  282. vl -o </I>1 <I>i^.v
  283. </PRE></TT></DL>
  284. might compile the command's source code, leaving the
  285. result in the appropriate file.
  286. </P>
  287. </I><P>
  288. Concatenation distributes over lists. The following
  289. <DL><DT><DD><TT><PRE>
  290. echo (a b c)^(1 2 3)
  291. src=(main subr io)
  292. cc src^.c
  293. </PRE></TT></DL>
  294. are equivalent to
  295. <DL><DT><DD><TT><PRE>
  296. echo a1 b2 c3
  297. cc main.c subr.c io.c
  298. </PRE></TT></DL>
  299. In detail, the rule is: if both operands of
  300. <TT>^</TT>
  301. are lists of the same non-zero number of strings, they are concatenated
  302. pairwise. Otherwise, if one of the operands is a single string,
  303. it is concatenated with each member of the other operand in turn.
  304. Any other combination of operands is an error.
  305. </P>
  306. <H4>8 Free carets
  307. </H4>
  308. <P>
  309. User demand has dictated that
  310. <I>rc</I>
  311. insert carets in certain places, to make the syntax
  312. look more like the Bourne shell. For example, this:
  313. <DL><DT><DD><TT><PRE>
  314. cc -<I>flags </I>stems.c
  315. </PRE></TT></DL>
  316. is equivalent to
  317. <DL><DT><DD><TT><PRE>
  318. cc -^<I>flags </I>stems^.c
  319. </PRE></TT></DL>
  320. In general,
  321. <I>rc</I>
  322. will insert
  323. <TT>^</TT>
  324. between two arguments that are not separated by white space.
  325. Specifically, whenever one of
  326. <TT></TT><I>'`</I><TT>
  327. follows a quoted or unquoted word, or an unquoted word follows
  328. a quoted word with no intervening blanks or tabs, an implicit
  329. </TT><TT>^</TT><TT>
  330. is inserted between the two. If an unquoted word immediately following a
  331. </TT><TT></TT><TT></TT><TT>
  332. contains a character other than an alphanumeric, underscore or
  333. </TT><TT>*</TT><TT>,
  334. a
  335. </TT><TT>^</TT><TT>
  336. is inserted before the first such character.
  337. </P>
  338. </TT><H4>9 Command substitution
  339. </H4>
  340. <P>
  341. It is often useful to build an argument list from the output of a command.
  342. <I>Rc</I>
  343. allows a command, enclosed in braces and preceded by a left quote,
  344. <TT>`{...}</TT>,
  345. anywhere that an argument is required. The command is executed and its
  346. standard output captured.
  347. The characters stored in the variable
  348. <TT>ifs</TT>
  349. are used to split the output into arguments.
  350. For example,
  351. <DL><DT><DD><TT><PRE>
  352. cat `{ls -tr|sed 10q}
  353. </PRE></TT></DL>
  354. will concatenate the ten oldest files in the current directory in temporal order, given the
  355. default
  356. <TT>ifs</TT>
  357. setting of space, tab, and newline.
  358. </P>
  359. <H4>10 Pipeline branching
  360. </H4>
  361. <P>
  362. The normal pipeline notation is general enough for almost all cases.
  363. Very occasionally it is useful to have pipelines that are not linear.
  364. Pipeline topologies more general than trees can require arbitrarily large pipe buffers,
  365. or worse, can cause deadlock.
  366. <I>Rc</I>
  367. has syntax for some kinds of non-linear but treelike pipelines.
  368. For example,
  369. <DL><DT><DD><TT><PRE>
  370. cmp &lt;{old} &lt;{new}
  371. </PRE></TT></DL>
  372. will regression-test a new version of a command.
  373. <TT>&lt;</TT>
  374. or
  375. <TT>&gt;</TT>
  376. followed by a command in braces causes the command to be run with
  377. its standard output or input attached to a pipe. The parent command
  378. (<TT>cmp</TT>
  379. in the example)
  380. is started with the other end of the pipe attached to some file descriptor
  381. or other, and with an argument that will connect to the pipe when opened
  382. (e.g.,
  383. <TT>/dev/fd/6</TT>).
  384. Some commands are unprepared to deal with input files that turn out not to be seekable.
  385. For example
  386. <TT>diff</TT>
  387. needs to read its input twice.
  388. </P>
  389. <H4>11 Exit status
  390. </H4>
  391. <P>
  392. When a command exits it returns status to the program that executed it.
  393. On Plan 9 status is a character string describing an error condition.
  394. On normal termination it is empty.
  395. </P>
  396. <P>
  397. <I>Rc</I>
  398. captures command exit status in the variable
  399. <TT></TT><I>status</I><TT>.
  400. For a simple command the value of
  401. </TT><TT></TT><TT>status</TT><TT>
  402. is just as described above. For a pipeline
  403. </TT><TT></TT><I>status</I><TT>
  404. is set to the concatenation of the statuses of the pipeline components with
  405. </TT><TT>|</TT><TT>
  406. characters for separators.
  407. </P>
  408. </TT><P>
  409. <I>Rc</I>
  410. has a several kinds of control flow,
  411. many of them conditioned by the status returned from previously
  412. executed commands. Any
  413. <TT></TT>status<TT>
  414. containing only
  415. </TT><TT>0</TT><TT>'s
  416. and
  417. </TT><TT>|</TT><TT>'s
  418. has boolean value
  419. </TT><I>true</I><TT>.
  420. Any other status is
  421. </TT><I>false</I><TT>.
  422. </P>
  423. </TT><H4>12 Command grouping
  424. </H4>
  425. <P>
  426. A sequence of commands enclosed in
  427. <TT>{}</TT>
  428. may be used anywhere a command is required.
  429. For example:
  430. <DL><DT><DD><TT><PRE>
  431. {sleep 3600;echo 'Time''s up!'}&amp;
  432. </PRE></TT></DL>
  433. will wait an hour in the background, then print a message.
  434. Without the braces,
  435. <DL><DT><DD><TT><PRE>
  436. sleep 3600;echo 'Time''s up!'&amp;
  437. </PRE></TT></DL>
  438. would lock up the terminal for an hour,
  439. then print the message in the background.
  440. </P>
  441. <H4>13 Control flow &#173; <TT>for</TT>
  442. </H4>
  443. <P>
  444. A command may be executed once for each member of a list
  445. by typing, for example:
  446. <DL><DT><DD><TT><PRE>
  447. for(i in printf scanf putchar) look <I>i /usr/td/lib/dw.dat
  448. </PRE></TT></DL>
  449. This looks for each of the words
  450. </I><TT>printf</TT><I>,
  451. </I><TT>scanf</TT><I>
  452. and
  453. </I><TT>putchar</TT><I>
  454. in the given file.
  455. The general form is
  456. <DL><DT><DD><TT><PRE>
  457. for(</I><I>name</I><I> in </I><I>list</I><I>) </I><I>command</I><I>
  458. </PRE></TT></DL>
  459. or
  460. <DL><DT><DD><TT><PRE>
  461. for(</I><I>name</I><I>) </I><I>command</I><I>
  462. </PRE></TT></DL>
  463. In the first case
  464. </I><I>command</I><I>
  465. is executed once for each member of
  466. </I><I>list</I><I>
  467. with that member assigned to variable
  468. </I><I>name</I><I>.
  469. If the clause
  470. ``</I><TT>in</TT><I>
  471. </I><I>list</I><I>''
  472. is missing,
  473. ``</I><TT>in</TT><I>
  474. </I><TT></TT><I>*</I><TT>''
  475. is assumed.
  476. </P>
  477. </TT><H4>14 Conditional execution &#173; <TT>if</TT>
  478. </H4>
  479. <P>
  480. <I>Rc</I>
  481. also provides a general if-statement. For example:
  482. <DL><DT><DD><TT><PRE>
  483. for(i in *.c) if(cpp <I>i &gt;/tmp/</I>i) vc /tmp/<I>i
  484. </PRE></TT></DL>
  485. runs the C compiler on each C source program that
  486. cpp processes without error.
  487. An `if not' statement provides a two-tailed conditional.
  488. For example:
  489. <DL><DT><DD><TT><PRE>
  490. for(i){
  491. if(test -f /tmp/</I>i) echo <I>i already in /tmp
  492. if not cp </I>i /tmp
  493. }
  494. </PRE></TT></DL>
  495. This loops over each file in
  496. <TT></TT><I>*</I><TT>,
  497. copying to
  498. </TT><TT>/tmp</TT><TT>
  499. those that do not already appear there, and
  500. printing a message for those that do.
  501. </P>
  502. </TT><H4>15 Control flow &#173; <TT>while</TT>
  503. </H4>
  504. <P>
  505. <I>Rc</I>'s
  506. while statement looks like this:
  507. <DL><DT><DD><TT><PRE>
  508. while(newer subr.v subr.c) sleep 5
  509. </PRE></TT></DL>
  510. This waits until
  511. <TT>subr.v</TT>
  512. is newer than
  513. <TT>subr.c</TT>,
  514. presumably because the C compiler finished with it.
  515. </P>
  516. <P>
  517. If the controlling command is empty, the loop will not terminate.
  518. Thus,
  519. <DL><DT><DD><TT><PRE>
  520. while() echo y
  521. </PRE></TT></DL>
  522. emulates the
  523. <I>yes</I>
  524. command.
  525. </P>
  526. <H4>16 Control flow &#173; <TT>switch</TT>
  527. </H4>
  528. <P>
  529. <I>Rc</I>
  530. provides a switch statement to do pattern-matching on
  531. arbitrary strings. Its general form is
  532. <DL><DT><DD><TT><PRE>
  533. switch(<I>word</I>){
  534. case <I>pattern ...</I>
  535. <I>commands</I>
  536. case <I>pattern ...</I>
  537. <I>commands</I>
  538. ...
  539. }
  540. </PRE></TT></DL>
  541. <I>Rc</I>
  542. attempts to match the word against the patterns in each case statement in turn.
  543. Patterns are the same as for filename matching, except that
  544. <TT>/</TT>
  545. and
  546. <TT>.</TT>
  547. and
  548. <TT>..</TT>
  549. need not be matched explicitly.
  550. </P>
  551. <P>
  552. If any pattern matches, the
  553. commands following that case up to
  554. the next case (or the end of the switch)
  555. are executed, and execution of the switch
  556. is complete. For example,
  557. <DL><DT><DD><TT><PRE>
  558. switch(#*){
  559. case 1
  560. cat &gt;&gt;<I>1
  561. case 2
  562. cat &gt;&gt;</I>2 &lt;<I>1
  563. case *
  564. echo 'Usage: append [from] to'
  565. }
  566. </PRE></TT></DL>
  567. is an append command. Called with one file argument,
  568. it appends its standard input to the named file. With two, the
  569. first is appended to the second. Any other number
  570. elicits an error message.
  571. </P>
  572. </I><P>
  573. The built-in
  574. <TT>~</TT>
  575. command also matches patterns, and is often more concise than a switch.
  576. Its arguments are a string and a list of patterns. It sets
  577. <TT></TT>status<TT>
  578. to true if and only if any of the patterns matches the string.
  579. The following example processes option arguments for the
  580. <A href="/magic/man2html/1/man"></TT><I>man</I><TT>(1)
  581. </A>command:
  582. <DL><DT><DD><TT><PRE>
  583. opt=()
  584. while(~ </TT><I>1 -* [1-9] 10){
  585. switch(</I><TT>1){
  586. case [1-9] 10
  587. sec=</TT><I>1 secn=</I><TT>1
  588. case -f
  589. c=f s=f
  590. case -[qwnt]
  591. cmd=</TT><I>1
  592. case -T*
  593. T=</I><TT>1
  594. case -*
  595. opt=(</TT><I>opt </I><TT>1)
  596. }
  597. shift
  598. }
  599. </PRE></TT></DL>
  600. </P>
  601. </TT><H4>17 Functions
  602. </H4>
  603. <P>
  604. Functions may be defined by typing
  605. <DL><DT><DD><TT><PRE>
  606. fn <I>name</I> { <I>commands</I> }
  607. </PRE></TT></DL>
  608. Subsequently, whenever a command named
  609. <I>name</I>
  610. is encountered, the remainder of the command's
  611. argument list will assigned to
  612. <TT></TT><I>*</I><TT>
  613. and
  614. </TT><I>rc</I><TT>
  615. will execute the
  616. </TT><I>commands</I><TT>.
  617. The value of
  618. </TT><TT></TT><TT>*</TT><TT>
  619. will be restored on completion.
  620. For example:
  621. <DL><DT><DD><TT><PRE>
  622. fn g {
  623. grep </TT><I>1 *.[hcyl]
  624. }
  625. </PRE></TT></DL>
  626. defines
  627. </I><TT>g</TT><I> pattern</I>n(Sf
  628. to look for occurrences of
  629. <I>pattern</I>
  630. in all program source files in the current directory.
  631. </P>
  632. <P>
  633. Function definitions are deleted by writing
  634. <DL><DT><DD><TT><PRE>
  635. fn <I>name</I>
  636. </PRE></TT></DL>
  637. with no function body.
  638. </P>
  639. <H4>18 Command execution
  640. </H4>
  641. <P>
  642. <I>Rc</I>
  643. does one of several things to execute a simple command.
  644. If the command name is the name of a function defined using
  645. <TT>fn</TT>,
  646. the function is executed.
  647. Otherwise, if it is the name of a built-in command, the
  648. built-in is executed directly by
  649. <I>rc</I>.
  650. Otherwise, directories mentioned in the variable
  651. <TT></TT>path<TT>
  652. are searched until an executable file is found.
  653. Extensive use of the
  654. </TT><TT></TT><I>path</I><TT>
  655. variable is discouraged in Plan 9. Instead, use the default
  656. </TT><TT>(.</TT><TT>
  657. </TT><TT>/bin)</TT><TT>
  658. and bind what you need into
  659. </TT><TT>/bin</TT><TT>.
  660. </P>
  661. </TT><H4>19 Built-in commands
  662. </H4>
  663. <P>
  664. Several commands are executed internally by
  665. <I>rc</I>
  666. because they are difficult to implement otherwise.
  667. </P>
  668. <DL COMPACT>
  669. <DT><TT>.<DD>
  670. [-i] </TT><I>file ...</I><TT></TT>.if w'<TT>. [-i] </TT><I>file ...</I><TT></TT>'-4n .br
  671. Execute commands from
  672. <I>file</I>.
  673. <TT></TT>*<TT>
  674. is set for the duration to the reminder of the argument list following
  675. </TT><I>file</I><TT>.
  676. </TT><TT></TT><I>path</I><TT>
  677. is used to search for
  678. </TT><I>file</I><TT>.
  679. Option
  680. </TT><TT>-i</TT><TT>
  681. indicates interactive input &#173; a prompt
  682. (found in
  683. </TT><TT></TT><TT>prompt</TT><TT>)
  684. is printed before each command is read.
  685. <DT></TT><TT>b<DD>
  686. uiltin </TT><I>command ...</I><TT></TT>.if w'<TT>builtin </TT><I>command ...</I><TT></TT>'-4n .br
  687. Execute
  688. <I>command</I>
  689. as usual except that any function named
  690. <I>command</I>
  691. is ignored.
  692. For example,
  693. <DL><DT><DD><TT><PRE>
  694. fn cd{
  695. builtin cd <I>* &amp;&amp; pwd
  696. }
  697. </PRE></TT></DL>
  698. defines a replacement for the
  699. </I><TT>cd</TT><I>
  700. built-in (see below) that announces the full name of the new directory.
  701. <DT></I><TT>c<DD>
  702. d [</TT><I>dir</I><TT>]</TT>.if w'<TT>cd [</TT><I>dir</I><TT>]</TT>'-4n .br
  703. Change the current directory to
  704. <I>dir</I>.
  705. The default argument is
  706. <TT></TT>home<TT>.
  707. </TT><TT></TT><I>cdpath</I><TT>
  708. is a list of places in which to search for
  709. </TT><I>dir</I><TT>.
  710. <DT></TT><TT>e<DD>
  711. val [</TT><I>arg ...</I><TT>]</TT>.if w'<TT>eval [</TT><I>arg ...</I><TT>]</TT>'-4n .br
  712. The arguments are concatenated (separated by spaces) into a string, read as input to
  713. <I>rc</I>,
  714. and executed. For example,
  715. <DL><DT><DD><TT><PRE>
  716. x='<TT>y'
  717. y=Doody
  718. eval echo Howdy, </TT><I>x
  719. </PRE></TT></DL>
  720. would echo
  721. <DL><DT><DD><TT><PRE>
  722. Howdy, Doody
  723. </PRE></TT></DL>
  724. since the arguments of
  725. </I><TT>eval</TT><I>
  726. would be
  727. <DL><DT><DD><TT><PRE>
  728. echo Howdy, </I><TT>y
  729. </PRE></TT></DL>
  730. after substituting for
  731. </TT><TT></TT><I>x</I><TT>.
  732. <DT></TT><TT>e<DD>
  733. xec [</TT><I>command ...</I><TT>]</TT>.if w'<TT>exec [</TT><I>command ...</I><TT>]</TT>'-4n .br
  734. <I>Rc</I>
  735. replaces itself with the given
  736. <I>command</I>.
  737. This is like a
  738. <I>goto</I>
  739. &#173;
  740. <I>rc</I>
  741. does not wait for the command to exit, and does not return to read any more commands.
  742. <DT><TT>e<DD>
  743. xit [</TT><I>status</I><TT>]</TT>.if w'<TT>exit [</TT><I>status</I><TT>]</TT>'-4n .br
  744. <I>Rc</I>
  745. exits immediately with the given status. If none is given, the current value of
  746. <TT></TT>status<TT>
  747. is used.
  748. <DT></TT><TT>f<DD>
  749. lag </TT><I>f</I><TT> [+-]</TT>.if w'<TT>flag </TT><I>f</I><TT> [+-]</TT>'-4n .br
  750. This command manipulates and tests the command line flags (described below).
  751. <DL><DT><DD><TT><PRE>
  752. flag <I>f</I><TT> +
  753. </PRE></TT></DL>
  754. sets flag
  755. </TT><I>f</I><TT>.
  756. <DL><DT><DD><TT><PRE>
  757. flag </TT><I>f</I><TT> -
  758. </PRE></TT></DL>
  759. clears flag
  760. </TT><I>f</I><TT>.
  761. <DL><DT><DD><TT><PRE>
  762. flag </TT><I>f</I><TT>
  763. </PRE></TT></DL>
  764. tests flag
  765. </TT><I>f</I><TT>,
  766. setting
  767. </TT><TT></TT><I>status</I><TT>
  768. appropriately.
  769. Thus
  770. <DL><DT><DD><TT><PRE>
  771. if(flag x) flag v +
  772. </PRE></TT></DL>
  773. sets the
  774. </TT><TT>-v</TT><TT>
  775. flag if the
  776. </TT><TT>-x</TT><TT>
  777. flag is already set.
  778. <DT></TT><TT>r<DD>
  779. fork [nNeEsfF]</TT>.if w'<TT>rfork [nNeEsfF]</TT>'-4n .br
  780. This uses the Plan 9
  781. <I>rfork</I>
  782. system entry to put
  783. <I>rc</I>
  784. into a new process group with the following attributes:
  785. <br><img src="data.19116850.gif"><br>
  786. Section
  787. <A href="/magic/man2html/2/fork"><I>fork</I>(2)
  788. </A>of the Programmer's Manual describes these attributes in more detail.
  789. <DT><TT>s<DD>
  790. hift [</TT><I>n</I><TT>]</TT>.if w'<TT>shift [</TT><I>n</I><TT>]</TT>'-4n .br
  791. Delete the first
  792. <I>n</I>
  793. (default 1) elements of
  794. <TT></TT>*<TT>.
  795. <DT></TT><TT>w<DD>
  796. ait [</TT><I>pid</I><TT>]</TT>.if w'<TT>wait [</TT><I>pid</I><TT>]</TT>'-4n .br
  797. Wait for the process with the given
  798. <I>pid</I>
  799. to exit. If no
  800. <I>pid</I>
  801. is given, all outstanding processes are waited for.
  802. <DT><TT>w<DD>
  803. hatis </TT><I>name ...</I><TT></TT>.if w'<TT>whatis </TT><I>name ...</I><TT></TT>'-4n .br
  804. Print the value of each
  805. <I>name</I>
  806. in a form suitable for input to
  807. <I>rc</I>.
  808. The output is an assignment to a variable, the definition of a function,
  809. a call to
  810. <TT>builtin</TT>
  811. for a built-in command, or the path name of a binary program.
  812. For example,
  813. <DL><DT><DD><TT><PRE>
  814. whatis path g cd who
  815. </PRE></TT></DL>
  816. might print
  817. <DL><DT><DD><TT><PRE>
  818. path=(. /bin)
  819. fn g {gre -e <I>1 *.[hycl]}
  820. builtin cd
  821. /bin/who
  822. </PRE></TT></DL>
  823. <DT></I><TT>~<DD>
  824. </TT><I>subject pattern ...</I><TT></TT>.if w'<TT>~ </TT><I>subject pattern ...</I><TT></TT>'-4n .br
  825. The
  826. <I>subject</I>
  827. is matched against each
  828. <I>pattern</I>
  829. in turn. On a match,
  830. <TT></TT>status<TT>
  831. is set to true.
  832. Otherwise, it is set to
  833. </TT><TT>'no match'</TT><TT>.
  834. Patterns are the same as for filename matching.
  835. The
  836. </TT><I>patterns</I><TT>
  837. are not subjected to filename replacement before the
  838. </TT><TT>~</TT><TT>
  839. command is executed, so they need not be enclosed in
  840. quotation marks, unless of course, a literal match for
  841. </TT><TT>*</TT><TT>
  842. </TT><TT>[</TT><TT>
  843. or
  844. </TT><TT>?</TT><TT>
  845. is required.
  846. For example
  847. <DL><DT><DD><TT><PRE>
  848. ~ </TT><I>1 ?
  849. </PRE></TT></DL>
  850. matches any single character, whereas
  851. <DL><DT><DD><TT><PRE>
  852. ~ </I><TT>1 '?'
  853. </PRE></TT></DL>
  854. only matches a literal question mark.
  855. </dl>
  856. </TT><H4>20 Advanced I/O Redirection
  857. </H4>
  858. <P>
  859. <I>Rc</I>
  860. allows redirection of file descriptors other than 0 and 1
  861. (standard input and output) by specifying the file descriptor
  862. in square brackets
  863. <TT>[ ]</TT>
  864. after the
  865. <TT>&lt;</TT>
  866. or
  867. <TT>&gt;</TT>.
  868. For example,
  869. <DL><DT><DD><TT><PRE>
  870. vc junk.c &gt;[2]junk.diag
  871. </PRE></TT></DL>
  872. saves the compiler's diagnostics from standard error in
  873. <TT>junk.diag</TT>.
  874. </P>
  875. <P>
  876. File descriptors may be replaced by a copy, in the sense of
  877. <A href="/magic/man2html/2/dup"><I>dup</I>(2),
  878. </A>of an already-open file by typing, for example
  879. <DL><DT><DD><TT><PRE>
  880. vc junk.c &gt;[2=1]
  881. </PRE></TT></DL>
  882. This replaces file descriptor 2 with a copy of file descriptor 1.
  883. It is more useful in conjunction with other redirections, like this
  884. <DL><DT><DD><TT><PRE>
  885. vc junk.c &gt;junk.out &gt;[2=1]
  886. </PRE></TT></DL>
  887. Redirections are evaluated from left to right, so this redirects
  888. file descriptor 1 to
  889. <TT>junk.out</TT>,
  890. then points file descriptor 2 at the same file.
  891. By contrast,
  892. <DL><DT><DD><TT><PRE>
  893. vc junk.c &gt;[2=1] &gt;junk.out
  894. </PRE></TT></DL>
  895. redirects file descriptor 2 to a copy of file descriptor 1
  896. (presumably the terminal), and then directs file descriptor 1
  897. to a file. In the first case, standard and diagnostic output
  898. will be intermixed in
  899. <TT>junk.out</TT>.
  900. In the second, diagnostic output will appear on the terminal,
  901. and standard output will be sent to the file.
  902. </P>
  903. <P>
  904. File descriptors may be closed by using the duplication notation
  905. with an empty right-hand side.
  906. For example,
  907. <DL><DT><DD><TT><PRE>
  908. vc junk.c &gt;[2=]
  909. </PRE></TT></DL>
  910. will discard diagnostics from the compilation.
  911. </P>
  912. <P>
  913. Arbitrary file descriptors may be sent through
  914. a pipe by typing, for example,
  915. <DL><DT><DD><TT><PRE>
  916. vc junk.c |[2] grep -v '^<I>'
  917. </PRE></TT></DL>
  918. This deletes blank lines
  919. from the C compiler's error output. Note that the output
  920. of
  921. </I><TT>grep</TT><I>
  922. still appears on file descriptor 1.
  923. </P>
  924. </I><P>
  925. Occasionally you may wish to connect the input side of
  926. a pipe to some file descriptor other than zero.
  927. The notation
  928. <DL><DT><DD><TT><PRE>
  929. cmd1 |[5=19] cmd2
  930. </PRE></TT></DL>
  931. creates a pipeline with
  932. <TT>cmd1</TT>'s
  933. file descriptor 5 connected through a pipe to
  934. <TT>cmd2</TT>'s
  935. file descriptor 19.
  936. </P>
  937. <H4>21 Here documents
  938. </H4>
  939. <P>
  940. <I>Rc</I>
  941. procedures may include data, called ``here documents'',
  942. to be provided as input to commands, as in this version of the
  943. <I>tel</I>
  944. command
  945. <DL><DT><DD><TT><PRE>
  946. for(i) grep i &lt;&lt;!
  947. ...
  948. tor 2T-402 2912
  949. kevin 2C-514 2842
  950. bill 2C-562 7214
  951. ...
  952. !
  953. </PRE></TT></DL>
  954. A here document is introduced by the redirection symbol
  955. <TT>&lt;&lt;</TT>,
  956. followed by an arbitrary EOF marker
  957. (<TT>!</TT>
  958. in the example). Lines following the command,
  959. up to a line containing only the EOF marker are saved
  960. in a temporary file that is connected to the command's
  961. standard input when it is run.
  962. </P>
  963. <P>
  964. <I>Rc</I>
  965. does variable substitution in here documents. The following command:
  966. <DL><DT><DD><TT><PRE>
  967. ed <I>3 &lt;&lt;EOF
  968. g/</I>1/s//<I>2/g
  969. w
  970. EOF
  971. </PRE></TT></DL>
  972. changes all occurrences of
  973. </I><TT></TT><I>1</I><TT>
  974. to
  975. </TT><TT></TT><I>2</I><TT>
  976. in file
  977. </TT><TT></TT><TT>3</TT><TT>.
  978. To include a literal
  979. </TT><TT></TT><I></I><TT>
  980. in a here document, type
  981. </TT><TT></TT><TT></TT><I></I><TT>.
  982. If the name of a variable is followed immediately by
  983. </TT><TT>^</TT><TT>,
  984. the caret is deleted.
  985. </P>
  986. </TT><P>
  987. Variable substitution can be entirely suppressed by enclosing
  988. the EOF marker following
  989. <TT>&lt;&lt;</TT>
  990. in quotation marks, as in
  991. <TT>&lt;&lt;'EOF'</TT>.
  992. </P>
  993. <P>
  994. Here documents may be provided on file descriptors other than 0 by typing, for example,
  995. <DL><DT><DD><TT><PRE>
  996. cmd &lt;&lt;[4]End
  997. ...
  998. End
  999. </PRE></TT></DL>
  1000. </P>
  1001. <P>
  1002. If a here document appears within a compound block, the contents of the document
  1003. must be after the whole block:
  1004. <DL><DT><DD><TT><PRE>
  1005. for(i in *){
  1006. mail <I>i &lt;&lt;EOF
  1007. }
  1008. words to live by
  1009. EOF
  1010. </PRE></TT></DL>
  1011. </P>
  1012. </I><H4>22 Catching Notes
  1013. </H4>
  1014. <P>
  1015. <I>Rc</I>
  1016. scripts normally terminate when an interrupt is received from the terminal.
  1017. A function with the name of a UNIX signal, in lower case, is defined in the usual way,
  1018. but called when
  1019. <I>rc</I>
  1020. receives the corresponding note.
  1021. The
  1022. <A href="/magic/man2html/2/notify"><I>notify</I>(2)
  1023. </A>section of the Programmer's Manual discusses notes in some detail.
  1024. Notes of interest are:
  1025. </P>
  1026. <DL COMPACT>
  1027. <DT><TT>s<DD>
  1028. ighup</TT>.if w'<TT>sighup</TT>'-4n .br
  1029. The note was `hangup'.
  1030. Plan 9 sends this when the terminal has disconnected from
  1031. <I>rc</I>.
  1032. <DT><TT>s<DD>
  1033. igint</TT>.if w'<TT>sigint</TT>'-4n .br
  1034. The note was `interrupt', usually sent when
  1035. the interrupt character (ASCII DEL) is typed on the terminal.
  1036. <DT><TT>s<DD>
  1037. igterm</TT>.if w'<TT>sigterm</TT>'-4n .br
  1038. The note was `kill', normally sent by
  1039. <A href="/magic/man2html/1/kill"><I>kill</I>(1).
  1040. </A><DT><TT>s<DD>
  1041. igexit</TT>.if w'<TT>sigexit</TT>'-4n .br
  1042. An artificial note sent when
  1043. <I>rc</I>
  1044. is about to exit.
  1045. </dl>
  1046. <P>
  1047. As an example,
  1048. <DL><DT><DD><TT><PRE>
  1049. fn sigint{
  1050. rm /tmp/junk
  1051. exit
  1052. }
  1053. </PRE></TT></DL>
  1054. sets a trap for the keyboard interrupt that
  1055. removes a temporary file before exiting.
  1056. </P>
  1057. <P>
  1058. Notes will be ignored if the note routine is set to
  1059. <TT>{}</TT>.
  1060. Signals revert to their default behavior when their handlers'
  1061. definitions are deleted.
  1062. </P>
  1063. <H4>23 Environment
  1064. </H4>
  1065. <P>
  1066. The environment is a list of name-value pairs made available to
  1067. executing binaries.
  1068. On Plan 9, the environment is stored in a file system named
  1069. <TT>#e</TT>,
  1070. normally mounted on
  1071. <TT>/env</TT>.
  1072. The value of each variable is stored in a separate file, with components
  1073. terminated by zero bytes.
  1074. (The file system is
  1075. maintained entirely in core, so no disk or network access is involved.)
  1076. The contents of
  1077. <TT>/env</TT>
  1078. are shared on a per-process group basis - when a new process group is
  1079. created it effectively attaches
  1080. <TT>/env</TT>
  1081. to a new file system initialized with a copy of the old one.
  1082. A consequence of this organization is that commands can change environment
  1083. entries and see the changes reflected in
  1084. <I>rc</I>.
  1085. </P>
  1086. <P>
  1087. Functions also appear in the environment, named by prefixing
  1088. <TT>fn#</TT>
  1089. to their names, like
  1090. <TT>/env/fn#roff</TT>.
  1091. </P>
  1092. <H4>24 Local Variables
  1093. </H4>
  1094. <P>
  1095. It is often useful to set a variable for the duration
  1096. of a single command. An assignment followed by a command
  1097. has this effect. For example
  1098. <DL><DT><DD><TT><PRE>
  1099. a=global
  1100. a=local echo a
  1101. echo <I>a
  1102. </PRE></TT></DL>
  1103. will print
  1104. <DL><DT><DD><TT><PRE>
  1105. local
  1106. global
  1107. </PRE></TT></DL>
  1108. This works even for compound commands, like
  1109. <DL><DT><DD><TT><PRE>
  1110. f=/fairly/long/file/name {
  1111. { wc </I>f; spell <I>f; diff </I>f.old <I>f } |
  1112. pr -h 'Facts about '</I>f | lp -dfn
  1113. }
  1114. </PRE></TT></DL>
  1115. </P>
  1116. <H4>25 Examples &#173; <I>cd, pwd</I>
  1117. </H4>
  1118. <P>
  1119. Here is a pair of functions that provide
  1120. enhanced versions of the standard
  1121. <TT>cd</TT>
  1122. and
  1123. <TT>pwd</TT>
  1124. commands. (Thanks to Rob Pike for these.)
  1125. <DL><DT><DD><TT><PRE>
  1126. ps1='% ' # default prompt
  1127. tab=' ' # a tab character
  1128. fn cd{
  1129. builtin cd <I>1 &amp;&amp;
  1130. switch(</I>#*){
  1131. case 0
  1132. dir=<I>home
  1133. prompt=(</I>ps1 <I>tab)
  1134. case *
  1135. switch(</I>1)
  1136. case /*
  1137. dir=<I>1
  1138. prompt=(`{basename `{pwd}}^</I>ps1 <I>tab)
  1139. case */* ..*
  1140. dir=()
  1141. prompt=(`{basename `{pwd}}^</I>ps1 <I>tab)
  1142. case *
  1143. dir=()
  1144. prompt=(</I>1^<I>ps1 </I>tab)
  1145. }
  1146. }
  1147. }
  1148. fn pwd{
  1149. if(~ <I>#dir 0)
  1150. dir=`{/bin/pwd}
  1151. echo </I>dir
  1152. }
  1153. </PRE></TT></DL>
  1154. Function
  1155. <TT>pwd</TT>
  1156. is a version of the standard
  1157. <TT>pwd</TT>
  1158. that caches its value in variable
  1159. <TT></TT><I>dir</I><TT>,
  1160. because the genuine
  1161. </TT><TT>pwd</TT><TT>
  1162. can be quite slow to execute.
  1163. (Recent versions of Plan 9 have very fast implementations of
  1164. </TT><TT>pwd</TT><TT>,
  1165. reducing the advantage of the
  1166. </TT><TT>pwd</TT><TT>
  1167. function.)
  1168. </P>
  1169. </TT><P>
  1170. Function
  1171. <TT>cd</TT>
  1172. calls the
  1173. <TT>cd</TT>
  1174. built-in, and checks that it was successful.
  1175. If so, it sets
  1176. <TT></TT>dir<TT>
  1177. and
  1178. </TT><TT></TT><I>prompt</I><TT>.
  1179. The prompt will include the last component of the
  1180. current directory (except in the home directory,
  1181. where it will be null), and
  1182. </TT><TT></TT><TT>dir</TT><TT>
  1183. will be reset either to the correct value or to
  1184. </TT><TT>()</TT><TT>,
  1185. so that the
  1186. </TT><TT>pwd</TT><TT>
  1187. function will work correctly.
  1188. </P>
  1189. </TT><H4>26 Examples &#173; <I>man</I>
  1190. </H4>
  1191. <P>
  1192. The
  1193. <I>man</I>
  1194. command prints pages of the Programmer's Manual.
  1195. It is called, for example, as
  1196. <DL><DT><DD><TT><PRE>
  1197. man 2 sinh
  1198. man rc
  1199. man -t cat
  1200. </PRE></TT></DL>
  1201. In the first case, the page for
  1202. <I>sinh</I>
  1203. in section 2 is printed.
  1204. In the second case, the manual page for
  1205. <I>rc</I>
  1206. is printed. Since no manual section is specified,
  1207. all sections are searched for the page, and it is found
  1208. in section 1.
  1209. In the third case, the page for
  1210. <I>cat</I>
  1211. is typeset (the
  1212. <TT>-t</TT>
  1213. option).
  1214. <DL><DT><DD><TT><PRE>
  1215. cd /sys/man || {
  1216. echo <I>0: No manual! &gt;[1=2]
  1217. exit 1
  1218. }
  1219. NT=n # default nroff
  1220. s='*' # section, default try all
  1221. for(i) switch(</I>i){
  1222. case -t
  1223. NT=t
  1224. case -n
  1225. NT=n
  1226. case -*
  1227. echo Usage: <I>0 '[-nt] [section] page ...' &gt;[1=2]
  1228. exit 1
  1229. case [1-9] 10
  1230. s=</I>i
  1231. case *
  1232. eval 'pages='<I>s/</I>i
  1233. for(page in <I>pages){
  1234. if(test -f </I>page)
  1235. <I>NT^roff -man </I>page
  1236. if not
  1237. echo <I>0: </I>i not found &gt;[1=2]
  1238. }
  1239. }
  1240. </PRE></TT></DL>
  1241. Note the use of
  1242. <TT>eval</TT>
  1243. to make a list of candidate manual pages.
  1244. Without
  1245. <TT>eval</TT>,
  1246. the
  1247. <TT>*</TT>
  1248. stored in
  1249. <TT></TT><I>s</I><TT>
  1250. would not trigger filename matching
  1251. &#173; it's enclosed in quotation marks,
  1252. and even if it weren't, it would be expanded
  1253. when assigned to
  1254. </TT><TT></TT><TT>s</TT><TT>.
  1255. Eval causes its arguments
  1256. to be re-processed by
  1257. </TT><I>rc</I><TT>'s
  1258. parser and interpreter, effectively delaying
  1259. evaluation of the
  1260. </TT><TT>*</TT><TT>
  1261. until the assignment to
  1262. </TT><TT></TT><I>pages</I><TT>.
  1263. </P>
  1264. </TT><H4>27 Examples &#173; <I>holmdel</I>
  1265. </H4>
  1266. <P>
  1267. The following
  1268. <I>rc</I>
  1269. script plays the deceptively simple game
  1270. <I>holmdel</I>,
  1271. in which the players alternately name Bell Labs locations,
  1272. the winner being the first to mention Holmdel.
  1273. <DL><DT><DD><TT><PRE>
  1274. t=/tmp/holmdelpid
  1275. fn read{
  1276. <I>1=`{awk '{print;exit}'}
  1277. }
  1278. ifs='
  1279. ' # just a newline
  1280. fn sigexit sigint sigquit sighup{
  1281. rm -f </I>t
  1282. exit
  1283. }
  1284. cat &lt;&lt;'!' &gt;<I>t
  1285. Allentown
  1286. Atlanta
  1287. Cedar Crest
  1288. Chester
  1289. Columbus
  1290. Elmhurst
  1291. Fullerton
  1292. Holmdel
  1293. Indian Hill
  1294. Merrimack Valley
  1295. Morristown
  1296. Neptune
  1297. Piscataway
  1298. Reading
  1299. Short Hills
  1300. South Plainfield
  1301. Summit
  1302. Whippany
  1303. West Long Branch
  1304. !
  1305. while(){
  1306. lab=`{fortune </I>t}
  1307. echo <I>lab
  1308. if(~ </I>lab Holmdel){
  1309. echo You lose.
  1310. exit
  1311. }
  1312. while(read lab; ! grep -i -s <I>lab </I>t) echo No such location.
  1313. if(~ <I>lab [hH]olmdel){
  1314. echo You win.
  1315. exit
  1316. }
  1317. }
  1318. </PRE></TT></DL>
  1319. </P>
  1320. </I><P>
  1321. This script is worth describing in detail
  1322. (rather, it would be if it weren't so silly.)
  1323. </P>
  1324. <P>
  1325. Variable
  1326. <TT></TT>t<TT>
  1327. is an abbreviation for the name of a temporary file.
  1328. Including
  1329. </TT><TT></TT><I>pid</I><TT>,
  1330. initialized by
  1331. </TT><I>rc</I><TT>
  1332. to its process-id,
  1333. in the names of temporary files insures that their
  1334. names won't collide, in case more than one instance
  1335. of the script is running at a time.
  1336. </P>
  1337. </TT><P>
  1338. Function
  1339. <TT>read</TT>'s
  1340. argument is the name of a variable into which a
  1341. line gathered from standard input is read.
  1342. <TT></TT>ifs<TT>
  1343. is set to just a newline. Thus
  1344. </TT><TT>read</TT><TT>'s
  1345. input is not split apart at spaces, but the terminating
  1346. newline is deleted.
  1347. </P>
  1348. </TT><P>
  1349. A handler is set to catch
  1350. <TT>sigint</TT>,
  1351. <TT>sigquit</TT>,
  1352. and
  1353. <TT>sighup,</TT>
  1354. and the artificial
  1355. <TT>sigexit</TT>
  1356. signal. It just removes the temporary file and exits.
  1357. </P>
  1358. <P>
  1359. The temporary file is initialized from a here
  1360. document containing a list of Bell Labs locations, and
  1361. the main loop starts.
  1362. </P>
  1363. <P>
  1364. First, the program guesses a location (in
  1365. <TT></TT><I>lab</I><TT>)
  1366. using the
  1367. </TT><TT>fortune</TT><TT>
  1368. program to pick a random line from the location list.
  1369. It prints the location, and if it guessed Holmdel, prints
  1370. a message and exits.
  1371. </P>
  1372. </TT><P>
  1373. Then it uses the
  1374. <TT>read</TT>
  1375. function to get lines from standard input and validity-check
  1376. them until it gets a legal name.
  1377. Note that the condition part of a
  1378. <TT>while</TT>
  1379. can be a compound command. Only the exit status of the
  1380. last command in the sequence is checked.
  1381. </P>
  1382. <P>
  1383. Again, if the result
  1384. is Holmdel, it prints a message and exits.
  1385. Otherwise it goes back to the top of the loop.
  1386. </P>
  1387. <H4>28 Design Principles
  1388. </H4>
  1389. <P>
  1390. <I>Rc</I>
  1391. draws heavily from Steve Bourne's
  1392. <TT>/bin/sh</TT>.
  1393. Any successor of the Bourne shell is bound to
  1394. suffer in comparison. I have tried to fix its
  1395. best-acknowledged shortcomings and to simplify things
  1396. wherever possible, usually by omitting inessential features.
  1397. Only when irresistibly tempted have I introduced novel ideas.
  1398. Obviously I have tinkered extensively with Bourne's syntax.
  1399. </P>
  1400. <P>
  1401. The most important principle in
  1402. <I>rc</I>'s
  1403. design is that it's not a macro processor. Input is never
  1404. scanned more than once by the lexical and syntactic analysis
  1405. code (except, of course, by the
  1406. <TT>eval</TT>
  1407. command, whose
  1408. <I>raison d'&ecirc;tre</I>
  1409. is to break the rule).
  1410. </P>
  1411. <P>
  1412. Bourne shell scripts can often be made
  1413. to run wild by passing them arguments containing spaces.
  1414. These will be split into multiple arguments using
  1415. <TT>IFS</TT>,
  1416. often at inopportune times.
  1417. In
  1418. <I>rc</I>,
  1419. values of variables, including command line arguments, are not re-read
  1420. when substituted into a command.
  1421. Arguments have presumably been scanned in the parent process, and ought
  1422. not to be re-read.
  1423. </P>
  1424. <P>
  1425. Why does Bourne re-scan commands after variable substitution?
  1426. He needs to be able to store lists of arguments in variables whose values are
  1427. character strings.
  1428. If we eliminate re-scanning, we must change the type of variables, so that
  1429. they can explicitly carry lists of strings.
  1430. </P>
  1431. <P>
  1432. This introduces some
  1433. conceptual complications. We need a notation for lists of words.
  1434. There are two different kinds of concatenation, for strings &#173;
  1435. <TT></TT>a^<I>b</I>,
  1436. and lists &#173;
  1437. <TT>(</TT>a <I>b)</I>.
  1438. The difference between
  1439. <TT>()</TT>
  1440. and
  1441. <TT>''</TT>
  1442. is confusing to novices,
  1443. although the distinction is arguably sensible &#173;
  1444. a null argument is not the same as no argument.
  1445. </P>
  1446. <P>
  1447. Bourne also rescans input when doing command substitution.
  1448. This is because the text enclosed in back-quotes is not
  1449. a string, but a command. Properly, it ought to
  1450. be parsed when the enclosing command is, but this makes
  1451. it difficult to
  1452. handle nested command substitutions, like this:
  1453. <DL><DT><DD><TT><PRE>
  1454. size=`wc -l \`ls -t|sed 1q\``
  1455. </PRE></TT></DL>
  1456. The inner back-quotes must be escaped
  1457. to avoid terminating the outer command.
  1458. This can get much worse than the above example;
  1459. the number of
  1460. <TT>\</TT>'s
  1461. required is exponential in the nesting depth.
  1462. <I>Rc</I>
  1463. fixes this by making the backquote a unary operator
  1464. whose argument is a command, like this:
  1465. <DL><DT><DD><TT><PRE>
  1466. size=`{wc -l `{ls -t|sed 1q}}
  1467. </PRE></TT></DL>
  1468. No escapes are ever required, and the whole thing
  1469. is parsed in one pass.
  1470. </P>
  1471. <P>
  1472. For similar reasons
  1473. <I>rc</I>
  1474. defines signal handlers as though they were functions,
  1475. instead of associating a string with each signal, as Bourne does,
  1476. with the attendant possibility of getting a syntax error message
  1477. in response to typing the interrupt character. Since
  1478. <I>rc</I>
  1479. parses input when typed, it reports errors when you make them.
  1480. </P>
  1481. <P>
  1482. For all this trouble, we gain substantial semantic simplifications.
  1483. There is no need for the distinction between
  1484. <TT></TT>*<TT>
  1485. and
  1486. </TT><TT></TT><I>@</I><TT>.
  1487. There is no need for four types of quotation, nor the
  1488. extremely complicated rules that govern them. In
  1489. </TT><I>rc</I><TT>
  1490. you use quotation marks when you want a syntax character
  1491. to appear in an argument, or an argument that is the empty string,
  1492. and at no other time.
  1493. </TT><TT>IFS</TT><TT>
  1494. is no longer used, except in the one case where it was indispensable:
  1495. converting command output into argument lists during command substitution.
  1496. </P>
  1497. </TT><P>
  1498. This also avoids an important UNIX security hole.
  1499. In UNIX, the
  1500. <I>system</I>
  1501. and
  1502. <I>popen</I>
  1503. functions call
  1504. <TT>/bin/sh</TT>
  1505. to execute a command. It is impossible to use either
  1506. of these routines with any assurance that the specified command will
  1507. be executed, even if the caller of
  1508. <I>system</I>
  1509. or
  1510. <I>popen</I>
  1511. specifies a full path name for the command. This can be devastating
  1512. if it occurs in a set-userid program.
  1513. The problem is that
  1514. <TT>IFS</TT>
  1515. is used to split the command into words, so an attacker can just
  1516. set
  1517. <TT>IFS=/</TT>
  1518. in his environment and leave a Trojan horse
  1519. named
  1520. <TT>usr</TT>
  1521. or
  1522. <TT>bin</TT>
  1523. in the current working directory before running the privileged program.
  1524. <I>Rc</I>
  1525. fixes this by never rescanning input for any reason.
  1526. </P>
  1527. <P>
  1528. Most of the other differences between
  1529. <I>rc</I>
  1530. and the Bourne shell are not so serious. I eliminated Bourne's
  1531. peculiar forms of variable substitution, like
  1532. <DL><DT><DD><TT><PRE>
  1533. echo {a=b} <I>{c-d} </I>{e?error}
  1534. </PRE></TT></DL>
  1535. because they are little used, redundant and easily
  1536. expressed in less abstruse terms.
  1537. I deleted the builtins
  1538. <TT>export</TT>,
  1539. <TT>readonly</TT>,
  1540. <TT>break</TT>,
  1541. <TT>continue</TT>,
  1542. <TT>read</TT>,
  1543. <TT>return</TT>,
  1544. <TT>set</TT>,
  1545. <TT>times</TT>
  1546. and
  1547. <TT>unset</TT>
  1548. because they seem redundant or
  1549. only marginally useful.
  1550. </P>
  1551. <P>
  1552. Where Bourne's syntax draws from Algol 68,
  1553. <I>rc</I>'s
  1554. is based on C or Awk. This is harder to defend.
  1555. I believe that, for example
  1556. <DL><DT><DD><TT><PRE>
  1557. if(test -f junk) rm junk
  1558. </PRE></TT></DL>
  1559. is better syntax than
  1560. <DL><DT><DD><TT><PRE>
  1561. if test -f junk; then rm junk; fi
  1562. </PRE></TT></DL>
  1563. because it is less cluttered with keywords,
  1564. it avoids the semicolons that Bourne requires
  1565. in odd places,
  1566. and the syntax characters better set off the
  1567. active parts of the command.
  1568. </P>
  1569. <P>
  1570. The one bit of large-scale syntax that Bourne
  1571. unquestionably does better than
  1572. <I>rc</I>
  1573. is the
  1574. <TT>if</TT>
  1575. statement with
  1576. <TT>else</TT>
  1577. clause.
  1578. <I>Rc</I>'s
  1579. <TT>if</TT>
  1580. has no terminating
  1581. <TT>fi</TT>-like
  1582. bracket. As a result, the parser cannot
  1583. tell whether or not to expect an
  1584. <TT>else</TT>
  1585. clause without looking ahead in its input.
  1586. The problem is that after reading, for example
  1587. <DL><DT><DD><TT><PRE>
  1588. if(test -f junk) echo junk found
  1589. </PRE></TT></DL>
  1590. in interactive mode,
  1591. <I>rc</I>
  1592. cannot decide whether to execute it immediately and print
  1593. <TT></TT><I>prompt(1)</I><TT>,
  1594. or to print
  1595. </TT><TT></TT><TT>prompt(2)</TT><TT>
  1596. and wait for the
  1597. </TT><TT>else</TT><TT>
  1598. to be typed.
  1599. In the Bourne shell, this is not a problem, because the
  1600. </TT><TT>if</TT><TT>
  1601. command must end with
  1602. </TT><TT>fi</TT><TT>,
  1603. regardless of whether it contains an
  1604. </TT><TT>else</TT><TT>
  1605. or not.
  1606. </P>
  1607. </TT><P>
  1608. <I>Rc</I>'s
  1609. admittedly feeble solution is to declare that the
  1610. <TT>else</TT>
  1611. clause is a separate statement, with the semantic
  1612. proviso that it must immediately follow an
  1613. <TT>if</TT>,
  1614. and to call it
  1615. <TT>if not</TT>
  1616. rather than
  1617. <TT>else</TT>,
  1618. as a reminder that something odd is going on.
  1619. The only noticeable consequence of this is that
  1620. the braces are required in the construction
  1621. <DL><DT><DD><TT><PRE>
  1622. for(i){
  1623. if(test -f <I>i) echo </I>i found
  1624. if not echo <I>i not found
  1625. }
  1626. </PRE></TT></DL>
  1627. and that
  1628. </I><I>rc</I><I>
  1629. resolves the ``dangling else'' ambiguity in opposition
  1630. to most people's expectations.
  1631. </P>
  1632. </I><P>
  1633. It is remarkable that in the four most recent editions of the UNIX system
  1634. programmer's manual the Bourne shell grammar described in the manual page
  1635. does not admit the command
  1636. <TT>who|wc</TT>.
  1637. This is surely an oversight, but it suggests something darker:
  1638. nobody really knows what the Bourne shell's grammar is. Even examination
  1639. of the source code is little help. The parser is implemented by recursive
  1640. descent, but the routines corresponding to the syntactic categories all
  1641. have a flag argument that subtly changes their operation depending on the
  1642. context.
  1643. <I>Rc</I>'s
  1644. parser is implemented using
  1645. <I>yacc</I>,
  1646. so I can say precisely what the grammar is.
  1647. </P>
  1648. <H4>29 Acknowledgements
  1649. </H4>
  1650. <P>
  1651. Rob Pike, Howard Trickey and other Plan 9 users have been insistent, incessant
  1652. sources of good ideas and criticism. Some examples in this document are plagiarized
  1653. from [Bourne],
  1654. as are most of
  1655. <I>rc</I>'s
  1656. good features.
  1657. </P>
  1658. <H4>30 Reference
  1659. </H4>
  1660. <br>&#32;<br>
  1661. S. R. Bourne,
  1662. UNIX Time-Sharing System: The UNIX Shell,
  1663. Bell System Technical Journal, Volume 57 number 6, July-August 1978
  1664. <br>&#32;<br>
  1665. <A href=http://www.lucent.com/copyright.html>
  1666. Copyright</A> &#169; 2004 Lucent Technologies Inc. All rights reserved.
  1667. </body></html>