/$hABfBfVBfV/`=25W25BfM01234568 `BfTBfUBfUJ +25W25BfTKLMY25W25BfTNOPQRSTV[25W25BfTfghijklnz25W25BfT2525BfTJj25W25BfT25W25BfT25W25 BfTQF25W25 BfTN25X25 BfT25X25 BfT'025X25 BfT !"#$&{25X25 BfT)*25X25 BfT+,-./z25X25 BfT025X25 BfT125X25 BfT225X25BfT3_25X25BfT4567825X25BfT9: 25X25BfT;<=25X25BfT>25X25BfT?25X25BfT@ABCD 525X25BfTEFG25X25BfTHIJK25X25BfTL&:25X25BfTMNOPQRSU 25Y25BfTXYZT25Y25BfT[j25Y25BfT\]%25Y25BfT^_O25Y25BfT`25Y25BfTa25Y25BfTbcb25Y25BfTdB25Y25BfTe~25Y25BfTfgy25Y25BfTh25Y25BfTij25Y25BfTk25Z25BfTlmnop25Z25BfTq25Z25BfTr25Z25BfTs~25Z25BfTtuK25Z25BfTvwxp25Z25BfTyO25Z25BfTz25Z25BfT{N25Z25BfT|725Z25BfT}~25Z25BfT|25Z25BfT 25Z25BfT25Z25BfT 25Z25BfT25Z25BfT6Bf{25BfT25Z25BfT125Z25BfT25[25BfT25[25BfT25[25BfT25[25BfThBf|25BfT[25[25BfT25[25BfTy25[25 BfT 25[25 BfTf25[25 BfTZ27x25 BfT25[25 BfT25[25 BfT25[25 BfTy25[25 BfT!25[25 BfT25\25 BfT25\25 BfT25\25 BfTMBf~25 BfT625\25 BfT,25\25 BfT 25\25 BfT25]25 BfT25]25 BfT]25]25 BfT25]25BfTb25]25BfT25]25BfT25^25BfTZ25^25BfT25^25BfTQ25^25BfT25^25BfT25^25BfT 2525BfT25_25BfU_25_25BfU?25_25BfU_25_25BfUo25_25BfU wBf 25BfU25_25BfU25`25BfUBf|25BfU25`25BfU[25a25BfU[25a25BfU25a25BfU25a25BfU25a25BfUCi25a25BfU25b25BfU125b25BfU 25b25BfU\25b25BfU25b25BfU\25b25BfU25b25BfUK25b25BfU25c25BfU25c25BfU25c25BfU25c25BfU 25c25BfU    25c25BfU 25d25BfU{25d25BfU25d25BfU25d25BfU 25d25BfUz25d25BfU25d25BfU !"25d25BfU#)25d25BfU$2525BfU%y25e25BfU&'+25e25BfU(25e25BfU)25e25BfU*25e25BfU+25e25BfU,-./0k25f25BfU1725f25BfU2425f25BfU3425f25BfU56789:;=25f25BfU>!25f25BfU?@925f25BfUA,25f25BfUBCDEFGHJK25f25BfUOPQ27|o25BfUR25f25BfUST\25f25BfUUV25g25BfUW25g25BfUX25g25BfUY25g25BfUZ25g25BfU[25g25BfU\25g25BfU]z25g25BfU^25g25BfU_Bfz25BfU`R25g25BfUabG25g25BfUc125g25BfUde25g25BfUf125g25BfUgO25g25BfUhi25g25BfUj25g25BfUk25g25BfUl25g25BfUm25g25BfUn25g25BfUo25g25BfUp[25g25BfUqS25h25BfUr0BfUBfUBfUsi25h25ߛBfUtu 25h25ߗBfUvwx!25h25ߜBfUy25h25ߜBfUz{25h25ߜBfU|]2525ߛBfU}25h25ߜBfU~25h25ߙBfU 25h25ߗBfU25h25ߗBfU25h25ߘBfU 25h25ߘBfU25h25ߘBfUP25h25ߘBfU25h25ߘBfU 25h25ߘBfU25h25ߘBfU[25h25ߘBfU25h25ߙBfU725h25ߙBfUG25h25ߙBfU25h25ߙBfUV25h25ߙBfU@25h25ߙBfU25h25ߚBfU 25h25ߚBfU 25h25ߚBfU25h25ߚBfU m25h25ߚBfU 25h25ߚBfU25h25ߚBfUk25h25ߚBfU*25h25ߚBfU25i25ߛBfU25i25ߛBfU25i25ߛBfU 25i25ߛBfU25i25ߛBfUI25i25ߜBfU25i25ߜBfUd25i25ߜBfUs25i25ߝBfU25i25ߝBfU25i25ߝBfU)25i25ߝBfU25i25ߝBfU25i25ߝBfUZ25i25ߝBfU 25i25ߝBfUBfUBfUBfU25i25BfU  25i25BfU   25i25BfUJ25i25BfU25i25BfU25j25BfU "25j25BfU#$:25j25BfU%25j25BfU&' 25j25BfU()*+ 25j25BfU,-.25j25BfU/012325j25BfU4l25j25BfU56 %25j25BfU789:225j25BfU;25j25BfU<25j25BfU=C25j25BfU>?25j25BfU@ABC25j25BfUDE"25k25BfUFGHIJKLNx25k25BfUP25k25BfUQRSTU25k25BfUV@25k25BfUW25k25BfUXY '25k25BfUZ[\;25k25BfU]^e25k25BfU_`25k25BfUab25k25BfUc25k25BfUd25k25BfUe _25k25BfUfgh|25k25BfUio25k25BfUjk H25k25BfUlmn25k25BfUopb25k25BfUqrstuvw 25k25BfUxy25k25BfUz225l25BfU{|25l25BfU} 25l25BfU~25l25BfU 25l25BfU2525BfU 25l25BfU725l25BfU 25l25BfUQ25l25BfU'25l25BfU25l25BfUBfUBfUBfU p25l25BfU25l25BfU25m25BfU 25m25BfU 25m25BfUp2525BfUK'25m25BfU25m25BfU!25m25BfUBfUBfUBfU 25m25+BfU25m25+BfU25m25,BfU2525,BfU25n25,BfU  m25n25-BfU   25n25,BfU>?@AB25n25,BfUCDz25n25,BfUEFGH25n25-BfUI25n25-BfUJKA25n25-BfULM25n25-BfUNO~25n25,BfUPQRST0BfUBfUBfUUC2525fBfUV`BfUBfUBfUWE2525|BfUXYZ25o25|BfU[\]^_25o25|BfU`abcdefh h25o25|BfUijkBfUBfUBfUlk25o25BfUm,525o25BfUnopqrstv25o25BfU{25o25BfU|25o25BfU}225o25BfU~ '25o25BfU 2525BfU :25o25BfU25o25BfU5m25o25BfU 25o25BfU25o25BfU25o25BfUY25o25BfUd25o25BfU25o25BfU 25o25BfU25o25BfU _25o25BfUmV25p25BfU925p25BfUO25p25BfU"25p25BfU25p25BfU25p25BfUQ25p25BfUV25p25BfU25p25BfU25p25BfU25p25BfU25p25BfU25p25BfU_25p25BfU25p25BfU25p25BfU25p25BfUq25p25BfU25p25BfU '25p25BfU25p25BfUa25p25BfU&25p25BfU25p25BfUBfUBfUBfU325q25BfU    !y25q25BfU22525BfU !"#% 2525BfU+,-.<25q25BfU/012345725q25BfU@ABCDEFH'25q25BfUfghijkln25q25BfUqrst o25q25BfUuvwxyz{}25q25BfU^25q25BfU2525BfU25q25BfU25q25BfU25q25޿BfMCBf25~BfMi1@1@n2 c0025M@242125MYl1111Pg1Pg1@H(1Pg1Pg1@IV111@JP1@1@1@K1Pg1Pg1@L-1Pg1Pg1@M001@P1@1@1@N1Pg1Pg1@O-1Pg1Pg1@P001@P1@1@1@Q1Pg1Pg1@R-1Pg1Pg1@SD17171@TUVP1@1@1@W1Pg1Pg1@X-1Pg1Pg1@Y~001@Z[P1@1@1@\1Pg1Pg1@]-1Pg1Pg1@^001@P1@1@1@_1Pg1Pg1@`-1Pg1Pg1@a001@bP1@1@1@c1Pg1Pg1@d-1Pg1Pg1@e,001@fP1@1@1@g1Pg1Pg1@h-1Pg1Pg1@i001@P1@1@1@j1Pg1Pg1@k-1Pg1Pg1@l001@p1@1@1@m1Pg1Pg1@n-1Pg1Pg1@o1*1*1@pqrstuvx1*1*1@1*1*1@!y21+1*t25LDyz{|}~P1@1@1@1Pg1Pg1@-1Pg1Pg1@1}1}1@p1@1@1@Y1Pg1Pg1@-1Pg1Pg1@316161@16161@16161@211625LP1@1@1@1Pg1Pg1@-1Pg1Pg1@k111@1@1@1@1Pg1Pg1@-1Pg1Pg1@'17171@17c17c1@17c17c1@17171@17171@!2121c25M212 a(25MPQRSTUVXP1@1@1@1Pg1Pg1@-1Pg1Pg1@1111@P1@1@1@1Pg1Pg1@-1Pg1Pg1@001@P1@1@1@1Pg1Pg1@-1Pg1Pg1@}111@1@1@1@1Pg1Pg1@-1Pg1Pg1@.19191@19191@19191@19191@19191@ 21$19 25M21'1925M...macros.9man1man2man3man4!man5+man6:man7<man8Aman9ntemplate.1}whatis~man3>man4Mman5Tman6bman7cman8gmantar.Ztemplate.0whatisgroup.\" Macro package for producing books (based on -ms) .nr PS 12 .nr PZ 12 .\" RT - reset everything to normal state .de RT .if !\\n(1T .BG .ce 0 .if !\\n(IK .if !\\n(IF .if !\\n(IX .if !\\n(BE .di .ul 0 .if \\n(QP \{\ . ll +\\n(QIu . in -\\n(QIu . nr QP -1\} .if \\n(NX<=1 .if \\n(AJ=0 .ll \\n(LLu .if \\n(IF=0 \{\ . ps \\n(PS . if \\n(VS>=41 .vs \\n(VSu . if \\n(VS<=40 .vs \\n(VSp\} .if \\n(IP .in -\\n(I\\n(IRu .if \\n(IP=0 .nr I0 \\n(PIu .if \\n(IP .nr IP -1 .ft 1 .bd 1 .ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n .fi .. . \"IZ - initialization .de IZ .nr TN 0 .em EM .if n .ds [. [ .if t .ds [. \s-2\v'-.4m'\f1 .if n .ds .] ] .if t .ds .] \v'.4m'\s+2\fP .if n .ds [o "" .if n .ds [c "" .if t .ds [o `` .if t .ds [c '' .ch FO \\n(YYu .if \\n(FM=0 .nr FM 1i .nr YY -\\n(FMu .nr XX 0 1 .nr IP 0 .nr PI 5n .nr QI 5n .nr I0 \\n(PIu .nr PZ 12 .nr VZ 13.8p .nr PS \n(PZ .nr VS \\n(VZu .if !\\n(PD .if n .nr PD 1v .if !\\n(PD .if t .nr PD 0.3v .nr ML 3v .ps \\n(PS .if \\n(VS>=41 .vs \\n(VSu .if \\n(VS<=40 .vs \\n(VSp .nr IR 0 .nr TB 0 .nr SJ \\n(.j .nr LL 6i .ll \\n(LLu .nr LT \\n(.l .lt \\n(LTu .ev 1 .nr FL \\n(LLu*11u/12u .ll \\n(FLu .ps 10 .vs 12p .ev .if \\*(CH .ds CH "\(hy \\\\n(PN \(hy .wh 0 NP .wh -\\n(FMu FO .ch FO 16i .wh -\\n(FMu FX .ch FO -\\n(FMu .if t .wh -\\n(FMu/2u BT .if n .wh -\\n(FMu/2u-1v BT .. . \"KS keep - for keep release features. As in IFM .de KS .nr KN \\n(.u .if \\n(IK=0 .if \\n(IF=0 .KQ .nr IK +1 .. . \"KQ - real keep processor .de KQ .br .nr KI \\n(.i .ev 2 .br .in \\n(KIu .ps \\n(PS .if \\n(VS>40 .vs \\n(VSu .if \\n(VS<=39 .vs \\n(VSp .ll \\n(LLu .lt \\n(LTu .if \\n(NX>1 .ll \\n(CWu .if \\n(NX>1 .lt \\n(CWu .di KK .nr TB 0 .nr KV 0 .. . \"KF - floating keep .de KF .nr KN \\n(.u .if !\\n(IK .FQ .nr IK +1 .. . \"FQ real floating keep processor .de FQ .nr KI \\n(.i .ev 2 .br .in \\n(KIu .ps \\n(PS .if \\n(VS>40 .vs \\n(VSu .if \\n(VS<=39 .vs \\n(VSp .ll \\n(LLu .lt \\n(LTu .if \\n(NX>1 .ll \\n(CWu .if \\n(NX>1 .lt \\n(CWu .di KK .nr TB 1 .nr KV 0 .. . \"KP - keep full page .de KP .nr KV 1 .. . \"KE release - everything between keep and release is together .de KE .if \\n(IK .if !\\n(IK-1 .if \\n(IF=0 .RQ .if \\n(IK .nr IK -1 .. . \"RQ real release .de RQ .br .di .nr NF 0 .if \\n(dn-\\n(.t .nr NF 1 .if \\n(TC .nr NF 1 .if \\n(KV .nr NF 1 \" if KV on full page needed, doesn't fit .if \\n(NF .if !\\n(TB .sp 11i .if !\\n(NF .if \\n(TB .nr TB 0 .nf .rs .nr TC 5 .in 0 .ls 1 .if \\n(TB=0 .ev .if \\n(TB=0 .br .if \\n(TB=0 .ev 2 .if \\n(TB=0 .KK .ls .ce 0 .if \\n(TB=0 .rm KK .if \\n(TB .da KJ .if \\n(TB \!.KD \\n(dn \\n(KV .if \\n(TB .KK .if \\n(TB .di .nr TC \\n(TB .if \\n(KN .fi .in .ev .. .de EQ \"equation, breakout and display .nr EF \\n(.u .rm EE .nr LE 1 \" 1 is center .ds EL \\$1 .if "\\$1"L" .ds EL \\$2 .if "\\$1"L" .nr LE 0 .if "\\$1"C" .ds EL \\$2 .if "\\$1"I" .nr LE 0 .if "\\$1"I" .ds EE \\h'|10n' .if "\\$1"I" .if !"\\$3"" .ds EE \\h'\\$3' .if "\\$1"I" .ds EL \\$2 .if \\n(YE>0 .nf .di EZ .. .de EN \" end of a displayed equation .br .di .rm EZ .nr ZN \\n(dn .if \\n(ZN>0 .if \\n(YE=0 .LP .if \\n(ZN=0 .if !"\\*(EL"" .nr ZN 1 .if "\\n(.z"" .if \\n(ZN>0 .if !\\n(nl=\\n(PE .if t .sp .5 .if "\\n(.z"" .if \\n(ZN>0 .if !\\n(nl=\\n(PE .if n .sp 1 .if !"\\n(.z"" .if \\n(ZN>0 .if !\\n(.d=\\n(PE .if t .sp .5 .if !"\\n(.z"" .if \\n(ZN>0 .if !\\n(.d=\\n(PE .if n .sp 1 'pc .if \\n(BD>0 .nr LE 0 \" can't mean centering in this case. .if \\n(MK>0 .if \\n(LE=1 .ds EE \\h'|10n' .if \\n(MK>0 .nr LE 0 \" don't center if mark/lineup 'lt \\n(.lu .if \\n(EP=0 .if \\n(ZN>0 .if \\n(LE>0 .tl \(ts\(ts\\*(10\(ts\\*(EL\(ts .if \\n(EP=0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD=0 .tl \(ts\\*(EE\\*(10\(ts\(ts\\*(EL\(ts .if \\n(EP=0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD>0 .if \\n(BD<\\w\(ts\\*(10\(ts .nr BD \\w\(ts\\*(10\(ts .if \\n(EP=0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD>0 \!\\*(10\\t\\*(EL .if \\n(EP>0 .if \\n(ZN>0 .if \\n(LE>0 .tl \(ts\\*(EL\(ts\\*(10\(ts\(ts .if \\n(EP>0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD=0 .tl \(ts\\*(EL\\*(EE\\*(10\(ts\(ts\(ts .if \\n(EP>0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD>0 .if \\n(BD<\\w\(ts\\*(10\(ts .nr BD \\w\(ts\\*(10\(ts .if \\n(EP>0 .if \\n(ZN>0 .if \\n(LE=0 .if \\n(BD>0 \!\\h'-\\\\n(.iu'\\*(EL\\h'|0'\\*(10 .\".di EZ \" GCOS patch .\"\\*(10 \" GCOS patch .\".br \" GCOS patch .\".di \" GCOS patch .\".rm EZ \" GCOS patch 'lt \\n(LLu 'pc % .if \\n(YE>0 .if \\n(EF>0 .fi .rm EL 10 11 12 13 14 15 16 17 18 19 20 21 22 23 .rr 10 11 12 13 14 15 16 17 18 19 20 21 22 23 .if \\n(ZN>0 .if t .sp .5 .if \\n(ZN>0 .if n .sp .if "\\n(.z"" .nr PE \\n(nl .if !"\\n(.z"" .nr PE \\n(.d .nr z 72-((\\n(nl-\\n(HM)%72) .if \\n(nl<\\n(HM .nr z 0 .if \\nz>0 .if \\nz<60 .sp \\nzu \"force post equation text to whole line .if \\nz>59 .if \\nz<72 .sp \\nzu-72u \"move backwards a fraction of a pica .. .de ME .nr SJ \\n(.j .if \\n(LL>0 .nr LT \\n(LL .nr YE 1 .if \\n(PO=0 .nr PO \\n(.o .if \\n(mo-0 .ds MO January .if \\n(mo-1 .ds MO February .if \\n(mo-2 .ds MO March .if \\n(mo-3 .ds MO April .if \\n(mo-4 .ds MO May .if \\n(mo-5 .ds MO June .if \\n(mo-6 .ds MO July .if \\n(mo-7 .ds MO August .if \\n(mo-8 .ds MO September .if \\n(mo-9 .ds MO October .if \\n(mo-10 .ds MO November .if \\n(mo-11 .ds MO December .if \\n(dw-0 .ds DW Sunday .if \\n(dw-1 .ds DW Monday .if \\n(dw-2 .ds DW Tuesday .if \\n(dw-3 .ds DW Wednesday .if \\n(dw-4 .ds DW Thursday .if \\n(dw-5 .ds DW Friday .if \\n(dw-6 .ds DW Saturday .if "\\*(DY"" .ds DY \\*(MO \\n(dy, 19\\n(yr .if "\\*(CF"" .if n .ds CF "\\*(DY .. . \"EM end up macro - process left over keep-release .de EM .br .if \\n(TB=0 .if t .wh -1p CM .if \\n(TB \&\c .if \\n(TB 'bp .if \\n(TB .NP .if \\n(TB .ch CM 160 .. . \"NP new page .de NP .if \\n(FM+\\n(HM>=\\n(.p .tm Margins bigger than page length. .if \\n(FM+\\n(HM>=\\n(.p .ab .if \\n(FM+\\n(HM>=\\n(.p .ex .nr PX \\n(.s .nr PF \\n(.f .nr PV \\n(.v .if t .CM .if \\n(HM=0 .nr HM 1i 'sp \\n(HMu/2u .lt \\n(LTu .ps \\n(PS .vs \\n(PS+2 .ft 1 .if \\n(PO>0 .po \\n(POu .PT .ps \\n(PX .vs \\n(PVu .ft \\n(PF 'sp |\\n(HMu .nr XX 0 1 .nr YY 0-\\n(FMu .ch FO 16i .ch FX 17i .ch FO \\n(.pu-\\n(FMu .ch FX \\n(.pu-\\n(FMu .if \\n(MF .FV .nr MF 0 .mk .os .ev 1 .if \\n(TD=0 .if \\n(TC<5 .XK .nr TC 0 .ns .ev .nr TQ \\n(.i .nr TK \\n(.u .if \\n(IT>0 \{\ . in 0 . nf . TT . in \\n(TQu . if \\n(TK .fi\ \} .mk #T .if t .if \\n(.o+\\n(LL>7.75i .tm Offset (\\n(.o) + line length (\\n(LL) exceeds 7.75 inches, too wide .. .de XK .nr TD 1 .nf .ls 1 .in 0 .rn KJ KL .KL .rm KL .if "\\n(.z"KJ" .di .nr TB 0 .if "\\n(.z"KJ" .nr TB 1 .br .in .ls .fi .if (\\n(nl+1v)>(\\n(.p-\\n(FM) .if \\n(NX>1 .RC .if (\\n(nl+1v)>(\\n(.p-\\n(FM) .if \\n(NX<1 .bp .nr TD 0 .. .de KD .nr KM 0 .if "\\n(.z"" .if \\$2>0 .if \\n(nl>\\n(HM .if (\\n(nl+1v)<(\\n(.p-\\n(FM) .di KJ .if "\\n(.z"" .if \\n(nl>\\n(HM .if \\$2>0 .sp 15i \" full page figure must have new page .if "\\n(.z"" .if \\n(nl>\\n(HM .if \\$2=0 .if (\\n(nl+1v)>(\\n(.p-\\n(FM) .sp 15i .if "\\n(.z"KJ" .nr KM 1 \" KM is 1 if in a rediversion of keeps .if \\n(KM>0 \!.KD \\$1 \\$2 .nr KR \\n(.t .if \\n(nl<=\\n(HM .nr KR 32767 .if \\n(KM=0 .if \\n(KR<\\$1 .di KJ .if \\n(KM=0 .if \\n(KR<\\$1 .nr KM 1 .if \\n(KM=0 .if \\$2>0 .if (\\n(nl+1v)>(\\n(.p-\\n(FM) .sp 15i .rs .if \\n(KM=0 .if \\$2>0 .sp \\n(.tu-\\$1u .. .de PT .lt \\n(LLu .pc % .nr PN \\n% ....if \\n%-1 .tl '\\*(LH'\\*(CH'\\*(RH' .lt \\n(.lu .. . \"FO - footer of page .de FO .rn FO FZ .if \\n(K1>0 .tm This memo has a multi-page cover sheet. You are .if \\n(K1>0 .tm rebuked in the name of the Committee on Technical Memoranda. .if \\n(IT>0 .nr T. 1 .if \\n(IT>0 .if \\n(FC=0 .T# 1 .if \\n(IT>0 .br .nr FC +1 .if \\n(NX<2 .nr WF 0 .nr dn 0 .if \\n(FC<=1 .if \\n(XX .XF .rn FZ FO .nr MF 0 .if \\n(dn .nr MF 1 .if !\\n(WF .nr YY 0-\\n(FMu .if !\\n(WF .ch FO \\n(YYu .if !\\n(dn .nr WF 0 .if \\n(FC<=1 .if \\n(XX=0 .if \\n(NX>1 .RC .nr x 7176u-\\n(.d .if \nL=1 .if \\n(FC<=1 .if \\n(XX=0 .if \\n(NX<1 'tm Chap=\\na page=\\n% short=\\nx .if \\n(FC<=1 .if \\n(XX=0 .if \\n(NX<1 'bp .nr FC -1 .if \\n(ML>0 .ne \\n(MLu .. . \"2C - begin double column .de 2C .MC \" default MC is double column .. .de MC \" multiple columns- arg is line length .nr L1 \\n(LL*7/15 .if \\n(.$>0 .nr L1 \\$1n .nr GW 0-1 .if \\n(.79:;<=>?@ABCDEFGHI$>1 .nr GW \\$1n .nr NQ \\n(LL/\\n(L1 .if \\n(NQ<1 .nr NQ 1 .if \\n(NQ>2 .if (\\n(LL%\\n(L1)=0 .nr NQ -1 .if \\n(1T=0 \{\ . BG . if n .sp 4 . if t .sp 2\} .if \\n(NX=0 .nr NX 1 .if !\\n(NX=\\n(NQ \{\ . RT . if \\n(NX>1 .bp . mk . nr NC 1 . po \\n(POu\} .if \\n(NQ>1 .hy 14 .nr NX \\n(NQ .nr CW \\n(L1 .ll \\n(CWu .nr FL \\n(CWu*11u/12u .if \\n(NX>1 .nr GW (\\n(LL-(\\n(NX*\\n(CW))/(\\n(NX-1) .nr RO \\n(CW+\\n(GW .ns .. .de RC .ie \\n(NC>=\\n(NX .C2 .el .C1 .. .de C1 .rt .po +\\n(ROu .nr NC +1 .if \\n(NC>\\n(NX .nr NC 1 .nr XX 0 1 .if \\n(MF .FV .ch FX \\n(.pu-\\n(FMu .ev 1 .if \\n(TB .XK .nr TC 0 .ev .nr TQ \\n(.i .if \\n(IT>0 .in 0 .if \\n(IT>0 .TT .if \\n(IT>0 .in \\n(TQu .mk #T .ns .. .de C2 .po \\n(POu .nr NC +1 .if \\n(NC>\\n(NX .nr NC 1 'bp .. . \"1C - return to single column format .de 1C .MC \\n(LLu .hy 14 .. . \".de R3 . \".pl 102 . \".nr LT \\n(.l . \".. .de BT .nr PX \\n(.s .nr PF \\n(.f .ft 1 .ps \\n(PS 'lt \\n(LTu .po \\n(POu .if \\n%>0 .tl '\\*(LF'\\*(CF'\\*(RF' .ft \\n(PF .ps \\n(PX .. . \"PP - paragraph .de PP .RT .if \\n(1T .sp \\n(PDu .ti +\\n(PIu .. . \"SH - (unnumbered) section heading .de SH .ti \\n(.iu .RT .if \\n(1T .sp 1 .if !\\n(1T .BG .RT .ne 4 .ft 3 .. . \"NH - numbered heading .de NH .RT .if \\n(1T .sp 1 .if !\\n(1T .BG .RT .ne 4 .ft 3 .nr NS \\$1 .if !\\n(.$ .nr NS 1 .if !\\n(NS .nr NS 1 .nr H\\n(NS +1 .if !\\n(NS-4 .nr H5 0 .if !\\n(NS-3 .nr H4 0 .if !\\n(NS-2 .nr H3 0 .if !\\n(NS-1 .nr H2 0 .if !\\$1 .if \\n(.$ .nr H1 1 .ds SN \\n(H1. .if \\na=0 .ds SN \\*(CN. .ti \\n(.iu .if \\n(NS-1 .as SN \\n(H2. .if \\n(NS-2 .as SN \\n(H3. .if \\n(NS-3 .as SN \\n(H4. .if \\n(NS-4 .as SN \\n(H5. \\*(SN .. . \"BG - begin, execute at first PP .de BG .br .ME .rm ME .di .ce 0 .nr KI 0 .hy 14 .nr 1T 1 .S\\n(ST .rm S0 .rm S1 .rm S2 .rm S3 .rm OD .rm OK .rm TX .rm AX .rm WT .rm CS .rm TM .rm IM .rm MF .rm MR .rm RP .rm I1 .rm I2 .rm I3 .rm I4 .rm I5 .rm CB .rm E1 .rm E2 .de TL .ft 3 .sp .if n .ul 100 .ce 100 .ps +2 \\.. .de AU .ft 2 .if n .ul 0 .ce 100 .sp .NL \\.. .de AI .ft 1 .ce 100 .if n .ul 0 .if n .sp .if t .sp .5 .NL \\.. .RA .rm RA .rn FJ FS .rn FK FE .nf .ev 1 .ps \\n(PS-2 .vs \\n(.s+2p .ev .if \\n(KG=0 .nr FP 0 .if \\n(GA>1 .if \\n(KG=0 .nr GA 0 \" next UNIX must be flagged. .nr KG 0 .if \\n(FP>0 .FS .if \\n(FP>0 .FG .if \\n(FP>0 .FE .br .if \\n(TV>0 .if n .sp 2 .if \\n(TV>0 .if t .sp 1 .fi .ll \\n(LLu .. .de RA \"redefine abstract macros .de AB .br .if !\\n(1T .BG .ce 1 .sp 1 .if \\n(.$=0 ABSTRACT .if \\n(.$>0 .if !"\\$1"-" .if !"\\$1"no" \\$1 .if \\n(.$=0 .sp .if \\n(.$>0 .if !"\\$1"-" .if !"\\$1"no" .sp .sp 1 .nr AJ 1 .in +\\n(.lu/12u .ll -\\n(.lu/12u .RT \\.. .de AE .nr AJ 0 .br .in 0 .ll \\n(LLu .if \\n(VS>=41 .vs \\n(VSu .if \\n(VS<=40 .vs \\n(VSp \\.. .. . \"IP - indented paragraph .de IP .RT .if !\\n(IP .nr IP +1 .sp \\n(PDu .if \\n(.$-1 .nr I\\n(IR \\$2n .in +\\n(I\\n(IRu .nr TY \\n(TZ-\\n(.i .ta \\n(I\\n(IRu \\n(TYuR .if \\n(.$>0 \{\ .ti -\\n(I\\n(IRu \&\\$1\t\c\} .. . \"LP - left aligned (block) paragraph .de LP .ti \\n(.iu .RT .if \\n(1T .sp \\n(PDu .. .de QP .ti \\n(.iu .RT .if \\n(1T .sp \\n(PDu .ne 1.1 .nr QP 1 .in +\\n(QIu .ll -\\n(QIu .ti \\n(.iu .. . \"IE - synonym for .LP .de IE .LP .. . \"LB - label paragraph .de LB .in +\\n(I\\n(IRu .ta \\n(I\\n(IRu .if \\n(.$ .ti -\\n(I\\n(IRu .if \\n(.$ \&\\$1\t\c .. .de XP .RT .if !\\n(IP .nr IP +1 .sp \\n(PDu .ne 3 .if \\n(.$=3 .nr I\\n(IR \\$3n .if \\n(.$=4 .nr I\\n(IR \\$4n .nr J\\n(IR \\n(IRu/2u .if \\n(.$=4 .nr J\\n(IR \\$3n .in +\\n(I\\n(IRu .ta \\n(J\\n(IRu \\n(I\\n(IRu .ti -\\n(I\\n(IRu \0\\$1\t\\$2\t\c .. . \"RS - prepare for double indenting .de RS .nr IS \\n(IP .RT .nr IP \\n(IS .if \\n(IP>0 .in +\\n(I\\n(IRu .nr IR +1 .nr I\\n(IR \\n(PIu .in +\\n(I\\n(IRu .nr TY \\n(TZ-\\n(.i .ta \\n(TYuR .. . \"RE - retreat to the left .de RE .nr IS \\n(IP .RT .nr IP \\n(IS .if \\n(IR>0 .nr IR -1 .if \\n(IP<=0 .in -\\n(I\\n(IRu .. .de TC .nr TZ \\n(.lu .if \\n(.$ .nr TZ \\$1n .ta \\n(TZuR .. .de TD .LP .nr TZ 0 .. . \"CM - cut mark .de CM .po 0 .lt 7.6i .ft 1 .ps 10 .vs 4p .po .vs .lt .ps .ft .. . \"B - bold font .de B .nr PQ \\n(.f .if t .ft 3 .if "\\$1"" .if n .ul 1000 .if !"\\$1"" .if n .ul 1 .if t .if !"\\$1"" \&\\$1\\f\\n(PQ\\$2 .if n .if \\n(.$=1 \&\\$1 .if n .if \\n(.$>1 \&\\$1\\c .if n .if \\n(.$>1 \\&\\$2 .. . \"R - Roman font .de R .if n .ul 0 .ft 1 .. . \"I - italic font .de I .nr PQ \\n(.f .if t .ft 2 .if "\\$1"" .if n .ul 1000 .if !"\\$1"" .if n .ul 1 .if t .if !"\\$1"" \&\\$1\\f\\n(PQ\\$2 .if n .if \\n(.$=1 \&\\$1 .if n .if \\n(.$>1 \&\\$1\\c .if n .if \\n(.$>1 \\&\\$2 .. . \"TA - tabs set in ens or chars .de TA .ta \\$1n \\$2n \\$3n \\$4n \\$5n \\$6n \\$7n \\$8n \\$9n .. . \"SM - make smaller size .de SM .if \\n(.$>0 \&\\$3\s-2\\$1\s0\\$2 .if \\n(.$=0 .ps -2 .. . \"LG - make larger size .de LG .ps +2 .. . \"NL - return to normal size .de NL .ps \\n(PS .. . \"DA - force date; ND - no date or new date. .de DA .if \\n(.$ .ds DY \\$1 \\$2 \\$3 \\$4 .ds CF \\*(DY .. .de ND .ME .rm ME .ds DY \\$1 \\$2 \\$3 \\$4 .rm CF .. .de FN .FS .. . \"FS - begin footnote .de FJ 'ce 0 .di .ev1 .ll \\n(FLu .da FF .br .if \\n(IF>0 .tm Footnote within footnote-illegal. .nr IF 1 .if !\\n+(XX-1 .FA .. . \"FE - footnote end .de FK .br .in 0 .nr IF 0 .di .ev .if !\\n(XX-1 .nr dn +\\n(.v .nr YY -\\n(dn .if \\n(NX=0 .nr WF 1 .if \\n(dl>\\n(CW .nr WF 1 .if (\\n(nl+\\n(.v)<=(\\n(.p+\\n(YY) .ch FO \\n(YYu .if (\\n(nl+\\n(.v)>(\\n(.p+\\n(YY) .if \\n(nl>(\\n(HM+1.5v) .ch FO \\n(nlu+\\n(.vu .if (\\n(nl+\\n(.v)>(\\n(.p+\\n(YY) .if \\n(nl+\\n(FM+1v>\\n(.p .ch FX \\n(.pu-\\n(FMu+2v .if (\\n(nl+\\n(.v)>(\\n(.p+\\n(YY) .if \\n(nl<=(\\n(HM+1.5v) .ch FO \\n(HMu+(4u*\\n(.vu) .. .\" First page footer. .de FS .ev1 .br .ll \\n(FLu .da FG .. .de FE .br .di .nr FP \\n(dn .if \\n(1T=0 .nr KG 1 \"not in abstract repeat next page. .if "\\n(.z"OD" .nr KG 0 \" if in OK, don't repeat. .ev .. .de FA .if n __________________________ .if t \l'1i' .br .. .de FV .FS .nf .ls 1 .FY .ls .fi .FE .. .de FX .if \\n(XX>0 .di FY .if \\n(XX>0 .ns .. .de XF .if \\n(nlu+1v>(\\n(.pu-\\n(FMu) .ch FX \\n(nlu+1.9v .ev1 .nf .ls 1 .FF .rm FF .nr XX 0 1 .br .ls .di .fi .ev .. .de FL .ev1 .nr FL \\$1n .ll \\$1 .ev .. .de UL \" underline argument, don't italicize .if t \\$1\l'|0\(ul'\\$2 .if n .I \\$1 \\$2 .. .de UX UNIX .. .de US the .UX operating system .. .de QS .br .LP .in +\\n(QIu .ll -\\n(QIu .. .de QE .br .ll +\\n(QIu .in -\\n(QIu .LP .. .de B1 \" begin boxed stuff .br .di BB .nr BC 0 .if "\\$1"C" .nr BC 1 .nr BE 1 .. .de B2 \" end boxed stuff .br .nr BI 1n .if \\n(.$>0 .nr BI \\$1n .di .nr BE 0 .nr BW \\n(dl .nr BH \\n(dn .ne \\n(BHu+\\n(.Vu .nr BQ \\n(.j .nf .ti 0 .if \\n(BC>0 .in +(\\n(.lu-\\n(BWu)/2u .in +\\n(BIu .BB .in -\\n(BIu .nr BW +2*\\n(BI .sp -1 \l'\\n(BWu\(ul'\L'-\\n(BHu'\l'|0\(ul'\h'|0'\L'\\n(BHu' .if \\n(BC>0 .in -(\\n(.lu-\\n(BWu)/2u .if \\n(BQ .fi .br .. .de AT .nf .sp .ne 2 Attached: .. .de CT .nf .sp .ne 2 .ie \\n(.$ Copy to \\$1: .el Copy to: .. .de BX .if t \(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul' .if n \(br\\kA\|\\$1\|\\kB\(br\v'-1v'\h'|\\nBu'\l'|\\nAu'\v'1v'\l'|\\nAu' .. .IZ .rm IZ .\" ------------------- VARIABLES ------------------------------ .\" \na - Current chapter .\" \nb - Current section .\" \nc - Current subsection .\" \nd - Set to 0 initially, 1 by PT, 2 by .PB Used to control running head .\" \ne - Current equation number .\" \ng - Used to count items in numbered lists .\" \nh - Counts number of times CP has been invoked .\" \nj - Set to 1 iff footer page number needed .\" \nk - Last figure number used .\" \nL - 1 if depth printed for each page .\" \nl - 1 old Agfa length to be used .\" \np - Numbers end-of-chapter problems .\" \nq - 1 for double spaced text, smaller vert. margins .\" \ns - initial page number .\" \nt - Variable part of spacing inside .BI macro .\" \nv - Scratch register in lower case roman numerals .\" \nx - Scratch register .\" ------------------- GENERAL PARAMETERS --------------------- .nr BO 43 \" number of lines of text per page .nr PO 1.3i .po \n(PO .if \nq=1 .ls 2 \" -rq1 invokes double spacing .nr LL 5.67i .if t \{ .nr PL 29.73c .nr PI 0.25i\} .if n \{ .nr LL 80m .nr PL 11.0i .nr PI 3m\} .pl \n(PLu .nr HM (\n(PLu-(\n(BOu*\n(VSu))/2u .nr FM \n(PLu-(\n(HMu+((\n(BOu-1u)*\n(VSu)+1u) .nr xx \n(HMu%\n(VZu .nr HM \n(HMu-\n(xxu .nr FM \n(FMu+\n(xxu .nr t 0 0 .\" ------------------- INITIALIZATION ------------------------- .nr d 0 0 .nr e 0 1 .nr h 0 1 .nr j 1 0 .nr t 0 0 .tr ~ .ds CT "~ \"initially empty .ND \"suppress date on bottom of page .af v i \"register v is in lower case roman .ch FO -\n(FMu .ch BT -\n(FMu+0.5P .\" ------------------- ALIGN TEXT TO A WHOLE NUMBER OF PICAS ---- .de AL 'nr xx \\n(.du%\\n(VZu 'nr xy \\n(VZu-\\n(xx 'if \\n(xy=\\n(VZu .nr xy 0 'sp \\n(xyu .. .\" ------------------- DIVISION OF TEXT INTO LOGICAL UNITS ---- .\" Define chapter number .de CP .ds CN \\$1 .ds CX CHAP. .if '\\$1'A' .ds CX APPENDIX .if '\\$1'B' .ds CX APPENDIX .if '\\$1'C' .ds CX APPENDIX .if '\\$1'D' .ds CX APPENDIX .if '\\$1'E' .ds CX APPENDIX .if '\\$1'F' .ds CX APPENDIX .if '\\$1'A' .nr a 0 0 .if '\\$1'B' .nr a 0 0 .if '\\$1'C' .nr a 0 0 .if '\\$1'D' .nr a 0 0 .if '\\$1'E' .nr a 0 0 .if '\\$1'F' .nr a 0 0 .nr H1 \\$1 0 .nr H2 0 1 .nr a \\$1 0 .nr b 0 1 .nr c 0 1 .nr d 1 1 .nr e 0 1 .nr k 0 1 .nr s \\n% .if \\nq=1 .PH 6 .ll \\n(LLu .nr LT \\n(LLu .lt \\n(LLu .ll \\n(LLu .pl \n(PLu .po \n(POu .in 0 .nr PS \\n(PZ .nr VS \\n(VZu .nr PD 0i .ds ST .ds CT \\$2 .if !'\\$3'' .as CT " \\$3 .if \\nh .bp .rs .sp 16P .B .ps 30 .vs 32 .ce 1 \\$1 .sp 4P .ps 18 .vs 20 .ce 1 \\$2 .sp 0.25i .if !'\\$3'' .ce 1 .if !'\\$3'' \\$3 .ps 10 .vs 12 .R .nr x \\n(.pu/2u .sp |\\nxu .nr h +1 1 .tr _\\(ru .AL .. .de SP .sp \\$1 \"used for temporary (page balancing ) fill .. .de HS .sp 0.5 .. .\" Major section (numbered) .de SE .nr b +1 1 .nr c 0 1 .ds ST \\$1 .sp 1 .NH 2 \\$1 .sp 1 .. .\" Subsection (numbered) .de SS .nr c +1 1 .NH 3 \\$1 .sp 1 .. .de UU .SH \\$1 .sp 1 .. .\"-------------------- PAGE TRANSITION MACROS USED BY -MS ------ .de PH \"select special running heads .nr d \\$1 .if \\$1=4 .nr j 1 .ds CT \\$2 .. .de PT .AL .pc % .PN \\n% 'sp |\\n(HMu-0.35i .ps 10 .\" .\" nd = 0 means no running head this time, normal next time .if \\nd=0 \{\ .tl '''' \" no running head on initial page transition .nr j 1 0\} .\" .\" nd = 1 is normal case: chapter heading even (left) and section odd(right) .if \\nd=1\{\ .if e .tl '\fB\s+2%\s-2\fR'\\*(CT'\\*(CX~ \\*(CN' \"normal case even page .if o .if \\nb>0 .tl 'SEC.~ \\*(CN.\\nb'\\*(ST'\fB\s+2%\s-2\fR' .if o .if \\nb=0 .tl '''\fB\s+2%\s-2\fR'\} .if o .if \\nb=-999 .tl '\\*(CX~ \\*(CN'\\*(CT'\fB\s+2%\s-2\fR'\} .\" .\" nd = 2 is for PROBLEMS; even normal, odd CHAP. ... PROBLEMS % .if \\nd=2\{\ .if e .tl '\fB\s+2%\s-2\fR'\\*(CT'\\*(CX~ \\*(CN' \"even page PROBLEMS .if o .if \\nd=2 .tl '\\*(CX~ \\*(CN'PROBLEMS'\fB\s+2%\s-2\fR' \} .\" .\" nd = 3 is for index, problem solutions & other cases with same odd even hd .if \\nd=3\{\ .if e .tl '\fB\s+2%\s-2\fR'\\*(CT'' .if o .tl ''\\*(CT'\fB\s+2%\s-2\fR'\} .\" .\" nd = 4 is like nd = 3, except page numbers are lower case roman .if \\nd=4\{\ .nr v \\n% .if e .tl '\fB\s+2\\nv\s-2\fR'\\*(CT'' .if o .tl ''\\*(CT'\fB\s+2\\nv\s-2\fR'\} .\" .\" nd = 5 suppresses running heads like nd=0, only it keeps them suppressed .if \\nd=5 .tl '''' .\" nd = 6 gives page number in right-hand corner only .if \\nd=6 .tl '''%' .if \\nd=0 .nr d 1 0 \" henceforth normal running heads .. .de BT .if \\n%=\\ns\{\ .nr x \\n(HMu+(\\n(BO*\\n(VSu)+2P 'sp |\\nxu .nr v \\n% .ie \\nd=4 .tl ''\fB\s-1\\nv\s0\fP'' .el .tl ''\fB\s-1\\n%\s0\fP''\} .nr j 0 0 .if \\nd=0 .nr d 1 0 .. .\"--------------- CHECK FOR INITIAL PAGE NUMBER --------------- .de PC .if \n%<\\$1\{ .tm You forgot to set the page number. Run aborted. Use troff -n .ex\} .if \n%>\\$2\{ .tm You forgot to set the page number. Run aborted. Use troff -n .ex\} .. .\"-------------------- LISTS OF THINGS ------------------------ .\" Start list .de LI .nr g 0 1 .in +0.25i .nr LL -0.25i .ll -0.25i .ne 3v .HS .. .\" End list .de LX .sp 1 .in -0.25i .nr LL +0.25i .ll +0.25i .LP .. .\" List item .de IT .HS .nr g \\ng+1 1 .ie \\ng<10 .IP \0\\ng. 4 .el .IP \\ng. 4 .. .\"Short unnumbered lines .de UN .HS .. .\"-------------------- END OF CHAPTER EXERCISES --------------- .de PB .nr d 2 0 .if \\nq=1 .PH 6 .ne 1.5i .sp 0.5i .ce 1 .B PROBLEMS .sp 1 .nr p 0 1 .. .de PR .ps 11 .vs 13 .nr PS 11 .nr VS 13.01p .HS .nr p +1 1 .in \w'00. 'u .ti -\w'00. 'u .if \\np>9 \fB\\np.\fR~~\c .if \\np<10 \fB\0\\np.\fR~~\c .. .de AA .sp 3 .if n .nr LL 84m .nr PS \\n(PZ .nr VS \\n(VZu .nr a \\$1 1 .nr b 0 0 .nr p 0 1 .ce 1 .nr x 1 .if '\\$1'A' .nr x 0 .if '\\$1'B' .nr x 0 .if '\\$1'C' .nr x 0 .if \\nq=1 .PH 6 .if \\nx\fBSOLUTIONS TO CHAPTER \\$1 PROBLEMS\fR .if !\\nx\fBSOLUTIONS TO APPENDIX \\$1 PROBLEMS\fR .sp 1v .. .de AN .HS .ps \\n(PZ .vs \\n(VSu .nr PS \\n(PZ .nr VS \\n(VZu .nr p +1 1 .in \w'00. 'u .ti -\w'00. 'u .if \\np>9 \fB\\np.\fR~~\c .if \\np<10 \fB\0\\np.\fR~~\c .. .\"-------------------- BIBLIOGRAPHY --------------------------- .de BB .sp 2 .in 0.25i .. .de BI .ps 10 .vs 12 .sp \\ntu .HS .if n .HS .ti -0.30i .R .. .\"-------------------- QUOTES --------------------------------- .ds OQ `\h'-1p'` .ds CQ '\h'-1p'' .\"-------------------- FIGS.----------------------------------- .de FC 'sp 1v .ps 10 .vs 12 .in +0.5i .ll -0.5i .B .if '\\$1'C' .ce 1 Fig.\|\|\|\\*(CN-\\n+k.~\c .R .. .de BF .KF 'sp 1v .nr TP \\n(.s .nr TV \\n(.v .nr TF \\n(.f .nr r 0 0 .if \\nq=0 .if "\\$1"PAGE" .KP .if \\nq=0 .if "\\$1"PAGE" .nr r 1 0 .if \\nq=0 .if !"\\$1"PAGE" .sp \\$1 .if \\nq=1 .sp 0.5i .FC \\$2 .. .de EF .in -0.5i .ll +0.5i .ps \\n(TP .vs \\n(TV .ft \\n(TF 'if \\nr==0 'sp 30u 'AL .KE .. .de NF .nr x \\nk+1 .ie !'\\$1'X' Fig.~\\*(CN-\\nx\\$1 .el Figure \\*(CN-\\nx\\$2 .. .de PF .ie !'\\$1'X' Fig.~\\*(CN-\\nk\\$1 .el Figure \\*(CN-\\nk\\$2 .. .\"-------------------- MULTIPLE BLANK PAGES ------------------- .de MP .if \\$1 \{\ .KF .KP .KE .MP \\$1-1 .if \\$1<2 .nr k +1 1 \} .. .\"-------------------- TABLE OF CONTENTS ---------------------- .de XT .if t .ta 0.4i 0.8i 0.9i \\n(LLuR .if n .ta 0.3i 1.0i 1.1i 5.0iR .ps 11 .vs 13 .nr a \\$1 0 .nr b 0 1 .nr c 0 1 .sp 0.40i .ne 0.3i .B \\s18\\$1\\s12 \\$2 \\$3\\fR\\s11 .br .if !'\\$4'' \\fB\\$4\\fR .R .sp 0.5v .. .de XE .nr b +1 1 .nr c 0 1 .HS \\na.\\nb \\$1 \\$2 .. .de XS .nr c +1 1 \\na.\\nb.\\nc \\$1 \\$2 .. .\"------------------- INDEX ----------------------------------- .de IL .nr PS \\n(PZ-2 .nr VS 12.01p .LP .nf .na .sp 2v .ne 2 \fB\s+4\\$1\\s0\fR .sp 1v .. .\"------------------- NEW .B MACRO ---------------------------- .rm B .de B .nr PQ \\n(.f .ft 3 .if !"\\$1"" \&\\$1\\f\\n(PQ\\$2 .. .\"--------------------- FIXES NEEDED TO -MS ------------------- .\" Remove .if n .ul 1000 from .NH .\" Remove .if n .ul 1000 from .SH .\" Fix to allow letters as chapter "numbers" .\" .\" Here is the b3mac file .nr Cs 10 .fp 5 H .ds fm \(fm .ds em \(em .de F \\fI\\$1\\fR\\$2 .. .de CC .HS ~~~~~\\s\\n(Cs\\f5\\$1\\fP\\s0 .HS .LP .. .de Cx ~~~~~\\s\\n(Cs\\f5\\$1\\fP\\s0\\$2 .. .de Cb .in +0.25i \\s\\n(Cs .HS \\f5 .. .de Ce .HS \\fR .nr PS \\n(PZ .nr VS \\n(VZ .LP .in -0.25i .. .de SY \\$3\s-2\\$1\s+2\\$2 .. .de SM \\$3\s-1\\$1\s+1\\$2 .. .de FN \&\\fI\\$1\\fR\\$2 .. .de DI \&\\fI\\$1\\fR\\$2 .. .de FI \&\\fI\\$1\\fR\\$2 .. .de LN .nr x \\$1+\\$2 \\$4line .L4 \\nx \\$3 .. .de LS .nr x \\$1+\\$2 .nr y \\$1+\\$3 .nr z \\nx+1 \\$5lines .L4 \\nx .ie \\ny=\\nz and .el to .L4 \\ny \\$4 .. .ds SQ \(fm\h'-0.05c'\(fm .de L4 .ie \\$1<10 000\\$1\\$2 .el .ie \\$1<100 00\\$1\\$2 .el .ie \\$1<1000 0\\$1\\$2 .el \\$1\\$2 .. .de KW \f5\\$1\\$2\fR .. .ds M0 MINIX .ds M1 \\s-1MINIX\\s+1 .ds M2 \\s-2MINIX\\s+2 .ds M9 \\s-1MINIX\\s+1 .ds m0 minix .de MX \s-2MINIX\s+2\\$1 .. .de Ux \s-2UNIX\s+2\\$1 .. .tr _\(ru .de UX \s-2UNIX\s+2\\$1 .. .ds Mx \\s-1MINIX\\s0 .ds Mp \\s-1MINIX-PC\\s0 .ds Ms \\s-1MINIX-ST\\s0 .de CW \f5 .. .de Bu .HS .IP "\0\(bu" 4 .. .de CD .ne 2 .if t .ta 0.9i 1.15i 2.75i 3.25i 3.75i .if n .ta 11m 15m 40m .nr x 0 0 .nr y 0 0 .nr z 0 0 .if n #\\$1 .if n .br \\fBCommand:\& \\$1\\fR .br .. .de SX .if \\nx<=0 \\fBSyntax:\& \\$1 .if \\nx>0 \& \\fB\\$1 .nr x 1 1 .br .. .de FL .if \\ny<=0 \\fBFlags:\& \\fB\\$1 \\fR\\$2 .if \\ny>0 \& \\fB\\$1 \\fR\\$2 .nr y 1 1 .br .. .de EX .br .nf .if \\nz<=0 \\fB\&Examples: \\fR\\$1 \\fR# \\$2 .if \\nz>0 \& \\fR\\$1 \\fR# \\$2 .nr z 1 1 .br .. .de EY .br .nf .if \\nz<=0 \\fB\&Example: \\fR\\$1 \\fR# \\$2 .if \\nz>0 \& \\fR\\$1 \\fR# \\$2 .nr z 1 1 .br .. ...yacc.1acd.1ash.1bc.1lp.1cawf.1 cdplay.1 eject.1 flex.1 flexdoc.1 format.1host.1hostaddr.1install.1isodir.1isoinfo.1isoread.1makewhatis.1man.1mixer.1mt.1playwave.1recwave.1remsync.1bsfilt.1vol.1whatis.1yap.1synctree.1 M.1!anm.1"ar.1#ascii.1$asize.1%at.1&banner.1'basename.1(btoa.1)cal.1*calendar.1+cat.1,cc.1-cdiff.1.cgrep.1/chgrp.10chmem.11chmod.12cksum.13clr.14cmp.15comm.16compress.17cp.18crc.19ctags.1:cut.1;date.1<dd.1=df.1>dhrystone.1?diff.1@diskcheck.1A.\" %W% %R% (Berkeley) %E% .\" .TH YACC 1 "July 15, 1990" .UC 6 .SH NAME yacc \- an LALR(1) parser generator .SH SYNOPSIS .B yacc [ -dlrtv ] [ -b .I file_prefix .B ] [ -p .I symbol_prefix .B ] .I filename .SH DESCRIPTION .I Yacc reads the grammar specification in the file .I filename and generates an LR(1) parser for it. The parsers consist of a set of LALR(1) parsing tables and a driver routine written in the C programming language. .I Yacc normally writes the parse tables and the driver routine to the file .IR y.tab.c. .PP The following options are available: .RS .TP \fB-b \fIfile_prefix\fR The .B -b option changes the prefix prepended to the output file names to the string denoted by .IR file_prefix. The default prefix is the character .IR y. .TP .B -d The \fB-d\fR option causes the header file .IR y.tab.h to be written. .TP .B -l If the .B -l option is not specified, .I yacc will insert #line directives in the generated code. The #line directives let the C compiler relate errors in the generated code to the user's original code. If the \fB-l\fR option is specified, .I yacc will not insert the #line directives. \&#line directives specified by the user will be retained. .TP \fB-p \fIsymbol_prefix\fR The .B -p option changes the prefix prepended to yacc-generated symbols to the string denoted by .IR symbol_prefix. The default prefix is the string .IR yy. .TP .B -r The .B -r option causes .I yacc to produce separate files for code and tables. The code file is named .IR y.code.c, and the tables file is named .IR y.tab.c. .TP .B -t The .B -t option changes the preprocessor directives generated by .I yacc so that debugging statements will be incorporated in the compiled code. .TP .B -v The .B -v option causes a human-readable description of the generated parser to be written to the file .IR y.output. .RE .PP If the environment variable TMPDIR is set, the string denoted by TMPDIR will be used as the name of the directory where the temporary files are created. .SH FILES .IR y.code.c .br .IR y.tab.c .br .IR y.tab.h .br .IR y.output .br .IR /tmp/yacc.aXXXXXX .br .IR /tmp/yacc.tXXXXXX .br .IR /tmp/yacc.uXXXXXX .SH DIAGNOSTICS If there are rules that are never reduced, the number of such rules is reported on standard error. If there are any LALR(1) conflicts, the number of conflicts is reported on standard error. .TH ACD 1 .SH NAME acd \- a compiler driver .SH SYNOPSIS .B acd \fB\-v\fR[\fIn\fR] \fB\-vn\fR[\fIn\fR] .BI \-name " name" .BI \-descr " descr" .BI \-T " dir" .RI [ arg " ...]" .SH DESCRIPTION .de SP .if t .sp 0.4 .if n .sp .. .B Acd is a compiler driver, a program that calls the several passes that are needed to compile a source file. It keeps track of all the temporary files used between the passes. It also defines the interface of the compiler, the options the user gets to see. .PP This text only describes .B acd itself, it says nothing about the different options the C-compiler accepts. (It has nothing to do with any language, other than being a tool to give a compiler a user interface.) .SH OPTIONS .B Acd itself takes five options: .TP \fB\-v\fR[\fIn\fR] Sets the diagnostic level to .I n (by default .BR 2 ). The higher .I n is, the more output .B acd generates: .B \-v0 does not produce any output. .B \-v1 prints the basenames of the programs called. .B \-v2 prints names and arguments of the programs called. .B \-v3 shows the commands executed from the description file too. .B \-v4 shows the program read from the description file too. Levels 3 and 4 use backspace overstrikes that look good when viewing the output with a smart pager. .TP \fB\-vn\fR[\fIn\fR] Like .B \-v except that no command is executed. The driver is just play-acting. .TP .BI \-name " name" .B Acd is normally linked to the name the compiler is to be called with by the user. The basename of this, say .BR cc , is the call name of the driver. It plays a role in selecting the proper description file. With the .B \-name option one can change this. .B Acd \-name cc has the same effect as calling the program as .BR cc . .TP .BI \-descr " descr" Allows one to choose the pass description file of the driver. By default .I descr is the same as .IR name , the call name of the program. If .I descr doesn't start with .BR / , .BR ./ , or .BR ../ then the file .BI /usr/lib/ descr /descr will be used for the description, otherwise .I descr itself. Thus .B cc \-descr newcc calls the C-compiler with a different description file without changing the call name. Finally, if .I descr is \fB"\-"\fP, standard input is read. (The default lib directory .BR /usr/lib , may be changed to .I dir at compile time by \fB\-DLIB=\e"\fP\fIdir\fP\fB\e"\fP. The default .I descr may be set with \fB\-DDESCR=\e"\fP\fIdescr\fP\fB\e"\fP for simple installations on a system without symlinks.) .TP .BI \-T " dir" Temporary files are made in .B /tmp by default, which may be overridden by the environment variable .BR TMPDIR , which may be overridden by the .B \-T option. .SH "THE DESCRIPTION FILE" The description file is a program interpreted by the driver. It has variables, lists of files, argument parsing commands, and rules for transforming input files. .SS Syntax There are four simple objects: .PP .RS Words, Substitutions, Letters, and Operators. .RE .PP And there are two ways to group objects: .PP .RS Lists, forming sequences of anything but letters, .SP Strings, forming sequences of anything but Words and Operators. .RE .PP Each object has the following syntax: .IP Words They are sequences of characters, like .BR cc , .BR \-I/usr/include , .BR /lib/cpp . No whitespace and no special characters. The backslash character .RB ( \e ) may be used to make special characters common, except whitespace. A backslash followed by whitespace is completely removed from the input. The sequence .B \en is changed to a newline. .IP Substitutions A substitution (henceforth called 'subst') is formed with a .BR $ , e.g. .BR $opt , .BR $PATH , .BR ${lib} , .BR $\(** . The variable name after the .B $ is made of letters, digits and underscores, or any sequence of characters between parentheses or braces, or a single other character. A subst indicates that the value of the named variable must be substituted in the list or string when fully evaluated. .IP Letters Letters are the single characters that would make up a word. .IP Operators The characters .BR = , .BR + , .BR \- , .BR \(** , .BR < , and .B > are the operators. The first four must be surrounded by whitespace if they are to be seen as special (they are often used in arguments). The last two are always special. .IP Lists One line of objects in the description file forms a list. Put parentheses around it and you have a sublist. The values of variables are lists. .IP Strings Anything that is not yet a word is a string. All it needs is that the substs in it are evaluated, e.g. .BR $LIBPATH/lib$key.a . A single subst doesn't make a string, it expands to a list. You need at least one letter or other subst next to it. Strings (and words) may also be formed by enclosing them in double quotes. Only .B \e and .B $ keep their special meaning within quotes. .SS Evaluation One thing has to be carefully understood: Substitutions are delayed until the last possible moment, and description files make heavy use of this. Only if a subst is tainted, either because its variable is declared local, or because a subst in its variable's value is tainted, is it immediately substituted. So if a list is assigned to a variable then this list is only checked for tainted substs. Those substs are replaced by the value of their variable. This is called partial evaluation. .PP Full evaluation expands all substs, the list is flattened, i.e. all parentheses are removed from sublists. .PP Implosive evaluation is the last that has to be done to a list before it can be used as a command to execute. The substs within a string have been evaluated to lists after full expansion, but a string must be turned into a single word, not a list. To make this happen, a string is first exploded to all possible combinations of words choosing one member of the lists within the string. These words are tried one by one to see if they exist as a file. The first one that exists is taken, if none exists than the first choice is used. As an example, assume .B LIBPATH equals .BR "(/lib /usr/lib)" , .B key is .B (c) and .B key happens to be local. Then we have: .PP .RS \fB"$LIBPATH/lib$key.a"\fP .RE .PP before evaluation, .PP .RS \fB"$LIBPATH/lib(c).a"\fP .RE .PP after partial evaluation, .PP .RS \fB"(/lib/libc.a /usr/lib/libc.a)"\fP .RE .PP after full evaluation, and finally .PP .RS .B /usr/lib/libc.a .RE .PP after implosion, if the file exists. .SS Operators The operators modify the way evaluation is done and perform a special function on a list: .TP .B \(** Forces full evaluation on all the list elements following it. Use it to force substitution of the current value of a variable. This is the only operator that forces immediate evaluation. .TP .B + When a .B + exists in a list that is fully evaluated, then all the elements before the .B + are imploded and all elements after the .B + are imploded and added to the list if they are not already in the list. So this operator can be used either for set addition, or to force implosive expansion within a sublist. .TP .B \- Like .BR + , except that elements after the .B \- are removed from the list. .PP The set operators can be used to gather options that exclude each other or for their side effect of implosive expansion. You may want to write: .PP .RS \fBcpp \-I$LIBPATH/include\fP .RE .PP to call cpp with an extra include directory, but .B $LIBPATH is expanded using a filename starting with .B \-I so this won't work. Given that any problem in Computer Science can be solved with an extra level of indirection, use this instead: .PP .RS .ft B cpp \-I$INCLUDE .br INCLUDE = $LIBPATH/include + .ft P .RE .SS "Special Variables" There are three special variables used in a description file: .BR $\(** , .BR $< , and .BR $> . These variables are always local and mostly read-only. They will be explained later. .SS "A Program" The lists in a description file form a program that is executed from the first to the last list. The first word in a list may be recognized as a builtin command (only if the first list element is indeed simply a word.) If it is not a builtin command then the list is imploded and used as a \s-2UNIX\s+2 command with arguments. .PP IndentatiUWXYZ[\]^_`abcdeon (by tabs or spaces) is not just makeup for a program, but are used to group lines together. Some builtin commands need a body. These bodies are simply lines at a deeper indentation. .PP Empty lines are not ignored either, they have the same indentation level as the line before it. Comments (starting with a .B # and ending at end of line) have an indentation of their own and can be used as null commands. .PP .B Acd will complain about unexpected indentation shifts and empty bodies. Commands can share the same body by placing them at the same indentation level before the indented body. They are then "guards" to the same body, and are tried one by one until one succeeds, after which the body is executed. .PP Semicolons may be used to separate commands instead of newlines. The commands are then all at the indentation level of the first. .SS "Execution phases" The driver runs in three phases: Initialization, Argument scanning, and Compilation. Not all commands work in all phases. This is further explained below. .SS "The Commands" The commands accept arguments that are usually generic expressions that implode to a word or a list of words. When .I var is specified, then a single word or subst needs to be given, so an assignment can be either .I name .B = .IR value , or .BI $ name .B = .IR value . .TP .IB "var " = " expr ..." The partially evaluated list of expressions is assigned to .IR var . During the evaluation is .I var marked as local, and after the assignment set from undefined to defined. .TP .BI unset " var" .I Var is set to null and is marked as undefined. .TP .BI import " var" If .I var is defined in the environment of .B acd then it is assigned to .IR var . The environment variable is split into words at whitespace and colons. Empty space between two colons .RB ( :: ) is changed to a dot. .TP .BI mktemp " var " [ suffix ] Assigns to .I var the name of a new temporary file, usually something like /tmp/acd12345x. If .I suffix is present then it will be added to the temporary file's name. (Use it because some programs require it, or just because it looks good.) .B Acd remembers this file, and will delete it as soon as you stop referencing it. .TP .BI temporary " word" Mark the file named by .I word as a temporary file. You have to make sure that the name is stored in some list in imploded form, and not just temporarily created when .I word is evaluated, because then it will be immediately removed and forgotten. .TP .BI stop " suffix" Sets the target suffix for the compilation phase. Something like .B stop .o means that the source files must be compiled to object files. At least one .B stop command must be executed before the compilation phase begins. It may not be changed during the compilation phase. (Note: There is no restriction on .IR suffix , it need not start with a dot.) .TP .BI treat " file suffix" Marks the file as having the given suffix for the compile phase. Useful for sending a .B \-l option directly to the loader by treating it as having the .B .a suffix. .TP .BI numeric " arg" Checks if .I arg is a number. If not then .B acd will exit with a nice error message. .TP .BI error " expr ..." Makes the driver print the error message .I "expr ..." and exit. .TP .BI if " expr " = " expr" .B If tests if the two expressions are equal using set comparison, i.e. each expression should contain all the words in the other expression. If the test succeeds then the if-body is executed. .TP .BI ifdef " var" Executes the ifdef-body if .I var is defined. .TP .BI ifndef " var" Executes the ifndef-body if .I var is undefined. .TP .BI iftemp " arg" Executes the iftemp-body if .I arg is a temporary file. Use it when a command has the same file as input and output and you don't want to clobber the source file: .SP .RS .nf .ft B transform .o .o iftemp $\(** $> = $\(** else cp $\(** $> optimize $> .ft P .fi .RE .TP .BI ifhash " arg" Executes the ifhash-body if .I arg is an existing file with a '\fB#\fP' as the very first character. This usually indicates that the file must be pre-processed: .SP .RS .nf .ft B transform .s .o ifhash $\(** mktemp ASM .s $CPP $\(** > $ASM else ASM = $\(** $AS \-o $> $ASM unset ASM .ft P .fi .RE .TP .B else Executes the else-body if the last executed .BR if , .BR ifdef , .BR ifndef , .BR iftemp , or .B ifhash was unsuccessful. Note that .B else need not immediately follow an if, but you are advised not to make use of this. It is a "feature" that may not last. .TP .BI apply " suffix1 suffix2" Executed inside a transform rule body to transform the input file according to another transform rule that has the given input and output suffixes. The file under .B $\(** will be replaced by the new file. So if there is a .B .c .i preprocessor rule then the example of .B ifhash can be replaced by: .SP .RS .nf .ft B transform .s .o ifhash $\(** apply .c .i $AS \-o $> $* .ft P .fi .RE .TP .BI include " descr" Reads another description file and replaces the .B include with it. Execution continues with the first list in the new program. The search for .I descr is the same as used for the .B \-descr option. Use .B include to switch in different front ends or back ends, or to call a shared description file with a different initialization. Note that .I descr is only evaluated the first time the .B include is called. After that the .B include has been replaced with the included program, so changing its argument won't get you a different file. .TP .BI arg " string ..." .B Arg may be executed in the initialization and scanning phase to post an argument scanning rule, that's all the command itself does. Like an .B if that fails it allows more guards to share the same body. .TP .BI transform " suffix1 suffix2" .BR Transform , like .BR arg , only posts a rule to transform a file with the suffix .I suffix1 into a file with the suffix .IR suffix2 . .TP .BI prefer " suffix1 suffix2" Tells that the transformation rule from .I suffix1 to .I suffix2 is to be preferred when looking for a transformation path to the stop suffix. Normally the shortest route to the stop suffix is used. .B Prefer is ignored on a .BR combine , because the special nature of combines does not allow ambiguity. .SP The two suffixes on a .B transform or .B prefer may be the same, giving a rule that is only executed when preferred. .TP .BI combine " suffix-list suffix" .B Combine is like .B transform except that it allows a list of input suffixes to match several types of input files that must be combined into one. .TP .B scan The scanning phase may be run early from the initialization phase with the .B scan command. Use it if you need to make choices based on the arguments before posting the transformation rules. After running this, .B scan and .B arg become no-ops. .TP .B compile Move on to the compilation phase early, so that you have a chance to run a few extra commands before exiting. This command implies a .BR scan . .PP Any other command is seen as a \s-2UNIX\s+2 command. This is where the .B < and .B > operators come into play. They redirect standard input and standard output to the file mentioned after them, just like the shell. .B Acd will stop with an error if the command is not successful. .SS The Initialization Phase The driver starts by executing the program once from top to bottom to initialize variables and post argument scanning and transformation rules. .SS The Scanning Phase In this phase the driver makes a pass over the command line arguments to process options. Each .B arg rule is tried one by one in the order they were posted against the front of the argument list. If a match is made then the matched arguments are removed from the argument list and the arg-body is executed. If no match can be made then the first argument is moved to the list of files waiting to be transformed and the scan is restarted. .PP The match is done as follows: Each of the strings after .B arg must match one argument at the front of the argument list. A character in a string must match a character in an argument word, a subst in a string may match 1 to all remaining characters in the argument, preferring the shortest possible match. The hyphen in a argument starting with a hyphen cannot be matched by a subst. Therefore: .PP .RS .B arg \-i .RE .PP matches only the argument .BR \-i . .PP .RS .B arg \-O$n .RE .PP matches any argument that starts with .B \-O and is at least three characters long. Lastly, .PP .RS .B arg \-o $out .RE .PP matches .B \-o and the argument following it, unless that argument starts with a hyphen. .PP The variable .B $\(** is set to all the matched arguments before the arg-body is executed. All the substs in the arg strings are set to the characters they match. The variable .B $> is set to null. All the values of the variables are saved and the variables marked local. All variables except .B $> are marked read-only. After the arg-body is executed is the value of .B $> concatenated to the file list. This allows one to stuff new files into the transformation phase. These added names are not evaluated until the start of the next phase. .SS The Compilation Phase The files gathered in the file list in the scanning phase are now transformed one by one using the transformation rules. The shortest, or preferred route is computed for each file all the way to the stop suffix. Each file is transformed until it lands at the stop suffix, or at a combine rule. After a while all files are either fully transformed or at a combine rule. .PP The driver chooses a combine rule that is not on a path from another combine rule and executes it. The file that results is then transformed until it again lands at a combine rule or the stop suffix. This continues until all files are at the stop suffix and the program exits. .PP The paths through transform rules may be ambiguous and have cycles, they will be resolved. But paths through combines must be unambiguous, because of the many paths from the different files that meet there. A description file will usually have only one combine rule for the loader. However if you do have a combine conflict then put a no-op transform rule in front of one to resolve the problem. .PP If a file matches a long and a short suffix then the long suffix is preferred. By putting a null input suffix (\fB""\fP) in a rule one can match any file that no other rule matches. You can send unknown files to the loader this way. .PP The variable .B $\(** is set to the file to be transformed or the files to be combined before the transform or combine-body is executed. .B $> is set to the output file name, it may again be modified. .B $< is set to the original name of the first file of .B $\(** with the leading directories and the suffix removed. .B $\(** will be made up of temporary files after the first rule. .B $> will be another temporary file or the name of the target file .RB ( $< plus the stop suffix), if the stop suffix is reached. .PP .B $> is passed to the next rule; it is imploded and checked to be a single word. This driver does not store intermediate object files in the current directory like most other compilers, but keeps them in .B /tmp too. (Who knows if the current directory can have files created in?) As an example, here is how you can express the "normal" method: .PP .RS .nf .ft B transform .s .o if $> = $<.o # Stop suffix is .o else $> = $<.o temporary $> $AS \-o $> $\(** .ft P .fi .RE .PP Note that .B temporary is not called if the target is already the object file, or you would lose the intended result! .B $> is known to be a word, because .B $< is local. (Any string whose substs are all expanded changes to a word.) .SS "Predefined Variables" The driver has three variables predefined: .BR PROGRAM , set to the call name of the driver, .BR VERSION , the driver's version number, and .BR ARCH , set to the name of the default output architecture. The latter is optional, and only defined if .B acd was compiled with \fB\-DARCH=\e"\fP\fIarch-name\fP\fB\e"\fP. .SH EXAMPLE As an example a description file for a C compiler is given. It has a front end (ccom), an intermediate code optimizer (opt), a code generator (cg), an assembler (as), and a loader (ld). The compiler can pre-process, but there is also a separate cpp. If the .B \-D and options like it are changed to look like .B \-o then this example is even as required by \s-2POSIX\s+2. .RS .nf # The compiler support search path. C = /lib /usr/lib /usr/local/lib # Compiler passes. CPP = $C/cpp $CPP_F CCOM = $C/ccom $CPP_F OPT = $C/opt CG = $C/cg AS = $C/as LD = $C/ld # Predefined symbols. CPP_F = \-D__EXAMPLE_CC__ # Library path. LIBPATH = $USERLIBPATH $C # Default transformation target. stop .out # Preprocessor directives. arg \-D$name arg \-U$name arg \-I$dir CPP_F = $CPP_F $\(** # Stop suffix. arg \-c stop .o arg \-E stop .E # Optimization. arg \-O prefer .m .m OPT = $OPT -O1 arg \-O$n numeric $n prefer .m .m OPT = $OPT $\(** # Add debug info to the executable. arg \-g CCOM = $CCOM -g # Add directories to the library path. arg \-L$dir USERLIBPATH = $USERLIBPATH $dir # \-llib must be searched in $LIBPATH later. arg \-l$lib $> = $LIBPATH/lib$lib.a # Change output file. arg \-o$out arg \-o $out OUT = $out # Complain about a missing argument. arg \-o error "argument expected after '$\(**'" # Any other option (like \-s) are for the loader. arg \-$any LD = $LD $\(** # Preprocess C-source. transform .c .i $CPP $\(** > $> # Preprocess C-source and send it to standard output or $OUT. transform .c .E ifndef OUT $CPP $\(** else $CPP $\(** > $OUT # Compile C-source to intermediate code. transform .c .m transform .i .m $CCOM $\(** $> # Intermediate code optimizer. transform .m .m $OPT $\(** > $> # Intermediate to assembly. transform .m .s $CG $\(** > $> # Assembler to object code. transform .s .o if $> = $<.o ifdef OUT $> = $OUT $AS \-o $> $\(** # Combine object files and libraries to an executable. combine (.o .a) .out ifndef OUT OUT = a.out $LD \-o $OUT $C/crtso.o $\(** $C/libc.a .fi .RE .SH FILES .TP 25n .RI /usr/lib/ descr /descr \- compiler driver description file. .SH "SEE ALSO" .BR cc (1). .SH ACKNOWLEDGEMENTS Even though the end result doesn't look much like it, many ideas were nevertheless derived from the ACK compiler driver by Ed Keizer. .SH BUGS \s-2POSIX\s+2 requires that if compiling one source file to an object file fails then the compiler should continue with the next source file. There is no way .B acd can do this, it always stops after error. It doesn't even know what an object file is! (The requirement is stupid anyhow.) .PP If you don't think that tabs are 8 spaces wide, then don't mix them with spaces for indentation. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .\" Copyright (c) 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Kenneth Almquist. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)sh.1 5.1 (Berkeley) 3/7/91 .\" .TH SH 1 "March 7, 1991" .UC 7 .de h \" subheading .sp .ti -0.3i .B "\\$1" .PP .. .de d \" begin display .sp .in +4 .nf .. .de e \" end display .in -4 .fi .sp .. .de c \" command, etc. .br .HP 3 \fB\\$1\fR .br .. .de b \" begin builtin command .HP 3 .B \\$1 .. .SH NAME ash, command, getopts, hash, jobs, local, return, setvar, unset \- a shell .SH SYNOPSIS .B ash [ .B -efIijnsxz ] [ .B +efIijnsxz ] [ .B -c .I command ] [ .I arg ] ... .SH COPYRIGHT Copyright 1989 by Kenneth Almquist. .SH DESCRIPTION .I Ash is a version of .I sh with features similar to those of the System V shell. This manual page lists all the features of .I ash but concentrates on the ones not in other shells. .h "Invocation" If the .B -c options is given, then the shell executes the specified shell command. The .B -s flag cause the shell to read commands from the standard input (after executing any command specified with the .B -c option. If neither the .B -s or .B -c options are set, then the first .I arg is taken as the name of a file to read commands from. If this is impossible because there are no arguments following the options, then .I ash will set the .B -s flag and will read commands from the standard input. .PP The shell sets the initial value of the positional parameters from the .IR arg s remaining after any .I arg used as the name of a file of commands is deleted. .PP The flags (other than .BR -c ) are set by preceding them with ``-'' and cleared by preceding them with ``+''; see the .I set builtin command for a list of flags. If no value is specified for the .B -i flag, the .B -s flag is set, and the standard input and output of the shell are connected to terminals, then the .B -i flag will be set. If no value is specified for the .B -j flag, then the .B -j flag will be set if the .B -i flag is set. .PP When the shell is invoked with the .B -c option, it is good practice to include the .I -i flag if the command was entered interactively by a user. For compatibility with the System V shell, the .I -i option should come after the .B -c option. .PP If the first character of argument zero to the shell is ``-'', the shell is assumed to be a login shell, and the files .B /etc/profile and .B .profile are read if they exist. If the environment variable SHINIT is set on entry to the shell, the commands in SHINIT are normally parsed and executed. SHINIT is not examined if the shell is a login shell, or if it the shell is running a shell procedure. (A shell is considered to be running a shell procedure if neither the .B -s nor the .B -c options are set.) .h "Control Structures" A .I list is a sequence of zero or more commands separated by newlines, semicolons, or ampersands, and optionally terminated by one of these three characters. (This differs from the System V shell, which requires a list to contain at least one command in most cases.) The commands in a list are executed in the order they are written. If command is followed by an ampersand, the shell starts the command and immediately proceed onto the next command; otherwise it waits for the command to terminate before proceeding to the next one. .PP ``&&'' and ``||'' are binary operators. ``&&'' executes the first command, and then executes the second command iff the exit status of the first command is zero. ``||'' is similar, but executes the second command iff the exit status of the first command is nonzero. ``&&'' and ``||'' both have the same priority. .PP The ``|'' operator is a binary operator which feeds the standard output of the first command into the standard input of the second command. The exit status of the ``|'' operator is the exit status of the second command. ``|'' has a higher priority than ``||'' or ``&&''. .PP An .I if command looks like .d \fBif\fR list \fBthen\fR list .ti -\w'[ 'u [ \fBelif\fR list \fBthen\fR list ] ... .ti -\w'[ 'u [ \fBelse\fR list ] \fBfi\fR .e .PP A .I while command looks like .d \fBwhile\fR list \fBdo\fR list \fBdone\fR .e The two lists are executed repeatedly while the exit status of the first list is zero. The .I until command is similar, but has the word .B until in place of .B while repeats until the exit status of the first list is zero. .PP The .I for command looks like .d \fBfor\fR variable \fBin\fR word... \fBdo\fR list \fBdone\fR .e The words are expanded, and then the list is executed repeatedly with the variable set to each word in turn. .B do and .B done may be replaced with ``{'' and ``}''. .PP The .I break and .I continue commands look like .d \fBbreak\fR [ num ] \fBcontinue\fR [ num ] .e .I Break terminates the .I num innermost .I for or .I while loops. .I Continue continues with the next iteration of the .IRnum'th innermost loop. These are implemented as builtin commands. .PP The .I case command looks like .d \fBcase\fR word \fBin\fR pattern\fB)\fR list \fB;;\fR \&... \fBesac\fR .e The pattern can actually be one or more patterns (see .I Patterns below), separated by ``|'' characters. .PP Commands may be grouped by writing either .d \fB(\fRlist\fB)\fR .e or .d \fB{\fR list; \fB}\fR .e The first of these executes the commands in a subshell. .PP A function definition looks like .d name \fB( )\fR command .e A function definition is an executable statement; when executed it installs a function named .B name and returns an exit status of zero. The command is normally a list enclosed between ``{'' and ``}''. .PP Variables may be declared to be local to a function by using a .I local command. This should appear as the first staement of a function, and looks like .d \fBlocal\fR [ variable | \fB-\fR ] ... .e .I Local is implemented as a builtin command. .PP When a variable is made local, it inherits the initial value and exported and readonly flags from the variable with the same name in the surrounding scope, if there is one. Otherwise, the variable is initially unset. .I Ash uses dynamic scoping, so that if you make the variable .B x local to function .IR f , which then calls function .IR g , references to the variable .B x made inside .I g will refer to the variable .B x declared inside .IR f , not to the global variable named .BR x . .PP The only special parameter than can be made local is ``\fB-\fR'mopqrstuvwxyz{|}~'. Making ``\fB-\fR'' local any shell options that are changed via the .I set command inside the function to be restored to their original values when the function returns. .PP The .I return command looks like .d \fBreturn\fR [ exitstatus ] .e It terminates the currently executing function. .I Return is implemented as a builtin command. .h "Simple Commands" A simple command is a sequence of words. The execution of a simple command proceeds as follows. First, the leading words of the form ``name=value'' are stripped off and assigned to the environment of the command. Second, the words are expanded. Third, the first remaining word is taken as the command name that command is located. Fourth, any redirections are performed. Fifth, the command is executed. We look at these operations in reverse order. .PP The execution of the command varies with the type of command. There are three types of commands: shell functions, builtin commands, and normal programs. .PP When a shell function is executed, all of the shell positional parameters (except $0, which remains unchanged) are set to the parameters to the shell function. The variables which are explicitly placed in the environment of the command (by placing assignments to them before the function name) are made local to the function and are set to values given. Then the command given in the function definition is executed. The positional parameters are restored to their original values when the command completes. .PP Shell builtins are executed internally to the shell, without spawning a new process. .PP When a normal program is executed, the shell runs the program, passing the parameters and the environment to the program. If the program is a shell procedure, the shell will interpret the program in a subshell. The shell will reinitialize itself in this case, so that the effect will be as if a new shell had been invoked to handle the shell procedure, except that the location of commands located in the parent shell will be remembered by the child. If the program is a file beginning with ``#!'', the remainder of the first line specifies an interpreter for the program. The shell (or the operating system, under Berkeley UNIX) will run the interpreter in this case. The arguments to the interpreter will consist of any arguments given on the first line of the program, followed by the name of the program, followed by the arguments passed to the program. .h "Redirection" Input/output redirections can be intermixed with the words in a simple command and can be placed following any of the other commands. When redirection occurs, the shell saves the old values of the file descriptors and restores them when the command completes. The ``<'', ``>'', and ``>>'' redirections open a file for input, output, and appending, respectively. The ``<&digit'' and ``>&digit'' makes the input or output a duplicate of the file descriptor numbered by the digit. If a minus sign is used in place of a digit, the standard input or standard output are closed. .PP The ``<<\ word'' redirection takes input from a .I here document. As the shell encounters ``<<'' redirections, it collects them. The next time it encounters an unescaped newline, it reads the documents in turn. The word following the ``<<'' specifies the contents of the line that terminates the document. If none of the quoting methods ('', "", or \e) are used to enter the word, then the document is treated like a word inside double quotes: ``$'' and backquote are expanded and backslash can be used to escape these and to continue long lines. The word cannot contain any variable or command substitutions, and its length (after quoting) must be in the range of 1 to 79 characters. If ``<<-'' is used in place of ``<<'', then leading tabs are deleted from the lines of the document. (This is to allow you do indent shell procedures containing here documents in a natural fashion.) .PP Any of the preceding redirection operators may be preceded by a single digit specifying the file descriptor to be redirected. There cannot be any white space between the digit and the redirection operator. .h "Path Search" When locating a command, the shell first looks to see if it has a shell function by that name. Then, if PATH does not contain an entry for "%builtin", it looks for a builtin command by that name. Finally, it searches each entry in PATH in turn for the command. .PP The value of the PATH variable should be a series of entries separated by colons. Each entry consists of a directory name, or a directory name followed by a flag beginning with a percent sign. The current directory should be indicated by an empty directory name. .PP If no percent sign is present, then the entry causes the shell to search for the command in the specified directory. If the flag is ``%builtin'' then the list of shell builtin commands is searched. If the flag is ``%func'' then the directory is searched for a file which is read as input to the shell. This file should define a function whose name is the name of the command being searched for. .PP Command names containing a slash are simply executed without performing any of the above searches. .h "The Environment" The environment of a command is a set of name/value pairs. When the shell is invoked, it reads these names and values, sets the shell variables with these names to the corresponding values, and marks the variables as exported. The .I export command can be used to mark additional variables as exported. .PP The environment of a command is constructed by constructing name/value pairs from all the exported shell variables, and then modifying this set by the assignments which precede the command, if any. .h "Expansion" The process of evaluating words when a shell procedure is executed is called .IR expansion . Expansion consists of four steps: variable substitution, command substitution, word splitting, and file name generation. If a word is the expression following the word .B case in a case statement, the file name which follows a redirection symbol, or an assignment to the environment of a command, then the word cannot be split into multiple words. In these cases, the last two steps of the expansion process are omitted. .h "Variable Substitution" To be written. .h "Command Substitution" .I Ash accepts two syntaxes for command substitution: .d `\fIlist\fR` .e and .d $(\fIlist\fR) .e Either of these may be included in a word. During the command substitution process, the command (syntactly a .IR list ) will be executed and anything that the command writes to the standard output will be captured by the shell. The final newline (if any) of the output will be deleted; the rest of the output will be substituted for the command in the word. .h "Word Splitting" When the value of a variable or the output of a command is substituted, the resulting text is subject to word splitting, unless the dollar sign introducing the variable or backquotes containing the text were enclosed in double quotes. In addition, ``$@'' is subject to a special type of splitting, even in the presence of double quotes. .PP Ash uses two different splitting algorithms. The normal approach, which is intended for splitting text separated by which space, is used if the first character of the shell variable IFS is a space. Otherwise an alternative experimental algorithm, which is useful for splitting (possibly empty) fields separated by a separator character, is used. .PP When performing splitting, the shell scans the replacement text looking for a character (when IFS does not begin with a space) or a sequence of characters (when IFS does begin with a space), deletes the character or sequence of characters, and spits the word into two strings at that point. When IFS begins with a space, the shell deletes either of the strings if they are null. As a special case, if the word containing the replacement text is the null string, the word is deleted. .PP The variable ``$@'' is special in two ways. First, splitting takes place between the positional parameters, even if the text is enclosed in double quotes. Second, if the word containing the replacement text is the null string and there are no positional parameters, then the word is deleted. The result of these rules is that "$@" is equivalent to "$1" "$2" ... "$\fIn\fR", where \fIn\fR is the number of positional parameters. (Note that this differs from the System V shell. The System V documentation claims that "$@" behaves this way; in fact on the System V shell "$@" is equivalent to "" when there are no positional paramteters.) .h "File Name Generation" Unless the .B -f flag is set, file name generation is performed after word splitting is complete. Each word is viewed as a series of patterns, separated by slashes. The process of expansion replaces the word with the names of all existing files whose names can be formed by replacing each pattern with a string that matches the specified pattern. There are two restrictions on this: first, a pattern cannot match a string containing a slash, and second, a pattern cannot match a string starting with a period unless the first character of the pattern is a period. .PP If a word fails to match any files and the .B -z flag is not set, then the word will be left unchanged (except that the meta-characters will be converted to normal characters). If the .B -z flag is set, then the word is only left unchanged if none of the patterns contain a character that can match anything besides itself. Otherwise the .B -z flag forces the word to be replaced with the names of the files that it matches, even if there are zero names. .h "Patterns" A .I pattern consists of normal characters, which match themselves, and meta-characters. The meta-characters are ``!'', ``*'', ``?'', and ``[''. These characters lose there special meanings if they are quoted. When command or variable substitution is performed and the dollar sign or back quotes are not double quoted, the value of the variable or the output of the command is scanned for these characters and they are turned into meta-characters. .PP Two exclamation points at the beginning of a pattern function as a ``not'' operator, causing the pattern to match any string that the remainder of the pattern does .I not match. Other occurances of exclamation points in a pattern match exclamation points. Two exclamation points are required rather than one to decrease the incompatibility with the System V shell (which does not treat exclamation points specially). .PP An asterisk (``*'') matches any string of characters. A question mark matches any single character. A left bracket (``['') introduces a character class. The end of the character class is indicated by a ``]''; if the ``]'' is missing then the ``['' matches a ``['' rather than introducing a character class. A character class matches any of the characters between the square brackets. A range of characters may be specified using a minus sign. The character class may be complemented by making an exclamation point the first character of the character class. .PP To include a ``]'' in a character class, make it the first character listed (after the ``!'', if any). To include a minus sign, make it the first or last character listed. .h "The /u Directory" By convention, the name ``/u/user'' refers to the home directory of the specified user. There are good reasons why this feature should be supported by the file system (using a feature such as symbolic links) rather than by the shell, but .I ash is capable of performing this mapping if the file system doesn't. If the mapping is done by .IR ash , setting the .B -f flag will turn it off. .h "Character Set" .I Ash silently discards nul characters. Any other character will be handled correctly by .IR ash , including characters with the high order bit set. .h "Job Names and Job Control" The term .I job refers to a process created by a shell command, or in the case of a pipeline, to the set of processes in the pipeline. The ways to refer to a job are: .d %\fInumber\fR %\fIstring\fR %% \fIprocess_id\fR .e The first form identifies a job by job number. When a command is run, .I ash assigns it a job number (the lowest unused number is assigned). The second form identifies a job by giving a prefix of the command used to create the job. The prefix must be unique. If there is only one job, then the null prefix will identify the job, so you can refer to the job by writing ``%''. The third form refers to the \fIcurrent job\fR. The current job is the last job to be stopped while it was in the foreground. (See the next paragraph.) The last form identifies a job by giving the process id of the last process in the job. .PP If the operating system that .I ash is running on supports job control, .I ash will allow you to use it. In this case, typing the suspend character (typically ^Z) while running a command will return you to .I ash and will make the suspended command the current job. You can then continue the job in the background by typing .IR bg , or you can continue it in the foreground by typing .IR fg . .h "Atty" If the shell variable ATTY is set, and the shell variable TERM is not set to ``emacs'', then \fIash\fR generates appropriate escape sequences to talk to .IR atty (1). .h "Exit Statuses" By tradition, an exit status of zero means that a command has succeeded and a nonzero exit status indicates that the command failed. This is better than no convention at all, but in practice it is extremely useful to allow commands that succeed to use the exit status to return information to the caller. A variety of better conventions have been proposed, but none of them has met with universal approval. The convention used by \fIash\fR and all the programs included in the \fIash\fR distribution is as follows: .ta 1i 2i .nf 0 Success. 1 Alternate success. 2 Failure. 129-... Command terminated by a signal. .fi The \fIalternate success\fR return is used by commands to indicate various conditions which are not errors but which can, with a little imagination, be conceived of as less successful than plain success. For example, .I test returns 1 when the tested condition is false and .I getopts returns 1 when there are no more options. Because this convention is not used universally, the .B -e option of .I ash causes the shell to exit when a command returns 1 even though that contradicts the convention described here. .PP When a command is terminated by a signal, the uses 128 plus the signal number as the exit code for the command. .h "Builtin Commands" This concluding section lists the builtin commands which are builtin because they need to perform some operation that can't be performed by a separate process. In addition to these, there are several other commands .RI ( catf , .IR echo , .IR expr , .IR line , .IR nlecho , .IR test , .RI `` : '', and .IR true ) which can optionally be compiled into the shell. The builtin commands described below that accept options use the System V Release 2 .IR getopt (3) syntax. .sp .b bg [ .I job ] ... .br Continue the specified jobs (or the current job if no jobs are given) in the background. This command is only available on systems with Bekeley job control. .b command .IR "command arg" ... .br Execute the specified builtin command. (This is useful when you have a shell function with the same name as a builtin command.) .b cd [ .I directory ] .br Switch to the specified directory (default $HOME). If the an entry for CDPATH appears in the environment of the cd command or the shell variable CDPATH is set and the directory name does not begin with a slash, then the directories listed in CDPATH will be searched for the specified directory. The format of CDPATH is the same as that of PATH. In an interactive shell, the cd command will print out the name of the directory that it actually switched to if this is different from the name that the user gave. These may be different either because the CDPATH mechanism was used or because a symbolic link was crossed. .\" .b ".\fI\h'0.1i'file" .\" Cawf can't do \h'0.1i' .b . .I file .br The commands in the specified file are read and executed by the shell. A path search is not done to find the file because the directories in PATH generally contain files that are intended to be executed, not read. .b eval .IR string ... .br The strings are parsed as shell commands and executed. (This differs from the System V shell, which concatenates the arguments (separated by spaces) and parses the result as a single command.) .b exec [ .IR "command arg" ... ] .br Unless .I command is omitted, the shell process is replaced with the specified program (which must be a real program, not a shell builtin or function). Any redirections on the exec command are marked as permanent, so that they are not undone when the exec command finishes. If the command is not found, the exec command causes the shell to exit. .b exit [ .I exitstatus ] .br Terminate the shell process. If .I exitstatus is given it is used as the exit status of the shell; otherwise the exit status of the preceding command is used. .b export .IR name ... .br The specified names are exported so that they will appear in the environment of subsequent commands. The only way to un-export a variable is to unset it. .I Ash allows the value of a variable to be set at the same time it is exported by writing .d \fBexport\fR name=value .e With no arguments the export command lists the names of all exported variables. .b fg [ .I job ] .br Move the specified job or the current job to the foreground. This command is only available on systems with Bekeley job control. .b getopts .I optstring .I var .br The System V .I getopts command. .b hash .B -rv .IR command ... .br The shell maintains a hash table which remembers the locations of commands. With no arguments whatsoever, the hash command prints out the contents of this table. Entries which have not been looked at since the last .I cd command are marked with an asterisk; it is possible for these entries to be invalid. .sp With arguments, the hash command removes the specified commands from the hash table (unless they are functions) and then locates them. With the .B -v option, .I hash prints the locations of the commands as it finds them. The .B -r option causes the .I hash command to delete all the entries in the hash table except for functions. .b jobid [ .I job ] .br Print the process id's of the processes in the job. If the job argument is omitted, use the current job. .b jobs .br This command lists out all the background processes which are children of the current shell process. .b pwd .br Print the current directory. The builtin command may differ from the program of the same name because the builtin command remembers what the current directory is rather than recomputing it each time. This makes it faster. However, if the current directory is renamed, the builtin version of pwd will continue to print the old name for the directory. .b read [ .B -p .I prompt ] [ .B -e ] .IR variable ... .br The prompt is printed if the .B -p option is specified and the standard input is a terminal. Then a line is read from the standard input. The trailing newline is deleted from the line and the line is split as described in the section on word splitting above, and the pieces are assigned to the variables in order. If there are more pieces than variables, the remaining pieces (along with the characters in IFS that separated them) are assigned to the last variable. If there are more variables than pieces, the remaining variables are assigned the null string. .sp The .B -e option causes any backslashes in the input to be treated specially. If a backslash is followed by a newline, the backslash and the newline will be deleted. If a backslash is followed by any other character, the backslash will be deleted and the following character will be treated as though it were not in IFS, even if it is. .b readonly .IR name ... .br The specified names are marked as read only, so that they cannot be subsequently modified or unset. .I Ash allows the value of a variable to be set at the same time it is marked read only by writing .d \fBreadonly\fR name=value .e With no arguments the readonly command lists the names of all read only variables. .b set [ { .BI - options | .BI + options | .B -- } ] .IR arg ... .br The .I set command performs three different functions. .sp With no arguments, it lists the values of all shell variables. .sp If options are given, it sets the specified option flags, or clears them if the option flags are introduced with a .B + rather than a .BR - . Only the first argument to .I set can contain options. The possible options are: .sp .ta 0.4i .in +0.4i .ti -0.4i \fB-e\fR Causes the shell to exit when a command terminates with a nonzero exit status, except when the exit status of the command is explicitly tested. The exit status of a command is considered to be explicitly tested if the command is used to control an .IR if , .IR elif , .IR while , or .IR until ; or if the command is the left hand operand of an ``&&'' or ``||'' operator. .sp .ti -0.4i \fB-f\fR Turn off file name generation. .sp .ti -0.4i \fB-I\fR Cause the shell to ignore end of file conditions. (This doesn't apply when the shell a script sourced using the ``.'' command.) The shell will in fact exit if it gets 50 eof's in a row. .sp .ti -0.4i \fB-i\fR Make the shell interactive. This causes the shell to prompt for input, to trap interrupts, to ignore quit and terminate signals, and to return to the main command loop rather than exiting on error. .sp .ti -0.4i \fB-j\fR Turns on Berkeley job control, on systems that support it. When the shell starts up, the .B -j is set by default if the .B -i flag is set. .sp .ti -0.4i \fB-n\fR Causes the shell to read commands but not execute them. (This is marginally useful for checking the syntax of scripts.) .sp .ti -0.4i \fB-s\fR If this flag is set when the shell starts up, the shell reads commands from its standard input. The shell doesn't examine the value of this flag any other time. .sp .ti -0.4i \fB-x\fR If this flag is set, the shell will print out each command before executing it. .sp .ti -0.4i \fB-z\fR If this flag is set, the file name generation process may generate zero files. If it is not set, then a pattern which does not match any files will be replaced by a quoted version of the pattern. .in -0.4i .sp The third use of the set command is to set the values of the shell's positional parameters to the specified .IR args . To change the positional parameters without changing any options, use ``\fB--\fR'' as the first argument to .IR set . If no args are present, the set command will leave the value of the positional parameters unchanged, so to set the positional parameters to set of values that may be empty, execute the command .d shift $# .e first to clear out the old values of the positional parameters. .b setvar .I variable .I value .br Assigns .I value to .IR variable . (In general it is better to write .I variable=value rather than using .IR setvar . .I Setvar is intended to be used in functions that assign values to variables whose names are passed as parameters.) .b shift [ .I n ] .br Shift the positional parameters .I n times. A shift sets the value of $1 to the value of $2, the value of $2 to the value of $3, and so on, decreasing the value of $# by one. If there are zero positional parameters, shifting doesn't do anything. .b trap [ .I action ] .IR signal ... .br Cause the shell to parse and execute .I action when any of the specified signals are received. The signals are specified by signal number. .I Action may be null or omitted; the former causes the specified signal to be ignored and the latter causes the default action to be taken. When the shell forks off a subshell, it resets trapped (but not ignored) signals to the default action. The trap command has no effect on signals that were ignored on entry to the shell. .b umask [ .I mask ] .br Set the value of umask (see .IR umask (2)) to the specified octal value. If the argument is omitted, the umask value is printed. .b unset .IR name ... .br The specified variables and functions are unset and unexported. If a given name corresponds to both a variable and a function, both the variable and the function are unset. .b wait [ .I job ] .br Wait for the specified job to complete and return the exit status of the last process in the job. If the argument is omitted, wait for all jobs to complete and the return an exit status of zero. .SH EXAMPLES The following function redefines the \fIcd\fR command: .d cd() { if command cd "$@" then if test -f .enter then . .enter else return 0 fi fi } .e This function causes the file ``.enter'' to be read when you enter a directory, if it exists. The \fIcommand\fR command is used to access the real \fIcd\fR command. The ``return 0'' ensures that the function will return an exit status of zero if it successfully changes to a directory that does not contain a ``.enter'' file. Redefining existing commands is not always a good idea, but this example shows that you can do it if you want to. .PP The suspend function distributed with .I ash looks like .d # Copyright (C) 1989 by Kenneth Almquist. All rights reserved. # This file is part of ash, which is distributed under the terms # specified by the Ash General Public License. suspend() { local - set +j kill -TSTP 0 } .e This turns off job control and then sends a stop signal to the current process group, which suspends the shell. (When job control is turned on, the shell ignores the TSTP signal.) Job control will be turned back on when the function returns because ``-'' is local to the function. As an example of what \fInot\fR to do, consider an earlier version of \fIsuspend\fR: .d suspend() { suspend_flag=$- set +j kill -TSTP 0 set -$suspend_flag } .e There are two problems with this. First, \fBsuspend_flag\fR is a global variable rather than a local one, which will cause problems in the (unlikely) circumstance that the user is using that variable for some other purpose. Second, consider what happens if shell received an interrupt signal after it executes the first \fIset\fR command but before it executes the second one. The interrupt signal will abort the shell function, so that the second \fIset\fR command will never be executed and job control will be left off. The first version of \fIsuspend\fR avoids this problem by turning job control off only in a local copy of the shell options. The local copy of the shell options is discarded when the function is terminated, no matter how it is terminated. .SH HINTS Shell variables can be used to provide abbreviations for things which you type frequently. For example, I set .br .\" \h'1i'export h=$HOME .\" Cawf can't do \h'1i' .in +1i export h=$HOME .in -1i .br in my .profile so that I can type the name of my home directory simply by typing ``$h''. .PP When writing shell procedures, try not to make assumptions about what is imported from the environment. Explicitly unset or initialize all variables, rather than assuming they will be unset. If you use cd, it is a good idea to unset CDPATH. .PP People sometimes use ``<&-'' or ``>&-'' to provide no input to a command or to discard the output of a command. A better way to do this is to redirect the input or output of the command to .BR /dev/null . .PP Word splitting and file name generation are performed by default, and you have to explicitly use double quotes to suppress it. This is backwards, but you can learn to live with it. Just get in the habit of writing double quotes around variable and command substitutions, and omit them only when you really want word splitting and file name generation. If you want word splitting but not file name generation, use the .B -f option. .SH AUTHORS Kenneth Almquist .SH "SEE ALSO" echo(1), expr(1), line(1), pwd(1), true(1). .SH BUGS When command substitution occurs inside a here document, the commands inside the here document are run with their standard input closed. For example, the following will not word because the standard input of the .I line command will be closed when the command is run: .d cat <<-! Line 1: $(line) Line 2: $(line) ! .e .PP Unsetting a function which is currently being executed may cause strange behavior. .PP The shell syntax allows a here document to be terminated by an end of file as well as by a line containing the terminator word which follows the ``<<''. What this means is that if you mistype the terminator line, the shell will silently swallow up the rest of your shell script and stick it in the here document. .\" .\" bc.1 - the *roff document processor source for the bc manual .\" .\" This file is part of bc written for MINIX. .\" Copyright (C) 1991, 1992 Free Software Foundation, Inc. .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License , or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; see the file COPYING. If not, write to .\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. .\" .\" You may contact the author by: .\" e-mail: phil@cs.wwu.edu .\" us-mail: Philip A. Nelson .\" Computer Science Department, 9062 .\" Western Washington University .\" Bellingham, WA 98226-9062 .\" .\" .TH bc 1 .\" "Command Manual" v1.02 "Feb 3, 1992" .SH NAME bc - An arbitrary precision calculator language .SH SYNTAX \fBbc\fR [ \fB-lws\fR ] [ \fI file ...\fR ] .SH VERSION This man page documents GNU bc version 1.02. .SH DESCRIPTION \fBbc\fR is a language that supports arbitrary precision numbers with interactive execution of statements. There are some similarities in the syntax to the C programming language. A standard math library is available by command line option. If requested, the math library is defined before processing any files. \fBbc\fR starts by processing code from all the files listed on the command line in the order listed. After all files have been processed, \fBbc\fR reads from the standard input. All code is executed as it is read. (If a file contains a command to halt the processor, \fBbc\fR will never read from the standard input.) .PP This version of \fBbc\fR contains several extensions beyond traditional \fBbc\fR implementations and the POSIX draft standard. Command line options can cause these extensions to print a warning or to be rejected. This document describes the language accepted by this processor. Extensions will be identified as such. .SS OPTIONS .IP -l Define the standard math library. .IP -w Give warnings for extensions to POSIX \fBbc\fR. .IP -s Process exactly the POSIX \fBbc\fR language. .SS NUMBERS The most basic element in \fBbc\fR is the number. Numbers are arbitrary precision numbers. This precision is both in the integer part and the fractional part. All numbers are represented internally in decimal and all computation is done in decimal. (This version truncates results from divide and multiply operations.) There are two attributes of numbers, the length and the scale. The length is the total number of significant decimal digits in a number and the scale is the total number of decimal digits after the decimal point. For example: .nf .RS .000001 has a length of 6 and scale of 6. 1935.000 has a length of 7 and a scale of 3. .RE .fi .SS VARIABLES Numbers are stored in two types of variables, simple variables and arrays. Both simple variables and array variables are named. Names begin with a letter followed by any number of letters, digits and underscores. All letters must be lower case. (Full alpha-numeric names are an extension. In POSIX \fBbc\fR all names are a single lower case letter.) The type of variable is clear by the context because all array variable names will be followed by brackets ([]). .PP There are four special variables, \fBscale, ibase, obase,\fR and \fBlast\fR. \fBscale\fR defines how some operations use digits after the decimal point. The default value of \fBscale\fR is 0. \fBibase\fR and \fBobase\fR define the conversion base for input and output numbers. The default for both input and output is base 10. \fBlast\fR (an extension) is a variable that has the value of the last printed number. These will be discussed in further detail where appropriate. All of these variables may have values assigned to them as well as used in expressions. .SS COMMENTS Comments in \fBbc\fR start with the characters \fB/*\fR and end with the characters \fB*/\fR. Comments may start anywhere and appear as a single space in the input. (This causes comments to delimit other input items. For example, a comment can not be found in the middle of a variable name.) Comments include any newlines (end of line) between the start and the end of the comment. .SS EXPRESSIONS The numbers are manipulated by expressions and statements. Since the language was designed to be interactive, statements and expressions are executed as soon as possible. There is no "main" program. Instead, code is executed as it is encountered. (Functions, discussed in detail later, are defined when encountered.) .PP A simple expression is just a constant. \fBbc\fR converts constants into internal decimal numbers using the current input base, specified by the variable \fBibase\fR. (There is an exception in functions.) The legal values of \fBibase\fR are 2 through 16 (F). Assigning a value outside this range to \fBibase\fR will result in a value of 2 or 16. Input numbers may contain the characters 0-9 and A-F. (Note: They must be capitals. Lower case letters are variable names.) Single digit numbers always have the value of the digit regardless of the value of \fBibase\fR. (i.e. A = 10.) For multi-digit numbers, \fBbc\fR changes all input digits greater or equal to ibase to the value of \fBibase\fR-1. This makes the number \fBFFF\fR always be the largest 3 digit number of the input base. .PP Full expressions are similar to many other high level languages. Since there is only one kind of number, there are no rules for mixing types. Instead, there are rules on the scale of expressions. Every expression has a scale. This is derived from the scale of original numbers, the operation performed and in many cases, the value of the variable \fBscale\fR. Legal values of the variable \fBscale\fR are 0 to the maximum number representable by a C integer. .PP In the following descriptions of legal expressions, "expr" refers to a complete expression and "var" refers to a simple or an array variable. A simple variable is just a .RS \fIname\fR .RE and an array variable is specified as .RS \fIname\fR[\fIexpr\fR] .RE Unless specifically mentioned the scale of the result is the maximum scale of the expressions involved. .IP "- expr" The result is the negation of the expression. .IP "++ var" The variable is incremented by one and the new value is the result of the expression. .IP "-- var" The variable is decremented by one and the new value is the result of the expression. .IP "var ++" The result of the expression is the value of the variable and then the variable is incremented by one. .IP "var --" The result of the expression is the value of the variable and then the variable is decremented by one. .IP "expr + expr" The result of the expression is the sum of the two expressions. .IP "expr - expr" The result of the expression is the difference of the two expressions. .IP "expr * expr" The result of the expression is the product of the two expressions. .IP "expr / expr" The result of the expression is the quotient of the two expressions. The scale of the result is the value of the variable \fBscale\fR. .IP "expr % expr" The result of the expression is the "remainder" and it is computed in the following way. To compute a%b, first a/b is computed to \fBscale\fR digits. That result is used to compute a-(a/b)*b to the scale of the maximum of \fBscale\fR+scale(b) and scale(a). If \fBscale\fR is set to zero and both expressions are integers this expression is the integer remainder function. .IP "expr ^ expr" The result of the expression is the value of the first raised to the second. The second expression must be an integer. (If the second expression is not an integer, a warning is generated and the expression is truncated to get an integer value.) The scale of the result is \fBscale\fR if the exponent is negative. If the exponent is positive the scale of the result is the minimum of the scale of the first expression times the value of the exponent and the maximum of \fBscale\fR and the scale of the first expression. (e.g. scale(a^b) = min(scale(a)*b, max( \fBscale,\fR scale(a))).) It should be noted that expr^0 will always return the value of 1. .IP "( expr )" This alters the standard precedence to force the evaluation of the expression. .IP "var = expr" The variable is assigned the value of the expression. .IP "var = expr" This is equivalent to "var = var expr" with the exception that the "var" part is evaluated only once. This can make a difference if "var" is an array. .PP Relational expressions are a special kind of expression that always evaluate to 0 or 1, 0 if the relation is false and 1 if the relation is true. These may appear in any legal expression. (POSIX bc requires that relational expressions are used only in if, while, and for statements and that only one relational test may be done in them.) The relational operators are .IP "expr1 < expr2" The result is 1 if expr1 is strictly less than expr2. .IP "expr1 <= expr2" The result is 1 if expr1 is less than or equal to expr2. .IP "expr1 > expr2" The result is 1 if expr1 is strictly greater than expr2. .IP "expr1 >= expr2" The result is 1 if expr1 is greater than or equal to expr2. .IP "expr1 == expr2" The result is 1 if expr1 is equal to expr2. .IP "expr1 != expr2" The result is 1 if expr1 is not equal to expr2. .PP Boolean operations are also legal. (POSIX \fBbc\fR does NOT have boolean operations). The result of all boolean operations are 0 and 1 (for false and true) as in relational expressions. The boolean operators are: .IP "!expr" The result is 1 if expr is 0. .IP "expr && expr" The result is 1 if both expressions are non-zero. .IP "expr || expr" The result is 1 if either expression is non-zero. .PP The expression precedence is as follows: (lowest to highest) .nf .RS || operator, left associative && operator, left associative ! operator, nonassociative Relational operators, left associative Assignment operator, right associative + and - operators, left associative *, / and % operators, left associative ^ operator, right associative unary - operator, nonassociative ++ and -- operators, nonassociative .RE .fi .PP This precedence was chosen so that POSIX compliant \fBbc\fR programs will run correctly. This will cause the use of the relational and logical operators to have some unusual behavior when used with assignment expressions. Consider the expression: .RS a = 3 < 5 .RE .PP Most C programmers would assume this would assign the result of "3 < 5" (the value 1) to the variable "a". What this does in \fBbc\fR is assign the value 3 to the variable "a" and then compare 3 to 5. It is best to use parenthesis when using relational and logical operators with the assignment operators. .PP There are a few more special expressions that are provided in \fBbc\fR. These have to do with user defined functions and standard functions. They all appear as "\fIname\fB(\fIparameters\fB)\fR". See the section on functions for user defined functions. The standard functions are: .IP "length ( expression )" The value of the length function is the number of significant digits in the expression. .IP "read ( )" The read function (an extension) will read a number from the standard input, regardless of where the function occurs. Beware, this can cause problems with the mixing of data and program in the standard input. The best use for this function is in a previously written program that needs input from the user, but never allows program code to be input from the user. The value of the read function is the number read from the standard input using the current value of the variable \fBibase\fR for the conversion base. .IP "scale ( expression )" The value of the scale function is the number of digits after the decimal point in the expression. .IP "sqrt ( expression )" The value of the sqrt function is the square root of the expression. If the expression is negative, a run time error is generated. .SS STATEMENTS Statements (as in most algebraic languages) provide the sequencing of expression evaluation. In \fBbc\fR statements are executed "as soon as possible." Execution happens when a newline in encountered and there is one or more complete statements. Due to this immediate execution, newlines are very important in \fBbc\fR. In fact, both a semicolon and a newline are used as statement separators. An improperly placed newline will cause a syntax error. Because newlines are statement separators, it is possible to hide a newline by using the backslash character. The sequence "\e", where is the newline appears to \fBbc\fR as whitespace instead of a newline. A statement list is a series of statements separated by semicolons and newlines. The following is a list of \fBbc\fR statements and what they do: (Things enclosed in brackets ([]) are optional parts of the statement.) .IP "expression" This statement does one of two things. If the expression starts with " ...", it is considered to be an assignment statement. If the expression is not an assignment statement, the expression is evaluated and printed to the output. After the number is printed, a newline is printed. For example, "a=1" is an assignment statement and "(a=1)" is an expression that has an embedded assignment. All numbers that are printed are printed in the base specified by the variable \fBobase\fR. The legal values for \fB obase\fR are 2 through BC_BASE_MAX. (See the section LIMITS.) For bases 2 through 16, the usual method of writing numbers is used. For bases greater than 16, \fBbc\fR uses a multi-character digit method of printing the numbers where each higher base digit is printed as a base 10 number. The multi-character digits are separated by spaces. Each digit contains the number of characters required to represent the base ten value of "obase-1". Since numbers are of arbitrary precision, some numbers may not be printable on a single output line. These long numbers will be split across lines using the "\e" as the last character on a line. The maximum number of characters printed per line is 70. Due to the interactive nature of \fBbc\fR printing a number cause the side effect of assigning the printed value the the special variable \fBlast\fR. This allows the user to recover the last value printed without having to retype the expression that printed the number. Assigning to \fBlast\fR is legal and will overwrite the last printed value with the assigned value. The newly assigned value will remain until the next number is printed or another value is assigned to \fBlast\fR. .IP "string" The string is printed to the output. Strings start with a double quote character and contain all characters until the next double quote character. All characters are take literally, including any newline. No newline character is printed after the string. .IP "\fBprint\fR list" The print statement (an extension) provides another method of output. The "list" is a list of strings and expressions separated by commas. Each string or expression is printed in the order of the list. No terminating newline is printed. Expressions are evaluated and their value is printed and assigned the the variable \fBlast\fR. Strings in the print statement are printed to the output and may contain special characters. Special characters start with the backslash character (\e). The special characters recognized by \fBbc\fR are "b" (bell), "f" (form feed), "n" (newline), "r" (carriage return), "t" (tab), and "\e" (backslash). Any other character following the backslash will be ignored. This still does not allow the double quote character to be part of any string. .IP "{ statement_list }" This is the compound statement. It allows multiple statements to be grouped together for execution. .IP "\fBif\fR ( expression ) \fBthen\fR statement1 [\fBelse\fR statement2]" The if statement evaluates the expression and executes statement1 or statement2 depending on the value of the expression. If the expression is non-zero, statement1 is executed. If statement2 is present and the value of the expression is 0, then statement2 is executed. (The else clause is an extension.) .IP "\fBwhile\fR ( expression ) statement" The while statement will execute the statement while the expression is non-zero. It evaluates the expression before each execution of the statement. Termination of the loop is caused by a zero expression value or the execution of a break statement. .IP "\fBfor\fR ( [expression1] ; [expression2] ; [expression3] ) statement" The for statement controls repeated execution of the statement. Expression1 is evaluated before the loop. Expression2 is evaluated before each execution of the statement. If it is non-zero, the statement is evaluated. If it is zero, the loop is terminated. After each execution of the statement, expression3 is evaluated before the reevaluation of expression2. If expression1 or expression3 are missing, nothing is evaluated at the point they would be evaluated. If expression2 is missing, it is the same as substituting the value 1 for expression2. (The optional expressions are an extension. POSIX \fBbc\fR requires all three expressions.) The following is equivalent code for the for statement: .nf .RS expression1; while (expression2) { statement; expression3; } .RE .fi .IP "\fBbreak\fR" This statement causes a forced exit of the most recent enclosing while statement or for statement. .IP "\fBcontinue\fR" The continue statement (an extension) causes the most recent enclosing for statement to start the next iteration. .IP "\fBhalt\fR" The halt statement (an extension) is an executed statement that causes the \fBbc\fR processor to quit only when it is executed. For example, "if (0 == 1) halt" will not cause \fBbc\fR to terminate because the halt is not executed. .IP "\fBreturn\fR" Return the value 0 from a function. (See the section on functions.) .IP "\fBreturn\fR ( expression )" Return the value of the expression from a function. (See the section on functions.) .SS PSEUDO STATEMENTS These statements are not statements in the traditional sense. They are not executed statements. Their function is performed at "compile" time. .IP "\fBlimits\fR" Print the local limits enforced by the local version of \fBbc\fR. This is an extension. .IP "\fBquit\fR" When the quit statement is read, the \fBbc\fR processor is terminated, regardless of where the quit statement is found. For example, "if (0 == 1) quit" will cause \fBbc\fR to terminate. .IP "\fBwarranty\fR" Print a longer warranty notice. This is an extension. .SS FUNCTIONS Functions provide a method of defining a computation that can be executed later. Functions in .B bc always compute a value and return it to the caller. Function definitions are "dynamic" in the sense that a function is undefined until a definition is encountered in the input. That definition is then used until another definition function for the same name is encountered. The new definition then replaces the older definition. A function is defined as follows: .nf .RS \fBdefine \fIname \fB( \fIparameters \fB) { \fInewline \fI auto_list statement_list \fB}\fR .RE .fi A function call is just an expression of the form "\fIname\fB(\fIparameters\fB)\fR". .PP Parameters are numbers or arrays (an extension). In the function definition, zero or more parameters are defined by listing their names separated by commas. Numbers are only call by value parameters. Arrays are only call by variable. Arrays are specified in the parameter definition by the notation "\fIname\fB[]\fR". In the function call, actual parameters are full expressions for number parameters. The same notation is used for passing arrays as for defining array parameters. The named array is passed by variable to the function. Since function definitions are dynamic, parameter numbers and types are checked when a function is called. Any mismatch in number or types of parameters will cause a runtime error. A runtime error will also occur for the call to an undefined function. .PP The \fIauto_list\fR is an optional list of variables that are for "local" use. The syntax of the auto list (if present) is "\fBauto \fIname\fR, ... ;". (The semicolon is optional.) Each \fIname\fR is the name of an auto variable. Arrays may be specified by using the same notation as used in parameters. These variables have their values pushed onto a stack at the start of the function. The variables are then initialized to zero and used throughout the execution of the function. At function exit, these variables are popped so that the original value (at the time of the function call) of these variables are restored. The parameters are really auto variables that are initialized to a value provided in the function call. Auto variables are different than traditional local variables in the fact that if function A calls function B, B may access function A's auto variables by just using the same name, unless function B has called them auto variables. Due to the fact that auto variables and parameters are pushed onto a stack, \fBbc\fR supports recursive functions. .PP The function body is a list of \fBbc\fR statements. Again, statements are separated by semicolons or newlines. Return statements cause the termination of a function and the return of a value. There are two versions of the return statement. The first form, "\fBreturn\fR", returns the value 0 to the calling expression. The second form, "\fBreturn ( \fIexpression \fB)\fR", computes the value of the expression and returns that value to the calling expression. There is an implied "\fBreturn (0)\fR" at the end of every function. This allows a function to terminate and return 0 without an explicit return statement. .PP Functions also change the usage of the variable \fBibase\fR. All constants in the function body will be converted using the value of \fBibase\fR at the time of the function call. Changes of \fBibase\fR will be ignored during the execution of the function except for the standard function \fBread\fR, which will always use the current value of \fBibase\fR for conversion of numbers. .SS MATH LIBRARY If \fBbc\fR is invoked with the \fB-l\fR option, a math library is preloaded and the default scale is set to 20. The math functions will calculate their results to the scale set at the time of their call. The math library defines the following functions: .IP "s (\fIx\fR)" The sine of x in radians. .IP "c (\fIx\fR)" The cosine of x in radians. .IP "a (\fIx\fR)" The arctangent of x. .IP "l (\fIx\fR)" The natural logarithm of x. .IP "e (\fIx\fR)" The exponential function of raising e to the value x. .IP "j (\fIn,x\fR)" The bessel function of integer order n of x. .SS EXAMPLES In /bin/sh, the following will assign the value of "pi" to the shell variable \fBpi\fR. .RS \fB pi=$(echo "scale=10; 4*a(1)" | bc -l) \fR .RE .PP The following is the definition of the exponential function used in the math library. This function is written in POSIX \fBbc\fR. .nf .RS \fB scale = 20 /* Uses the fact that e^x = (e^(x/2))^2 When x is small enough, we use the series: e^x = 1 + x + x^2/2! + x^3/3! + ... */ define e(x) { auto a, d, e, f, i, m, v, z /* Check the sign of x. */ if (x<0) { m = 1 x = -x } /* Precondition x. */ z = scale; scale = 4 + z + .44*x; while (x > 1) { f += 1; x /= 2; } /* Initialize the variables. */ v = 1+x a = x d = 1 for (i=2; 1; i++) { e = (a *= x) / (d *= i) if (e == 0) { if (f>0) while (f--) v = v*v; scale = z if (m) return (1/v); return (v/1); } v += e } } \fR .RE .fi .PP The following is code that uses the extended features of \fBbc\fR to implement a simple program for calculating checkbook balances. This program is best kept in a file so that it can be used many times without having to retype it at every use. .nf .RS \fB scale=2 print "\enCheck book program!\en" print " Remember, deposits are negative transactions.\en" print " Exit by a 0 transaction.\en\en" print "Initial balance? "; bal = read() bal /= 1 print "\en" while (1) { "current balance = "; bal "transaction? "; trans = read() if (trans == 0) break; bal -= trans bal /= 1 } quit \fR .RE .fi .PP The following is the definition of the recursive factorial function. .nf .RS \fB define f (x) { if (x <= 1) return (1); return (f(x-1) * x); } \fR .RE .fi .SS DIFFERENCES This version of .B bc was implemented from the POSIX P1003.2/D11 draft and contains several differences and extensions relative to the draft and traditional implementations. It is not implemented in the traditional way using .I dc(1). This version is a single process which parses and runs a byte code translation of the program. There is an "undocumented" option (-c) that causes the program to output the byte code to the standard output instead of running it. It was mainly used for debugging the parser and preparing the math library. .PP A major source of differences is extensions, where a feature is extended to add more functionality and additions, where new features are added. The following is the list of differences and extensions. .IP LANG 11n This version does not conform to the POSIX standard in the processing of the LANG environment variable and all environment variables starting with LC_. .IP names Traditional and POSIX .B bc have single letter names for functions, variables and arrays. They have been extended to be multi-character names that start with a letter and may contain letters, numbers and the underscore character. .IP Strings Strings are not allowed to contain NUL characters. POSIX says all characters must be included in strings. .IP last POSIX \fBbc\fR does not have a \fBlast\fR variable. Some implementations of \fBbc\fR use the period (.) in a similar way. .IP comparisons POSIX \fBbc\fR allows comparisons only in the if statement, the while statement, and the second expression of the for statement. Also, only one relational operation is allowed in each of those statements. .IP "if statement, else clause" POSIX \fBbc\fR does not have an else clause. .IP "for statement" POSIX \fBbc\fR requires all expressions to be present in the for statement. .IP "&&, ||, !" POSIX \fBbc\fR does not have the logical operators. .IP "read function" POSIX \fBbc\fR does not have a read function. .IP "print statement" POSIX \fBbc\fR does not have a print statement . .IP "continue statement" POSIX \fBbc\fR does not have a continue statement. .IP "array parameters" POSIX \fBbc\fR does not have array parameters. Other implementations of \fBbc\fR may have call by value array parameters. .IP "=+, =-, =*, =/, =%, =^" POSIX \fBbc\fR does not require these "old style" assignment operators to be defined. This version may allow these "old style" assignments. Use the limits statement to see if the installed version supports them. If it does support the "old style" assignment operators, the statement "a =- 1" will decrement \fBa\fR by 1 instead of setting \fBa\fR to the value -1. .IP "spaces in numbers" Other implementations of \fBbc\fR allow spaces in numbers. For example, "x=1 3" would assign the value 13 to the variable x. The same statement would cause a syntax error in this version of \fBbc\fR. .IP "errors and execution" This implementation varies from other implementations in terms of what code will be executed when syntax and other errors are found in the program. If a syntax error is found in a function definition, error recovery tries to find the beginning of a statement and continue to parse the function. Once a syntax error is found in the function, the function will not be callable and becomes undefined. Syntax errors in the interactive execution code will invalidate the current execution block. The execution block is terminated by an end of line that appears after a complete sequence of statements. For example, .nf .RS a = 1 b = 2 .RE .fi has two execution blocks and .nf .RS { a = 1 b = 2 } .RE .fi has one execution block. Any runtime error will terminate the execution of the current execution block. A runtime warning will not terminate the current execution block. .IP "Interrupts" During an interactive session, the SIGINT signal (usually generated by the control-C character from the terminal) will cause execution of the current execution block to be interrupted. It will display a "runtime" error indicating which function was interrupted. After all runtime structures have been cleaned up, a message will be printed to notify the user that \fBbc\fR is ready for more input. All previously defined functions remain defined and the value of all non-auto variables are the value at the point of interruption. All auto variables and function parameters are removed during the clean up process. During a non-interactive session, the SIGINT signal will terminate the entire run of \fBbc\fR. .SS LIMITS The following are the limits currently in place for this .B bc processor. Some of them may have been changed by an installation. Use the limits statement to see the actual values. .IP BC_BASE_MAX The maximum output base is currently set at 999. The maximum input base is 16. .IP BC_DIM_MAX This is currently an arbitrary limit of 65535 as distributed. Your installation may be different. .IP BC_SCALE_MAX The number of digits after the decimal point is limited to INT_MAX digits. Also, the number of digits before the decimal point is limited to INT_MAX digits. .IP BC_STRING_MAX The limit on the number of characters in a string is INT_MAX characters. .IP exponent The value of the exponent in the raise operation (^) is limited to LONG_MAX. .IP multiply The multiply routine may yield incorrect results if a number has more than LONG_MAX / 90 total digits. For 32 bit longs, this number is 23,860,929 digits. .IP "code size" Each function and the "main" program are limited to 10240 bytes of compiled byte code each. This limit (BC_MAX_SEGS) can be easily changed to have more than 10 segments of 1024 bytes. .IP "variable names" The current limit on the number of unique names is 32767 for each of simple variables, arrays and functions. .SH FILES In most installations, \fBbc\fR is completely self-contained. Where executable size is of importance or the C compiler does not deal with very long strings, \fBbc\fR will read the standard math library from the file /usr/local/lib/libmath.b. (The actual location may vary. It may be /lib/libmath.b.) .SH DIAGNOSTICS If any file on the command line can not be opened, \fBbc\fR will report that the file is unavailable and terminate. Also, there are compile and run time diagnostics that should be self-explanatory. .SH BUGS Error recovery is not very good yet. .SH AUTHOR .nf Philip A. Nelson phil@cs.wwu.edu .fi .SH ACKNOWLEDGEMENTS The author would like to thank Steve Sommars (sesv@iwtsf.att.com) for his extensive help in testing the implementation. Many great suggestions were given. This is a much better product due to his involvement. .TH LP 1 .SH NAME lp, lpd \- copy a file to the line printer .SH SYNOPSIS .B lp .RI [ file " ...]" .SH DESCRIPTION Each file argument to .B lp is send to the line printer to be printed. Standard input is read and printed if there are no arguments. .B Lp executes .B /usr/lib/lpd with each file as input. .B Lpd puts the file in .B /usr/spool/lpd and starts printing the jobs on .B /dev/lp unless another .B lpd is already running. If .B lpd finds any character in the input that it doesn't know how to handle then it will print the rest of the file without any special treatment. This also means that no formfeed is sent after the file has been printed to force out the page. .B Lpd simply assumes that you know what you are doing. (dumb, eh?) .PP Note: Don't do anything with a file until it is printed, .B lpd only makes a copy of a file in the spool directory when it is not world readable. If it can be read then it is printed directly. .SH FILES .TP 20 .BI /usr/spool/lpd/job XXXXX Information about a job. .TP .BI /usr/spool/lpd/tmp XXXXX Associated file to be printed. .TP .B /etc/termcap The 'lp' entry describes the printer by the "li#" and "co#" fields. By default 66 lines (li#66), and 80 columns (co#80). .SH "SEE ALSO" .BR lp (4), .BR termcap (5), .BR termcap (7). .SH BUGS Not spooling a world readable file may not be such a smart idea. .PP A formfeed should be printed and the printer reset after a job full of escape codes, but this may cost paper. .PP No banner page. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .\" manual page for cawf(1) .\" .\" .\" Copyright (c) 1991 Purdue University Research Foundation, .\" West Lafayette, Indiana 47907. All rights reserved. .\" .\" Written by Victor A. Abell , Purdue .\" University Computing Center. Not derived from licensed software; .\" derived from awf(1) by Henry Spencer of the University of Toronto. .\" .\" Permission is granted to anyone to use this software for any .\" purpose on any computer system, and to alter it and redistribute .\" it freely, subject to the following restrictions: .\" .\" 1. The author is not responsible for any consequences of use of .\" this software, even if they arise from flaws in it. .\" .\" 2. The origin of this software must not be misrepresented, either .\" by explicit claim or by omission. Credits must appear in the .\" documentation. .\" .\" 3. Altered versions must be plainly marked as such, and must not .\" be misrepresented as being the original software. Credits must .\" appear in the documentation. .\" .\" 4. This notice may not be removed or altered. .\" .\" Some of the stuff in this file is a bit contorted, because it's also .\" the regression-test input. .nr ES 5n .de ES .PP .in +\\n(ESu .nf .. .de EE .in -\\n(ESu .fi .PP .. .de PT .ie \\n(.$>1 .TP "\\$2" .el .TP .ie !'\\$1'' \\$1 .el \(bu .. .ds Nr \fInroff\fR .TH CAWF 1 "November, 1992" .BY "Purdue University" .SH NAME cawf, nroff \- C version of the nroff-like, Amazingly Workable (text) Formatter .SH SYNOPSIS .B cawf [ .BI \-c config ] [ .BI \-d device ] [ .B \-e ] [ .BI \-f font ] [ .B \-h ] [ .BI \-m acros ] [ file ... ] .SH DESCRIPTION .if t .tm OOPS -- CAWF THINKS IT'S TROFF!!! .I Cawf formats the text from the input \fIfile\fR(s) (standard input if none) in an approximation of \*(Nr. It comes closest to duplicating \*(Nr's .B man or .B ms macro package styles. It has some limited support for \*(Nr's .B me macros. .SH OPTIONS Options must precede file names. .TP .BI \-c config defines an alternate path to the device configuration file. Normally the device configuration file is found in .I device.cf in the .I cawf library (see the .B FILES section). .IP The device configuration file contains device character strings for selecting fonts and the bold or italic type faces. See the .B DEVICES section for more information. .TP .BI \-d device specifies the name of the output device. There are three built\-in devices \- ANSI, NONE and NORMAL \- and other devices may be defined in the device configuration file. See the .B DEVICES section for more information. .IP The NORMAL device is the default. .TP .B \-e directs .I cawf to issue an eject (FF or ^L) after the last page. .TP .BI \-f font specifies the one font for the device, declared with the .BI \-d device option, that is to be used for the entire document. .I Font must match a font associated with the device's stanza in the device configuration file. See the .B DEVICES section for more information. .IP No .I font may be specified for the built\-in devices ANSI, NONE or NORMAL. .TP .B \-h requests a help display. .TP .BI \-m acro specifies the macro file to be used. The standard .I cawf distribution supplies macro files to support ``\-man'', ``\-me'' or ``\-ms''. .I Cawf finds a macro file by constructing its name from `m', .I acro and .B .mac \- e. g., .BI \-m an is converted to .BR man.mac . The default directory for macro files is defined when .I cawf is compiled; it's \fIC:\\SYS\\LIB\\CAWF\fP in the MS\-DOS environment; .I /usr/lib/cawf in the UNIX environment. .TP file ... are the names of files containing \*(Nr source text. .SH NROFF COMPATIBILITY .I Cawf accepts the following raw \*(Nr requests: .LP .\e" .ad .bp .br .ce .de .di .ds .el .fi .fl .ft .i0 .ie .if .in .it .lg .li .ll .ls .na .ne .nf .nr .ns .pl .po .ps .rm .rn .rr .rs .so .sp .ta .ti .tm .tr .LP and the following in-text codes: .ES \e$ \e% \e* \e" \ec \ef \eh \ek \en \es \ew .EE plus the full list of \*(Nr/\c .I troff special characters in the original V7 \fItroff\fR manual. .PP Many restrictions are present; the behavior in general is a subset of \*(Nr's. Of particular note are the following: .IP \(bu 2 The fully supported nroff request control character is the period. There is limited support for the non\-break, acute accent control character. .PT Point sizes do not exist; .B .ps is ignored. .PT Special vertical spacing \- the .B .vs request included \- is ignored. .PT Conditionals cover only the numeric comparisons >, =, <, >= and <= on .BR \en(.$ ; string com\%par\%isons between a macro parameter and a literal; .B n (always true); and .BR t (always false). Only single line input is accepted from conditionals; multi\-line input \- e.g., \\(\fIanything\fP\\) \- is not supported. .PT The handling of strings is generally primitive. .IP \(bu Horizontal motion via .B \eh must be supplied with a number register interpolation and must be positive - e. g., .BR \ew\en(NN , where the value in NN is >= 0. .IP \(bu The .B \ek function is reliable only after TAB characters, so it is useful only for measuring table positions. .IP \(bu The .B .di request only turns output on and off \- any macro name is ignored. .IP \(bu Expressions - e. g., .B .sp - are reasonably general, but the .BR | , .BR & , and .BR :\& operators do not exist, there must be white space between the end of the \*(Nr function and the beginning of the expression, and .B \ew requires that quote (') be used as the delimiters. .B \ew counts the characters inside the quotes and scales the result in ens, so that, for example, \ew'\e(bu' equals 4n, and \ew'\e(bu'/1n equals 4. .PT The only acceptable count for the .B .it request is one, and it is effective only with .BR man , .B me or .B ms macros. .PT The default scaling factor is `v' for the .BR .ne , .BR .sp , and .B .pl raw \*(Nr requests; it is `u' for .BR .nr ; and `n' for .BR .in , .BR .ll , .BR .ls , .BR .po , .BR .ta and .BR .ti . (A different scaling factor may be specified with a trailing character.) .PT Some obsolete or meaningless requests \- .BR .i0 , .B .lg and .B .li \&\- are silently ignored. .P White space at the beginning of lines, and embedded white space within lines is dealt with properly. Sentence terminators at ends of lines are understood to imply extra space afterward in filled lines. Tabs are im\%plemented crudely and not exactly, although usually they work as expected. Hyphenation is done only at explicit hyphens, em-dashes, and \*(Nr discretionary hyphens. By default bold and italic characters are emulated with backspacing and overprinting, but the .B \-d and .B \-f options, combined with the contents of the device configuration file, may be used to generate special codes for bold and italic characters. (See the .B DEVICES section for more information.) .SH "MAN MACROS" The .B man macro set replicates the full V7 manual macros, plus a few semi-random oddballs. The full list is: .ES \&.AT .B .BI .BR .BY .DE .DS .DT .HP .I \&.IB .IP .IR .IX .LP .NB .P .PD .PP .RB \&.RE .RI .RS .SH .SM .SS .TH .TP .UC .EE .B .BY and .B .NB each take a single string argument (respectively, an indi\%cation of authorship and a note about the status of the manual page) and arrange to place it in the page footer. .B .AT and .B .IX do nothing. .SH "ME MACROS" The .B me macro subset has been derived from the .I cawf .B ms macros by Chet Creider . It includes: .ES \&.(l .(q .)l .)q .b .bu .i .ip .lp .np \&.pp .r .sh .sm .u .uh .EE The .(l C and .(l L options are supported. In addition, the .AB, .AE, .AI, .AU, .DA, .ND, .TL and .UX macros have been retained from the .B ms set, and the .XP macro has been borrowed from the Berkeley additions to the .B ms macro set. .SH "MS MACROS" The .B ms macro set is a substantial subset of the V7 manuscript macros. The macros are: .ES \&.AB .AE .AI .AU .B .CD .DA .DE .DS .I \&.ID .IP .LD .LG .LP .ND .NH .NL .PP .QE \&.QP .QS .R .RE .RP .RS .SH .SM .TL .TP \&.UL .UX .EE Size changes are recognized but ignored, as are .B .RP and .BR .ND . .B .UL just prints its argument in italics. .BR .DS / .DE does not do a keep, nor do any of the other macros that normally imply keeps. .LP The .B DY string variable is available. The .BR PD , .BR PI , and .BR LL number registers exist and can be changed. .SH "HEADERS AND FOOTERS" .I Cawf allows the placement of text into the five line header and footer sections from the .BR LH , .BR CH , .BR RF , .BR LF , .BR CF , and .B RF string variables, via the control of the .B .^b request: .LP .ta \w'.^b HF 0'u+3n .nf \&.^b fh 1 enables header string placement on the first page \&.^b fh 0 disables header string placement on the first page \&.^b HF 1 enables header/footer string placement \&.^b HF 0 disables header/footer string placement .fi .LP There are appropriate .B .^b requests in the distribution .BR man , .B me and .B ms macro files. (The .B me and .B ms macro files use another .B .^b request, \fB.^b NH\fP, to enable numbered header processing.) .SH OUTPUT The default output format supported by .IR cawf , in its distributed form, is that appropriate to a dumb terminal, using overprinting for italics (via underlining) and bold. The \*(Nr special characters are printed as some vague approximation (it's sometimes extremely vague) to their correct appearance. .PP One part of .IR cawf 's knowledge of the output device, related to the formation of characters, is established by a device file, which is read before the user's input. The search for it begins in .IR cawf 's library directory, under the name \fIterm\fP.\fBdev\fP (where \fIterm\fR is the value of the TERM environment variable). Failing to find that, .I cawf searches for .BR dumb.dev . (See the .B FILES section for a description of the path to .IR cawf 's library directory.) The device file uses special internal requests to set up resolution, special characters and more normal \*(Nr functions to set up page length, etc. .PP .I Cawf has limited support for fonts special forms of bold and italic characters. It is provided through the .B \-c .IR config , .BI \-d device and .BI \-f font options. See the .B DEVICES section for more information. .PP Note the distinction between the device and the output device configuration files. The device file typically defines characters and constant output parameters. The output device configuration file defines font and type face codes. It is usually not necessary to define a separate device file for each device represented in the output device configuration file \- the .I dumb.dev device file will suffice for almost all representations. .SH DEVICES .I Cawf supports primitive output device configuration for font and type face control. One font may be selected for the entire document by directing .I cawf to issue a font selection control character string at the beginning of the document, and control character strings may be selected for switching between the bold, italic and Roman type faces. .PP The .B \-c .IR config, .BI \-d device and .BI \-f font options direct the font and type face selections. .PP The .BI \-d device option specifies the name of the device. .I Cawf has three built\-in devices \- ANSI, NONE and NORMAL. When the ANSI device is selected, .I cawf issues the ANSI shadow mode control codes, ``ESC [ 7 m'', to represent the bold face; the ANSI underscore control codes, ``ESC [ 4 m'', to represent the italic face; and the ANSI control codes, ``ESC [ 0 m'', to represent the ROMAN face. No .BI \-f font specification is permitted with the ANSI device. .PP When the NONE device is selected, .I cawf uses no special output codes to represent the type faces. No .BI \-f font specification is permitted with the ANSI device. .PP The NORMAL output device is the default. When it's selected, .I cawf overprints each bold character two times, using three issuances of each bold character, separated by backspace characters; it issues an underscore and backspace before each italic character. No .BI \-f font specification is permitted with the ANSI device. The .IR bsfilt (1) filter may be used to further process the backspace codes output for a NORMAL device. .PP All other devices named in the .BI \-d device option must be represented by a stanza in the device configuration file. The device configuration file is usually contained in .I device.cf in .IR cawf's library directory (see the .B FILES section for more information). An alternate device configuration file path may be specified with the .BI \-c config option. .PP The .B DEVICE CONFIGURATION FILE section describes the organization of the device configuration file. It is easy to add devices to the .I device.cf supplied in the .I cawf distribution. .PP The .BI \-f font option may be used with the .BI \-d device option, when the appropriate stanza in the device configuration file contains an entry for the named .IR font . The .B DEVICE CONFIGURATION FILE section describes how fonts are defined in device configuration file stanzas. .SH DEVICE CONFIGURATION FILE The device configuration file defines the special character codes necessary to direct output devices to select fonts and to produce bold, italic and Roman type faces. .PP The configuration file is usually found in .I device.cf in .IR cawf 's library directory (see the .B FILES section for more information). It is organized into two main parts \- comments and device stanzas. Comments are any lines that begin with the pound sign (`#') character. They are informational only and .I cawf ignores them. .I Cawf also ignores empty lines, so they may be used as vertical white space. .PP Stanzas name devices and define their font and type face control strings. A stanza begins with the name of the device, starting at the beginning of a line and occupying the entire line. The body of the stanza, defining fonts and type faces, is formed of lines beginning with white space (a TAB or space characters) that directly follow the device name. .PP Individual lines of the stanza body contain a key character, followed by a equal sign, followed by the font name (if a font key) and the output device control codes. .I Cawf issues the font control codes once, at the beginning of output, so only one font may be selected. The type face control codes are issued at each change of type face. .PP The key characters are: .ne 4 .DS b for bold f for font definition i for italic r for Roman .DE The `b', `i' and `r' key codes are followed by an equal sign (`=') and their control code definition. The `f' key code is followed by an equal sign (`='), the font name, another equal sign and the font control code definition. .PP Control code definitions may contain any printable ASCII characters. Non\-printable characters may be encoded in octal notation with the `\\nnn' form or in hexadecimal with the `\\xnn' form. The special code, `\\E' (or `\\e') represents the ESC control character (\\033 or \\x1b). .PP Here's a sample showing the definition for the HP LaserJet III. The stanza name is ``lj3''. All its non\-printable characters are ESCs; the first is coded in octal form; the second with '\\E'; the rest, in hexadecimal form. TAB is used as the leading white space character for the stanza body lines. .DS # HP LaserJet III lj3 b=\\033(s7B i=\\E(s1S r=\\x1b(s0B\\x1b(s0S f=c10=\x1b&l0O\x1b(8U\x1b(s0p12h10v0s0b3T f=c12ibm=\x1b&l0O\x1b(10U\x1b(s0p10.00h12.0v0s0b3T f=lg12=\x1b&l0O\x1b(8U\x1b(s12h12v0s0b6T .DE .PP The distribution .I device.cf file defines the following devices and fonts. .LP .ta \w'kxp1180'u+3n +\w'Italic:'u+3n +\w'bps10'u+6n .nf .ne 3 epson dot matrix printer in Epson FX-86e/FX-800 mode Bold: Double-strike Fonts: none .ne 4 ibmppds IBM Personal Printer Data Stream (PPDS) protocol Bold: Double-strike Italic: Underline Fonts: none .ne 12 kxp1124 Panasonic KX\-P1124 dot matrix printer in PGM mode Bold: Emphasized Fonts: c10 10 Characters Per Inch (CPI) Courier c12 12 CPI Courier bps10 10 CPI Bold PS bps12 12 CPI Bold PS p10 10 CPI Prestige p12 12 CPI Prestige s10 10 CPI Script s12 12 CPI Script ss10 10 CPI Sans Serif ss12 12 CPI Sans Serif .ne 10 kxp1180 Panasonic KX\-P1180 dot matrix printer in PGM mode Bold: Emphasized Fonts: c10 10 Characters Per Inch (CPI) Courier c12 12 CPI Courier bps10 10 CPI Bold PS bps12 12 CPI Bold PS p10 10 CPI Prestige p12 12 CPI Prestige ss10 10 CPI Sans Serif ss12 12 CPI Sans Serif .ne 6 lj3 HP LaserJet III Fonts: c10 10 point, 12 Characters Per Inch (CPI) Courier c12ibm 12 point, 10 CPI Courier, IBM\-PC Symbol Set lg12 12 point, 12 CPI Letter Gothic .ne 4 vgamono VGA monochrome monitor for MS\-DOS (ANSI.SYS driver required for MS\-DOS) Italic: Reverse-video Fonts: none .SH FILES .I Cawf resource files are located in the .I cawf library directory \- \fI C:\\SYS\\LIB\\CAWF\fP, the MS\-DOS environment default; or .IR /usr/lib/cawf , the UNIX environment default. These defaults can be overridden by the CAWFLIB environment variable, or changed in the cawflib.h header file. .ta \w'device.cf'u+3n .nf common common device-independent initialization device.cf output device configurations *.dev device-specific initialization m*.mac macro package files .SH DIAGNOSTICS Unlike .IR nroff , .I cawf complains whenever it sees unknown requests. All diagnostics appear on the standard error file. .ad .SH HISTORY Vic Abell of Purdue University derived .I cawf from .IR awf , \&``the Amazingly Workable (text) Formatter,'' written by Henry Spencer of the University of Toronto. The Toronto work was a supplement to the C News project. The Purdue effort was aimed at producing a C language version that would run on small systems, particularly MS\-DOS ones. The adaptation of the .B me macros was done by Chet Creider . Chet also contributed ideas for device, font and type face support. .PP The MS\-DOS version of .I cawf has been compiled with version 2.5 of Microsoft's Quick-C compiler. It runs under the Mortis Kern Systems Toolkit KornShell, .IR ksh (1), and COMMAND.COM. .SH BUGS Nroff and troff mavens will have many complaints. Some may even represent bugs and not deliberate omissions. .PP Watch out for scaling factors - especially on requests like .BR \ew . .PP The overprinting required to create bold and italicized characters is tiresome on a slow printer. The .IR bsfilt (1) post\-filter from this distribution may be used to alleviate that nuisance by managing the backspacing codes from .IR cawf 's NORMAL device output. .PP The printing of bold and italic characters is sometimes better handled by special printer codes. Use .IR cawf 's .B \-c .IR config , .BI \-d device and .BI \-f font options to produce special font and device output control codes. .PP .I Cawf has a small amount of built-in code for the .BR man , .B me and .B ms macro packages, but none for any others. .PP The stacking for the .B .so request is limited. .SH SEE ALSO bsfilt(1), colcrt(1), man(7), me(7), ms(7) and nroff(1). .TH CDPLAY 1 .SH NAME cdplay \- play audio compact disks .SH SYNOPSIS \fBcdplay\fP [ \-\fBa\fP]|[\-\fBr\fP] .SH DESCRIPTION \fBCdplay\fP is an audio\-cdplayer it can be used interactively or non-interactively. With no flags \fBcdplay\fP is used interactively. When used interactively \fBcdplay\fP can be either in non-playing or playing mode. In non-playing mode you can select tracks to be played. In playing mode \fBcdplay\fP shows the track-time, remaining track-time, total-time and remaining total-time. \fBCdplay\fP assumes the drive to be at \fI/dev/cd0\fP. .PP During non-playing mode the following commands are available: .IP cursor-up/down browse through the track-list .IP spacebar add track to the play-list .IP backspace remove a track from the play-list .IP s start playing the tracks in the play-list. When the play-list is empty start playing from the current position in the track-list until the end of the cd .IP p play the track on the current position in the track-list .IP r play all tracks in a random order (shuffle play) .IP e exit cdplay .SH During playing mode the following commands are available: .IP s stop playing, return to non-playing mode .IP spacebar pause/resume current track .IP cursor-up/down skip to next/previous track .SH OPTIONS When one of these options is used \fBcdplay\fP does everything in the background. .IP \-a Play all tracks, \fBcdplay\fP tells the drive to play all tracks and then it immediately returns to the user .IP \-r Play all tracks in random order (shuffle play). \fBCdplay\fP forks of a new process which starts up a track, during that track it sleeps. When the track is finished it wakes up to start the next track and goes to sleep again. The parent process immediately returns to the user. .SH BUGS \fBCdplay\fP does not sense if a cd has changed, so don't switch cd's. If you want to play another cd you have to insert the new cd and start \fBcdplay\fP again. .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH EJECT 1 .SH NAME eject \- eject removable media .SH SYNOPSIS .B eject .I device .SH DESCRIPTION .B Eject tells a device to eject removable media, usually a floppy or CD-ROM. .B Eject invokes the .B DIOCEJECT ioctl on the device. The media will then be ejected, or allowed to be removed. The call will fail if the device is still in use. .PP Tapes can't be unloaded with this command, use .B mt offline instead. .SH "SEE ALSO" .BR mt (1), .BR hd (4), .BR sd (4). .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH FLEX 1 "26 May 1990" "Version 2.3" .SH NAME flex, lex - fast lexical analyzer generator .SH SYNOPSIS .B flex .B [-bcdfinpstvFILT8 -C[efmF] -Sskeleton] .I [filename ...] .SH DESCRIPTION .I flex is a tool for generating .I scanners: programs which recognized lexical patterns in text. .I flex reads the given input files, or its standard input if no file names are given, for a description of a scanner to generate. The description is in the form of pairs of regular expressions and C code, called .I rules. flex generates as output a C source file, .B lex.yy.c, which defines a routine .B yylex(). This file is compiled and linked with the .B -lfl library to produce an executable. When the executable is run, it analyzes its input for occurrences of the regular expressions. Whenever it finds one, it executes the corresponding C code. .LP For full documentation, see .B flexdoc(1). This manual entry is intended for use as a quick reference. .SH OPTIONS .I flex has the following options: .TP .B -b Generate backtracking information to .I lex.backtrack. This is a list of scanner states which require backtracking and the input characters on which they do so. By adding rules one can remove backtracking states. If all backtracking states are eliminated and .B -f or .B -F is used, the generated scanner will run faster. .TP .B -c is a do-nothing, deprecated option included for POSIX compliance. .IP .B NOTE: in previous releases of .I flex .B -c specified table-compression options. This functionality is now given by the .B -C flag. To ease the the impact of this change, when .I flex encounters .B -c, it currently issues a warning message and assumes that .B -C was desired instead. In the future this "promotion" of .B -c to .B -C will go away in the name of full POSIX compliance (unless the POSIX meaning is removed first). .TP .B -d makes the generated scanner run in .I debug mode. Whenever a pattern is recognized and the global .B yy_flex_debug is non-zero (which is the default), the scanner will write to .I stderr a line of the form: .nf --accepting rule at line 53 ("the matched text") .fi The line number refers to the location of the rule in the file defining the scanner (i.e., the file that was fed to flex). Messages are also generated when the scanner backtracks, accepts the default rule, reaches the end of its input buffer (or encounters a NUL; the two look the same as far as the scanner's concerned), or reaches an end-of-file. .TP .B -f specifies (take your pick) .I full table or .I fast scanner. No table compression is done. The result is large but fast. This option is equivalent to .B -Cf (see below). .TP .B -i instructs .I flex to generate a .I case-insensitive scanner. The case of letters given in the .I flex input patterns will be ignored, and tokens in the input will be matched regardless of case. The matched text given in .I yytext will have the preserved case (i.e., it will not be folded). .TP .B -n is another do-nothing, deprecated option included only for POSIX compliance. .TP .B -p generates a performance report to stderr. The report consists of comments regarding features of the .I flex input file which will cause a loss of performance in the resulting scanner. .TP .B -s causes the .I default rule (that unmatched scanner input is echoed to .I stdout) to be suppressed. If the scanner encounters input that does not match any of its rules, it aborts with an error. .TP .B -t instructs .I flex to write the scanner it generates to standard output instead of .B lex.yy.c. .TP .B -v specifies that .I flex should write to .I stderr a summary of statistics regarding the scanner it generates. .TP .B -F specifies that the .I fast scanner table representation should be used. This representation is about as fast as the full table representation .RB ( \-f ), and for some sets of patterns will be considerably smaller (and for others, larger). See .B flexdoc(1) for details. .IP This option is equivalent to .B -CF (see below). .TP .B -I instructs .I flex to generate an .I interactive scanner, that is, a scanner which stops immediately rather than looking ahead if it knows that the currently scanned text cannot be part of a longer rule's match. Again, see .B flexdoc(1) for details. .IP Note, .B -I cannot be used in conjunction with .I full or .I fast tables, i.e., the .B -f, -F, -Cf, or .B -CF flags. .TP .B -L instructs .I flex not to generate .B #line directives in .B lex.yy.c. The default is to generate such directives so error messages in the actions will be correctly located with respect to the original .I flex input file, and not to the fairly meaningless line numbers of .B lex.yy.c. .TP .B -T makes .I flex run in .I trace mode. It will generate a lot of messages to .I stdout concerning the form of the input and the resultant non-deterministic and deterministic finite automata. This option is mostly for use in maintaining .I flex. .TP .B -8 instructs .I flex to generate an 8-bit scanner. On some sites, this is the default. On others, the default is 7-bit characters. To see which is the case, check the verbose .B (-v) output for "equivalence classes created". If the denominator of the number shown is 128, then by default .I flex is generating 7-bit characters. If it is 256, then the default is 8-bit characters. .TP .B -C[efmF] controls the degree of table compression. .IP .B -Ce directs .I flex to construct .I equivalence classes, i.e., sets of characters which have identical lexical properties. Equivalence classes usually give dramatic reductions in the final table/object file sizes (typically a factor of 2-5) and are pretty cheap performance-wise (one array look-up per character scanned). .IP .B -Cf specifies that the .I full scanner tables should be generated - .I flex should not compress the tables by taking advantages of similar transition functions for different states. .IP .B -CF specifies that the alternate fast scanner representation (described in .B flexdoc(1)) should be used. .IP .B -Cm directs .I flex to construct .I meta-equivalence classes, which are sets of equivalence classes (or characters, if equivalence classes are not being used) that are commonly used together. Meta-equivalence classes are often a big win when using compressed tables, but they have a moderate performance impact (one or two "if" tests and one array look-up per character scanned). .IP A lone .B -C specifies that the scanner tables should be compressed but neither equivalence classes nor meta-equivalence classes should be used. .IP The options .B -Cf or .B -CF and .B -Cm do not make sense together - there is no opportunity for meta-equivalence classes if the table is not being compressed. Otherwise the options may be freely mixed. .IP The default setting is .B -Cem, which specifies that .I flex should generate equivalence classes and meta-equivalence classes. This setting provides the highest degree of table compression. You can trade off faster-executing scanners at the cost of larger tables with the following generally being true: .nf slowest & smallest -Cem -Cm -Ce -C -C{f,F}e -C{f,F} fastest & largest .fi .IP .B -C options are not cumulative; whenever the flag is encountered, the previous -C settings are forgotten. .TP .B -Sskeleton_file overrides the default skeleton file from which .I flex constructs its scanners. You'll never need this option unless you are doing .I flex maintenance or development. .SH SUMMARY OF FLEX REGULAR EXPRESSIONS The patterns in the input are written using an extended set of regular expressions. These are: .nf x match the character 'x' . any character except newline [xyz] a "character class"; in this case, the pattern matches either an 'x', a 'y', or a 'z' [abj-oZ] a "character class" with a range in it; matches an 'a', a 'b', any letter from 'j' through 'o', or a 'Z' [^A-Z] a "negated character class", i.e., any character but those in the class. In this case, any character EXCEPT an uppercase letter. [^A-Z\\n] any character EXCEPT an uppercase letter or a newline r* zero or more r's, where r is any regular expression r+ one or more r's r? zero or one r's (that is, "an optional r") r{2,5} anywhere from two to five r's r{2,} two or more r's r{4} exactly 4 r's {name} the expansion of the "name" definition (see above) "[xyz]\\"foo" the literal string: [xyz]"foo \\X if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', then the ANSI-C interpretation of \\x. Otherwise, a literal 'X' (used to escape operators such as '*') \\123 the character with octal value 123 \\x2a the character with hexadecimal value 2a (r) match an r; parentheses are used to override precedence (see below) rs the regular expression r followed by the regular expression s; called "concatenation" r|s either an r or an s r/s an r but only if it is followed by an s. The s is not part of the matched text. This type of pattern is called as "trailing context". ^r an r, but only at the beginning of a line r$ an r, but only at the end of a line. Equivalent to "r/\\n". r an r, but only in start condition s (see below for discussion of start conditions) r same, but in any of start conditions s1, s2, or s3 <> an end-of-file <> an end-of-file when in start condition s1 or s2 .fi The regular expressions listed above are grouped according to precedence, from highest precedence at the top to lowest at the bottom. Those grouped together have equal precedence. .LP Some notes on patterns: .IP - Negated character classes .I match newlines unless "\\n" (or an equivalent escape sequence) is one of the characters explicitly present in the negated character class (e.g., "[^A-Z\\n]"). .IP - A rule can have at most one instance of trailing context (the '/' operator or the '$' operator). The start condition, '^', and "<>" patterns can only occur at the beginning of a pattern, and, as well as with '/' and '$', cannot be grouped inside parentheses. The following are all illegal: .nf foo/bar$ foo|(bar$) foo|^bar foobar .fi .SH SUMMARY OF SPECIAL ACTIONS In addition to arbitrary C code, the following can appear in actions: .IP - .B ECHO copies yytext to the scanner's output. .IP - .B BEGIN followed by the name of a start condition places the scanner in the corresponding start condition. .IP - .B REJECT directs the scanner to proceed on to the "second best" rule which matched the input (or a prefix of the input). .B yytext and .B yyleng are set up appropriately. Note that .B REJECT is a particularly expensive feature in terms scanner performance; if it is used in .I any of the scanner's actions it will slow down .I all of the scanner's matching. Furthermore, .B REJECT cannot be used with the .I -f or .I -F options. .IP Note also that unlike the other special actions, .B REJECT is a .I branch; code immediately following it in the action will .I not be executed. .IP - .B yymore() tells the scanner that the next time it matches a rule, the corresponding token should be .I appended onto the current value of .B yytext rather than replacing it. .IP - .B yyless(n) returns all but the first .I n characters of the current token back to the input stream, where they will be rescanned when the scanner looks for the next match. .B yytext and .B yyleng are adjusted appropriately (e.g., .B yyleng will now be equal to .I n ). .IP - .B unput(c) puts the character .I c back onto the input stream. It will be the next character scanned. .IP - .B input() reads the next character from the input stream (this routine is called .B yyinput() if the scanner is compiled using .B C++). .IP - .B yyterminate() can be used in lieu of a return statement in an action. It terminates the scanner and returns a 0 to the scanner's caller, indicating "all done". .IP By default, .B yyterminate() is also called when an end-of-file is encountered. It is a macro and may be redefined. .IP - .B YY_NEW_FILE is an action available only in <> rules. It means "Okay, I've set up a new input file, continue scanning". .IP - .B yy_create_buffer( file, size ) takes a .I FILE pointer and an integer .I size. It returns a YY_BUFFER_STATE handle to a new input buffer large enough to accomodate .I size characters and associated with the given file. When in doubt, use .B YY_BUF_SIZE for the size. .IP - .B yy_switch_to_buffer( new_buffer ) switches the scanner's processing to scan for tokens from the given buffer, which must be a YY_BUFFER_STATE. .IP - .B yy_delete_buffer( buffer ) deletes the given buffer. .SH VALUES AVAILABLE TO THE USER .IP - .B char *yytext holds the text of the current token. It may not be modified. .IP - .B int yyleng holds the length of the current token. It may not be modified. .IP - .B FILE *yyin is the file which by default .I flex reads from. It may be redefined but doing so only makes sense before scanning begins. Changing it in the middle of scanning will have unexpected results since .I flex buffers its input. Once scanning terminates because an end-of-file has been seen, .B void yyrestart( FILE *new_file ) may be called to point .I yyin at the new input file. .IP - .B FILE *yyout is the file to which .B ECHO actions are done. It can be reassigned by the user. .IP - .B YY_CURRENT_BUFFER returns a .B YY_BUFFER_STATE handle to the current buffer. .SH MACROS THE USER CAN REDEFINE .IP - .B YY_DECL controls how the scanning routine is declared. By default, it is "int yylex()", or, if prototypes are being used, "int yylex(void)". This definition may be changed by redefining the "YY_DECL" macro. Note that if you give arguments to the scanning routine using a K&R-style/non-prototyped function declaration, you must terminate the definition with a semi-colon (;). .IP - The nature of how the scanner gets its input can be controlled by redefining the .B YY_INPUT macro. YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its action is to place up to .I max_size characters in the character array .I buf and return in the integer variable .I result either the number of characters read or the constant YY_NULL (0 on Unix systems) to indicate EOF. The default YY_INPUT reads from the global file-pointer "yyin". A sample redefinition of YY_INPUT (in the definitions section of the input file): .nf %{ #undef YY_INPUT #define YY_INPUT(buf,result,max_size) \\ { \\ int c = getchar(); \\ result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \\ } %} .fi .IP - When the scanner receives an end-of-file indication from YY_INPUT, it then checks the .B yywrap() function. If .B yywrap() returns false (zero), then it is assumed that the function has gone ahead and set up .I yyin to point to another input file, and scanning continues. If it returns true (non-zero), then the scanner terminates, returning 0 to its caller. .IP The default .B yywrap() always returns 1. Presently, to redefine it you must first "#undef yywrap", as it is currently implemented as a macro. It is likely that .B yywrap() will soon be defined to be a function rather than a macro. .IP - YY_USER_ACTION can be redefined to provide an action which is always executed prior to the matched rule's action. .IP - The macro .B YY_USER_INIT may be redefined to provide an action which is always executed before the first scan. .IP - In the generated scanner, the actions are all gathered in one large switch statement and separated using .B YY_BREAK, which may be redefined. By default, it is simply a "break", to separate each rule's action from the following rule's. .SH FILES .TP .I flex.skel skeleton scanner. .TP .I lex.yy.c generated scanner (called .I lexyy.c on some systems). .TP .I lex.backtrack backtracking information for .B -b flag (called .I lex.bck on some systems). .TP .B -lfl library with which to link the scanners. .SH "SEE ALSO" .LP flexdoc(1), lex(1), yacc(1), sed(1), awk(1). .LP M. E. Lesk and E. Schmidt, .I LEX - Lexical Analyzer Generator .SH DIAGNOSTICS .I reject_used_but_not_detected undefined or .LP .I yymore_used_but_not_detected undefined - These errors can occur at compile time. They indicate that the scanner uses .B REJECT or .B yymore() but that .I flex failed to notice the fact, meaning that .I flex scanned the first two sections looking for occurrences of these actions and failed to find any, but somehow you snuck some in (via a #include file, for example). Make an explicit reference to the action in your .I flex input file. (Note that previously .I flex supported a .B %used/%unused mechanism for dealing with this problem; this feature is still supported but now deprecated, and will go away soon unless the author hears from people who can argue compellingly that they need it.) .LP .I flex scanner jammed - a scanner compiled with .B -s has encountered an input string which wasn't matched by any of its rules. .LP .I flex input buffer overflowed - a scanner rule matched a string long enough to overflow the scanner's internal input buffer (16K bytes - controlled by .B YY_BUF_MAX in "flex.skel"). .LP .I scanner requires -8 flag - Your scanner specification includes recognizing 8-bit characters and you did not specify the -8 flag (and your site has not installed flex with -8 as the default). .LP .I fatal flex scanner internal error--end of buffer missed - This can occur in an scanner which is reentered after a long-jump has jumped out (or over) the scanner's activation frame. Before reentering the scanner, use: .nf yyrestart( yyin ); .fi .LP .I too many %t classes! - You managed to put every single character into its own %t class. .I flex requires that at least one of the classes share characters. .SH AUTHOR Vern Paxson, with the help of many ideas and much inspiration from Van Jacobson. Original version by Jef Poskanzer. .LP See flexdoc(1) for additional credits and the address to send comments to. .SH DEFICIENCIES / BUGS .LP Some trailing context patterns cannot be properly matched and generate warning messages ("Dangerous trailing context"). These are patterns where the ending of the first part of the rule matches the beginning of the second part, such as "zx*/xy*", where the 'x*' matches the 'x' at the beginning of the trailing context. (Note that the POSIX draft states that the text matched by such patterns is undefined.) .LP For some trailing context rules, parts which are actually fixed-length are not recognized as such, leading to the abovementioned performance loss. In particular, parts using '|' or {n} (such as "foo{3}") are always considered variable-length. .LP Combining trailing context with the special '|' action can result in .I fixed trailing context being turned into the more expensive .I variable trailing context. For example, this happens in the following example: .nf %% abc | xyz/def .fi .LP Use of unput() invalidates yytext and yyleng. .LP Use of unput() to push back more text than was matched can result in the pushed-back text matching a beginning-of-line ('^') rule even though it didn't come at the beginning of the line (though this is rare!). .LP Pattern-matching of NUL's is substantially slower than matching other characters. .LP .I flex does not generate correct #line directives for code internal to the scanner; thus, bugs in .I flex.skel yield bogus line numbers. .LP Due to both buffering of input and read-ahead, you cannot intermix calls to routines, such as, for example, .B getchar(), with .I flex rules and expect it to work. Call .B input() instead. .LP The total table entries listed by the .B -v flag excludes the number of table entries needed to determine what rule has been matched. The number of entries is equal to the number of DFA states if the scanner does not use .B REJECT, and somewhat greater than the number of states if it does. .LP .B REJECT cannot be used with the .I -f or .I -F options. .LP Some of the macros, such as .B yywrap(), may in the future become functions which live in the .B -lfl library. This will doubtless break a lot of code, but may be required for POSIX-compliance. .LP The .I flex internal algorithms need documentation. .TH FLEX 1 "26 May 1990" "Version 2.3" .SH NAME flexdoc - fast lexical analyzer generator .SH SYNOPSIS .B flex .B [-bcdfinpstvFILT8 -C[efmF] -Sskeleton] .I [filename ...] .SH DESCRIPTION .I flex is a tool for generating .I scanners: programs which recognized lexical patterns in text. .I flex reads the given input files, or its standard input if no file names are given, for a description of a scanner to generate. The description is in the form of pairs of regular expressions and C code, called .I rules. flex generates as output a C source file, .B lex.yy.c, which defines a routine .B yylex(). This file is compiled and linked with the .B -lfl library to produce an executable. When the executable is run, it analyzes its input for occurrences of the regular expressions. Whenever it finds one, it executes the corresponding C code. .SH SOME SIMPLE EXAMPLES .LP First some simple examples to get the flavor of how one uses .I flex. The following .I flex input specifies a scanner which whenever it encounters the string "username" will replace it with the user's login name: .nf %% username printf( "%s", getlogin() ); .fi By default, any text not matched by a .I flex scanner is copied to the output, so the net effect of this scanner is to copy its input file to its output with each occurrence of "username" expanded. In this input, there is just one rule. "username" is the .I pattern and the "printf" is the .I action. The "%%" marks the beginning of the rules. .LP Here's another simple example: .nf int num_lines = 0, num_chars = 0; %% \\n ++num_lines; ++num_chars; . ++num_chars; %% main() { yylex(); printf( "# of lines = %d, # of chars = %d\\n", num_lines, num_chars ); } .fi This scanner counts the number of characters and the number of lines in its input (it produces no output other than the final report on the counts). The first line declares two globals, "num_lines" and "num_chars", which are accessible both inside .B yylex() and in the .B main() routine declared after the second "%%". There are two rules, one which matches a newline ("\\n") and increments both the line count and the character count, and one which matches any character other than a newline (indicated by the "." regular expression). .LP A somewhat more complicated example: .nf /* scanner for a toy Pascal-like language */ %{ /* need this for the call to atof() below */ #include %} DIGIT [0-9] ID [a-z][a-z0-9]* %% {DIGIT}+ { printf( "An integer: %s (%d)\\n", yytext, atoi( yytext ) ); } {DIGIT}+"."{DIGIT}* { printf( "A float: %s (%g)\\n", yytext, atof( yytext ) ); } if|then|begin|end|procedure|function { printf( "A keyword: %s\\n", yytext ); } {ID} printf( "An identifier: %s\\n", yytext ); "+"|"-"|"*"|"/" printf( "An operator: %s\\n", yytext ); "{"[^}\\n]*"}" /* eat up one-line comments */ [ \\t\\n]+ /* eat up whitespace */ . printf( "Unrecognized character: %s\\n", yytext ); %% main( argc, argv ) int argc; char **argv; { ++argv, --argc; /* skip over program name */ if ( argc > 0 ) yyin = fopen( argv[0], "r" ); else yyin = stdin; yylex(); } .fi This is the beginnings of a simple scanner for a language like Pascal. It identifies different types of .I tokens and reports on what it has seen. .LP The details of this example will be explained in the following sections. .SH FORMAT OF THE INPUT FILE The .I flex input file consists of three sections, separated by a line with just .B %% in it: .nf definitions %% rules %% user code .fi The .I definitions section contains declarations of simple .I name definitions to simplify the scanner specification, and declarations of .I start conditions, which are explained in a later section. .LP Name definitions have the form: .nf name definition .fi The "name" is a word beginning with a letter or an underscore ('_') followed by zero or more letters, digits, '_', or '-' (dash). The definition is taken to begin at the first non-white-space character following the name and continuing to the end of the line. The definition can subsequently be referred to using "{name}", which will expand to "(definition)". For example, .nf DIGIT [0-9] ID [a-z][a-z0-9]* .fi defines "DIGIT" to be a regular expression which matches a single digit, and "ID" to be a regular expression which matches a letter followed by zero-or-more letters-or-digits. A subsequent reference to .nf {DIGIT}+"."{DIGIT}* .fi is identical to .nf ([0-9])+"."([0-9])* .fi and matches one-or-more digits followed by a '.' followed by zero-or-more digits. .LP The .I rules section of the .I flex input contains a series of rules of the form: .nf pattern action .fi where the pattern must be unindented and the action must begin on the same line. .LP See below for a further description of patterns and actions. .LP Finally, the user code section is simply copied to .B lex.yy.c verbatim. It is used for companion routines which call or are called by the scanner. The presence of this section is optional; if it is missing, the second .B %% in the input file may be skipped, too. .LP In the definitions and rules sections, any .I indented text or text enclosed in .B %{ and .B %} is copied verbatim to the output (with the %{}'s removed). The %{}'s must appear unindented on lines by themselves. .LP In the rules section, any indented or %{} text appearing before the first rule may be used to declare variables which are local to the scanning routine and (after the declarations) code which is to be executed whenever the scanning routine is entered. Other indented or %{} text in the rule section is still copied to the output, but its meaning is not well-defined and it may well cause compile-time errors (this feature is present for .I POSIX compliance; see below for other such features). .LP In the definitions section, an unindented comment (i.e., a line beginning with "/*") is also copied verbatim to the output up to the next "*/". Also, any line in the definitions section beginning with '#' is ignored, though this style of comment is deprecated and may go away in the future. .SH PATTERNS The patterns in the input are written using an extended set of regular expressions. These are: .nf x match the character 'x' . any character except newline [xyz] a "character class"; in this case, the pattern matches either an 'x', a 'y', or a 'z' [abj-oZ] a "character class" with a range in it; matches an 'a', a 'b', any letter from 'j' through 'o', or a 'Z' [^A-Z] a "negated character class", i.e., any character but those in the class. In this case, any character EXCEPT an uppercase letter. [^A-Z\\n] any character EXCEPT an uppercase letter or a newline r* zero or more r's, where r is any regular expression r+ one or more r's r? zero or one r's (that is, "an optional r") r{2,5} anywhere from two to five r's r{2,} two or more r's r{4} exactly 4 r's {name} the expansion of the "name" definition (see above) "[xyz]\\"foo" the literal string: [xyz]"foo \\X if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', then the ANSI-C interpretation of \\x. Otherwise, a literal 'X' (used to escape operators such as '*') \\123 the character with octal value 123 \\x2a the character with hexadecimal value 2a (r) match an r; parentheses are used to override precedence (see below) rs the regular expression r followed b     y the regular expression s; called "concatenation" r|s either an r or an s r/s an r but only if it is followed by an s. The s is not part of the matched text. This type of pattern is called as "trailing context". ^r an r, but only at the beginning of a line r$ an r, but only at the end of a line. Equivalent to "r/\\n". r an r, but only in start condition s (see below for discussion of start conditions) r same, but in any of start conditions s1, s2, or s3 <> an end-of-file <> an end-of-file when in start condition s1 or s2 .fi The regular expressions listed above are grouped according to precedence, from highest precedence at the top to lowest at the bottom. Those grouped together have equal precedence. For example, .nf foo|bar* .fi is the same as .nf (foo)|(ba(r*)) .fi since the '*' operator has higher precedence than concatenation, and concatenation higher than alternation ('|'). This pattern therefore matches .I either the string "foo" .I or the string "ba" followed by zero-or-more r's. To match "foo" or zero-or-more "bar"'s, use: .nf foo|(bar)* .fi and to match zero-or-more "foo"'s-or-"bar"'s: .nf (foo|bar)* .fi .LP Some notes on patterns: .IP - A negated character class such as the example "[^A-Z]" above .I will match a newline unless "\\n" (or an equivalent escape sequence) is one of the characters explicitly present in the negated character class (e.g., "[^A-Z\\n]"). This is unlike how many other regular expression tools treat negated character classes, but unfortunately the inconsistency is historically entrenched. Matching newlines means that a pattern like [^"]* can match an entire input (overflowing the scanner's input buffer) unless there's another quote in the input. .IP - A rule can have at most one instance of trailing context (the '/' operator or the '$' operator). The start condition, '^', and "<>" patterns can only occur at the beginning of a pattern, and, as well as with '/' and '$', cannot be grouped inside parentheses. A '^' which does not occur at the beginning of a rule or a '$' which does not occur at the end of a rule loses its special properties and is treated as a normal character. .IP The following are illegal: .nf foo/bar$ foobar .fi Note that the first of these, can be written "foo/bar\\n". .IP The following will result in '$' or '^' being treated as a normal character: .nf foo|(bar$) foo|^bar .fi If what's wanted is a "foo" or a bar-followed-by-a-newline, the following could be used (the special '|' action is explained below): .nf foo | bar$ /* action goes here */ .fi A similar trick will work for matching a foo or a bar-at-the-beginning-of-a-line. .SH HOW THE INPUT IS MATCHED When the generated scanner is run, it analyzes its input looking for strings which match any of its patterns. If it finds more than one match, it takes the one matching the most text (for trailing context rules, this includes the length of the trailing part, even though it will then be returned to the input). If it finds two or more matches of the same length, the rule listed first in the .I flex input file is chosen. .LP Once the match is determined, the text corresponding to the match (called the .I token) is made available in the global character pointer .B yytext, and its length in the global integer .B yyleng. The .I action corresponding to the matched pattern is then executed (a more detailed description of actions follows), and then the remaining input is scanned for another match. .LP If no match is found, then the .I default rule is executed: the next character in the input is considered matched and copied to the standard output. Thus, the simplest legal .I flex input is: .nf %% .fi which generates a scanner that simply copies its input (one character at a time) to its output. .SH ACTIONS Each pattern in a rule has a corresponding action, which can be any arbitrary C statement. The pattern ends at the first non-escaped whitespace character; the remainder of the line is its action. If the action is empty, then when the pattern is matched the input token is simply discarded. For example, here is the specification for a program which deletes all occurrences of "zap me" from its input: .nf %% "zap me" .fi (It will copy all other characters in the input to the output since they will be matched by the default rule.) .LP Here is a program which compresses multiple blanks and tabs down to a single blank, and throws away whitespace found at the end of a line: .nf %% [ \\t]+ putchar( ' ' ); [ \\t]+$ /* ignore this token */ .fi .LP If the action contains a '{', then the action spans till the balancing '}' is found, and the action may cross multiple lines. .I flex knows about C strings and comments and won't be fooled by braces found within them, but also allows actions to begin with .B %{ and will consider the action to be all the text up to the next .B %} (regardless of ordinary braces inside the action). .LP An action consisting solely of a vertical bar ('|') means "same as the action for the next rule." See below for an illustration. .LP Actions can include arbitrary C code, including .B return statements to return a value to whatever routine called .B yylex(). Each time .B yylex() is called it continues processing tokens from where it last left off until it either reaches the end of the file or executes a return. Once it reaches an end-of-file, however, then any subsequent call to .B yylex() will simply immediately return, unless .B yyrestart() is first called (see below). .LP Actions are not allowed to modify yytext or yyleng. .LP There are a number of special directives which can be included within an action: .IP - .B ECHO copies yytext to the scanner's output. .IP - .B BEGIN followed by the name of a start condition places the scanner in the corresponding start condition (see below). .IP - .B REJECT directs the scanner to proceed on to the "second best" rule which matched the input (or a prefix of the input). The rule is chosen as described above in "How the Input is Matched", and .B yytext and .B yyleng set up appropriately. It may either be one which matched as much text as the originally chosen rule but came later in the .I flex input file, or one which matched less text. For example, the following will both count the words in the input and call the routine special() whenever "frob" is seen: .nf int word_count = 0; %% frob special(); REJECT; [^ \\t\\n]+ ++word_count; .fi Without the .B REJECT, any "frob"'s in the input would not be counted as words, since the scanner normally executes only one action per token. Multiple .B REJECT's are allowed, each one finding the next best choice to the currently active rule. For example, when the following scanner scans the token "abcd", it will write "abcdabcaba" to the output: .nf %% a | ab | abc | abcd ECHO; REJECT; .|\\n /* eat up any unmatched character */ .fi (The first three rules share the fourth's action since they use the special '|' action.) .B REJECT is a particularly expensive feature in terms scanner performance; if it is used in .I any of the scanner's actions it will slow down .I all of the scanner's matching. Furthermore, .B REJECT cannot be used with the .I -f or .I -F options (see below). .IP Note also that unlike the other special actions, .B REJECT is a .I branch; code immediately following it in the action will .I not be executed. .IP - .B yymore() tells the scanner that the next time it matches a rule, the corresponding token should be .I appended onto the current value of .B yytext rather than replacing it. For example, given the input "mega-kludge" the following will write "mega-mega-kludge" to the output: .nf %% mega- ECHO; yymore(); kludge ECHO; .fi First "mega-" is matched and echoed to the output. Then "kludge" is matched, but the previous "mega-" is still hanging around at the beginning of .B yytext so the .B ECHO for the "kludge" rule will actually write "mega-kludge". The presence of .B yymore() in the scanner's action entails a minor performance penalty in the scanner's matching speed. .IP - .B yyless(n) returns all but the first .I n characters of the current token back to the input stream, where they will be rescanned when the scanner looks for the next match. .B yytext and .B yyleng are adjusted appropriately (e.g., .B yyleng will now be equal to .I n ). For example, on the input "foobar" the following will write out "foobarbar": .nf %% foobar ECHO; yyless(3); [a-z]+ ECHO; .fi An argument of 0 to .B yyless will cause the entire current input string to be scanned again. Unless you've changed how the scanner will subsequently process its input (using .B BEGIN, for example), this will result in an endless loop. .IP - .B unput(c) puts the character .I c back onto the input stream. It will be the next character scanned. The following action will take the current token and cause it to be rescanned enclosed in parentheses. .nf { int i; unput( ')' ); for ( i = yyleng - 1; i >= 0; --i ) unput( yytext[i] ); unput( '(' ); } .fi Note that since each .B unput() puts the given character back at the .I beginning of the input stream, pushing back strings must be done back-to-front. .IP - .B input() reads the next character from the input stream. For example, the following is one way to eat up C comments: .nf %% "/*" { register int c; for ( ; ; ) { while ( (c = input()) != '*' && c != EOF ) ; /* eat up text of comment */ if ( c == '*' ) { while ( (c = input()) == '*' ) ; if ( c == '/' ) break; /* found the end */ } if ( c == EOF ) { error( "EOF in comment" ); break; } } } .fi (Note that if the scanner is compiled using .B C++, then .B input() is instead referred to as .B yyinput(), in order to avoid a name clash with the .B C++ stream by the name of .I input.) .IP - .B yyterminate() can be used in lieu of a return statement in an action. It terminates the scanner and returns a 0 to the scanner's caller, indicating "all done". Subsequent calls to the scanner will immediately return unless preceded by a call to .B yyrestart() (see below). By default, .B yyterminate() is also called when an end-of-file is encountered. It is a macro and may be redefined. .SH THE GENERATED SCANNER The output of .I flex is the file .B lex.yy.c, which contains the scanning routine .B yylex(), a number of tables used by it for matching tokens, and a number of auxiliary routines and macros. By default, .B yylex() is declared as follows: .nf int yylex() { ... various definitions and the actions in here ... } .fi (If your environment supports function prototypes, then it will be "int yylex( void )".) This definition may be changed by redefining the "YY_DECL" macro. For example, you could use: .nf #undef YY_DECL #define YY_DECL float lexscan( a, b ) float a, b; .fi to give the scanning routine the name .I lexscan, returning a float, and taking two floats as arguments. Note that if you give arguments to the scanning routine using a K&R-style/non-prototyped function declaration, you must terminate the definition with a semi-colon (;). .LP Whenever .B yylex() is called, it scans tokens from the global input file .I yyin (which defaults to stdin). It continues until it either reaches an end-of-file (at which point it returns the value 0) or one of its actions executes a .I return statement. In the former case, when called again the scanner will immediately return unless .B yyrestart() is called to point .I yyin at the new input file. ( .B yyrestart() takes one argument, a .B FILE * pointer.) In the latter case (i.e., when an action executes a return), the scanner may then be called again and it will resume scanning where it left off. .LP By default (and for purposes of efficiency), the scanner uses block-reads rather than simple .I getc() calls to read characters from .I yyin. The nature of how it gets its input can be controlled by redefining the .B YY_INPUT macro. YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its action is to place up to .I max_size characters in the character array .I buf and return in the integer variable .I result either the number of characters read or the constant YY_NULL (0 on Unix systems) to indicate EOF. The default YY_INPUT reads from the global file-pointer "yyin". .LP A sample redefinition of YY_INPUT (in the definitions section of the input file): .nf %{ #undef YY_INPUT #define YY_INPUT(buf,result,max_size) \\ { \\ int c = getchar(); \\ result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \\ } %} .fi This definition will change the input processing to occur one character at a time. .LP You also can add in things like keeping track of the input line number this way; but don't expect your scanner to go very fast. .LP When the scanner receives an end-of-file indication from YY_INPUT, it then checks the .B yywrap() function. If .B yywrap() returns false (zero), then it is assumed that the function has gone ahead and set up .I yyin to point to another input file, and scanning continues. If it returns true (non-zero), then the scanner terminates, returning 0 to its caller. .LP The default .B yywrap() always returns 1. Presently, to redefine it you must first "#undef yywrap", as it is currently implemented as a macro. As indicated by the hedging in the previous sentence, it may be changed to a true function in the near future. .LP The scanner writes its .B ECHO output to the .I yyout global (default, stdout), which may be redefined by the user simply by assigning it to some other .B FILE pointer. .SH START CONDITIONS .I flex provides a mechanism for conditionally activating rules. Any rule whose pattern is prefixed with "" will only be active when the scanner is in the start condition named "sc". For example, .nf [^"]* { /* eat up the string body ... */ ... } .fi will be active only when the scanner is in the "STRING" start condition, and .nf \\. { /* handle an escape ... */ ... } .fi will be active only when the current start condition is either "INITIAL", "STRING", or "QUOTE". .LP Start conditions are declared in the definitions (first) section of the input using unindented lines beginning with either .B %s or .B %x followed by a list of names. The former declares .I inclusive start conditions, the latter .I exclusive start conditions. A start condition is activated using the .B BEGIN action. Until the next .B BEGIN action is executed, rules with the given start condition will be active and rules with other start conditions will be inactive. If the start condition is .I inclusive, then rules with no start conditions at all will also be active. If it is .I exclusive, then .I only rules qualified with the start condition will be active. A set of rules contingent on the same exclusive start condition describe a scanner which is independent of any of the other rules in the .I flex input. Because of this, exclusive start conditions make it easy to specify "mini-scanners" which scan portions of the input that are syntactically different from the rest (e.g., comments). .LP If the distinction between inclusive and exclusive start conditions is still a little vague, here's a simple example illustrating the connection between the two. The set of rules: .nf %s example %% foo /* do something */ .fi is equivalent to .nf %x example %% foo /* do something */ .fi .LP The default rule (to .B ECHO any unmatched character) remains active in start conditions. .LP .B BEGIN(0) returns to the original state where only the rules with no start conditions are active. This state can also be referred to as the start-condition "INITIAL", so .B BEGIN(INITIAL) is equivalent to .B BEGIN(0). (The parentheses around the start condition name are not required but are considered good style.) .LP .B BEGIN actions can also be given as indented code at the beginning of the rules section. For example, the following will cause the scanner to enter the "SPECIAL" start condition whenever .I yylex() is called and the global variable .I enter_special is true: .nf int enter_special; %x SPECIAL %% if ( enter_special ) BEGIN(SPECIAL); blahblahblah ...more rules follow... .fi .LP To illustrate the uses of start conditions, here is a scanner which provides two different interpretations of a string like "123.456". By default it will treat it as as three tokens, the integer "123", a dot ('.'), and the integer "456". But if the string is preceded earlier in the line by the string "expect-floats" it will treat it as a single token, the floating-point number 123.456: .nf %{ #include %} %s expect %% expect-floats BEGIN(expect); [0-9]+"."[0-9]+ { printf( "found a float, = %f\\n", atof( yytext ) ); } \\n { /* that's the end of the line, so * we need another "expect-number" * before we'll recognize any more * numbers */ BEGIN(INITIAL); } [0-9]+ { printf( "found an integer, = %d\\n", atoi( yytext ) ); } "." printf( "found a dot\\n" ); .fi Here is a scanner which recognizes (and discards) C comments while maintaining a count of the current input line. .nf %x comment %% int line_num = 1; "/*" BEGIN(comment); [^*\\n]* /* eat anything that's not a '*' */ "*"+[^*/\\n]* /* eat up '*'s not followed by '/'s */ \\n ++line_num; "*"+"/" BEGIN(INITIAL); .fi Note that start-conditions names are really integer values and can be stored as such. Thus, the above could be extended in the following fashion: .nf %x comment foo %% int line_num = 1; int comment_caller; "/*" { comment_caller = INITIAL; BEGIN(comment); } ... "/*" { comment_caller = foo; BEGIN(comment); } [^*\\n]* /* eat anything that's not a '*' */ "*"+[^*/\\n]* /* eat up '*'s not followed by '/'s */ \\n ++line_num; "*"+"/" BEGIN(comment_caller); .fi One can then implement a "stack" of start conditions using an array of integers. (It is likely that such stacks will become a full-fledged .I flex feature in the future.) Note, though, that start conditions do not have their own name-space; %s's and %x's declare names in the same fashion as #define's. .SH MULTIPLE INPUT BUFFERS Some scanners (such as those which support "include" files) require reading from several input streams. As .I flex scanners do a large amount of buffering, one cannot control where the next input will be read from by simply writing a .B YY_INPUT which is sensitive to the scanning context. .B YY_INPUT is only called when the scanner reaches the end of its buffer, which may be a long time after scanning a statement such as an "include" which requires switching the input source. .LP To negotiate these sorts of problems, .I flex provides a mechanism for creating and switching between multiple input buffers. An input buffer is created by using: .nf YY_BUFFER_STATE yy_create_buffer( FILE *file, int size ) .fi which takes a .I FILE pointer and a size and creates a buffer associated with the given file and large enough to hold .I size characters (when in doubt, use .B YY_BUF_SIZE for the size). It returns a .B YY_BUFFER_STATE handle, which may then be passed to other routines: .nf void yy_switch_to_buffer( YY_BUFFER_STATE new_buffer ) .fi switches the scanner's input buffer so subsequent tokens will come from .I new_buffer. Note that .B yy_switch_to_buffer() may be used by yywrap() to sets things up for continued scanning, instead of opening a new file and pointing .I yyin at it. .nf void yy_delete_buffer( YY_BUFFER_STATE buffer ) .fi is used to reclaim the storage associated with a buffer. .LP .B yy_new_buffer() is an alias for .B yy_create_buffer(), provided for compatibility with the C++ use of .I new and .I delete for creating and destroying dynamic objects. .LP Finally, the .B YY_CURRENT_BUFFER macro returns a .B YY_BUFFER_STATE handle to the current buffer. .LP Here is an example of using these features for writing a scanner which expands include files (the .B <> feature is discussed below): .nf /* the "incl" state is used for picking up the name * of an include file */ %x incl %{ #define MAX_INCLUDE_DEPTH 10 YY_BUFFER_STATE include_stack[MAX_INCLUDE_DEPTH]; int include_stack_ptr = 0; %} %% include BEGIN(incl); [a-z]+ ECHO; [^a-z\\n]*\\n? ECHO; [ \\t]* /* eat the whitespace */ [^ \\t\\n]+ { /* got the include file name */ if ( include_stack_ptr >= MAX_INCLUDE_DEPTH ) { fprintf( stderr, "Includes nested too deeply" ); exit( 1 ); } include_stack[include_stack_ptr++] = YY_CURRENT_BUFFER; yyin = fopen( yytext, "r" ); if ( ! yyin ) error( ... ); yy_switch_to_buffer( yy_create_buffer( yyin, YY_BUF_SIZE ) ); BEGIN(INITIAL); } <> { if ( --include_stack_ptr < 0 ) { yyterminate(); } else yy_switch_to_buffer( include_stack[include_stack_ptr] ); } .fi .SH END-OF-FILE RULES The special rule "<>" indicates actions which are to be taken when an end-of-file is encountered and yywrap() returns non-zero (i.e., indicates no further files to process). The action must finish by doing one of four things: .IP - the special .B YY_NEW_FILE action, if .I yyin has been pointed at a new file to process; .IP - a .I return statement; .IP - the special .B yyterminate() action; .IP - or, switching to a new buffer using .B yy_switch_to_buffer() as shown in the example above. .LP <> rules may not be used with other patterns; they may only be qualified with a list of start conditions. If an unqualified <> rule is given, it applies to .I all start conditions which do not already have <> actions. To specify an <> rule for only the initial start condition, use .nf <> .fi .LP These rules are useful for catching things like unclosed comments. An example: .nf %x quote %% ...other rules for dealing with quotes... <> { error( "unterminated quote" ); yyterminate(); } <> { if ( *++filelist ) { yyin = fopen( *filelist, "r" ); YY_NEW_FILE; } else yyterminate(); } .fi .SH MISCELLANEOUS MACROS The macro .B YY_USER_ACTION can be redefined to provide an action which is always executed prior to the matched rule's action. For example, it could be #define'd to call a routine to convert yytext to lower-case. .LP The macro .B YY_USER_INIT may be redefined to provide an action which is always executed before the first scan (and before the scanner's internal initializations are done). For example, it could be used to call a routine to read in a data table or open a logging file. .LP In the generated scanner, the actions are all gathered in one large switch statement and separated using .B YY_BREAK, which may be redefined. By default, it is simply a "break", to separate each rule's action from the following rule's. Redefining .B YY_BREAK allows, for example, C++ users to #define YY_BREAK to do nothing (while being very careful that every rule ends with a "break" or a "return"!) to avoid suffering from unreachable statement warnings where because a rule's action ends with "return", the .B YY_BREAK is inaccessible. .SH INTERFACING WITH YACC One of the main uses of .I flex is as a companion to the .I yacc parser-generator. .I yacc parsers expect to call a routine named .B yylex() to find the next input token. The routine is supposed to return the type of the next token as well as putting any associated value in the global .B yylval. To use .I flex with .I yacc, one specifies the .B -d option to .I yacc to instruct it to generate the file .B y.tab.h containing definitions of all the .B %tokens appearing in the .I yacc input. This file is then included in the .I flex scanner. For example, if one of the tokens is "TOK_NUMBER", part of the scanner might look like: .nf %{ #include "y.tab.h" %} %% [0-9]+ yylval = atoi( yytext ); return TOK_NUMBER; .fi .SH TRANSLATION TABLE In the name of POSIX compliance, .I flex supports a .I translation table for mapping input characters into groups. The table is specified in the first section, and its format looks like: .nf %t 1 abcd 2 ABCDEFGHIJKLMNOPQRSTUVWXYZ 52 0123456789 6 \\t\\ \\n %t .fi This example specifies that the characters 'a', 'b', 'c', and 'd' are to all be lumped into group #1, upper-case letters in group #2, digits in group #52, tabs, blanks, and newlines into group #6, and .I no other characters will appear in the patterns. The group numbers are actually disregarded by .I flex; .B %t serves, though, to lump characters together. Given the above table, for example, the pattern "a(AA)*5" is equivalent to "d(ZQ)*0". They both say, "match any character in group #1, followed by zero-or-more pairs of characters from group #2, followed by a character from group #52." Thus .B %t provides a crude way for introducing equivalence classes into the scanner specification. .LP Note that the .B -i option (see below) coupled with the equivalence classes which .I flex automatically generates take care of virtually all the instances when one might consider using .B %t. But what the hell, it's there if you want it. .SH OPTIONS .I flex has the following options: .TP .B -b Generate backtracking information to .I lex.backtrack. This is a list of scanner states which require backtracking and the input characters on which they do so. By adding rules one can remove backtracking states. If all backtracking states are eliminated and .B -f or .B -F is used, the generated scanner will run faster (see the .B -p flag). Only users who wish to squeeze every last cycle out of their scanners need worry about this option. (See the section on PERFORMANCE CONSIDERATIONS below.) .TP .B -c is a do-nothing, deprecated option included for POSIX compliance. .IP .B NOTE: in previous releases of .I flex .B -c specified table-compression options. This functionality is now given by the .B -C flag. To ease the the impact of this change, when .I flex encounters .B -c, it currently issues a warning message and assumes that .B -C was desired instead. In the future this "promotion" of .B -c to .B -C will go away in the name of full POSIX compliance (unless the POSIX meaning is removed first). .TP .B -d makes the generated scanner run in .I debug mode. Whenever a pattern is recognized and the global .B yy_flex_debug is non-zero (which is the default), the scanner will write to .I stderr a line of the form: .nf --accepting rule at line 53 ("the matched text") .fi The line number refers to the location of the rule in the file defining the scanner (i.e., the file that was fed to flex). Messages are also generated when the scanner backtracks, accepts the default rule, reaches the end of its input buffer (or encounters a NUL; at this point, the two look the same as far as the scanner's concerned), or reaches an end-of-file. .TP .B -f specifies (take your pick) .I full table or .I fast scanner. No table compression is done. The result is large but fast. This option is equivalent to .B -Cf (see below). .TP .B -i instructs .I flex to generate a .I case-insensitive scanner. The case of letters given in the .I flex input patterns will be ignored, and tokens in the input will be matched regardless of case. The matched text given in .I yytext will have the preserved case (i.e., it will not be folded). .TP .B -n is another do-nothing, deprecated option included only for POSIX compliance. .TP .B -p generates a performance report to stderr. The report consists of comments regarding features of the .I flex input file which will cause a loss of performance in the resulting scanner. Note that the use of .I REJECT and variable trailing context (see the BUGS section in flex(1)) entails a substantial performance penalty; use of .I yymore(), the .B ^ operator, and the .B -I flag entail minor performance penalties. .TP .B -s causes the .I default rule (that unmatched scanner input is echoed to .I stdout) to be suppressed. If the scanner encounters input that does not match any of its rules, it aborts with an error. This option is useful for finding holes in a scanner's rule set. .TP .B -t instructs .I flex to write the scanner it generates to standard output instead of .B lex.yy.c. .TP .B -v specifies that .I flex should write to .I stderr a summary of statistics regarding the scanner it generates. Most of the statistics are meaningless to the casual .I flex user, but the first line identifies the version of .I flex, which is useful for figuring out where you stand with respect to patches and new releases, and the next two lines give the date when the scanner was created and a summary of the flags which were in effect. .TP .B -F specifies that the .I fast scanner table representation should be used. This representation is about as fast as the full table representation .RB ( \-f ), and for some sets of patterns will be considerably smaller (and for others, larger). In general, if the pattern set contains both "keywords" and a catch-all, "identifier" rule, such as in the set: .nf "case" return TOK_CASE; "switch" return TOK_SWITCH; ... "default" return TOK_DEFAULT; [a-z]+ return TOK_ID; .fi then you're better off using the full table representation. If only the "identifier" rule is present and you then use a hash table or some such to detect the keywords, you're better off using .BR \-F . .IP This option is equivalent to .B -CF (see below). .TP .B -I instructs .I flex to generate an .I interactive scanner. Normally, scanners generated by .I flex always look ahead one character before deciding that a rule has been matched. At the cost of some scanning overhead, .I flex will generate a scanner which only looks ahead when needed. Such scanners are called .I interactive because if you want to write a scanner for an interactive system such as a command shell, you will probably want the user's input to be terminated with a newline, and without .B -I the user will have to type a character in addition to the newline in order to have the newline recognized. This leads to dreadful interactive performance. .IP If all this seems to confusing, here's the general rule: if a human will be typing in input to your scanner, use .B -I, otherwise don't; if you don't care about squeezing the utmost performance from your scanner and you don't want to make any assumptions about the input to your scanner, use .B -I. .IP Note, .B -I cannot be used in conjunction with .I full or .I fast tables, i.e., the .B -f, -F, -Cf, or .B -CF flags. .TP .B -L instructs .I flex not to generate .B #line directives. Without this option, .I flex peppers the generated scanner with #line directives so error messages in the actions will be correctly located with respect to the original .I flex input file, and not to the fairly meaningless line numbers of .B lex.yy.c. (Unfortunately .I flex does not presently generate the necessary directives to "retarget" the line numbers for those parts of .B lex.yy.c which it generated. So if there is an error in the generated code, a meaningless line number is reported.) .TP .B -T makes .I flex run in .I trace mode. It will generate a lot of messages to .I stdout concerning the form of the input and the resultant non-deterministic and deterministic finite automata. This option is mostly for use in maintaining .I flex. .TP .B -8 instructs .I flex to generate an 8-bit scanner, i.e., one which can recognize 8-bit characters. On some sites, .I flex is installed with this option as the default. On others, the default is 7-bit characters. To see which is the case, check the verbose .B (-v) output for "equivalence classes created". If the denominator of the number shown is 128, then by default .I flex is generating 7-bit characters. If it is 256, then the default is 8-bit characters and the .B -8 flag is not required (but may be a good idea to keep the scanner specification portable). Feeding a 7-bit scanner 8-bit characters will result in infinite loops, bus errors, or other such fireworks, so when in doubt, use the flag. Note that if equivalence classes are used, 8-bit scanners take only slightly more table space than 7-bit scanners (128 bytes, to be exact); if equivalence classes are not used, however, then the tables may grow up to twice their 7-bit size. .TP .B -C[efmF] controls the degree of table compression. .IP .B -Ce directs .I flex to construct .I equivalence classes, i.e., sets of characters which have identical lexical properties (for example, if the only appearance of digits in the .I flex input is in the character class "[0-9]" then the digits '0', '1', ..., '9' will all be put in the same equivalence class). Equivalence classes usually give dramatic reductions in the final table/object file sizes (typically a factor of 2-5) and are pretty cheap performance-wise (one array look-up per character scanned). .IP .B -Cf specifies that the .I full scanner tables should be generated - .I flex should not compress the tables by taking advantages of similar transition functions for different states. .IP .B -CF specifies that the alternate fast scanner representation (described above under the .B -F flag) should be used. .IP .B -Cm directs .I flex to construct .I meta-equivalence classes, which are sets of equivalence classes (or characters, if equivalence classes are not being used) that are commonly used together. Meta-equivalence classes are often a big win when using compressed tables, but they have a moderate performance impact (one or two "if" tests and one array look-up per character scanned). .IP A lone .B -C specifies that the scanner tables should be compressed but neither equivalence classes nor meta-equivalence classes should be used. .IP The options .B -Cf or .B -CF and .B -Cm do not make sense together - there is no opportunity for meta-equivalence classes if the table is not being compressed. Otherwise the options may be freely mixed. .IP The default setting is .B -Cem, which specifies that .I flex should generate equivalence classes and meta-equivalence classes. This setting provides the highest degree of table compression. You can trade off faster-executing scanners at the cost of larger tables with the following generally being true: .nf slowest & smallest -Cem -Cm -Ce -C -C{f,F}e -C{f,F} fastest & largest .fi Note that scanners with the smallest tables are usually generated and compiled the quickest, so during development you will usually want to use the default, maximal compression. .IP .B -Cfe is often a good compromise between speed and size for production scanners. .IP .B -C options are not cumulative; whenever the flag is encountered, the previous -C settings are forgotten. .TP .B -Sskeleton_file overrides the default skeleton file from which .I flex constructs its scanners. You'll never need this option unless you are doing .I flex maintenance or development. .SH PERFORMANCE CONSIDERATIONS The main design goal of .I flex is that it generate high-performance scanners. It has been optimized for dealing well with large sets of rules. Aside from the effects of table compression on scanner speed outlined above, there are a number of options/actions which degrade performance. These are, from most expensive to least: .nf REJECT pattern sets that require backtracking arbitrary trailing context '^' beginning-of-line operator yymore() .fi with the first three all being quite expensive and the last two being quite cheap. .LP .B REJECT should be avoided at all costs when performance is important. It is a particularly expensive option. .LP Getting rid of backtracking is messy and often may be an enormous amount of work for a complicated scanner. In principal, one begins by using the .B -b flag to generate a .I lex.backtrack file. For example, on the input .nf %% foo return TOK_KEYWORD; foobar return TOK_KEYWORD; .fi the file looks like: .nf State #6 is non-accepting - associated rule line numbers: 2 3 out-transitions: [ o ] jam-transitions: EOF [ \\001-n p-\\177 ] State #8 is non-accepting - associated rule line numbers: 3 out-transitions: [ a ] jam-transitions: EOF [ \\001-` b-\\177 ] State #9 is non-accepting - associated rule line numbers: 3 out-transitions: [ r ] jam-transitions: EOF [ \\001-q s-\\177 ] Compressed tables always backtrack. .fi The first few lines tell us that there's a scanner state in which it can make a transition on an 'o' but not on any other character, and that in that state the currently scanned text does not match any rule. The state occurs when trying to match the rules found at lines 2 and 3 in the input file. If the scanner is in that state and then reads something other than an 'o', it will have to backtrack to find a rule which is matched. With a bit of headscratching one can see that this must be the state it's in when it has seen "fo". When this has happened, if anything other than another 'o' is seen, the scanner will have to back up to simply match the 'f' (by the default rule). .LP The comment regarding State #8 indicates there's a problem when "foob" has been scanned. Indeed, on any character other than a 'b', the scanner will have to back up to accept "foo". Similarly, the comment for State #9 concerns when "fooba" has been scanned. .LP The final comment reminds us that there's no point going to all the trouble of removing backtracking from the rules unless we're using .B -f or .B -F, since there's no performance gain doing so with compressed scanners. .LP The way to remove the backtracking is to add "error" rules: .nf %% foo return TOK_KEYWORD; foobar return TOK_KEYWORD; fooba | foob | fo { /* false alarm, not really a keyword */ return TOK_ID; } .fi .LP Eliminating backtracking among a list of keywords can also be done using a "catch-all" rule: .nf %% foo return TOK_KEYWORD; foobar return TOK_KEYWORD; [a-z]+ return TOK_ID; .fi This is usually the best solution when appropriate. .LP Backtracking messages tend to cascade. With a complicated set of rules it's not uncommon to get hundreds of messages. If one can decipher them, though, it often only takes a dozen or so rules to eliminate the backtracking (though it's easy to make a mistake and have an error rule accidentally match a valid token. A possible future .I flex feature will be to automatically add rules to eliminate backtracking). .LP .I Variable trailing context (where both the leading and trailing parts do not have a fixed length) entails almost the same performance loss as .I REJECT (i.e., substantial). So when possible a rule like: .nf %% mouse|rat/(cat|dog) run(); .fi is better written: .nf %% mouse/cat|dog run(); rat/cat|dog run(); .fi or as .nf %% mouse|rat/cat run(); mouse|rat/dog run(); .fi Note that here the special '|' action does .I not provide any savings, and can even make things worse (see .B BUGS in flex(1)). .LP Another area where the user can increase a scanner's performance (and one that's easier to implement) arises from the fact that the longer the tokens matched, the faster the scanner will run. This is because with long tokens the processing of most input characters takes place in the (short) inner scanning loop, and does not often have to go through the additional work of setting up the scanning environment (e.g., .B yytext) for the action. Recall the scanner for C comments: .nf %x comment %% int line_num = 1; "/*" BEGIN(comment); [^*\\n]* "*"+[^*/\\n]* \\n ++line_num; "*"+"/" BEGIN(INITIAL); .fi This could be sped up by writing it as: .nf %x comment %% int line_num = 1; "/*" BEGIN(comment); [^*\\n]* [^*\\n]*\\n ++line_num; "*"+[^*/\\n]* "*"+[^*/\\n]*\\n ++line_num; "*"+"/" BEGIN(INITIAL); .fi Now instead of each newline requiring the processing of another action, recognizing the newlines is "distributed" over the other rules to keep the matched text as long as possible. Note that .I adding rules does .I not slow down the scanner! The speed of the scanner is independent of the number of rules or (modulo the considerations given at the beginning of this section) how complicated the rules are with regard to operators such as '*' and '|'. .LP A final example in speeding up a scanner: suppose you want to scan through a file containing identifiers and keywords, one per line and with no other extraneous characters, and recognize all the keywords. A natural first approach is: .nf %% asm | auto | break | ... etc ... volatile | while /* it's a keyword */ .|\\n /* it's not a keyword */ .fi To eliminate the back-tracking, introduce a catch-all rule: .nf %% asm | auto | break | ... etc ... volatile | while /* it's a keyword */ [a-z]+ | .|\\n /* it's not a keyword */ .fi Now, if it's guaranteed that there's exactly one word per line, then we can reduce the total number of matches by a half by merging in the recognition of newlines with that of the other tokens: .nf %% asm\\n | auto\\n | break\\n | ... etc ... volatile\\n | while\\n /* it's a keyword */ [a-z]+\\n | .|\\n /* it's not a keyword */ .fi One has to be careful here, as we have now reintroduced backtracking into the scanner. In particular, while .I we know that there will never be any characters in the input stream other than letters or newlines, .I flex can't figure this out, and it will plan for possibly needing backtracking when it has scanned a token like "auto" and then the next character is something other than a newline or a letter. Previously it would then just match the "auto" rule and be done, but now it has no "auto" rule, only a "auto\\n" rule. To eliminate the possibility of backtracking, we could either duplicate all rules but without final newlines, or, since we never expect to encounter such an input and therefore don't how it's classified, we can introduce one more catch-all rule, this one which doesn't include a newline: .nf %% asm\\n | auto\\n | break\\n | ... etc ... volatile\\n | while\\n /* it's a keyword */ [a-z]+\\n | [a-z]+ | .|\\n /* it's not a keyword */ .fi Compiled with .B -Cf, this is about as fast as one can get a .I flex scanner to go for this particular problem. .LP A final note: .I flex is slow when matching NUL's, particularly when a token contains multiple NUL's. It's best to write rules which match .I short amounts of text if it's anticipated that the text will often include NUL's. .SH INCOMPATIBILITIES WITH LEX AND POSIX .I flex is a rewrite of the Unix .I lex tool (the two implementations do not share any code, though), with some extensions and incompatibilities, both of which are of concern to those who wish to write scanners acceptable to either implementation. At present, the POSIX .I lex draft is very close to the original .I lex implementation, so some of these incompatibilities are also in conflict with the POSIX draft. But the intent is that except as noted below, .I flex as it presently stands will ultimately be POSIX conformant (i.e., that those areas of conflict with the POSIX draft will be resolved in .I flex's favor). Please bear in mind that all the comments which follow are with regard to the POSIX .I draft standard of Summer 1989, and not the final document (or subsequent drafts); they are included so .I flex users can be aware of the standardization issues and those areas where .I flex may in the near future undergo changes incompatible with its current definition. .LP .I flex is fully compatible with .I lex with the following exceptions: .IP - The undocumented .I lex scanner internal variable .B yylineno is not supported. It is difficult to support this option efficiently, since it requires examining every character scanned and reexamining the characters when the scanner backs up. Things get more complicated when the end of buffer or file is reached or a NUL is scanned (since the scan must then be restarted with the proper line number count), or the user uses the yyless(), unput(), or REJECT actions, or the multiple input buffer functions. .IP The fix is to add rules which, upon seeing a newline, increment yylineno. This is usually an easy process, though it can be a drag if some of the patterns can match multiple newlines along with other characters. .IP yylineno is not part of the POSIX draft. .IP - The .B input() routine is not redefinable, though it may be called to read characters following whatever has been matched by a rule. If .B input() encounters an end-of-file the normal .B yywrap() processing is done. A ``real'' end-of-file is returned by .B input() as .I EOF. .IP Input is instead controlled by redefining the .B YY_INPUT macro. .IP The .I flex restriction that .B input() cannot be redefined is in accordance with the POSIX draft, but .B YY_INPUT has not yet been accepted into the draft (and probably won't; it looks like the draft will simply not specify any way of controlling the scanner's input other than by making an initial assignment to .I yyin). .IP - .I flex scanners do not use stdio for input. Because of this, when writing an interactive scanner one must explicitly call fflush() on the stream associated with the terminal after writing out a prompt. With .I lex such writes are automatically flushed since .I lex scanners use .B getchar() for their input. Also, when writing interactive scanners with .I flex, the .B -I flag must be used. .IP - .I flex scanners are not as reentrant as .I lex scanners. In particular, if you have an interactive scanner and an interrupt handler which long-jumps out of the scanner, and the scanner is subsequently called again, you may get the following message: .nf fatal flex scanner internal error--end of buffer missed .fi To reenter the scanner, first use .nf yyrestart( yyin ); .fi .IP - .B output() is not supported. Output from the .B ECHO macro is done to the file-pointer .I yyout (default .I stdout). .IP The POSIX draft mentions that an .B output() routine exists but currently gives no details as to what it does. .IP - .I lex does not support exclusive start conditions (%x), though they are in the current POSIX draft. .IP - When definitions are expanded, .I flex encloses them in parentheses. With lex, the following: .nf NAME [A-Z][A-Z0-9]* %% foo{NAME}? printf( "Found it\\n" ); %% .fi will not match the string "foo" because when the macro is expanded the rule is equivalent to "foo[A-Z][A-Z0-9]*?" and the precedence is such that the '?' is associated with "[A-Z0-9]*". With .I flex, the rule will be expanded to "foo([A-Z][A-Z0-9]*)?" and so the string "foo" will match. Note that because of this, the .B ^, $, , /, and .B <> operators cannot be used in a .I flex definition. .IP The POSIX draft interpretation is the same as .I flex's. .IP - To specify a character class which matches anything but a left bracket (']'), in .I lex one can use "[^]]" but with .I flex one must use "[^\\]]". The latter works with .I lex, too. .IP - The .I lex .B %r (generate a Ratfor scanner) option is not supported. It is not part of the POSIX draft. .IP - If you are providing your own yywrap() routine, you must include a "#undef yywrap" in the definitions section (section 1). Note that the "#undef" will have to be enclosed in %{}'s. .IP The POSIX draft specifies that yywrap() is a function and this is very unlikely to change; so .I flex users are warned that .B yywrap() is likely to be changed to a function in the near future. .IP - After a call to .B unput(), .I yytext and .I yyleng are undefined until the next token is matched. This is not the case with .I lex or the present POSIX draft. .IP - The precedence of the .B {} (numeric range) operator is different. .I lex interprets "abc{1,3}" as "match one, two, or three occurrences of 'abc'", whereas .I flex interprets it as "match 'ab' followed by one, two, or three occurrences of 'c'". The latter is in agreement with the current POSIX draft. .IP - The precedence of the .B ^ operator is different. .I lex interprets "^foo|bar" as "match either 'foo' at the beginning of a line, or 'bar' anywhere", whereas .I flex interprets it as "match either 'foo' or 'bar' if they come at the beginning of a line". The latter is in agreement with the current POSIX draft. .IP - To refer to yytext outside of the scanner source file, the correct definition with .I flex is "extern char *yytext" rather than "extern char yytext[]". This is contrary to the current POSIX draft but a point on which .I flex will not be changing, as the array representation entails a serious performance penalty. It is hoped that the POSIX draft will be emended to support the .I flex variety of declaration (as this is a fairly painless change to require of .I lex users). .IP - .I yyin is .I initialized by .I lex to be .I stdin; .I flex, on the other hand, initializes .I yyin to NULL and then .I assigns it to .I stdin the first time the scanner is called, providing .I yyin has not already been assigned to a non-NULL value. The difference is subtle, but the net effect is that with .I flex scanners, .I yyin does not have a valid value until the scanner has been called. .IP - The special table-size declarations such as .B %a supported by .I lex are not required by .I flex scanners; .I flex ignores them. .IP - The name .B FLEX_SCANNER is #define'd so scanners may be written for use with either .I flex or .I lex. .LP The following .I flex features are not included in .I lex or the POSIX draft standard: .nf yyterminate() <> YY_DECL #line directives %{}'s around actions yyrestart() comments beginning with '#' (deprecated) multiple actions on a line .fi This last feature refers to the fact that with .I flex you can put multiple actions on the same line, separated with semi-colons, while with .I lex, the following .nf foo handle_foo(); ++num_foos_seen; .fi is (rather surprisingly) truncated to .nf foo handle_foo(); .fi .I flex does not truncate the action. Actions that are not enclosed in braces are simply terminated at the end of the line. .SH DIAGNOSTICS .I reject_used_but_not_detected undefined or .I yymore_used_but_not_detected undefined - These errors can occur at compile time. They indicate that the scanner uses .B REJECT or .B yymore() but that .I flex failed to notice the fact, meaning that .I flex scanned the first two sections looking for occurrences of these actions and failed to find any, but somehow you snuck some in (via a #include file, for example). Make an explicit reference to the action in your .I flex input file. (Note that previously .I flex supported a .B %used/%unused mechanism for dealing with this problem; this feature is still supported but now deprecated, and will go away soon unless the author hears from people who can argue compellingly that they need it.) .LP .I flex scanner jammed - a scanner compiled with .B -s has encountered an input string which wasn't matched by any of its rules. .LP .I flex input buffer overflowed - a scanner rule matched a string long enough to overflow the scanner's internal input buffer (16K bytes by default - controlled by .B YY_BUF_SIZE in "flex.skel". Note that to redefine this macro, you must first .B #undefine it). .LP .I scanner requires -8 flag - Your scanner specification includes recognizing 8-bit characters and you did not specify the -8 flag (and your site has not installed flex with -8 as the default). .LP .I fatal flex scanner internal error--end of buffer missed - This can occur in an scanner which is reentered after a long-jump has jumped out (or over) the scanner's activation frame. Before reentering the scanner, use: .nf yyrestart( yyin ); .fi .LP .I too many %t classes! - You managed to put every single character into its own %t class. .I flex requires that at least one of the classes share characters. .SH DEFICIENCIES / BUGS See flex(1). .SH "SEE ALSO" .LP flex(1), lex(1), yacc(1), sed(1), awk(1). .LP M. E. Lesk and E. Schmidt, .I LEX - Lexical Analyzer Generator .SH AUTHOR Vern Paxson, with the help of many ideas and much inspiration from Van Jacobson. Original version by Jef Poskanzer. The fast table representation is a partial implementation of a design done by Van Jacobson. The implementation was done by Kevin Gong and Vern Paxson. .LP Thanks to the many .I flex beta-testers, feedbackers, and contributors, especially Casey Leedom, benson@odi.com, Keith Bostic, Frederic Brehm, Nick Christopher, Jason Coughlin, Scott David Daniels, Leo Eskin, Chris Faylor, Eric Goldman, Eric Hughes, Jeffrey R. Jones, Kevin B. Kenny, Ronald Lamprecht, Greg Lee, Craig Leres, Mohamed el Lozy, Jim Meyering, Marc Nozell, Esmond Pitt, Jef Poskanzer, Jim Roskind, Dave Tallman, Frank Whaley, Ken Yap, and those whose names have slipped my marginal mail-archiving skills but whose contributions are appreciated all the same. .LP Thanks to Keith Bostic, John Gilmore, Craig Leres, Bob Mulcahy, Rich Salz, and Richard Stallman for help with various distribution headaches. .LP Thanks to Esmond Pitt and Earle Horton for 8-bit character support; to Benson Margulies and Fred Burke for C++ support; to Ove Ewerlid for the basics of support for NUL's; and to Eric Hughes for the basics of support for multiple buffers. .LP Work is being done on extending .I flex to generate scanners in which the state machine is directly represented in C code rather than tables. These scanners may well be substantially faster than those generated using -f or -F. If you are working in this area and are interested in comparing notes and seeing whether redundant work can be avoided, contact Ove Ewerlid (ewerlid@mizar.DoCS.UU.SE). .LP This work was primarily done when I was at the Real Time Systems Group at the Lawrence Berkeley Laboratory in Berkeley, CA. Many thanks to all there for the support I received. .LP Send comments to: .nf Vern Paxson Computer Science Department 4126 Upson Hall Cornell University Ithaca, NY 14853-7501 vern@cs.cornell.edu decvax!cornell!vern .fi .TH FORMAT 1 .SH NAME format \- format a PC floppy diskette .SH SYNOPSIS .B format .RB [ \-v ] .I device .RI [ media-size .RI [ drive-size ]] .SH DESCRIPTION .de SP .if t .sp 0.4 .if n .sp .. .B Format allows a user with read-write permission to .I device to format a floppy. Either one of the special floppy devices must be used, see .BR fd (4), or an automatic device may be used with the size of the floppy specified on the command line. Two sizes must be given when formatting a low density diskette in a high density drive. For example: .PP .RS .ft B .nf format /dev/at1 format /dev/fd1 1200 format /dev/fd1 360 1200 .fi .ft P .RE .PP The first two commands format a 1.2M diskette, the last formats a 360k diskette in a 1.2M drive. A 1.44M drive knows when it's dealing with a low density floppy, so all these commands format a 720k diskette: .PP .RS .ft B .nf format /dev/fd0 720 format /dev/fd0 720 1440 format /dev/ps0 .fi .ft P .RE .PP No sizes may be specified when using a special floppy device, a size must be specified when using an automatic device. .SH OPTIONS .TP .B \-v Verify the process by reading each track after formatting it. Formatting is normally blind, the controller has no idea whether it succeeds or not. Use .B \-v on a new box of cheap diskettes, or on a diskette that may have gone bad. Verifying will increase formatting time by 50%. .SH "SEE ALSO" .BR mkfs (1), .BR fd (4). .SH DIAGNOSTICS Numbers will be printed on standard output to show that it is busy. The locations of bad sectors are printed on standard error when verifying. The exit code is zero unless there are too many bad spots. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .\" ++Copyright++ 1993 .\" - .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" - .\" Portions Copyright (c) 1993 by Digital Equipment Corporation. .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies, and that .\" the name of Digital Equipment Corporation not be used in advertising or .\" publicity pertaining to distribution of the document or software without .\" specific, written prior permission. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL .\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT .\" CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. .\" - .\" --Copyright-- .\" $Id: host.1,v 4.9.1.1 1993/05/02 23:50:13 vixie Rel vixie $ .TH HOST 1 .SH NAME host \- look up host names using domain server .SH SYNOPSIS host [-l] [-v] [-w] [-r] [-d] [-t querytype] [-a] host [ server ] .SH DESCRIPTION .I Host looks for information about Internet hosts. It gets this information from a set of interconnected servers that are spread across the country. By default, it simply converts between host names and Internet addresses. However with the -t or -a options, it can be used to find all of the information about this host that is maintained by the domain server. .PP The arguments can be either host names or host numbers. The program first attempts to interpret them as host numbers. If this fails, it will treat them as host names. A host number consists of first decimal numbers separated by dots, e.g. 128.6.4.194 A host name consists of names separated by dots, e.g. topaz.rutgers.edu. Unless the name ends in a dot, the local domain is automatically tacked on the end. Thus a Rutgers user can say "host topaz", and it will actually look up "topaz.rutgers.edu". If this fails, the name is tried unchanged (in this case, "topaz"). This same convention is used for mail and other network utilities. The actual suffix to tack on the end is obtained by looking at the results of a "hostname" call, and using everything starting at the first dot. (See below for a description of how to customize the host name lookup.) .PP The first argument is the host name you want to look up. If this is a number, an "inverse query" is done, i.e. the domain system looks in a separate set of databases used to convert numbers to names. .PP The second argument is optional. It allows you to specify a particular server to query. If you don't specify this argument, the default server (normally the local machine) is used. .PP If a name is specified, you may see output of three different kinds. Here is an example that shows all of them: .br % host sun4 .br sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU .br ATHOS.RUTGERS.EDU has address 128.6.5.46 .br ATHOS.RUTGERS.EDU has address 128.6.4.4 .br ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU .br The user has typed the command "host sun4". The first line indicates that the name "sun4.rutgers.edu" is actually a nickname. The official host name is "ATHOS.RUTGERS.EDU'. The next two lines show the address. If a system has more than one network interface, there will be a separate address for each. The last line indicates that ATHOS.RUTGERS.EDU does not receive its own mail. Mail for it is taken by ARAMIS.RUTGERS.EDU. There may be more than one such line, since some systems have more than one other system that will handle mail for them. Technically, every system that can receive mail is supposed to have an entry of this kind. If the system receives its own mail, there should be an entry the mentions the system itself, for example "XXX mail is handled by XXX". However many systems that receive their own mail do not bother to mention that fact. If a system has a "mail is handled by" entry, but no address, this indicates that it is not really part of the Internet, but a system that is on the network will forward mail to it. Systems on Usenet, Bitnet, and a number of other networks have entries of this kind. .PP There are a number of options that can be used before the host name. Most of these options are meaningful only to the staff who have to maintain the domain database. .PP The option -w causes host to wait forever for a response. Normally it will time out after around a minute. .PP The option -v causes printout to be in a "verbose" format. This is the official domain master file format, which is documented in the man page for "named". Without this option, output still follows this format in general terms, but some attempt is made to make it more intelligible to normal users. Without -v, "a", "mx", and "cname" records are written out as "has address", "mail is handled by", and "is a nickname for", and TTL and class fields are not shown. .PP The option -r causes recursion to be turned off in the request. This means that the name server will return only data it has in its own database. It will not ask other servers for more information. .PP The option -d turns on debugging. Network transactions are shown in detail. .PP The option -t allows you to specify a particular type of information to be looked up. The arguments are defined in the man page for "named". Currently supported types are a, ns, md, mf, cname, soa, mb, mg, mr, null, wks, ptr, hinfo, minfo, mx, uinfo, uid, gid, unspec, and the wildcard, which may be written as either "any" or "*". Types must be given in lower case. Note that the default is to look first for "a", and then "mx", except that if the verbose option is turned on, the default is only "a". .PP The option -a (for "all") is equivalent to "-v -t any". .PP The option -l causes a listing of a complete domain. E.g. .br host -l rutgers.edu .br will give a listing of all hosts in the rutgers.edu domain. The -t option is used to filter what information is presented, as you would expect. The default is address information, %'(which also include PTR and NS records. The command .br host -l -v -t any rutgers.edu .br will give a complete download of the zone data for rutgers.edu, in the official master file format. (However the SOA record is listed twice, for arcane reasons.) NOTE: -l is implemented by doing a complete zone transfer and then filtering out the information the you have asked for. This command should be used only if it is absolutely necessary. .SH CUSTOMIZING HOST NAME LOOKUP In general, if the name supplied by the user does not have any dots in it, a default domain is appended to the end. This domain can be defined in /etc/resolv.conf, but is normally derived by taking the local hostname after its first dot. The user can override this, and specify a different default domain, using the environment variable .IR LOCALDOMAIN . In addition, the user can supply his own abbreviations for host names. They should be in a file consisting of one line per abbreviation. Each line contains an abbreviation, a space, and then the full host name. This file must be pointed to by an environment variable .IR HOSTALIASES , which is the name of the file. .SH "See Also" named (8) .SH BUGS Unexpected effects can happen when you type a name that is not part of the local domain. Please always keep in mind the fact that the local domain name is tacked onto the end of every name, unless it ends in a dot. Only if this fails is the name used unchanged. .PP The -l option only tries the first name server listed for the domain that you have requested. If this server is dead, you may need to specify a server manually. E.g. to get a listing of foo.edu, you could try "host -t ns foo.edu" to get a list of all the name servers for foo.edu, and then try "host -l foo.edu xxx" for all xxx on the list of name servers, until you find one that works. .TH HOSTADDR 1 .SH NAME hostaddr \- show ethernet address, IP address or hostname .SH SYNOPSIS .B hostaddr .RB [ \-eia ] .RB [ \-E .IR eth-device ] .RB [ \-I .IR ip-device ] .SH DESCRIPTION Without any of the .B \-eia options, .B hostaddr shows the ethernet address, IP address and hostname of the local host on one line in the given order. With options only the wanted fields are shown, still in the same order, not in option order. .SH OPTIONS .TP .B \-e Show the ethernet address. .TP .B \-i Show the IP address. This will not work if no IP address has been found by RARP or by setting it with .BR ifconfig (8). .TP .B \-a Show the fully qualified hostname. The IP address is shown again if it can't be translated to a host name. (This usually indicates that the DNS reverse address translation tables are incomplete.) .SH "SEE ALSO" .BR ifconfig (8), .BR rarpd (8), .BR nonamed (8), .BR set_net_default (8), .BR boot (8). .SH DIAGNOSTICS "Timeout" .br .B Hostaddr timed out trying to get the IP address. This means that the network connection is out of order or that the setup of the machine is bad. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH INSTALL 1 .SH NAME install \- install files .SH SYNOPSIS .in +5 .ti -5 .B install .RB [ \-lcsz\fIN\fP "] [" \-o .IR owner ] .RB [ \-g .IR group ] .RB [ \-m .IR mode ] .RB [ \-S .IR stack ] .RI [ file1 ] .I file2 .br .ti -5 .B install .RB [ \-lcsz\fIN\fP "] [" \-o .IR owner ] .RB [ \-g .IR group ] .RB [ \-m .IR mode ] .RB [ \-S .IR stack ] .IR file " ... " dir .br .ti -5 .B install \-d .RB [ \-o .IR owner ] .RB [ \-g .IR group ] .RB [ \-m .IR mode ] .I directory .in -5 .SH DESCRIPTION .de SP .if t .sp 0.4 .if n .sp .. .B Install puts executables, manual pages, and library files in their proper place in the bin, man, and lib directories. The first two forms of the command are like .BR cp (1) copying either one file to another or copying several files to a directory. The "\fB\-d\fP" form is like .BR mkdir (1) with the .B \-p flag. .I File1 may be omitted if neither .B \-l nor .B \-c is given to change the attributes of .IR file2 . .PP Attributes are always copied from the source file, use the options to change. Note that the source file's attributes are changed with the destination file if they are linked. So copy the file if you change it in a way that makes it read-only. You would otherwise not be able to compile a command again. .SH OPTIONS .TP .B \-l Link the destination to the source file instead of copying it. This is done to either save space on a file system with both the source and the bin directories on it, or to install synonyms to a command. .TP .B \-c Copy the source file to its proper place. This option is the default if .B \-l is not given. With .BR \-l , the file is copied if the link fails. .TP .B \-s Strip the destination file of its symbol table, .I if it is an executable, and .I if it is actually copied. It has no effect on a link or a non-executable. .TP .B \-z Compress the executable using .BR compress (1) and prepend a header line that calls .BR zexec (1) to decompress and execute the binary. This will on average save 40% disk space at the expense of a slower startup time. Like .B \-s the file must be actually copied for the flag to have effect. .TP .BI \- N Use .BI "gzip \-" N to compress the binary. You may see up to 60% space savings, but it will take much longer. .I N is a digit from 1 to 9 telling the compression effort, see .BR gzip (1). .TP .B \-d Make a directory, usually to install files in a separate directory in a library. Intermediate directories in the path are created with the same attributes as the final directory. Only the attributes of the final directory are set if the directory exists. .TP .BI \-o " owner" Set the owner of the target. This only works if the invoker is the super-user, or if .B install is run setuid root and the invoker is a member of group zero. If .B \-o is omitted then the ownership is copied from the source file, or set to the id of the invoker if a directory is made. .TP .BI \-g " group" Like .BR \-o , but for the group ownership of the target. .TP .BI \-m " mode" .I Mode is an octal number that specifies the mode the target should get. The default is the source file's mode with a .B chmod a+rX applied to it, or 755 for a new directory. Implies .BR "\-o 0" , or .BR "\-g 0" if a file is to be set-uid or set-gid and the invoker has permission to change ownership. This trick allows a group 0 member to install third party software, even though it expects to be installed by root. .TP .BI \-S " stack" Sets the maximum amount of heap + stack that an executable may have when running. The argument is a C-style decimal, octal or hexadecimal number, optionally followed by the multipliers .BR m , .BR k , .BR w , and .B b for mega (1024*1024), kilo (1024), "word" (2 or 4), and byte (1). Uppercase .B M is also accepted for those who know what S.I. means. The compilers use .B \-S 32kw by default, that translates to 64kb for an 8086, and 128kb for other architectures. This option is ignored on a non-executable. .SH "SEE ALSO" .BR ln (1), .BR cp (1), .BR strip (1), .BR compress (1), .BR gzip (1), .BR zexec (1), .BR chown (8), .BR chgrp (8), .BR chmod (1), .BR chmem (1), .BR mkdir (1). .SH BUGS Uppercase .BR K , .BR W , and .B B are also accepted for those who don't know what S.I. means. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH ISODIR 1 .SH NAME isodir \- list ISO9660 or High Sierra directories .SH SYNOPSIS \fBisodir\fP \-[\fBlr\fP] \fIinput_file\fP [\fIdir\fP] .SH DESCRIPTION \fBIsodir\fP reads directories on a file system in ISO9660 or High Sierra Group format (usually residing on cdrom) and lists their contents on standard output. Directory names should contain slashes to separate components. The names \fBisodir\fP, \fBisoread\fP, and \fBisoinfo\fP are all links to the same program. The program sees which function to perform by looking how it was called. .PP .IP \-l Lists all info on files and directories (size, date, time) .IP \-r Recursively descend and print subdirectories .SH "BUGS" Only Interchange level-1 is supported. The Red Rock extensions and Interchange level-2 are not implemented. .SH "SEE ALSO" .BR isoread (1), .BR isoinfo (1). .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH ISOINFO 1 .SH NAME isoinfo \- list an ISO9660 or High Sierra volume descriptor .SH SYNOPSIS \fBisoinfo\fP [\fIinput_file\fP] .SH DESCRIPTION \fBIsoinfo\fP reads the volume descriptor from an ISO9660 or High Sierra Group file system (usually residing on cdrom) and lists its contents on standard output. \fBisodir\fP, \fBisoread\fP, and \fBisoinfo\fP are all links to the same program. The program sees which function to perform by looking how it was called. .SH "BUGS" Only Interchange level-1 is supported. The Red Rock extensions and Interchange level-2 are not implemented. .SH "SEE ALSO" .BR isodir (1), .BR isoread (1). .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH ISOREAD 1 .SH NAME isoread \- read a file in ISO9660 or High Sierra format .SH SYNOPSIS \fBisoread\fP [\fIinput_file\fP] \fIfile\fP .SH DESCRIPTION \fBIsoread\fP reads a file in ISO9660 or High Sierra Group format (usually residing on cdrom) and lists its contents on standard output. The file path should contain slashes to separate components. The names \fBisodir\fP, \fBisoread\fP, and \fBisoinfo\fP are all links to the same program. The program sees which function to perform by looking how it was called. .SH "BUGS" Only Interchange level-1 is supported. The Red Rock extensions and Interchange level-2 are not implemented. .SH "SEE ALSO" .BR isodir (1), .BR isoinfo (1). .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH MAKEWHATIS 1 .SH NAME makewhatis \- build the whatis(5) database .SH SYNOPSIS .B makewhatis .I directory .SH DESCRIPTION .B Makewhatis makes the .BR whatis (5) database in the given manual page directory. This database is used by .BR man (1) to map titles to manual page names and by .BR whatis (1) to give one line descriptions. See .BR whatis (5) for a desciption of what a whatis database should look like and the restrictions that are placed on the NAME sections so that .B makewhatis can make whatis lines out of the manual pages. .SH "SEE ALSO" .BR whatis (5). .SH BUGS Removing only font and size changes from the NAME section is often not enough. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH MAN 1 .SH NAME man \- display online manual pages .SH SYNOPSIS .B man .RB [ \-antkf ] .RB [ \-M .IR path ] .RB [ \-s .IR section ] .IR title " ..." .SH DESCRIPTION .B Man displays the online manual pages for the specified titles in the specified sections. The sections are as follows: .PP .TP .B 1 User Commands .br Generic commands such as .BR ls , .BR cp , .BR grep . .TP .B 2 System Calls .br Low level routines that directly interface with the kernel. .TP .B 3 Library Routines .br Higher level C language subroutines. .TP .B 4 Device Files .br Describes devices in .BR /dev . .TP .B 5 File Formats .br Formats of files handled by various utilities and subroutines. .TP .B 6 Games .br It's not \s-2UNIX\s+2 without an adventure game. .TP .B 7 Miscellaneous .br Macro packages, miscellaneous tidbits. .TP .B 8 System Utilities .br Commands for the System Administrator. .TP .B 9 Documents .br Larger manuals explaining some commands in more detail. .PP (If you are new to Minix then try .BR "man hier" , it will show you around the file system and give you many pointers to other manual pages.) .PP By default, .B man will try the following files in a manual page directory for the command .BR "man \-s 1 ls" : .PP .RS .ft B .nf cat1/ls.1 cat1/ls.1.Z man1/ls.1 man1/ls.1.Z .fi .ft P .RE .PP Files in the man[1\-8] directories are formatted with .BR "nroff \-man" . Those in man9 are formatted with .BR "nroff \-mnx" . Files in the cat? directories are preformatted. Files with names ending in .B .Z are decompressed first with .B zcat (see .BR compress (1)). The end result is presented to the user using a pager if displaying on the screen. .PP For each manual page directory in its search path, .B man will first try all the subdirectories of the manual page directory for the files above, and then the directory itself. The directory .B /usr/man contains the standard manual pages, with manual pages for optional packages installed in a subdirectory of /usr/man, with the same structure as /usr/man. The directory .B /usr/local/man contains manual pages for locally added software. By default /usr/local/man is searched first, then /usr/man. .PP A title is not simply used as a filename, because several titles may refer to the same manual page. Each manual page directory contains a database of titles in the .BR whatis (5) file that is created by .BR makewhatis (8) from the NAME sections of all the manual pages. A title is searched in this database and the first title on a whatis line is used as a filename. .SH OPTIONS The options may be interspersed with the titles to search, and take effect for the titles after them. .TP .B \-a Show all the manual pages or one line descriptions with the given title in all the specified sections in all the manual directories in the search path. Normally only the first page found is shown. .TP .B \-n Use .B nroff \-man to format manual pages (default). .TP .B \-t Use .B troff \-man to format manual pages. .TP .B \-f Use .BR whatis (1) to show a one line description of the title from the .BR whatis (5) file. .TP .B \-k Use .BR apropos (1) to show all the one line descriptions of the title anywhere in the .BR whatis (5) files (implies .BR \-a ). .TP .BI \-M " path" Use .I path as the search path for manual directories. .TP .BI \-s " section" .I Section is the section number the page is to be found in, or a comma separated list of sections to use. Normally all sections are searched. The search is always in numerical order no matter what your section list looks like. A single digit is treated as a section number without the .B \-s for compatibility with BSD-style .B man commands. .SH ENVIRONMENT .TP 15n .B MANPATH This is a colon separated list of directories to search for manual pages, by default .BR /usr/local/man:/usr/man . .TP .B PAGER The program to use to display the manual page or one line descriptions on the screen page by page. By default .BR more . .SH FILES .TP 25n /usr/man/whatis One of the .BR whatis (5) databases. .SH "SEE ALSO" .BR nroff (1), .BR troff (1), .BR more (1), .BR whatis (1), .BR makewhatis (1), .BR catman (1), .BR whatis (5), .BR man (7). .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH MIXER 1 .SH NAME mixer \- manipulate mixer settings on a sound card .SH SYNOPSIS \fBmixer\fP [\-\fBr\fP] .SH DESCRIPTION \fBMixer\fP, invoked without arguments, turns the screen into a sound mixer. Levels can be changed with the cursor-left and cursor-right keys. Input and output settings can be toggled with the space bar. For every sound source there are two, or one when mono, sliders. The input controls have only effect when recording with the Dac. These settings can also be used to switch the left and right channels or, when both channels are enabled on both Dac channels, record in mono. To exit the mixer use the 'e' key. Mixer settings can be stored and restored with the 's' (store) and 'r' keys. When the store function is used \fBMixer\fP will write the settings to a file in the user's home directory called \fI\.mixer\fP. The restore function reads this file to restore saved settings. .SH OPTIONS .IP \-r restore settings saved in \fI\.mixer\fP and exit immediately .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH MT 1 .SH NAME mt \- magnetic tape control .SH SYNOPSIS .B mt .RB [ \-f .IR device ] .RI [ count ] .SH DESCRIPTION .B Mt is a user interface to the magnetic tape commands described in .BR mtio (4). It allows one to space a tape forwards or backwards, write end of file markers, etc. .PP With the .B \-f option a tape device can be named, otherwise the environment variable .B TAPE is used if set, otherwise the default device .B /dev/nrst4 is assumed. Standard input is used if the tape name is a dash (\-). The .I count argument is used to tell how many blocks or files to space or how many file markers to write. It may be a C-style decimal, octal or hexadecimal constant, by default "1". .PP .I Command is the action to perform, it may be one of the following, or any unambiguous prefix (like .B st for .BR status ): .TP 15 .B eof, weof Write .I count end-of-file markers. .TP .B fsf Forward space .I count file markers. .TP .B fsr Forward space .I count records. (The size of a record depends on the tape, and may even be variable, depending on the size of the writes.) .TP .B bsf Backwards space .I count files. The count may be zero to backspace to the start of the current file. (A tape device need not support backwards movement, or may be very slow doing it. Rewinding and forward spacing may be better.) .TP .B bsr Backwards space .I count records. The tape is positioned after the last block of the previous file if you hit a filemark when spacing backwards. The block count is set to -1 to indicate that the driver has no idea where it is on the previous file. .TP .B eom Forward space to the end of media. .TP .B rewind Rewind the tape. .TP .B offline, rewoffl Rewind and take offline. This may cause some drives to eject the tape. .TP .B status Shows the status of the drive, the sense key of the last SCSI error, current file number, current record number, residual count if the last command that encountered end-of-file, and the current block size. .TP .B retension Removes tape tension by winding and rewinding the tape completely. .TP .B erase Erases the tape completely and rewinds it. .TP .B density Sets the density code to read or write the tape to .IR count . Density codes supported depend on the drive. This command need not be used if the drive senses the proper density on read and can only write one density. .TP .B blksize, blocksize Sets the block size used to read or write the tape to .IR count . This command may be used to select a fixed block size for a variable block size tape. This will speed up I/O for small block sizes. Use a zero .I count to use variable sized blocks again. .SH ENVIRONMENT .TP 15n .B TAPE Tape drive to use if set. .SH FILES .TP 15n .B /dev/nrst4 Default tape device. .SH "SEE ALSO" .BR mtio (4), .BR st (4). .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH PLAYWAVE 1 .SH NAME playwave \- play an audio file in MicroSoft PCM wave format .SH SYNOPSIS \fBplaywave\fP [\-\fBi\fP] file .SH DESCRIPTION \fBPlaywave\fP writes the samples in a wave file to \fI/dev/audio\fP. The wave file must be in Microsoft PCM format. .SH OPTIONS .IP \-i display information about wave file .SH BUGS The highest sample rate that can be used depends on the speed of the system and the size of the DMA buffer used in the driver. (/usr/src/kernel/sb16.h) .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH RECWAVE 1 .SH NAME recwave \- record an audio file in MicroSoft PCM wave format .SH SYNOPSIS \fBrecwave\fP [\-\fBb\fP \-\fBs\fP \-\fBr\fP] file .SH DESCRIPTION \fBRecwav\fP takes samples from \fI/dev/audio\fP and writes them to \fIfile\fP in Microsoft PCM wave format. .SH OPTIONS .IP \-b number of bits to use for one sample. Must be 8 or 16, default is 8 .IP \-s enable stereo sampling. 0 = mono (default), 1 = stereo .IP \-r sample rate in samples/sec. 4000 - 44100 (default 22050) .SH BUGS The highest sample rate that can be used depends on the speed of the system and the size of the DMA buffer used in the driver. (/usr/src/kernel/sb16.h) .SH AUTHOR Michel R. Prevenier (mrpreve@cs.vu.nl) .TH REMSYNC 1 .SH NAME remsync - remotely synchronize file trees .SH SYNOPSIS .B remsync .B \-sxv .I tree .RI [ state-file ] .br .B remsync .B \-duxvD .I tree .RI [ state-file .RI [ diff-file ]] .br .B remsync .RB [ \-xv ] .I tree .RI [ diff-file ] .SH DESCRIPTION .de SP .if t .sp 0.4 .if n .sp .. .B Remsync synchronizes file trees of distant machines, i.e. machines that do not have a fast network between them. It accomplishes this in three steps: .PP .RS Create a state file containing a description of the machine to be updated. .RE .PP .RS Compute a file of differences on the source machine using the state file to compare the two file trees. .RE .PP .RS Update the target machine using the data in the differences file. .RE .PP This process requires that you move two files, a state file from the target machine to the source machine, and a differences file from the source machine to the target machine. The state file is an ASCII file that may be edited, usually to make .B remsync ignore some files or file trees. .PP The argument .I tree may be a single file or a directory. A directory is traversed recursively. The .I state-file and .I diff-file arguments may be of any file type. The differences file contains an end marker, so it may be followed by trailing junk. Standard input or output is used if these arguments are omitted or replaced by a minus sign. .SS "State file format" A state file has a line for each file in a tree. A line looks like this formally for a simple file: .PP .RS .I "name mode owner group length date" .RI [ link-number .RB [ last ]] .RE .PP The best way to show how each type of file is represented is by example: .PP .RS .nf .ta +10 +8 +4 +4 +6 +12 +4 / d755 0 0 bin d755 2 0 .in +2 [ 644 2 0 233 759160857 1 cat 755 2 0 3772 768742021 test 755 2 0 233 759160857 1 last .in -2 dev d755 0 0 .in +2 fd0 b666 0 0 200 console c600 10 0 400 sd2 b600 0 0 a02 fifo p700 2 0 .in -2 opt -> usr/opt usr ignore (Cross-device link) .fi .RE .PP The root of the tree is always represented by a /, no matter what type of file it may be. Directory entries of the root follow at the same level. Files in subdirectories are indented by two spaces. (Eight spaces are replaced by a TAB.) Normal files have their length and modified time in the state file, devices have their device number in hex, etc. If files are hard linked to each other then they all get an extra "link number" to bind them together. The last link is marked with the word .BR last . .PP One usually only modifies a state file to ignore differences between two files. One does this by replacing the file attributes with the word .BR ignore . .RB ( Remsync generates this keyword too, with the reason why added in parentheses.) .SH OPTIONS .TP .B \-s Generate a state file. .TP .B \-d Generate a differences file. (The default is to apply a differences file.) .TP .B \-u Only add new files or update files with newer versions. .TP .B \-x Do not cross device boundaries. This allows one to operate on the root file system for instance ignoring the .B /usr file system. .TP .B \-D Debug differences file generation. With this flag no file contents are added to the differences file. The result is then human readable. .TP .B \-v Lists the commands added to the differences file, or the actions done applying a differences file. The output looks like \s-2UNIX\s+2 commands except for the words "add", "restore" and "update" indicating addition of a new file, replacing a file with an older version, or replacement by a newer version. .SH EXAMPLES Actions taken by the author to update his notebook "finiah" from his main machine "darask": .PP .RS .nf finiah# remsync -s /usr /tmp/finiah.state .SP Edit the state file to ignore .Xauthority files and /usr/var. .SP finiah# tar cvf /dev/fd0 /tmp/finiah.state .SP darask# tar xvf /dev/fd0 .br darask# remsync -dv /usr /tmp/finiah.state | vol 1440 /dev/fd0 .SP finiah# vol 1440 /dev/fd0 | remsync -v /usr .fi .RE .PP One could add a file compression/decompression program between .B remsync and .BR vol , to reduce the number of floppies to move about, but that actually slows things down! (Note that one only needs to shuffle two floppies about if the two machines are adjacent. To update a remote machine it does make sense to use compression to reduce the number of floppies to carry.) .SH "SEE ALSO" .BR synctree (1), .BR vol (1), .BR tar (1). .SH NOTES Nothing stops you from using .B remsync over a fast network of course. .B Synctree can be a bit tedious if you only want to ignore a few files. Editing a state file is then easier. .SH BUGS Files are overwritten, not removed, when they are updated. This means that links outside the tree are also updated. The less desirable alternative to this is to break the link before the update. .PP The verbose option may say that a link is to be created when making a differences file. The link is often already there when the update takes place, so no action is taken, and thus no talk about it. So you may miss a few mutterings about links if you compare the messages. .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .\" manual page for bsfilt(1) .\" .\" .\" Copyright (c) 1991 Purdue University Research Foundation, .\" West Lafayette, Indiana 47907. All rights reserved. .\" .\" Written by Victor A. Abell , Purdue .\" University Computing Center. Not derived from licensed software; .\" derived from awf(1) by Henry Spencer of the University of Toronto. .\" .\" Permission is granted to anyone to use this software for any .\" purpose on any computer system, and to alter it and redistribute .\" it freely, subject to the following restrictions: .\" .\" 1. The author is not responsible for any consequences of use of .\" this software, even if they arise from flaws in it. .\" .\" 2. The origin of this software must not be misrepresented, either .\" by explicit claim or by omission. Credits must appear in the .\" documentation. .\" .\" 3. Altered versions must be plainly marked as such, and must not .\" be misrepresented as being the original software. Credits must .\" appear in the documentation. .\" .\" 4. This notice may not be removed or altered. .\" .TH BSFILT 1 "February, 1991" .BY "Purdue University" .SH NAME bsfilt, colcrt \- a colcrt-like backspace filter .SH SYNOPSIS .B bsfilt [ .B - ] [ .B -U ] [ file ... ] .SH DESCRIPTION .I Bsfilt filters backspace sequences from the input \fIfile\fR(s) (standard input if none) in an approximation of .IR colcrt (1). Both the backspace and the character it returns to are removed, unless they form an underline sequence. Underline sequences are treated according to the settings of the .B \- and .B \-U options. .SH OPTIONS .TP .B \- specifies that no underlining of any kind is to be propagated. Without this option or the .B \-U option, .I bsfilt approximates underlining with minus signs (`-') in following lines. .TP .B \-U specifies that underlining with underscore (`_') and backspace (`\b') character sequences is permitted. .SH SEE ALSO cawf(1), colcrt(1) and nroff(1). .SH DIAGNOSTICS Diagnostic messages are delivered to the standard error file. .SH HISTORY Vic Abell of Purdue University wrote .I bsfilt to have a backspace filter for .IR cawf (1) that is independent of licensed source code. .SH BUGS The maximum length of a line that can be underlined with minus signs is fixed. .LP .I Bsfilt does not examine the characters that are being overprinted via backspace operations. Thus, overprinting that is intended to form a new character from several different ones is ineffective and only the last character of the sequence is propagated \- e. g., ``o^H+'', intended to look like a bullet, is reduced to `+'. .TH VOL 1 .SH NAME vol \- split input on or combine output from several volumes .SH SYNOPSIS .B vol .RB [ \-rw1 ] .RB [ \-b .IR blocksize ] .RB [ \-m .IR multiple ] .RI [ size ] .I device .SH DESCRIPTION .B Vol either reads a large input stream from standard input and distributes it over several volumes or combines volumes and sends them to standard output. The size of the volumes is determined automatically if the device supports this, but may be specified before the argument naming the device if automated detection is not possible or if only part of the physical volume is used. The direction of the data is automatically determined by checking whether the input or output of .B vol is a file or pipe. Use the .B \-r or .B \-w flag if you want to specify the direction explicitly, in shell scripts for instance. .PP .B Vol waits for each new volume to be inserted, typing return makes it continue. If no size is explicitely given then the size of the device is determined each time before it is read or written, so it is possible to mix floppies of different sizes. If the size cannot be determined (probably a tape) then the device is assumed to be infinitely big. .B Vol can be used both for block or character devices. It will buffer the data and use a block size appropriate for fixed or variable block sized tapes. .PP .B Vol reads or writes 8192 bytes to block devices, usually floppies. Character devices are read or written using a multiple of 512 bytes. This multiple has an upper limit of 32767 bytes (16-bit machine), 64 kb (32-bit), or even 1 Mb (32-bit VM). The last partial write to a character device is padded with zeros to the block size. If a character device is a tape device that responds to the .BR mtio (4) status call then the reported tape block size will be used as the smallest unit. If the tape is a variable block length device then it is read or written like a block device, 8192 bytes at the time, with a minimum unit of one byte. .PP All sizes may be suffixed by the letters .BR M , .BR k , .BR b or .BR w to multiply the number by mega, kilo, block (512), or word (2). The volume size by default in kilobytes if there is no suffix. .SH OPTIONS .TP .B \-rw Explicitly specify reading or writing. Almost mandatory in scripts. .TP .B \-1 Just one volume, start immediately. .TP .BI \-b " blocksize" Specify the device block size. .TP .BI \-m " multiple" Specify the maximum read or write size of multiple blocks. The .B \-b and .B \-m options allow one to modify the block size assumptions that are made above. These assumptions are .B "\-b 1 \-m 8192" for block devices or variable length tapes, and .B "\-b 512 \-m 65536" for character devices (32 bit machine.) These options will not override the tape block size found out with an .BR mtio (4) call. The multiple may be larger then the default if .B vol can allocate the memory required. .SH EXAMPLES To back up a tree to floppies as a compressed tarfile: .PP .RS tar cf \- . | compress | vol /dev/fd0 .RE .PP To restore a tree from 720 kb images from possibly bigger floppies: .PP .RS vol 720 /dev/fd0 | uncompress | tar xfp \- .RE .PP Read or write a device with 1024 byte blocks: .PP .RS vol \-b 1k /dev/rsd15 .RE .PP Read or write a variable block length tape using blocking factor 20 as used by default by many .BR tar (1) commands: .PP .RS vol \-m 20b /dev/rst5 .RE .PP Note that .B \-m was used in the last example. It sets the size to use to read or write, .B \-b sets the basic block size that may be written in multiples. .SH "SEE ALSO" .BR dd (1), .BR tar (1), .BR mt (1), .BR mtio (4). .TH WHATIS 1 .SH NAME whatis, apropos \- give single line descriptions for manual pages .SH SYNOPSIS .B whatis .RB [ \-a ] .I title .br .B apropos .I keyword .SH DESCRIPTION .B Whatis lists the one line description from the .BR whatis (5) database describing the title given. It displays all the lines with the title from the first whatis file that has those titles. It uses the same search path as .BR man (1). .PP .B Apropos searches through all whatis files for the given keywords. It lists any line that has the keyword anywhere on the line. .SH OPTIONS .TP .B \-a Search all whatis files. .SH "SEE ALSO" .BR man (1), .BR grep (1), .BR whatis (5). .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .\" $Header: yap.1,v 6.2 88/04/29 11:47:43 ceriel Exp $ .\" nroff -man yap.1 .tr ~ .TH YAP 1 local .SH NAME yap, more \- yet another pager .SH SYNOPSIS .B yap [ .B \-cnuq ] [ .B \-\fIn\fP ] [ .B +\fIcommand\fP ] [ name ... ] .SH DESCRIPTION .I Yap is a program allowing the user to examine a continuous text one screenful at a time on a video display terminal. It does so by pausing after each screenful, waiting for the user to type a command. The commands are enumerated later. .IR Yap 's main feature is, that it can page both forwards and backwards, even when reading from standard input. .PP The command line options are: .TP .I \-n An integer which is the size (in lines) of a page (the initial .IR page-size . .TP .B \-c Normally, .I yap will display each page by beginning at the top of the screen and erasing each line just before it displays on it. If your terminal cannot erase a line, .I yap will clear the screen before it displays a page. .br This avoids scrolling the screen, making it easier to read while .I yap is writing. The .B -c option causes .I yap to scroll the screen instead of beginning at the top of the screen. This is also done if your terminal cannot either erase a line or clear the screen. .TP .B \-u Normally, .I yap handles underlining such as produced by nroff in a manner appropriate to the particular terminal: if the terminal can perform underlining well (t.i., the escape sequences for underlining do not occupy space on the screen), .I yap will underline underlined information in the input. The .B -u option supresses this underlining. .TP .B \-n Normally, .I yap also recognises escape sequences for stand-out mode or underlining mode in the input, and knows how much space these escape sequences will occupy on the screen, so that .I yap will not fold lines erroneously. The .B -n option supresses this pattern matching. .TP .B \-q This option will cause .I yap to exit only on the "quit" command. .TP .BI + command \fIcommand\fP is taken to be an initial command to .IR yap . .PP .I Yap uses the .IR termcap (5) database to determine the terminal capabilities and the default .IR page-size . It examines the $TERM environment variable to identify the terminal type. If $TERM is not set, it defaults to .IR dumb . .I Yap Also examines the $TERMCAP environment variable to locate the .IR termcap (5) database. If $TERMCAP is not set, it defaults to .IR /etc/termcap . .PP .I Yap looks in the $YAP environment variable to pre-set flags. For instance, if you prefer the .B -c mode of operation, just set the $YAP environment variable to .BR -c . .PP The commands of .I yap can be bound to sequences of keystrokes. The environment variable $YAPKEYS may contain the bindings in the form of a list of colon-separated `name=sequence' pairs. The .I name is a short mnemonic for the command, the .I sequence is the sequence of keystrokes to be typed to invoke the command. This sequence may contain a ^X escape, which means control-X, and a \\X escape, which means X. The latter can be used to get the characters `^', `\\' and `:' in the sequence. There are two keymaps available, the default one and a user-defined one. You can switch between one and the other with the .I change keymap command. .PP The .I yap commands are described below. The mnemonics for the commands are given in parentheses. The default key sequences (if any) are given after the mnemonic. Every command takes an optional integer argument, which may be typed before the command. Some commands just ignore it. The integer argument is referred to as .IR i . Usually, if .I i is not given, it defaults to 1. .de Nc .PP \&\\$1 .RI ( \\$2 ) .BR \\$3 .br .RS .. .de Ec .RE .. .Nc "visit previous file" bf P Visit the .IR i -th previous file given in the command line. .Ec .Nc "scroll one line up or go to line" bl "^K ~or~ k" If .I i is not given, scroll one line up. Otherwise, .I i will be interpreted as a line number. A page starting with the line indicated will then be displayed. .Ec .Nc "bottom" bot "l ~or~ $" Go to the last line of the input. .Ec .Nc "display previous page" bp - Display the previous page, consisting of .I i lines, (or .I page-size lines if no argument is given). .Ec .Nc "display previous page and set pagesize" bps Z Display the previous page, consisting of .I i lines, (or .I page-size lines if no argument is given). If .I i is given, the .I page-size is set to .IR i . .Ec .Nc "scroll up" bs ^B Scroll up .I i lines (or .I scroll-size lines if .I i is not given. Initially, the .I scroll-size is 11). .Ec .Nc "search backwards for pattern" bse ? Search backwards for the .IR i -th occurrence of a regular expression which will be prompted for. If there are less than .I i occurrences of the expression, the position in the file remains unchanged. Otherwise, a page is displayed, starting two lines before the place where the expression was found. The user's erase and kill characters may be used to edit the expression. Erasing back past the first character cancels the search command. .br Note: Some systems do not have .IR regex (3). On those systems, searches are still supported, but regular expressions are not. .Ec .Nc "skip lines backwards" bsl S Skip .I i lines backwards and display a page. .Ec .Nc "skip pages backwards" bsp F Skip .I i pages backwards and display a page. .Ec .Nc "scroll up and set scrollsize" bss b Scroll up .I i lines (or .I scroll-size lines if .I i is not given. If .I i is given, the .I scroll-size is set to .IR i . .Ec .Nc "change key map" chm ^[ Change from the current key map to the other (if there is one). .Ec .Nc "exchange current page and mark" exg x Set the mark to the current page, and display the previously marked page. .Ec .Nc "visit next file" ff N Visit the .IR i -th next file given in the command line. .Ec .Nc "scroll one line down or go to line" fl "^J ~or~ ^M ~or~ j" If .I i is not given, scroll one line down. Otherwise, .I i will be interpreted as a line number. A page starting with the line indicated will then be displayed. .Ec .Nc "display next page" fp Display the next page, consisting of .I i lines, (or .I page-size lines if no argument is given). .Ec .Nc "display next page and set pagesize" fps z Display the next page, consisting of .I i lines, (or .I page-size lines if no argument is given). If .I i is given, the .I page-size is set to .IR i . .Ec .Nc "scroll down" fs ^D Scroll down .I i lines (or .I scroll-size lines if no argument is given). .Ec .Nc "search forwards for pattern" fse / Search forwards for the .IR i -th occurrence of a regular expression which will be prompted for. If there are less than .I i occurrences of the expression, the position in the file remains unchanged. Otherwise, a page is displayed, starting two lines before the place where the expression was found. The user's erase and kill characters may be used to edit the expression. Erasing back past the first character cancels the search command. .br Note: Some systems do not have .IR regex (3). On those systems, searches are still supported, but regular expressions are not. .Ec .Nc "skip lines forwards" fsl s Skip .I i lines and display a page. .Ec .Nc "skip pages forwards" fsp f Skip .I i pages and display a page. .Ec .Nc "scroll down and set scrollsize" fss d Scroll down .I i lines (or .I scroll-size lines if .I i is not given. If .I i is given, the .I scroll-size is set to .IR i . .Ec .Nc "help" hlp h Give a short description of all commands that are bound to a key sequence. .Ec .Nc "set a mark" mar m Set a mark on the current page. .Ec .Nc "repeat last search" nse n Search for the .IR i -th occurrence of the last regular expression entered, in the direction of the last search. .Ec .Nc "repeat last search in other direction" nsr r Search for the .IR i -th occurrence of the last regular expression entered, but in the other direction. .Ec .Nc "quit" qui "Q ~or~ q" Exit from .IR yap . .Ec .Nc "redraw" red ^L Redraw the current page. .Ec .Nc "repeat" rep . Repeat the last command. This does not always make sense, so not all commands can be repeated. .Ec .Nc "shell escape" shl ! Invoke the shell with a command that will be prompted for. In the command, the characTVWters `%' and `!' are replaced with the current file name and the previous shell command respectively. The sequences `\\%' and `\\!' are replaced by `%' and `!' respectively. The user's erase and kill characters can be used to edit the command. Erasing back past the first character cancels the command. .Ec .Nc "pipe to shell command" pip | Pipe the current input file into a shell command that will be prompted for. The comments given in the description of the shell escape command apply here too. .Ec .Nc "go to mark" tom ' Display the marked page. .Ec .Nc "top" top ^^ Display a page starting with the first line of the input. .Ec .Nc "visit file" vis e Visit a new file. The filename will be prompted for. If you just type a return, the current file is revisited. .Ec .Nc "write input to a file" wrf w Write the input to a file, whose name will be prompted for. .Ec .PP The commands take effect immediately, i.e., it is not necessary to type a carriage return. Up to the time when the command sequence itself is given, the user may give an interrupt to cancel the command being formed. .SH AUTHOR Ceriel J.H. Jacobs .SH FILES .DT /etc/termcap Terminal capabilities data base .SH SEE ALSO .IR termcap (5), ~regex (3). .SH BUGS .I Yap will find your terminal very stupid and act like it, if it has no way of placing the cursor on the home position, or cannot either erase a line or insert one. .PP In lines longer than about 2000 characters, a linefeed is silently inserted. .PP The percentage, given in the prompt when .I yap reads from a file (and knows it), is not always very accurate. .TH SYNCTREE 1 .SH NAME synctree \- synchronize directory trees. .SH SYNOPSIS .nf \fBsynctree\fP [\fB\-iuf\fP] [[\fIuser1\fP@]\fImachine1\fP:]\fIdir1\fP [[\fIuser2\fP@]\fImachine2\fP:]\fIdir2\fP .fi .SH DESCRIPTION .B Synctree synchronizes the directory tree rooted at \fIdir2\fP with \fIdir1\fP. It walks recursively through both trees, and deletes and adds files in \fIdir2\fP to make it equal to \fIdir1\fP. Mode, owner and group are set for each file unless the \fB\-u\fP flag is given. In its normal mode of operation, synctree will ask if it may delete or add directories assuming that you don't want to. Non-directories are simply deleted or added, but synctree will ask if it needs to update a normal file with a default answer of 'y'. Simply typing return will choose the default answer, typing end-of-file is like typing return to this question and all other questions. .PP You can specify a hostname and user-id to be used to access \fIdir1\fP or \fIdir2\fP. Synctree will use \fBrsh\fP(1) to run a copy of itself on the remote machine. The call interface mimics that of \fBrcp\fP(1), but you can use more than one user@machine prefix if you want to make things really interesting. .PP Hard links are enforced, an update is done by first deleting the old file so that links to unknown files are broken. Links to files within \fIdir2\fP will be restored. .PP If either directory contains the file \fB.backup\fP, then this file will be used as an alternate inode table. This allows one to make a backup copy of a file tree full of special files and differing user-ids on a remote machine under an unpriviledged user-id. .PP .SH OPTIONS .TP 5 .B \-i Ask for permission (with default answer 'n') to delete or add any file or directory. .TP 5 .B \-u Only install newer files, i.e. merge the directory trees. .TP 5 .B \-f Don't ask, think 'yes' on any question. .SH "SEE ALSO" .BR remsync (1), .BR cpdir (1), .BR rsh (1), .BR rcp (1), .BR perror (3). .SH DIAGNOSTICS Messages may come from three different processes. One named "Slave" running in \fIdir1\fP, one named "Master" running in \fIdir2\fP, and synctree itself in a mediator role. The mediator will also perform the task of either the master or the slave if one of them is running locally. You need to know this to interpret the error messages coming from one of these processes. The messages are normally based on \fBperror\fP(3). Failure to contact a remote machine will be reported by \fBrsh\fP. \fBSynctree\fP should have a zero exit status if no errors have been encountered. .SH BUGS Directory \fIdir2\fP will be created without asking. .PP The master and slave processes get their error output mixed up sometimes (nice puzzle). .PP The local and remote machine must use the same file type encoding. .PP The link replacement strategy may lead to lack of space on a small device. Let \fBsynctree\fP run to completion and then rerun it to pick up the pieces. .PP Letting the local process keep its "synctree" name may be a mistake. .PP It talks too much. .SH AUTHOR Kees J. Bot, (kjb@cs.vu.nl) .TH M 1 .SH NAME M, U \- conveniently mount and unmount .SH SYNOPSIS \fBM \fIdevice\fR [\fB\-r\fR]\fR .br \fBU \fIdevice\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-r" "Mount read-only" .SH EXAMPLES .EX "M root" "Mount the RAM image on /root" .EX "M 0" "Mount /dev/fd0 on /fd0" .EX "U fd1" "Unmount /dev/fd1 from /fd1" .SH DESCRIPTION .PP \fIM\fR and \fIU\fR allow easy mounting and unmounting of a device by using only an abbreviated device name or keyword. Special keywords are \fBroot\fR, \fBtmp\fR, and \fBusr\fR for the three hard disk partitions Minix runs in. Floppy devices are mounted on \fB/fd0\fR or \fB/fd1\fR. You can use \fB0\fR and \fB1\fR instead of \fBfd0\fR and \fBfd1\fP. A device it doesn't know about is mounted on \fB/mnt\fR. .SH "SEE ALSO" .BR mount (1), .BR umount (1). .TH ANM 1 .SH NAME anm \- print name list .SH SYNOPSIS \fBanm \fR[\fB\-gnoprus\fR] \fIfile\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-g" "Global symbols only" .FL "\-n" "Sort numerically" .FL "\-o" "Prepend the filename to each line" .FL "\-p" "No sorting\(emuse symbol table order" .FL "\-r" "Sort in reverse order" .FL "\-u" "List undefined symbols only" .FL "\-s" "Sort in section order" .SH EXAMPLES .EX "anm \-gn test.o" "Print global symbols in numerical order" .SH DESCRIPTION .PP .I Anm prints the name list (symbol table) of each ACK format object .I file in the argument list. If no file name is given, \fIa.out\fR is used. Each symbol name is preceded by its value, a section indicator and a type indicator. The section indicators are: .PP .ta 0.25i 0.50i .nf \fBU\fR Undefined symbol \fBA\fR Absolute symbol \fB\-\fR Other symbol .sp The type indicators are: .PP \fBF\fR Filename \fBM\fR Module name \fBS\fR Section name \fBE\fR External (global) symbol \fB\-\fR Local symbol .fi .PP The output is sorted alphabetically, unless otherwise specified. Notice that \fIanm\fR can only be used on ACK format object files (that is: \fI.o\fR and \fI.out\fR files). If you want to get the name list of an executable program use .I nm instead. .SH "SEE ALSO" .BR asize (1), .BR nm (1), .BR ar (1), .BR size (1). .TH AR 1 .SH NAME ar, aal \- archivers .SH SYNOPSIS \fBar\fR [\fBdmpqrtx\fR][\fBabciluv\fR]\fR [\fIposname\fR] \fIarchive\fR [\fIfile \fR...]\fR .br \fBaal\fR [\fBdpqrtx\fR][\fBclv\fR]\fR \fIarchive\fR [\fIfile \fR...]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "ar r libc.a sort.s" "Replace \fIsort\fR.s in \fIlibc.a\fR" .EX "ar rb a.s libc.a b.s" "Insert \fIb.s\fR before \fIa.s\fR in \fIlibc.a\fR" .SH DESCRIPTION .PP \fIAr\fR allows groups of files to be put together into a single archive. It is normally used for libraries of compiled procedures. \fIAal\fR is like \fIar\fP, but is to be used with the ACK compiler. The following keys are allowed: .PP .ta 0.25i 0.50i .nf \fBd\fR: Delete. \fIAr\fR will delete the named members. \fBm\fR: Move named files. \fIAr\fR expects \fIa\fR, \fIb\fR, or \fIi\fR to be specified. \fBp\fR: Print the named files (list them on \fIstdout\fR) \fBq\fR: Quickly append to the end of the archive file. \fBr\fR: Replace (append when not in archive). \fBt\fR: Print the archive's table of contents. \fBx\fR: Extract .fi .PP \fBThe keys may optionally concatencated with one or more of the following\fR: .nf .PP \fBa\fR: After \fIposname\fR \fBb\fR: Before \fIposname\fR \fBc\fR: Create (suppresses creation message) \fBi\fR: Before \fIposname\fR \fBl\fR: Local temporary file for work instead of \fI/tmp/ar.$$$$$\fR \fBu\fR: Replace only if dated later than member in archive \fBv\fR: Verbose .PP .fi .SH "SEE ALSO" .BR anm (1), .BR asize (1), .BR nm (1), .BR size (1). .TH ASCII 1 .SH NAME ascii \- strip all the pure ASCII lines from a file .SH SYNOPSIS \fBascii\fR [\fB\-n\fR]\fR [\fIfile\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-n" "Extract the lines containing nonASCII characters" .SH EXAMPLES .EX "ascii file >outf" "Write all the ASCII lines on \fIoutf\fR" .EX "ascii \-n outf" "Write all the nonASCII lines on \fIoutf\fR" .SH DESCRIPTION .PP Sometimes a file contains some nonASCII characters that are in the way. This program allows the lines containing only ASCII characters to be \fIgrepped\fR from the file. With the \fB\-n\fR flag, the nonASCII lines are \fIgrepped\fR. No matter whether the flag is used or not, the program returns an exit status of true if the file is pure ASCII, and false otherwise. .SH "SEE ALSO" .BR tr (1). .TH ASIZE 1 .SH NAME asize \- report the size of an object file .SH SYNOPSIS \fBasize \fIfile\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "asize test.o" "Give the size of \fItest.o\fR" .SH DESCRIPTION .PP .I Asize prints for each argument the (decimal) number of bytes used by the different sections, as well as their sum in decimal and hexadecimal. If no .I file is given \fIa.out\fR is used. .I Asize can only be used to obtain the size of a \(M2 \fI.o\fR or \fI.out\fR file. To obtain the size of an executable, use .I size instead. .SH "SEE ALSO" .BR anm (1), .BR nm (1), .BR ar (1), .BR size (1). .TH AT 1 .SH NAME at, atrun \- execute commands at a later time .SH SYNOPSIS \fBat \fItime\fR [\fImonth day\fR] [\fIfile\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "at 2315 Jan 31 myfile" "Myfile executed Jan 31 at 11:15 pm" .EX "at 0900" "Job input read from \fIstdin\fR" .EX "at 0711 4 29 " "Read from \fIstdin\fR, exec on April 29" .SH DESCRIPTION .PP \fIAt\fR prepares a file to be executed later at the specified time by creating a special entry in \fI/usr/spool/at\fR. The program \fIatrun\fR should be started periodically, for example, every minute by \fIcron\fR. \fIAtrun\fR checks to see if any files in \fI/usr/spool/at\fR should now be run, and if so, it runs them and then puts them in \fI/usr/spool/at/past\fR. The name of the file created in \fI/usr/spool/at\fR by \fIat\fR is YY.DDD.HHMM.UU (where YY, DDD, HH, and MM give the time to execute and UU is a unique number). Note that when the command runs, it will not be able to use \fIstdin\fR or \fIstdout\fR unless specifically redirected. In the first example above, it might be necessary to put \fI>/dev/log\fR on some lines in the shell script \fImyfile\fR. The same holds for the commands typed directly to \fIat\fR. .SH "SEE ALSO" .BR cron (8). .TH BANNER 1 .SH NAME banner \- print a banner .SH SYNOPSIS \fBbanner \fIarg ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "banner happy birthday" "Print a banner saying happy birthday" .SH DESCRIPTION .PP \fIBanner\fR prints its arguments on \fIstdout\fR using a matrix of 6 x 6 pixels per character. .TH BASENAME 1 .SH NAME basename, dirname \- strip off file prefixes and suffixes .SH SYNOPSIS \fBbasename \fIfile\fR [\fIsuffix\fR]\fR .br \fBdirname \fIfile\fR .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS (none) .SH EXAMPLES .EX "basename /user/ast/file.c" "Strips path to yield \fIfile.c\fP" .EX "basename /user/file.c .c" "Strips path and \fI.c\fP to yield \fIfile\fP" .EX "dirname /user/file.c" "Strips basename to yield \fI/user\fP" .SH DESCRIPTION .PP .I Basename removes the initial directory names (if any) yielding the name of the file itself. If a second argument is present, it is interpreted as a suffix and is also stripped, if present. .PP .I Dirname removes the final component of a path, yielding the directory a file is in. .PP These programs are primarily used in shell scripts. .TH BTOA 1 .SH NAME btoa \- binary to ascii conversion .SH SYNOPSIS \fBbtoa\fR [\fB\-adhor\fR]\fR [\fIinfile\fR] [\fIoutfile\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-a" "Decode, rather than encode, the file" .FL "\-d" "Extracts repair file from diagnosis file" .FL "\-h" "Help menu is displayed giving the options" .FL "\-o" "The obsolete algorithm is used for backward compatibility" .FL "\-r" "Repair a damaged file" .SH EXAMPLES .EX "btoa a.btoa" "Convert \fIa.out\fR to ASCII" .EX "btoa \-a a.out" "Reverse the above" .SH DESCRIPTION .PP \fIBtoa\fR is a filter that converts a binary file to ascii for transmission over a telephone line. If two file names are provided, the first in used for input and the second for output. If only one is provided, it is used as the input file. The program is a functionally similar alternative to \fIuue/uud\fR, but the encoding is completely different. Since both of these are widely used, both have been provided with \s-2MINIX\s+2. The file is expanded about 25 percent in the process. .SH "SEE ALSO" .BR uue (1), .BR uud (1). .TH CAL 1 .SH NAME cal \- print a calendar .SH SYNOPSIS \fBcal\fR [\fImonth\fR] \fIyear\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "cal 3 1992" "Print March 1992" .SH DESCRIPTION .PP \fICal\fR prints a calendar for a month or year. The year can be between 1 and 9999. Note that the year 91 is not a synonym for 1991, but is itself a valid year about 19 centuries ago. The calendar produced is the one used by England and her colonies. Try Sept. 1752, Feb 1900, and Feb 2000. If you do not understand what is going on, look up \fICalendar, Gregorian\fR in a good encyclopedia. .TH CALENDAR 1 .SH NAME calendar \- reminder service .SH SYNOPSIS \fBcalendar [\fB\-\fR] [\fB\-r\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-" "Work for every user and send mail to him" .FL "\-r" "Restrict multiple execution on the same day" .SH EXAMPLES .EX "calendar" "Check \fIcalendar\fR file in current directory" .EX "calendar" "Normary used under the control of cron(8)" .EX "calendar \-r" " Normary used in /etc/rc file" .SH DESCRIPTION .PP Basically \fIcalendar\fR program consults the file \fIcalendar\fR in the current directory and display lines which contain today's or tomorrow's date. Month-day formats such as '12/25', 'Dec. 25', 'december 25', '*/25', '12/*', '*/*' are recognized. The asterisk means 'all' days or 'all' months. On weekends 'tomorrow' extends through next Monday without any consideration about holidays. To prevent ambiguity, the formats '25 Dec.' and '25/12' are not recognized. .PP When an argument \fB\-\fR is present, \fIcalendar\fR works for all users with a file \fIcalendar\fR in their login directories and sends them mail. Normally this is done daily under the control of \fIcron\fR. .PP The \fB\-r\fR option does its the same job as \fB\-\fR option, but touches the \fIcalendar\fR to prevents further access on the same day. Normally this is done in the \fI/etc/rc\fR file on a machine which may be booted several times in one day. .SH "SEE ALSO" .BR cron (8). .TH CAT 1 .SH NAME cat \- concatenate files and write them to stdout .SH SYNOPSIS \fBcat\fR [\fB\-u\fR]\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-u" "Unbuffered output" .SH EXAMPLES .EX "cat file" "Display file on the terminal" .EX "cat file1 file2 | lpr" "Concatenate 2 files and print result" .SH DESCRIPTION .PP .I Cat concatenates its input files and copies the result to \fIstdout\fR. If no input file is named, or \- is encountered as a file name, standard input is used. Output is buffered in 512 byte blocks unless the .B \-u flag is given. If you just want to copy a file, \fIcp\fR should be used since it is faster. .SH "SEE ALSO" .BR cp (1). .TH CC 1 .SH NAME cc \- C compiler .SH SYNOPSIS \fBcc\fR [\fB\-STOUfcimos\fR]\fR [\fB\-w[aos]\fR] [\fB\-v[n]\fR] [\fB\-D\fIname\fR]* [\fB\-I\fIdir\fR]* [\fB\-L\fIdir\fR]* \fIfile\fR+ [\fB\-l\fIname\fR]*\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-D" "The flag \fB\-D\fIx[=y]\fR defines a macro \fIx\fR with (optional) value \fIy\fR" .FL "\-I" "\fB\-I\fIdir\fR searches \fIdir\fR for include files" .FL "\-L" "\fB\-L\fIdir\fR searches \fIdir\fR for \fB\-l\fIname\fR libraries" .FL "\-O" "Optimize the code" .FL "\-S" "Produce an assembly code file, then stop" .FL "\-T" "The flag \fB\-T\fIdir\fR tells \fIcc\fR and \fIas\fR to use \fIdir\fR for temporary files" .FL "\-U" "Undefine a macro" .FL "\-E" "Preprocess to standard output" .FL "\-c" "Compile only. Do not link" .FL "\-f" "Link with floating point emulation library" .FL "\-i" "Use separate I & D space (64K + 64K) (\*(Mp only)" .FL "\-l" "The flag \fB\-l\fIname\fR causes the library lib\fIname\fR.a to be linked" .FL "\-m" "Remove unnecessary prototypes after preprocessing (\*(Mp only)" .FL "\-o" "Put output on file named by next arg" .FL "\-s" "Strip the symbol-table from executable file" .FL "\-v" "Verbose; print pass names" .FL "\-vn" "\fRVerbose; print pass names but do not run them" .FL "\-w" "\fRSuppress warning messages" .FL "\-ws" "\fRSuppress strict messages" .FL "\-wa" "\fRSuppress all warning and strict messages" .FL "\-wo" "\fRSuppress messages about old-style" .FL "\-.o" "Do not link the default run-time start-off" .SH EXAMPLES .EX "cc \-c file.c" "Compile \fIfile.c\fR" .EX "cc \-DFOO file.c" "Treat the symbol \fIFOO\fR as defined" .EX "cc \-wo \-o out file.c" "Compile old-style code; output to \fIout\fR" .SH DESCRIPTION .\" .if t .ta 0.9i 1.25i 2.75i 3.25i 3.75i .\" .if n .ta 10 15 39 .PP This is the C compiler. It has eight passes, as follows: .PP .if t .ta 1.4i 2.1i 2.8i .if n .ta 13 21 30 \fBProgram Input Output Operation performed\fR .br lib/ncpp prog.c prog.i C preprocessor: #include, #define, #ifdef .br lib/irrel prog.i prog.i Removal of unnecessary prototypes .br lib/ncem prog.i prog.k Parsing and semantic analysis .br lib/nopt prog.k prog.m Optimization of the intermediate code .br lib/ncg prog.m prog.s Code generation .br bin/as prog.s prog.o Assembly .br lib/ld prog.o prog.out Linking .br lib/cv prog.out a.out Conversion to \s-1MINIX\s0 a.out format .PP In the 68000 versions of \s-1MINIX\s0 , the preprocessor is not called since the front-end contains the preprocessor. This increases compilation speed. .PP The main program, .I cc , forks appropriately to call the passes, transmitting flags and arguments. The \fB\-v\fR flag causes the passes to be listed as they are called, and the \fB\-vn\fR flag causes the passes to be listed but not called. .PP The libraries should be made with \fIaal\fR (which is the same as \fIar\fR on the 68000 versions), and consist of .o files. The internal order of files inside the library is unimportant, but the order in which the libraries are specified is. .PP .PP When \fB\-T\fR is used, the intermediate files end up in the directory specified. Otherwise, .B /tmp is used. When available memory is very limited (e.g., a 512K machine), it may be necessary to run .I chmem to reduce the sizes of the compiler passes that do not fit, typically .I ncem . .PP On the other hand, if the compiler (or, in fact, almost any program) begins acting strange, it is almost always due to its running out of space, either stack space or scratch file space. The relevant pass can be given more stack space using .I chmem . More space for scratch files can be obtained by removing other files on the device. .PP If the compiler runs out of memory, it may be necessary to use the \fB\-m\fR flag. This causes .I irrel to be run, which removes unnecessary prototypes and thus frees up extra table space within the compiler. Beware, however, that running this pass may cause strictly conforming programs to become non-conforming and vice versa, so you should only run this pass as a last resort. .PP The compiler is derived from the ACK system (Tanenbaum et al., \fICommunications of the ACM\fR, Sept. 1983), not from the AT&T portable C compiler. It has been shoehorned onto the PC with some loss of performance. .SH "SEE ALSO" .BR make (1). .TH CDIFF 1 .SH NAME cdiff \- context diff .SH SYNOPSIS \fBcdiff\fR [\fB\-c\fIn\fR] \fIoldfile \fInewfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-c" "Provide \fIn\fR lines of context" .SH EXAMPLES .EX "cdiff old new >f" "Write context diff on \fIf\fR" .EX "cdiff \-c1 old new >f" "Use only 1 line of context" .SH DESCRIPTION .PP \fICdiff\fR produces a context diff by first running \fIdiff\fR and then adding context. Some update programs, like \fIpatch\fR, can use context diffs to update files, even in the presence of other, independent changes. .SH "SEE ALSO" .BR cmp (1), .BR diff (1), .BR patch (1). .TH CGREP 1 .SH NAME cgrep \- grep and display context .SH SYNOPSIS \fBcgrep\fR [\fB\-a \fIn\fR]\fR [\fB\-b \fIn\fR] [\fB\-f\fR] [\fB\-l \fIn\fR] [\fB\-n\fR] [\fB\-w \fIn\fR] \fIpattern\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-a" "How many lines to display after the matching line" .FL "\-b" "How many lines to display before the matching line" .FL "\-f" "Suppress file name in the output" .FL "\-l" "Lines are truncated to this length before comparison" .FL "\-n" "Suppress line numbers in the output" .FL "\-w" "Sets window size (same as \fB\-a\fR n \fB\-b\fR n)" .SH EXAMPLES .EX "cgrep \-w 3 hello file1" "Print 3 lines of context each way" .SH DESCRIPTION .PP \fICgrep\fR is a program like \fIgrep\fR, except that it also can print a few lines above and/or below the matching lines. It also prints the line numbers of the output. .SH "SEE ALSO" .BR grep (1), .BR fgrep (1). .TH CHGRP 1 .SH NAME chgrp \- change group .SH SYNOPSIS \fBchgrp [\fB\-R\fR] [\fIowner:\fR]\fIgroup \fIfile\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-R" "Change directory hierarchies" .SH EXAMPLES .EX "chgrp system file1 file2" "Make \fIsystem\fR the group of the files" .EX "chrgp \-R other dir1" "Make \fIother\fR the group of all files below dir1" .SH DESCRIPTION .PP The group field (and optionally owner field) of the named files is changed to .I group and .I owner . Alternatively, a decimal gid (uid) may be specified instead of a group name. If the \fB\-R\fR flag is used, the changes will be applied recursively to all files in named directories. Only the superuser may execute this command to set arbitrary groups. Normal users can only change the group if they own the file, and the group is their own group (Minix), or one of their supplementary groups (Minix-vmd). .SH "SEE ALSO" .BR chown (1), .BR chmod (1), .BR ls (1), .BR chown (2). .TH CHMEM 1 .SH NAME chmem \- change memory allocation .SH SYNOPSIS \fBchmem\fR [\fB+\fR]\fR [\fB\-\fR] [\fB=\fR] \fIamount file\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "chmem =50000 a.out" "Give \fIa.out\fP 50K of stack space" .EX "chmem \-4000 a.out" "Reduce the stack space by 4000 bytes" .EX "chmem +1000 file1" "Increase each stack by 1000 bytes" .SH DESCRIPTION .PP When a program is loaded into memory, it is allocated enough memory for the text and data+bss segments, plus an area for the stack. Data segment growth using .I malloc , .I brk , or .I sbrk eats up stack space from the low end. The amount of stack space to allocate is derived from a field in the executable program's file header. If the combined stack and data segment growth exceeds the stack space allocated, the program will be terminated. .PP It is therefore important to set the amount of stack space carefully. If too little is provided, the program may crash. If too much is provided, memory will be wasted, and fewer programs will be able to fit in memory and run simultaneously. \s-2MINIX\s+2 does not swap, so that when memory is full, subsequent attempts to fork will fail. The compiler sets the stack space to the largest possible value (for the Intel CPUs, 64K \- text \- data). For many programs, this value is far too large. Nonrecursive programs that do not call .I brk , .I sbrk , or .I malloc , and do not have any local arrays usually do not need more than 8K of stack space. .PP The .I chmem command changes the value of the header field that determines the stack allocation, and thus indirectly the total memory required to run the program. The = option sets the stack size to a specific value; the + and \- options increment and decrement the current value by the indicated amount. The old and new stack sizes are printed. .SH "SEE ALSO" .BR install (1), .BR brk (2). .TH CHMOD 1 .SH NAME chmod \- change access mode for files .SH SYNOPSIS \fBchmod [\fB\-R\fR] \fImode \fIfile\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-R" "Change hierarchies recursively" .SH EXAMPLES .EX "chmod 755 file" "Owner: rwx Group: r\-x Others: r\-x" .EX "chmod +x file1 file2" "Make \fIfile1\fR and \fIfile2\fR executable" .EX "chmod a\-w file" "Make \fIfile\fR read only" .EX "chmod u+s file" "Turn on SETUID for \fIfile\fR" .EX "chmod \-R o+w dir" "Allow writing for all files in dir" .SH DESCRIPTION .PP The given mode is applied to each file in the file list. If the \fB\-R\fR flag is present, the files in a directory will be changed as well. The mode can be either absolute or symbolic. Absolute modes are given as an octal number that represents the new file mode. The mode bits are defined as follows: .ta 0.25i .nf .PP 4000 Set effective user id on execution to file's owner id 2000 Set effective group id on execution to file's group id 0400 file is readable by the owner of the file 0200 writeable by owner 0100 executable by owner 0070 same as above, for other users in the same group 0007 same as above, for all other users .PP .fi Symbolic modes modify the current file mode in a specified way. The form is: .PP [who] op permissions { op permissions ...} {, [who] op ... } .PP The possibilities for \fIwho\fR are \fIu\fR, \fIg\fR, \fIo\fR, and \fIa\fR, standing for user, group, other and all, respectively. If \fIwho\fR is omitted, \fIa\fR is assumed, but the current umask is used. The op can be \fI+\fR, \fI-\fR, or \fI=\fR; \fI+\fR turns on the given permissions, \fI\- \fRturns them off; \fI=\fR sets the permissions exclusively for the given \fIwho\fR. For example \fIg=x\fR sets the group permissions to \fI--x\fR. .PP The possible permissions are \fIr\fR, \fIw\fR, \fIx\fR; which stand for read, write, and execute; \fIs\fR turns on the set effective user/group id bits. \fIs\fR only makes sense with \fIu\fR and \fIg\fR;\fR o+s\fR is harmless. .SH "SEE ALSO" .BR ls (1), .BR chmod (2). .TH CKSUM 1 .SH NAME cksum \- display file checksum and size .SH SYNOPSIS \fBcksum \fR[\fIfile\fR ...]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "cksum" "Display CRC and size of \fIstdin\fR" .EX "cksum *.c" "Display CRC and size of \fI.c\fP files" .SH DESCRIPTION .PP .I Cksum calculates and writes to standard output the 32-bits CRC of the input .I files , or of stdin if no .I files were specified. The size in bytes of each .I file will be displayed after a space. The name of each .I file will be displayed after another space. .SH "SEE ALSO" .BR crc (1), .BR sum (1). .TH CLR 1 .SH NAME clr \- clear the screen .SH SYNOPSIS \fBclr \fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "clr " "Clear the screen" .SH DESCRIPTION .PP All text is removed from the screen, resulting in an empty screen with the cursor positioned in the upper left-hand corner. .TH CMP 1 .SH NAME cmp \- compare two files .SH SYNOPSIS \fBcmp\fR [\fB\-ls\fR] \fIfile1 file2\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-l" "Loud mode. Print bytes that differ (in octal)" .FL "\-s" "Silent mode. Print nothing, just return exit status" .SH EXAMPLES .EX "cmp file1 file2" "Tell whether the files are the same" .EX "cmp \-l file1 file2" "Print all corresponding bytes that differ" .SH DESCRIPTION .PP Two files are compared. If they are identical, exit status 0 is returned. If they differ, exit status 1 is returned. If the files cannot be opened, exit status 2 is returned. If one of the file arguments is \-, then \fIstdin\fR is compared to the other file. .SH "SEE ALSO" .BR comm (1), .BR diff (1). .TH COMM 1 .SH NAME comm \- print lines common to two sorted files .SH SYNOPSIS \fBcomm\fR [\fB\-123\fR] \fIfile1 file2\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-1" "Suppress column 1 (lines present only in \fIfile1\fP)" .FL "\-2" "Suppress column 2 (lines present only in \fIfile2\fP)" .FL "\-3" "Suppress column 3 (lines present in both files)" .SH EXAMPLES .EX "comm file1 file2" "Print all three columns" .EX "comm \-12 file1 file2" "Print only lines common to both files" .SH DESCRIPTION .PP Two sorted files are read and compared. A three column listing is produced. Files only in .I file1 are in column 1; files only in .I file2 are in column 2; files common to both files are in column 3. The file name \- means \fIstdin\fR. .SH "SEE ALSO" .BR cmp (1), .BR diff (1), .BR sort (1). .TH COMPRESS 1 .SH NAME compress, uncompress, zcat \- compress a file using modified Lempel-Ziv coding .SH SYNOPSIS \fBcompress\fR [\fB\-cdfv\fR]\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-c" "Put output on \fIstdout\fR instead of on \fIfile.Z\fR" .FL "\-d" "Decompress instead of compress" .FL "\-f" "Force output even if there is no saving" .FL "\-v" "Verbose mode" .SH EXAMPLES .EX "compress outfile" "Compress 1 file" .EX "compress x y z" "Compress 3 files to \fIx.Z\fR, \fIy.Z\fR, and \fIz.Z\fR" .EX "compress \-d file.Z" "Decompress \fIfile.Z\fR to \fIfile\fR" .SH DESCRIPTION .PP The listed files (or \fIstdin\fR, if none are given) are compressed using the Ziv-Lempel algorithm. If the output is smaller than the input, the output is put on \fIfile.Z\fR or \fIstdout\fR if no files are listed. If \fIcompress\fR is linked to \fIuncompress\fR, the latter is the same as giving the \fB\-d\fP flag. Similarly, a link to \fIzcat\fR decompresses to \fIstdout\fR. The \s-2MINIX\s+2 version of \fIcompress\fR uses 13-bit compression. This means that when compressing files on other systems for transmission to \s-2MINIX\s+2, be sure that only 13-bit compression is used. On many systems, the default is 16-bit (too big). .SH "SEE ALSO" .BR tar (1). .TH CP 1 .SH NAME cp, cpdir \- file copy .SH SYNOPSIS \fBcp [\fB\-pifsmrRvx\fR] \fIfile1\fR \fIfile2\fR\fR .br \fBcp [\fB\-pifsrRvx\fR] \fIfile\fR ... \fIdirectory\fR\fR .br \fBcpdir [\fB\-ifvx\fR] \fIfile1\fR \fIfile2\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-p" "Preserve full mode, uid, gid and times" .FL "\-i" "Ask before removing existing file" .FL "\-f" "Forced remove existing file" .FL "\-s" "Make similar, copy some attributes" .FL "\-m" "Merge trees, disable the into-a-directory trick" .FL "\-r" "Copy directory trees with link structure, etc. intact" .FL "\-R" "Copy directory trees and treat special files as ordinary" .FL "\-v" "Display what cp is doing" .FL "\-x" "Do not cross device boundaries" .SH EXAMPLES .EX "cp oldfile newfile" "Copy \fIoldfile\fR to \fInewfile\fR" .EX "cp -R dir1 dir2" "Copy a directory tree" .SH DESCRIPTION .PP .I Cp copies one file to another, or copies one or more files to a directory. Special files are normally opened and read, unless \fB\-r\fP is used. \fB\-r\fP also copies the link structure, something \fB\-R\fP doesn't care about. The \fB\-s\fP option differs from \fB\-p\fP that it only copies the times if the target file already exists. A normal copy only copies the mode of the file, with the file creation mask applied. Set-uid bits are cleared if the owner cannot be set. (The \fB\-s\fP flag does not patronize you by clearing bits. Alas \fB\-s\fP and \fB\-r\fP are nonstandard.) .PP .I Cpdir is a convenient synonym for \fBcp \-psmr\fP to make a precise copy of a directory tree. .SH "SEE ALSO" .BR cat (1), .BR mkdir (1), .BR rmdir (1), .BR ln (1), .BR rm (1). .TH CRC 1 .SH NAME crc \- print the checksum of the file data .SH SYNOPSIS \fBcrc \fIfile\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "crc *.c" "Print checksums of all the C programs" .SH DESCRIPTION .PP The checksum of each argument is computed and printed, along with the file length and its name, one file per line. This program is useful for seeing if a file transmitted to another machine has arrived correctly. It is conceptually similar to \fIsum\fR, except that it uses a stronger checksum algorithm and also prints the length. .SH "SEE ALSO" .BR cksum (1), .BR sum (1). .TH CTAGS 1 .SH NAME ctags - Generates "tags" and (optionally) "refs" files .SH SYNOPSIS \fBctags\fP [\fB-stvra\fP] \fIfilesnames\fP... .SH DESCRIPTION \fIctags\fP generates the "tags" and "refs" files from a group of C source files. The "tags" file is used by Elvis' ":tag" command, control-] command, and -t option. The "refs" file is sometimes used by the \fIref(1)\fP program. .PP Each C source file is scanned for #define statements and global function definitions. The name of the macro or function becomes the name of a tag. For each tag, a line is added to the "tags" file which contains: .RS .nf - the name of the tag - a tab character - the name of the file containing the tag - a tab character - a way to find the particular line within the file. .RE .fi .PP The filenames list will typically be the names of all C source files in the current directory, like this: .RS .nf $ ctags -stv *.[ch] .RE .fi .SH OPTIONS .IP \fB-t\fR Include typedefs. A tag will be generated for each user-defined type. Also tags will be generated for struct and enum names. Types are considered to be global if they are defined in a header file, and static if they are defined in a C source file. .IP \fB-v\fR Include variable declarations. A tag will be generated for each variable, except for those that are declared inside the body of a function. .IP \fB-s\fR Include static tags. \fICtags\fR will normally put global tags in the "tags" file, and silently ignore the static tags. This flag causes both global and static tags to be added. The name of a static tag is generated by prefixing the name of the declared item with the name of the file where it is defined, with a colon in between. For example, "static foo(){}" in "bar.c" results in a tag named "bar.c:foo". .IP \fB-r\fP This causes \fIctags\fP to generate both "tags" and "refs". Without \fB-r\fP, it would only generate "tags". .IP \fB-a\fR Append to "tags", and maybe "refs". Normally, \fIctags\fR overwrites these files each time it is invoked. This flag is useful when you have to many files in the current directory for you to list them on a single command-line; it allows you to split the arguments among several invocations. .SH FILES .IP tags A cross-reference that lists each tag name, the name of the source file that contains it, and a way to locate a particular line in the source file. .IP refs The "refs" file contains the definitions for each tag in the "tags" file, and very little else. This file can be useful, for example, when licensing restrictions prevent you from making the source code to the standard C library readable by everybody, but you still everybody to know what arguments the library functions need. .SH BUGS .PP \fIctags\fR is sensitive to indenting and line breaks. Consequently, it might not discover all of the tags in a file that is formatted in an unusual way. .SH "SEE ALSO" elvis(1), refs(1) .SH AUTHOR .nf Steve Kirkendall kirkenda@cs.pdx.edu .fi .TH CUT 1 .SH NAME cut \- select out columns of a file .SH SYNOPSIS \fBcut [ \fB \-b \fR|\fB \-c\fR] \fIlist\fR [\fIfile...\fR]\fR .br \fBcut \-f \fIlist\fR [\fB\-d \fIdelim\fR] [\fB \-s\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-b" "Cut specified bytes" .FL "\-c" "Select out specific characters" .FL "\-d" "Change the column delimiter to \fIdelim\fR" .FL "\-f" "Select out specific fields that are separated by the .FL "\-i" "Runs of delimiters count as one" .FL "\-s" "Suppres lines with no delimiter characters, when used .SH EXAMPLES .EX "cut \-f 2 file" "Extract field 2" .EX "cut \-c 1\-2,5 file" "Extract character columns 1, 2, and 5" .EX "cut \-c 1\-5,7\- file" "Extract all columns except 6" .SH DESCRIPTION [\fIfile...\fR]" delimiter character ( see \fIdelim\fR)" with the \-f option. Lines with no delimiters are passwd through untouched" .PP \fICut\fR extracts one or more fields or columns from a file and writes them on standard output. If the \fB\-f\fR flag is used, the fields are separated by a delimiter character, normally a tab, but can be changed using the \fB\-d\fR flag. If the \fB\-c\fR flag is used, specific columns can be specified. The list can be comma or BLANK separated. The \fB\-f\fR and \fB\-c\fR flags are mutually exclusive. Note: The POSIX1003.2 standard requires the option \-b to cut out specific bytes in a file. It is intended for systems with multi byte characters (e.g. kanji), since MINIX uses only one byte characters, this option is equivalent to \-c. For the same reason, the option \-n has no effect and is not listed in this manual page. .SH "SEE ALSO" .BR sed (1), .BR awk (9). .TH DATE 1 .SH NAME date \- print or set the date and time .SH SYNOPSIS \fBdate [\fB\-qsu\fR] [[\fIMMDDYY\fR]\fIhhmm\fR[\fIss\fR]] [\fI+format\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-q" "Read the date from \fIstdin\fR" .FL "\-s" "Set the time (implicit for \fB\-q\fR or a date string)" .FL "\-u" "Print the date as GMT" .FL "\-t" "Use this number of seconds instead of current time" .SH EXAMPLES .EX "date" "Print the date and time" .EX "date 0221921610" "Set date to Feb 21, 1992 at 4:10 p.m." .SH DESCRIPTION .PP With the \fB\-q\fR flag or a numeric argument, .I date sets the GMT time and date. .I MMDDYY refers to the month, day, and year; .I hhmmss refers to the hour, minute and second. Each of the six fields must be exactly two digits, no more and no less. .I date always display the date and time, with the default format for the system. The \fB\-u\fR flag request GMT time instead of local time. A format may be specified with a + followed by a printf-like string with the following options: .ta 0.25i .nf .PP %% % character %A Name of the day %B Name of the month %D mm/dd/yy %H Decimal hour on 2 digits %I Decimal hour modulo 12 on 2 digits %M Decimal minute on 2 digits %S Decimal seconds on 2 digits %T HH:MM:SS %U Decimal week number, Sunday being first day of week %W Decimal week number, Monday being first day of week %X Same as %T %Y Decimal year on 4 digits %Z Time Zone (if any) %a Abbreviated name of the day %b Abbreviated name of the month %c Appropriate date & time (default format) %d Decimal day of the month on 2 digits %e Same as %d, but a space replaces leading 0 %h Same as %b %j Decimal dey of the year on 3 digits %m Decimal month on 2 digits %n Newline character %p AM or PM %r 12-hour clock time with AM/PM %s Number of seconds since the epoch %t Tab character %w Decimal day of the week (0=Sunday) %x Same as %D %y Decimal year on 2 digits .SH "SEE ALSO" .BR time (2), .BR ctime (3), .BR readclock (8). .TH DD 1 .SH NAME dd \- disk dumper .SH SYNOPSIS \fBdd\fR [\fIoption = value\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "dd if=/dev/fd0 of=/dev/fd1" "Copy disk 0 to disk 1" .EX "dd if=x of=y bs=1w skip=4" "Copy \fIx\fP to \fIy\fP, skipping 4 words" .EX "dd if=x of=y count=3" "Copy three 512\-byte blocks" .SH DESCRIPTION .PP This command is intended for copying partial files. The block size, skip count, and number of blocks to copy can be specified. The options are: .PP .ta 0.25i 1.5i \fBif\fR = file \- Input file (default is \fIstdin\fR) .br \fBof\fR = file \- Output file (default is standard output) .br \fBibs\fR = n \- Input block size (default 512 bytes) .br \fBobs\fR = n \- Output block size (default is 512 bytes) .br \fBbs\fR = n \- Block size; sets \fIibs\fP and \fIobs\fP (default is 512 bytes) .br \fBskip\fR = n \- Skip \fIn\fP input blocks before reading .br \fBseek\fR = n \- Skip \fIn\fP output blocks before writing .br \fBcount\fR = n \- Copy only \fIn\fP input blocks .br \fBconv = lcase\fR \- Convert upper case letters to lower case .br \fBconv = ucase\fR \- Convert lower case letters to upper case .br \fBconv = swab\fR \- Swap every pair of bytes .br \fBconv = noerror\fR \- Ignore errors and just keep going .br \fBconv = silent\fR \- Suppress statistics (Minix specific flag) .PP Where sizes are expected, they are in bytes. However, the letters \fBw\fR, \fBb\fR, or \fBk\fR may be appended to the number to indicate words (2 bytes), blocks (512 bytes), or K (1024 bytes), respectively. When .I dd is finished, it reports the number of full and partial blocks read and written. .SH "SEE ALSO" .BR vol (1). .TH DF 1 .SH NAME df \- report on free disk space and i-nodes .SH SYNOPSIS \fBdf \fIspecial ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "df /dev/ram" "Report on free RAM disk space" .EX "df /dev/fd0 /dev/fd1" "Report on diskette space" .EX "df " "Report on all mounted devices" .SH DESCRIPTION .PP The amount of disk space and number of i-nodes, both free and used is reported. If no argument is given, \fIdf\fR reports on the root device and all mounted file systems. .SH "SEE ALSO" .BR du (1), .BR fstab (5). .TH DHRYSTONE 1 .SH NAME dhrystone \- integer benchmark .SH SYNOPSIS \fBdhrystone\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "dhrystone" "Run the dhrystone benchmark" .SH DESCRIPTION .PP Many years ago, a floating-point benchmark called \fIwhetstone\fR was popular for benchmarking FORTRAN programs. Nowadays, an integer benchmark called \fIdhrystone\fR is widely used for benchmarking UNIX systems. This is it. Be warned, however, that \fIdhrystone\fR is entirely CPU bound, and goes blindingly fast on machines with high-speed caches. Although this is a good measure for programs that spend most of their time in some inner loop, it is a poor benchmark for I/O bound applications. .TH DIFF 1 .SH NAME diff \- print differences between two files .SH SYNOPSIS \fBdiff \fR [\fB\-c \fR|\fB \-e \fR|\fB \-C \fIn\fR\] [\fB\-br\fR]\fIfile1 file2\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-C \fIn" "Produce output that contains \fIn\fR lines of context" .FL "\-b" "Ignore white space when comparing" .FL "\-c" "Produce output that contains three lines of context" .FL "\-e" "Produce an \fIed\fR-script to convert \fIfile1\fR into \fIfile2\fR" .FL "\-r" "Apply \fIdiff\fR recursively to files and directories of .SH EXAMPLES .EX "diff file1 file2" "Print differences between 2 files" .EX "diff -C 0 file1 file2" "Same as above" .EX "diff -C 3 file1 file2" "Output three lines of context with every .EX "diff -c file1 file2" Same as above" .EX "diff /etc /dev" "Compares recursively the directories \fI/etc\fR and \fI/dev\fR" .EX "diff passwd /etc" "Compares \fI./passwd\fR to \fI/etc/passwd" .SH DESCRIPTION the same name, when \fIfile1\fR and \fIfile2\fR are both directories" difference encountered" .PP \fIDiff\fR compares two files and generates a list of lines telling how the two files differ. Lines may not be longer than 128 characters. If the two arguments on the command line are both directories, \fIdiff\fR recursively steps through all subdirectories comparing files of the same name. If a file name is found only in one directory, a diagnostic message is written to \fIstdout\fR. A file that is of either block special, character special or FIFO special type, cannot be compared to any other file. On the other hand, if there is one directory and one file given on the command line, \fIdiff\fR tries to compare the file with the same name as \fIfile\fR in the directory \fIdirectory\fR. .SH "SEE ALSO" .BR cdiff (1), .BR cmp (1), .BR comm (1), .BR patch (1). .TH DISKCHECK 1 .SH NAME diskcheck \- check a disk for bad sectors .SH SYNOPSIS \fBdiskcheck \fIdevice \fIstart \fIcount\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "diskcheck /dev/at0 0 1200" "Check 1.2 MB diskette" .EX "diskcheck /dev/at0 100 50" "Check blocks 100 to 149" .SH DESCRIPTION .PP \fIDiskcheck\fR checks a disk for bad sectors by reading in each sector, writing a known bit pattern onto it, reading it back in and comparing with what was written. This check is then done a second time. Bad sectors are reported. After each sector is tested, the original sector is restored. Only use this program on unmounted partitions. Killing it part way through may result in lost data. .SH "SEE ALSO" .BR format (1). dosdir.1Bdosread.1Cdoswrite.1Ddu.1Eecho.1Fed.1Gelvis.1Helvrec.1Iexpand.1Jexpr.1Kfactor.1Lfgrep.1Mfile.1Nfind.1Ofinger.1Pfmt.1Qfold.1Rfortune.1Sfsck.1Tgather.1Ugrep.1Vhead.1Wic.1Xid.1Yifdef.1Zjoin.1[kill.1\last.1]leave.1^ln.1_loadfont.1`loadkeys.1alogin.1blook.1cls.1dmail.1emake.1fmesg.1gmkdir.1hmkfifo.1imkfs.1jmkproto.1kmodem.1lmount.1mmref.1nmv.1onm.1pod.1qpasswd.1rpaste.1spatch.1tpathchk.1upostmort.1vpr.1wprep.1xpretty.1yprintenv.1zps.1{pwd.1|rcp.1}readall.1~readfs.1recover.1ref.1.TH DOSDIR 1 .SH NAME dosdir \- list an MS-DOS directory [IBM] .SH SYNOPSIS \fBdosdir\fR [\fB\-lr\fR] \fIdrive\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-l" "Long listing" .FL "\-r" "Recursively descend and print subdirectories" .SH EXAMPLES .EX "dosdir \-l A" "List root directory on drive A" .EX "dosdir \-r C x/y" "Recursively list directory \fIx/y\fR" .EX "dosdir \-r fd1" "List device \fI/dev/fd1\fR" .SH DESCRIPTION .PP .I Dosdir reads standard IBM PC diskettes or hard disk partitions in \s-2MS-DOS\s+2 format and lists their contents on standard output. Directory names should contain slashes to separate components, even though \s-2MS-DOS\s+2 uses backslashes. The names .I dosdir , .I dosread , and .I doswrite are all links to the same program. The program sees which function to perform by seeing how it was called. A drive code of .I A causes the program to use \fI/dev/dosA\fR, for example, a link to \fI/dev/fd0\fR. Similarly, to have hard disk partition 1 be DOS drive C, \fI/dev/dosC\fR could be a link to \fI/dev/hd1\fR, and so on for other drive codes. A normal device name may also be used instead of a drive code. .TH DOSREAD 1 .SH NAME dosread \- read a file from an MS-DOS diskette [IBM] .SH SYNOPSIS \fBdosread\fR [\fB\-a\fR] \fIdrive \fIfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-a" "ASCII file" .SH EXAMPLES .EX "dosread C g/adv >adv" "Read file \fIg/adv\fR from hard disk" .EX "dosread \-a A prog.c >x" "Read ASCII file \fIprog.c\fR from drive A" .SH DESCRIPTION .PP .I Dosread reads one \s-2MS-DOS\s+2 file and writes it on standard output. The file name must use slash, not backslash as a separator. ASCII files have the final CTRL-Z stripped, and carriage return plus line feed are mapped to line feed only, the usual \s-2MINIX\s+2 convention. See \fBdosdir\fR on the use of single letter drive codes. .TH DOSWRITE 1 .SH NAME doswrite \- write a file onto an MS-DOS diskette [IBM] .SH SYNOPSIS \fBdoswrite\fR [\fB\-a\fR] \fIdrive \fIfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-a" "ASCII file" .SH EXAMPLES .EX "doswrite A x/y =, >}, {+, \-}, *, /, %, and :. Parentheses are permitted. .SH "SEE ALSO" .BR sh (1), .BR test (1). .TH FACTOR 1 .SH NAME factor \- factor an integer less than 2**31 .SH SYNOPSIS \fBfactor \fInumber\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "factor 450180" "Print the prime factors of 450180" .SH DESCRIPTION .PP \fIFactor\fR prints the prime factors of its argument in increasing order. Each factor is printed as many times as it appears in the number. .TH FGREP 1 .SH NAME fgrep \- fixed grep .SH SYNOPSIS \fBfgrep\fR [\fB\-cfhlnsv\fR]\fR [\fIstring_file\fR] [\fIstring\fR] [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-c" "Count matching lines and only print count, not the lines" .FL "\-f" "Take strings from file named in following argument" .FL "\-h" "Omit file headers from printout" .FL "\-l" "List file names once only" .FL "\-n" "Each line is preceded by its line number" .FL "\-s" "Status only, no output" .FL "\-v" "Print only lines not matching" .SH EXAMPLES .EX "fgrep % prog.c" "Print lines containing % sign" .EX "fgrep \-f pattern prog.c" "Take strings from \fIpattern\fR" .SH DESCRIPTION .PP \fIFgrep\fR is essentially the same as grep, except that it only searches for lines containing literal strings (no wildcard characters). The pattern may consist of several lines with one string to search on each line. .SH "SEE ALSO" .BR cgrep (1), .BR grep (1). .TH FILE 1 .SH NAME file \- make a guess as to a file's type based on contents .SH SYNOPSIS \fBfile \fIname ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "file a.out ar.h" "Guess at types" .SH DESCRIPTION .PP \fIFile\fR reads the first block of a file and tries to make an intelligent guess about what kind of file it is. It understands about archives, C source programs, executable binaries, shell scripts, and English text. .TH FIND 1 .SH NAME find \- find files meeting a given condition .SH SYNOPSIS \fBfind \fIdirectory \fIexpression\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "find / \-name a.out \-print " "Print all \fIa.out\fR paths" .EX "find /usr/ast ! \-newer f \-ok rm {} \\\\\^; " "Ask before removing" .EX "find /usr \-size +20 \-exec mv {} /big \\\\\^; " "move files > 20 blks" .EX "find / \( \-name a.out \-o \-name \(fm*.o\(fm \) \-exec rm {}\\\\\^;" "2 conds" .SH DESCRIPTION .PP \fIFind\fR descends the file tree starting at the given directory checking each file in that directory and its subdirectories against a predicate. If the predicate is true, an action is taken. The predicates may be connected by \fB\-a\fR (Boolean and), \fB\-o\fR (Boolean or) and ! (Boolean negation). Each predicate is true under the conditions specified below. The integer \fIn\fR may also be +\fIn\fR to mean any value greater than \fIn\fR, \fI\-n\fR to mean any value less than \fIn\fR, or just \fIn\fR for exactly \fIn\fR. .PP .ta 0.25i 1.0i .nf \-name s true if current filename is \fIs\fR (include shell wild cards) \-size n true if file size is \fIn\fR blocks \-inum n true if the current file's i-node number is \fIn\fR \-mtime n true if modification time relative to today (in days) is \fIn\fR \-links n true if the number of links to the file is \fIn\fR \-newer f true if the file is newer than \fIf\fR \-perm n true if the file's permission bits = \fIn\fR (\fIn\fR is in octal) \-user u true if the uid = \fIu\fR (a numerical value, not a login name) \-group g true if the gid = \fIg\fR (a numerical value, not a group name) \-type x where \fIx\fR is \fBbcdfug\fR (block, char, dir, regular file, setuid, setgid) \-xdev do not cross devices to search mounted file systems .fi .PP Following the expression can be one of the following, telling what to do when a file is found: .PP .nf \-print print the file name on standard output \-exec execute a \s-2MINIX\s0 command, {} stands for the file name \-ok prompts before executing the command .fi .SH "SEE ALSO" .BR test (1), .BR xargs (1). .\" Copyright (c) 1980 Regents of the University of California. .\" All rights reserved. The Berkeley software License Agreement .\" specifies the terms and conditions for redistribution. .\" .\" @(#)finger.1 6.4 (Berkeley) 5/10/86 .\" .TH FINGER 1 "May 10, 1986" .UC 4 .SH NAME finger \- user information lookup program .SH SYNOPSIS .B finger [ options ] name ... .SH DESCRIPTION By default .B finger lists the login name, full name, terminal name and write status (as a `*' before the terminal name if write permission is denied), idle time, login time, and office location and phone number (if they are known) for each current UNIX user. (Idle time is minutes if it is a single integer, hours and minutes if a ':' is present, or days and hours if a 'd' is present.) .PP A longer format also exists and is used by .B finger whenever a list of people's names is given. (Account names as well as first and last names of users are accepted.) This format is multi-line, and includes all the information described above as well as the user's home directory and login shell, any plan which the person has placed in the file .B \&.plan in their home directory, and the project on which they are working from the file .B \&.project also in the home directory. .PP .B Finger may be used to lookup users on a remote machine. The format is to specify the user as ``user@host.'' If the user name is left off, the standard format listing is provided on the remote machine. .PP .B Finger options include: .TP .B \-m Match arguments only on user name. .TP .B \-l Force long output format. .TP .B \-p Suppress printing of the .B \&.plan files .TP .B \-s Force short output format. .SH FILES .ta 2i /etc/utmp who file .br /etc/passwd for users names, offices, ... .br /usr/adm/lastlog last login times .br ~/.plan plans .br ~/.project projects .SH "SEE ALSO" .BR chfn (1), .BR w (1), .BR who (1). .SH AUTHOR Earl T. Cohen .SH BUGS Only the first line of the .B .project file is printed. .PP There is no way to pass arguments to the remote machine as .B finger uses an internet standard port. .TH FMT 1 .SH NAME fmt - adjust line-length for paragraphs of text .SH SYNOPSIS \fBfmt\fP [\-\fIwidth\fP] [\fIfiles\fP]... .SH DESCRIPTION \fIfmt\fR is a simple text formatter. It inserts or deletes newlines, as necessary, to make all lines in a paragraph be approximately the same width. It preserves indentation and word spacing. .PP The default line width is 72 characters. You can override this with the \-\fIwidth\fR flag. If you don't name any files on the command line, then \fIfmt\fR will read from stdin. .PP It is typically used from within \fIvi\fR to adjust the line breaks in a single paragraph. To do this, move the cursor to the top of the paragraph, type "!}fmt", and hit . .SH AUTHOR .nf Steve Kirkendall kirkenda@cs.pdx.edu .fi .TH FOLD 1 .SH NAME fold \- fold long lines .SH SYNOPSIS \fBfold\fR [\fB\-\fIn\fR]\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-\fIn\fR" "How long should the output lines be" .SH EXAMPLES .EX "fold \-60" "Fold \fIstdin\fR to 60 characters" .EX "fold file" "Fold \fIfile\fP to 80 characters" .SH DESCRIPTION .PP \fIFold\fR takes copies its input from the named file (or \fIstdin\fR, if none is specified) to standard output. However, lines longer than the given maximum (default 80) are broken into multiple lines of the maximum length by inserting new line characters. .SH "SEE ALSO" .BR width (1). .TH FORTUNE 1 .SH NAME fortune \- print a fortune .SH SYNOPSIS \fBfortune\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "fortune" "Print a fortune" .SH DESCRIPTION .PP \fIFortune\fR prints a fortune at random from the fortunes file, \fI/usr/lib/fortune.dat\fR. This file consists of pieces of text separated by a line containing only %%. .TH FSCK 1 .SH NAME fsck, fsck1 \- perform file system consistency check .SH SYNOPSIS \fBfsck\fR [\fB\-aclmrs\fR]\fR [\fIdevice\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-a" "Automatically repair inconsistencies" .FL "\-c" "Check and list only the specified i-nodes .FL "\-l" "List the files and directories in the filesytem .FL "\-r" "Prompt user for repairs if inconsistencies are found .FL "\-s" "List the superblock of the file system" .SH EXAMPLES .EX "fsck /dev/hd4" "Check file system on \fI/dev/hd4\fR" .EX "fsck \-a /dev/at0" "Automatically fix errors on \fI/dev/at0\fR" .EX "fsck \-l /dev/fd0" "List the contents of \fI/dev/fd0\fR" .EX "fsck \-c 2 3 /dev/hd3" "Check and list \fI/dev/hd3\fR i-nodes 2 & 3" .SH DESCRIPTION .PP \fIFsck\fR performs consistency checks on the file systems which reside on the specified devices. \fIFsck1\fR is an alternate version for use on obsolete V1 file systems. When either the \fB\-a\fR or \fB\-r\fR flags are given, the file system will be repaired if errors are found. Before running \fIfsck\fR on a mounted file system, it must first be unmounted. Trying to repair a mounted file system is dangerous and should not be attempted. .PP To repair the root file system (which cannot be unmounted), first type CTRL-F9 at the console to kill any and all processes. Log back in as \fBroot\fR, type \fIsync\fR to force any buffered changes to disk, run \fIfsck\fR on the root file system and immediately reboot the computer by typing \fIreboot\fR. .PP It is necessary to kill all processes before repairing the root file system to prevent them from modifying any disk blocks while \fIfsck\fR is running. This is only necessary for the root file system, any other file system can simply be unmounted before it is checked. .SH "SEE ALSO" .BR mkfs (1), .BR mount (1). .TH GATHER 1 .SH NAME gather \- gather up the files in a directory for transmission .SH SYNOPSIS \fBgather\fR [\fB\-s\fR] \fIsource_dir [\fB\-d\fR] dest_dir\fR [\fB\-b\fR] \fIbytes\fR [\fB\-f\fR] \fIfile\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-b" "Desired number of bytes per output file" .FL "\-d" "Destination directory" .FL "\-f" "Base name of output files" .FL "\-s" "Source directory" .SH EXAMPLES .EX "gather" "Collect files in current dir into 60K archives" .EX "gather \-d dir" "Put the archives in \fIdir\fR .EX "gather \-b 90000" "Try to produce 90K archives" .EX "gather \-s .. \-d targ \-b 5000" "Try to produce 5K archives" .SH DESCRIPTION .PP It is often useful to collect all the files in a directory into one or more archives for transmission by mail. This program collects all the files in the source directory (default: current directory) and puts them into a shar archive. The shar archive is then compressed and uuencoded. An attempt is made to have the final \fI.uue\fR file be about the given size (default: 60K), but since \fIgather\fR cannot really predict how much \fIshar\fR will add to the file, how much \fIcompress\fR will reduce the file, and how much \fIuue\fR will add again, the sizes can fluctuate. If the \fB\-f \fIfile\fR flag is given, the archives will be given the names \fIfile_00.uue\fR, \fIfile_01.uue\fR etc. If \fB\-f\fR is not given, the name of the source directory is used as the base name. Since 7 characters of suffix are appended, the base name should not exceed 7 characters. .TH GREP 1 .SH NAME grep \- search a file for lines containing a given pattern .SH SYNOPSIS \fBgrep\fR [\fB\-elnsv\fR] \fIpattern\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-e" "\fB\-e \fIpattern\fR is the same as \fIpattern\fP .FL "\-c" "Print a count of lines matched" .FL "\-i" "Ignore case" .FL "\-l" "Print file names, no lines" .FL "\-n" "Print line numbers" .FL "\-s" "Status only, no printed output" .FL "\-v" "Select lines that do not match" .SH EXAMPLES .EX "grep mouse file " "Find lines in \fIfile\fP containing \fImouse\fP" .EX "grep [0\-9] file" "Print lines containing a digit" .SH DESCRIPTION .PP .I Grep searches one or more files (by default, \fIstdin\fR) and selects out all the lines that match the pattern. All the regular expressions accepted by .I ed and .I mined are allowed. In addition, + can be used instead of \(** to mean 1 or more occurrences, ? can be used to mean 0 or 1 occurrences, and | can be used between two regular expressions to mean either one of them. Parentheses can be used for grouping. If a match is found, exit status 0 is returned. If no match is found, exit status 1 is returned. If an error is detected, exit status 2 is returned. .SH "SEE ALSO" .BR cgrep (1), .BR fgrep (1), .BR sed (1), .BR awk (9). .TH HEAD 1 .SH NAME head \- print the first few lines of a file .SH SYNOPSIS \fBhead\fR [\fB\-\fIn\fR]\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-\fIn\fR" "How many lines to print" .SH EXAMPLES .EX "head \-6" "Print first 6 lines of \fIstdin\fR" .EX "head \-1 file1 file2" "Print first line of two files" .SH DESCRIPTION .PP The first few lines of one or more files are printed. The default count is 10 lines. The default file is \fIstdin\fR. .SH "SEE ALSO" .BR tail (1). .TH IC 1 .SH NAME ic \- integer calculator .SH SYNOPSIS \fBic\fR [\fIexpression\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "ic " "Start the calculator" .EX "ic 250 300+" "Start calculator with 550 on the stack" .SH DESCRIPTION .PP \fIIc\fR is a simple RPN (Reverse Polish Notation) calculator, used for small calculations and base conversions. All calculations are done using 32 bit integers. The standard input is usually a keyboard and the standard output requires a device with a \&'termcap\&' entry. The program starts by interpreting any as commands, where the separation between arguments is considered to be the same as the ENTER key. For example, .PP .B " ""ic 692 784+" .PP After reading the arguments input is from the keyboard. .SS "Stack Operations" .PP The operation of this program is similar to an RPN calculator. A six level stack is used. The ENTER key pushes the stack up one level. For example, \&'12+5\&' is entered as \&'12 ENTER 5 +". .PP The top two entries on the stack are exchanged by the \fIx\fR command, and the stack is rolled down one (popped) by the \fIp\fR key. The top of the stack may be cleared by pressing the back-space key. The whole stack and the registers are initialized by a \fIz\fR. .SS "Numeric Entry" .PP The input and output bases are initially decimal, but they may be changed using the \fIi\fR and \fIo\fR commands. The \fIi\fR command changes both bases, but the \fIo\fR command changes just the output base. These commands take a one character argument of \fIh\fR, \fId\fR, \fIo\fR or \fIb\fR to change to Hexadecimal, Decimal, Octal or Binary. While the input base is hexadecimal the letters \fIa\fR through \fIf\fR are used to represent the decimal values 10 through 15. .PP When the input base is decimal: multiply, divide and remainder are signed, otherwise they are performed unsigned. .PP The output base may also be changed to ASCII (\fIa\fR), this causes the least significant 7 bits of a value to be displayed as a character. To input an ASCII value the translate (\fIt\fR) command may be used, it accepts one character as its argument. .SS "Calculations" .PP The arithmetic operations supported are: Negate (\&'.\&'), Add (\&'+\&'), Subtract (\&'\(mi\&'), Multiply (\&'*\&'), Divide (\&'/\&'), and Remainder (\&'%\&'). The logical (Boolean) operations available are: NOT (\&'~\&'), AND (\&'&\&'), OR (\&'|\&'), and EXCLUSIVE-OR (\&'^\&'). .PP After one of these operations the last top of stack value is saved. It may be restored by pressing \fIl\fR (L). .SS "Saving Results" .PP Ten temporary registers are available. The Store (\fIs\fR) command followed by a digit (\&'0\&'..\&'9\&') will copy the top of the stack to the specified register. The Recall (\fIr\fR) command pushes the contents of a register onto the top of the stack. .PP If the Store command is followed by a \&'+\&' preceding the digit, then the top of the stack will be added to the specified \&'accumulator\&' register. .PP Values may also be written to a file. The \fIw\fR command writes the top of the stack, using the current output base, to a file called \&'pad\&' in the current directory. If the user does not have write access to the current directory then the file \fI/tmp/pad_$USER\fR is used as the scratch pad. The scratch pad file is erased on the first use of the \fIw\fR command within each new invocation of \&'ic\&'. .SS "Miscellaneous" .PP The Quit (\fIq\fR) key causes an immediate exit. The \fIm\fR command temporarily leaves \fIic\fR by invoking the shell as a sub-process. For help while using \fIic\fR, hit the \fIh\fR key. If an erroneous key is pressed the bell will sound. .SS "Command Summary" .PP Note that many commands have an alternative key-code available on the extended AT keyboard. This aids entry by including most commands on the right side of the keyboard. .ta 0.25i 1.5i .nf .PP ENTER Enter (push up) BS (DEL) Clear top of stack h Help i Input base (h, d, o, b) l (PGDN) Last top of stack m \s-2MINIX\s0 shell o Output base (h, d, o, b, a) p (DOWN) Pop stack (roll down) q (END) Quit r (LEFT) Recall (0-9) s (RIGHT) Store [+] (0-9) t Translate (char) w (PGUP) Write top of stack to scratch pad x (UP) Exchange top of stack z (HOME) Zero all state . Change sign + (+) Add - (-) Subtract * Multiply / Divide % (sh/5) Remainder (tilde) Not & And | Or ^ Exclusive-or .fi .SS "Author" .PP \fIIc\fR was written by Terrence W. Holm. .TH ID 1 .SH NAME id \- print the uid and gid .SH SYNOPSIS \fBid\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "id" "Print the uid and gid" .SH DESCRIPTION .PP \fIId\fR prints the current uid and gid, both numerically and symbolically. If the effective uid and gid are different from the real ones, all of them are printed. .PP Under Minix-vmd the supplementary group IDs are also printed. .SH "SEE ALSO" .BR getuid (2), .BR getgid (2), .BR getgroups (2). .TH IFDEF 1 .SH NAME ifdef \- remove #ifdefs from a file .SH SYNOPSIS \fBifdef \fR[\fB\-t\fR] [\fB\-d\fIsymbol\fR] [\fB\-D\fIsymbol\fR] [\fB\-U\fIsymbol\fR] [\fB\-I\fIsymbol\fR] [file]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-D" "Define symbol permanently" .FL "\-I" "Ignore symbol" .FL "\-U" "Undefine symbol permanently" .FL "\-d" "Define symbol. It may be #undef'ed later" .FL "\-t" "Produce a table of the symbols on \fIstdout\fR" .SH EXAMPLES .EX "ifdef \-DUNIX file.c >newfile.c" "Define \fIUNIX\fR" .EX "ifdef \-D_MINIX \-UDOS y.c "Define \fI_MINIX\fR, undefine \fIDOS\fR" .SH DESCRIPTION .PP \fIIfdef\fR allows conditional code [ #ifdef ... #endif ] to be selectively removed from C files, but at the same time leaving all other C preprocessor commands intact such as #define, #include etc. Input to .I ifdef is either the file named as the last argument, or \fIstdin\fR if no file is named. Output goes to \fIstdout\fR. .PP Symbols may be defined with the \fB\-d\fR or \fB\-D\fR flags just like \fIcpp\fR, except that the latter option ignores subsequent \fI#undefs\fR. It is not permitted to give values to symbols. Similarly, \fB\-U\fR undefines a symbol and ignores subsequent \fI#defines\fRs. Symbols defined with \fB\-I\fR are ignored; any \fI#ifdef\fR using an ignored symbol will be left intact. .\" @(#)join.1 6.1 (Berkeley) 4/29/85 .\" .TH JOIN 1 "April 29, 1985" .AT 3 .SH NAME join \- relational database operator .SH SYNOPSIS .B join .RB [ \-a\fIn ] .RB [ \-e .IR s ] .RB [ \-o .IR list ] .RB [ \-t\fIc ] file1 file2 .SH DESCRIPTION .B Join forms, on the standard output, a join of the two relations specified by the lines of .I file1 and .IR file2 . If .I file1 is `\-', the standard input is used. .PP .I File1 and .I file2 must be sorted in increasing ASCII collating sequence on the fields on which they are to be joined, normally the first in each line. .PP There is one line in the output for each pair of lines in .I file1 and .I file2 that have identical join fields. The output line normally consists of the common field, then the rest of the line from .IR file1 , then the rest of the line from .IR file2 . .PP Fields are normally separated by blank, tab or newline. In this case, multiple separators count as one, and leading separators are discarded. .PP These options are recognized: .TP .BI \-a n In addition to the normal output, produce a line for each unpairable line in file .IR n , where .I n is 1 or 2. .TP .BI \-e " s" Replace empty output fields by string .IR s . .ig .TP .BI \-j "n m" Join on the .IR m th field of file .IR n . If .I n is missing, use the .IR m th field in each file. .. .TP .BI \-o " list" Each output line comprises the fields specified in .IR list , each element of which has the form .IR n . m , where .I n is a file number and .I m is a field number. .PP .TP .BI \-t c Use character .I c as a separator (tab character). Every appearance of .I c in a line is significant. .SH "SEE ALSO" .BR sort (1), .BR comm (1), .BR awk (1). .SH BUGS With default field separation, the collating sequence is that of .BR "sort \-b" ; with .BR \-t , the sequence is that of a plain sort. .PP The conventions of .BR join , .BR sort , .BR comm , .BR uniq , .BR look and .BR awk (1) are wildly incongruous. .TH KILL 1 .SH NAME kill \- send a signal to a process .SH SYNOPSIS \fBkill\fR [\fB\-\fIn\fR] \fIprocess\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-\fIn\fR" "Signal number to send" .FL "\-\fINAME\fR" "Named signal to send" .SH EXAMPLES .EX "kill 35" "Send signal 15 to process 35" .EX "kill \-9 40" "Send signal 9 to process 40" .EX "kill \-2 0" "Send signal 2 to whole terminal process group" .EX "kill \-HUP -123" "Send a hangup to process group 123" .SH DESCRIPTION .PP A signal is sent to a given process. By default signal 15 (SIGTERM) is sent. Process 0 means all the processes in the sender's process group. A process group can be signalled by the negative value of the process group ID. Signals may be numerical, or the name of the signal without \fBSIG\fP. .SH "SEE ALSO" .BR kill (2), .BR sigaction (2). .TH LAST 1 .SH NAME last \- display recent on-line session records .SH SYNOPSIS \fBlast\fR [\fB\-f \fIfile\fR]\fR [\fB\-r\fR] [\fB\-\fIn\fR] [\fIname\fR] [\fItty\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-f" "Use \fIfile\fR instead of /usr/adm/wtmp" .FL "\-r" "Search backwards only to last reboot" .FL "\-\fIn\fP" "Print a maximum of \fIn\fR lines" .SH EXAMPLES .EX "last reboot" "When was the system last rebooted?" .EX "last ast" "When was the last login for ast?" .EX "last \-10 tty00 tty01" "Display last 10 logins on tty00 or tty01" .SH DESCRIPTION .PP .I Last Searches backward through the login administration file (default is \fI/usr/adm/wtmp\fR), printing information about previous logins and reboots. During a long search, the SIGQUIT signal (CTRL-\\) causes \fIlast\fR to display how far back it has gone; it then continues. .SH "SEE ALSO" .BR login (1). .TH LEAVE 1 .SH NAME leave \- warn when it is time to go home .SH SYNOPSIS \fBleave\fR [\fR [\fB+\fR] \fIhh\fR[\fB:\fR]\fImm\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "leave 1500" "Issue a warning at 2:55 p.m." .EX "leave 10:00" "Issue a warning at 9:55 a.m." .EX "leave + 30" "Issue a warning in 25 minutes" .SH DESCRIPTION .PP \fILeave\fR sets an alarm clock to a specified time and issues a warning 5 minutes before, 1 minute before, and at the time to leave. It then keeps issuing warnings every minute for 10 minutes, then quits. If no time is provided, the program prompts for one. .TH LN 1 .SH NAME ln, clone \- create a link to a file .SH SYNOPSIS \fBln [\fB\-ifmrRvx\fR] \fIfile\fR [\fIname\fR]\fR .br \fBln [\fB\-ifrRvx\fR] \fIfile\fR ... \fIdir\fR\fR .br \fBclone [\fB\-ifmvx\fR] \fIfile\fR [\fIname\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-i" "Ask if ok to remove a file" .FL "\-f" "Remove existing links" .FL "\-m" "Merge trees, disable the into-a-directory trick" .FL "\-rR" "Recursively link a directory tree" .FL "\-v" "Display what ln is doing" .FL "\-x" "Do not cross device boundaries" .SH EXAMPLES .EX "ln file newname" "Make \fInewname\fP a synonym for \fIfile\fP" .EX "ln /usr/games/chess" "Create a link called \fIchess\fP" .SH DESCRIPTION .PP A directory entry is created for .I name . The entry points to .I file . Henceforth, .I name and .I file can be used interchangeably. If .I name is not supplied, the last component of .I file is used as the link name. If more than one .I file is supplied or the .I name refers to an existing directory, links will be created in that directory. An existing .I name will not be removed unless the \fB\-i\fR or \fB\-f\fR flag is specified. .PP .I Clone is a convenient synonym for \fBln \-fmr\fP to create a so-called "link farm", a directory full of links to the original tree. .SH "SEE ALSO" .BR cp (1), .BR link (2), .BR unlink (2). .TH LOADFONT 1 .SH NAME loadfont \- load a font into the video card .SH SYNOPSIS \fBloadfont \fIfontfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "loadfont iso1.fnt" "Loads the ISO 8859-1 (Latin-1) font" .SH DESCRIPTION .PP .I Loadfont loads a custom font into the video card (EGA or VGA). The font character size has to be 8x16 pixels and the font file must contain 256 characters for a total size of 4 kilobytes. .PP .I Loadfont together with .I loadkeys allow the console and keyboard to be customized to national conventions. .PP If it exists, the file .I /etc/font is loaded as a custom font by .I /etc/rc at boot time. .SH "SEE ALSO" .BR console (4). .TH LOADKEYS 1 .SH NAME loadkeys \- load a keyboard map into the keyboard driver .SH SYNOPSIS \fBloadkeys \fImapfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "loadkeys spanish.map" "Load a map for a Spanish keyboard" .SH DESCRIPTION .PP .I Loadkeys changes the key number to character mapping. This is necessary for national keyboards that have different symbols on the keys that the standard U.S. English keyboard. The file .I /etc/keymap is the first thing loaded by .I /etc/rc at boot time if it exists. .SH "SEE ALSO" .BR console (4). .TH LOGIN 1 .SH NAME login \- log into the computer .SH SYNOPSIS \fBlogin\fR [\fIuser\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "login ast" "Login as ast" .SH DESCRIPTION .PP \fILogin\fR allows a logged in user to login as someone else without first logging out. If a password is needed, \fIlogin\fR will prompt for it. .SH "SEE ALSO" .BR su (1), .BR init (8), .BR getty (8), .BR rlogin (1). .TH LOOK 1 .SH NAME look \- find lines in a sorted list .SH SYNOPSIS .B look .RB [ \-df ] .I string .RI [ file ] .SH DESCRIPTION .B Look consults a sorted file and prints all lines that begin with .IR string . It uses binary search. The options .B \-d and .B \-f affect comparisons as in .BR sort (1). If no file is specified, .B /usr/lib/dict/words is assumed with collating sequence .BR \-df . .SH OPTIONS .TP 5 .B \-d Dictionary order: compare letters, digits and whitespace. .TP 5 .B \-f Fold. Upper case letters compare equal to lower case. .SH FILES .TP 25 .B /usr/lib/dict/words Sorted list of English words. .SH "SEE ALSO" .BR sort (1), .BR spell (1). .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH LS 1 .SH NAME ls \- list the contents of a directory .SH SYNOPSIS \fBls\fP [\fB\-acdfgilqrstu1ACFLMRTX\fP] [\fIname\fP...] .SH DESCRIPTION For each file argument, list it. For each directory argument, list its contents. The current working directory is listed when no files are named. Information is printed multicolumn on terminals, single column if the output is redirected. The options control what information is shown and how. .PP .B Ls has two sources other then the commands line to draw options from, one is the environment variable .B LSOPTS and is used only when the output of .B ls is displayed on a terminal. The other is the name of .B ls itself. If .B ls is linked to another name, then all the characters after the l are used as flags too, except that f, r, t and x are translated to F, R, T and X. Useful links are .BR ll , .BR lf , .B lm and .BR lx . .PP Files whose names start with a dot are by default not listed. .PP Note that standard Minix doesn't have symbolic links or sockets and .B \-u and .B \-c are no-ops on a V1 file system, since only modified times are stored in V1 inodes. .SH OPTIONS .TP .B \-a All entries are listed, even .B . and .B .. .TP .B \-c Use inode changed time for sorting, listing or searching. .TP .B \-d Do not list contents of directories, but list the directory itself. .TP .B \-f Do not sort (should also be: treat a file as a directory, but that can't be implemented portably). .TP .B \-g Suppress the owner name on a long listing (implies .BR \-l ). .TP .B \-i I-node number printed in first column. .TP .B \-l Long listing: mode, links, owner, group, size and time. .RB ( "ls \-lC" uses columns in a wide enough window!) .TP .B \-n Print numerical user and group id's. .TP .B \-q Print nongraphic characters as '\fB?\fP' (default on terminals). .TP .B \-r Reverse the sort order. .TP .B \-s Give size in kilobytes. .TP .B \-t Sort by time (modified time default), latest first. .TP .B \-u Use last accessed time for sorting, listing or searching. .TP .B \-1 Print in one column. .TP .B \-A List all entries, but not .B . and .B .. (This is the default for privileged users.) .TP .B \-C Print multicolumn (default on terminals). .TP .B \-F Mark directories with a '\fB/\fP', executables with a '\fB*\fP', \s-2UNIX\s+2 domain sockets with a '\fB=\fP' and symbolic links with a '\fB@\fP' behind the name. .TP .B \-L Print the file referenced by a symbolic link instead of the link. .TP .B \-M List mode before name (implies .BR \-C ). .TP .B \-R List directory trees recursively. .TP .B \-T Group files by type, i.e. regular files together, directories together, etc. .TP .B \-X Print crunched mode and size before name (implies .BR \-C ). Only the rwx permissions that its caller has on the file, but they are in upper case if the caller owns the file and has given the permission to the callers group or other users. The size is listed in bytes (<= 5K), or rounded up kilo, mega or gigabytes. .SH "SEE ALSO" .BR du (1), .BR stat (1), .BR stat (2). .SH BUGS Having to type .B ls \-C when viewing files through .BR more (1). .PP Is only portable to systems with the same st_mode (see .BR stat (2)). .PP The .B LSOPTS variable and the .BR -M , .B -T and .B -X flags are not found on other .B ls implementations. (They have there own nonstandard flags.) .SH AUTHOR Kees J. Bot (kjb@cs.vu.nl) .TH MAIL 1 .SH NAME mail \- send and receive electronic mail .SH SYNOPSIS \fBmail\fR [\fB\-dpqrv\fR]\fR [\fB\-f \fIfile\fR] [\fIuser\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-d" "Force use of the shell variable \fIMAILER\fR" .FL "\-f" "Use \fIfile\fR instead of \fI/usr/spool/mail/user\fR as mailbox" .FL "\-p" "Print all mail and then exit" .FL "\-q" "Quit program if SIGINT received" .FL "\-r" "Reverse print order, i.e., print oldest first" .FL "\-v" "Verbose mode" .SH EXAMPLES .EX "mail ast" "Send a message to \fIast\fR" .EX "mail" "Read your mail" .SH DESCRIPTION .PP \fIMail\fR is an extremely simple electronic mail program. It can be used to send or receive email on a single \s-2MINIX\s+2 system, in which case it functions as user agent and local delivery agent. If the flag \fIMAILER\fR is defined in \fImail.c\fR, it can also call a trans\%port agent to handle remote mail as well. No such agent is supplied with \s-2MINIX\s+2. .PP When called by \fIuser\fR with no arguments, it examines the mailbox \fI/usr/spool/mail/user\fR, prints one message (depending on the \fB\-r\fR flag), and waits for one of the following commands: .PP .nf .ta 0.25i 1.25i Go to the next message \- Print the previous message !command Fork off a shell and execute \fIcommand\fR CTRL-D Update the mailbox and quit (same as q) d Delete the current message and go to the next one q Update the mailbox and quit (same as CTRL-D) p Print the current message again s [\fIfile\fR] Save message in the named file x Exit without updating the mailbox .PP .PP To send mail, the program is called with the name of the recipient as an argument. The mail is sent, along with a postmark line containing the date. For local delivery, a file named after the recipient in the directory \fI/usr/spool/mail\fR must be writable. .PP If the directory \fI/usr/spool/mail\fR does not exist then the mail is dumped on the console, so that system programs have a way to notify a user on a system that does not have a mail spool. .TH MAKE 1 .SH NAME make \- a program for maintaining large programs .SH SYNOPSIS \fBmake\fR [\fB\-f \fIfile\fR]\fR [\fB\-iknpqrst\fR] [\fIoption\fR] ... [\fItarget\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-f" "Use \fIfile\fP as the makefile" .FL "\-i" "Ignore status returned by commands" .FL "\-k" "On error, skip to next command" .FL "\-n" "Report, but do not execute" .FL "\-p" "Print macros and targets" .FL "\-q" "Question up-to-dateness of target" .FL "\-r" "Rule inhibit; do not use default rules" .FL "\-s" "Silent mode" .FL "\-t" "Touch files instead of making them" .SH EXAMPLES .EX "make kernel" "Make \fIkernel\fP up to date" .EX "make \-n \-f mfile" "Tell what needs to be done" .SH DESCRIPTION .PP .I Make is a program that is normally used for developing large programs consisting of multiple files. It keeps track of which object files depend on which source and header files. When called, it does the minimum amount of recompilation to bring the target file up to date. .PP The file dependencies are expected in .I makefile or .I Makefile , unless another file is specified with \fB\-f\fR. .I Make has some default rules built in, for example, it knows how to make .I .s files from .I .c files. Here is a sample .I makefile . .PP .nf .ta 0.25i 1.0i 3.0i d=/user/ast # \fId\fP is a macro program: head.s tail.s # \fIprogram\fR depends on these cc \-o program head.s tail.s # tells how to make \fIprogram\fP echo Program done. # announce completion head.s: $d/def.h head.c # \fIhead.s\fP depends on these .br tail.s: $d/var.h tail.c # \fItail.s\fP depends on these .PP .fi A complete description of \fImake\fR would require too much space here. Many books on \s-2UNIX\s+2 discuss .I make . Study the numerous \fIMakefiles\fR in the \s-2MINIX\s+2 source tree for examples. .SH "SEE ALSO" .BR cc (1). .\" @(#)mesg.1 6.1 (Berkeley) 4/29/85 .\" .TH MESG 1 "April 29, 1985" .AT 3 .SH NAME mesg \- permit or deny messages .SH SYNOPSIS .B mesg [ .B n ] [ .B y ] .SH DESCRIPTION .B Mesg with argument .B n forbids messages via .B write and .BR talk (1) by revoking non-user write permission on the user's terminal. .B Mesg with argument .B y reinstates permission. All by itself, .B mesg reports the current state without changing it. .SH FILES /dev/tty* .SH "SEE ALSO" .BR write (1), .BR talk (1). .SH DIAGNOSTICS Exit status is 0 if messages are receivable, 1 if not, 2 on error. .TH MKDIR 1 .SH NAME mkdir \- make a directory .SH SYNOPSIS \fBmkdir [\fB\-p\fR] [\fB\-m \fImode\fR] \fIdirectory ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-m" "Create directory with mode" .FL "\-p" "Create missing intermediate directories" .SH EXAMPLES .EX "mkdir dir" "Create \fIdir\fP in the current directory" .EX "mkdir \-p /user/ast/dir" "Create the \fI/user/ast\fP and \fI/user/ast/dir\fP" .SH DESCRIPTION .PP The specified directory or directories are created and initialized. If any intermediate directory is missing and \fB\-p\fR is specified, the missing component will be created and no error displayed if directory already exists. If the \fB\-m\fR flag is used, this will be equivalent to a chmod on the directory after its creation. .SH "SEE ALSO" .BR chmod (1), .BR rmdir (1), .BR mkdir (2). .TH MKFIFO 1 .SH NAME mkfifo \- make a named pipe .SH SYNOPSIS \fBmkfifo [\fB\-m \fImode\fR] \fIfifo ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-m" "Create fifo with specified mode" .SH EXAMPLES .EX "mkfifo pipe" "Create \fIpipe\fP in the current directory" .EX "mkfifo -m a+w systatus" "Create the \fIsystatus\fP writable by all" .SH DESCRIPTION .PP The specified fifo special files are created. If the \fB\-m\fR flag is used, this will be equivalent to a chmod on the fifo special file after its creation. .SH "SEE ALSO" .BR chmod (1), .BR mknod (2), .BR mknod (8). .TH MKFS 1 .SH NAME mkfs \- make a file system .SH SYNOPSIS \fBmkfs \fR[\fB\-Ldot\fR] [\fB\-i \fIinodes\fR] [\fB\-b \fIblocks\fR] \fIspecial \fIprototype\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-L" "Make a listing on standard output" .FL "\-d" "Use mod time of \fImkfs\fR binary for all files" .FL "\-o" "Use a drive other than 0 or 1 (safety precaution)" .FL "\-t" "Do not test if file system fits on the medium" .FL "\-1" "Make a version 1 file system (for backward compatibility)" .FL "\-i" "Number of i-nodes (files)" .FL "\-b" "Filesystem size" .SH EXAMPLES .EX "mkfs /dev/fd1 proto" "Make a file system on \fI/dev/fd1\fR" .EX "mkfs -b 360 /dev/fd1" "Make empty 360 block file system" .EX "mkfs /dev/fd1 360" "Alternate way to specify the size" .SH DESCRIPTION .PP .I Mkfs builds a file system and copies specified files to it. The prototype file tells which directories and files to copy to it. If the prototype file cannot be opened, and its name is just a string of digits, an empty file system will be made with the specified number of blocks. A sample prototype file follows. The text following the \fI#\fR sign in the example below is comment. In real prototype files, comments are not allowed. .PP .nf .ta 0.20i 0.70i 1.10i 3i 3.5i 4i boot # boot block file (ignored) 360 63 # blocks and i-nodes d--755 1 1 # root directory bin d--755 \|2 1 # bin dir: mode (755), uid (2), gid (1) sh \|---755 2 1 /user/bin/shell # shell has mode \fIrwxr-xr-x\fP mv -u-755 2 1 /user/bin/mv # u = SETUID bit login -ug755 2 1 /user/bin/login # SETUID and SETGID $ # end of \fI/bin\fP dev d--755 2 1 # special files: tty (char), fd0 (block) tty c--777 2 1 4 0 # uid=2, gid=1, major=4, minor=0 fd0 b--644 2 1 2 0 360 # uid, gid, major, minor, blocks $ # end of \fI/dev\fP user d--755 12 1 # user dir: mode (755), uid (12), gid (1) ast d--755 12 1 # \fI/user/ast\fP $ # \fI/user/ast\fP is empty $ # end of \fI/user\fP $ # end of root directory .PP .fi The first entry on each line (except the first 3 and the $ lines, which terminate directories) is the name the file or directory will get on the new file system. Next comes its mode, with the first character being \fB\-dbc\fR for regular files, directories, block special files and character special files, respectively. The next two characters are used to specify the SETUID and SETGID bits, as shown above. The last three characters of the mode are the .I rwx protection bits. .PP Following the mode are the uid and gid. For special files, the major and minor devices are needed. The size in blocks must also be specified for block special files (the \s-2MINIX\s+2 block size is 1K; this can only be changed by changing .I BLOCK_SIZE and then recompiling the operating system). .PP The maximum size of a file system is 1 Gb for a version 2 file system, and 64 Mb for a version 1 file system. Alas the 8086 .I fsck runs out of memory on a V2 file system larger than 128 Mb, so for the 8086 version of \s-2MINIX\s+2 you have to limit yourself to file systems of that size. .SH "SEE ALSO" .BR mkproto (1), .BR fsck (1), .BR mount (1). .TH MKPROTO 1 .SH NAME mkproto \- create a MINIX prototype file .SH SYNOPSIS \fBmkproto \fR[\fB\-b \fIn\fR] [\fB\-d \fIstr\fR] [\fB\-g \fIn\fR] [\fB\-i \fIn\fR] [\fB\-p \fInnn\fR] [\fB\-s\fR] [\fB\-t \fIroot\fR] [\fB\-u \fIn\fR] \fIsource_directory\fR [\fIprototype_file\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-b" "Number of blocks in the prototype is \fIn\fR" .FL "\-d" "Indent the prototype file using \fIstr\fR instead of tab" .FL "\-g" "Use \fIn\fR as the gid for all files and directories" .FL "\-i" "Number of i-nodes in the prototype is \fIn\fR" .FL "\-p" "Use \fInnn\fR (3 octal digits) as the protection mode" .FL "\-s" "Use the same uid, gid and mode as the source files have" .FL "\-t" "Use the string \fIroot\fR as the path prefix for every file" .FL "\-u" "Use \fIn\fR as the uid for all files and directories" .SH EXAMPLES .EX "mkproto \-b360" "Make a 360K prototype of this directory" .EX "mkproto \-u2 \-g1 \-p644" "Give all files uid 2, gid 1 and mode 644" .SH DESCRIPTION .PP \fIMkproto\fR creates an \fImkfs\fR prototype file for the specified source-directory. The prototype file is either written to \fIstdout\fR or, if specified, the proto-file. .SH "SEE ALSO" .BR mkfs (1). .TH MODEM 1 .SH NAME modem \- switch the modem and getty state .SH SYNOPSIS \fBmodem \fR[\fB\-o\fR] [\fB\-i \fInum\fR] \fBtty\fIn\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-o" "Turn getty off and set modem to dialout" .FL "\-i" "Set line to dialin" .SH EXAMPLES .EX "modem \-o tty00" "Set tty00 to dialout" .EX "modem \-i2 tty00" "Set tty00 to dialin (2 rings)" .SH DESCRIPTION .PP The \fIgetty\fR program allows a terminal port to be used for both dialin and dialout. This little program switches the getty state, and also sends some commands to the modem attached to the specified line. If the \fB\-o\fR flag is presnt, \fImodem\fR will put the getty process (if any) connected to the specified line into SUSPEND state, which means that it will not pay attention to that line until it is reset to RESTART state. Also, \fImodem\fR will send some (Hayes) commands to the attached modem to disable the auto-nanswer mode. The \fB\-i\fR flag specifies the number of times the telephone has to ring before the modem may answer the call (to give the operator a chance). .SH "SEE ALSO" .BR term (1), .BR getty (8). .TH MOUNT 1 .SH NAME mount \- mount a file system .SH SYNOPSIS \fBmount \fIspecial \fIfile\fR [\fB\-r\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-r" "File system is mounted read-only" .SH EXAMPLES .EX "mount /dev/fd1 /user" "Mount diskette 1 on \fI/user\fP" .SH DESCRIPTION .PP The file system contained on the special file is mounted on \fIfile\fP. In the example above, the root directory of the file system in drive 1 can be accessed as .B /user after the mount. When the file system is no longer needed, it must be unmounted before being removed from the drive. .SH "SEE ALSO" .BR df (1), .BR mkfs (1), .BR fsck (1), .BR umount (1), .BR mount (2), .BR fstab (5). .TH MREF 1 .SH NAME mref \- make listing and cross reference map of MINIX .SH SYNOPSIS \fBmref\fR [\fB\-dlmstx\fR] [\fB\-p \fIn\fR] [\fB\-\fIn\fR] \fIfile ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-d" "Do not produce definition file (global symbol table)" .FL "\-l" "Do not produce listing" .FL "\-m" "Multiple references on one line are cited only once" .FL "\-p" "Set initial page number to \fIn\fR" .FL "\-s" "Suppress line numbering between procedures" .FL "\-t" "Generate output for \fItroff\fR" .FL "\-x" "Do not produce the cross reference map" .FL "\-\fIn" "Number of lines to print per page, default = 50" .SH EXAMPLES .EX "mref *.[\fIhc\fR]" "List and cross reference files \fI.h\fR and \fI.c\fR" .EX "mref \-60 \-t *.c" "Produce \fItroff\fR input at 60 lines/page" .EX "mref \-dx \-p 100 *.c" "Listing only, first page is numbered 100" .SH DESCRIPTION .PP In default mode, .I mref produces three output files: a numbered listing of the input files (on standard output), a global symbol table (on \fIsymbol.out\fR), and a cross reference map to the global symbols (on \fIxref.out\fR). A global symbol in this context is one present in a #define, PUBLIC, PRIVATE, or SYMBOL statement (the latter being introduced to allow users to explicitly declare certain symbols as global). Any of the three outputs can be suppressed, or alternatively, be made suitable for input to \fItroff\fR for typesetting. .TH MV 1 .SH NAME mv \- move or rename a file .SH SYNOPSIS \fBmv [\fB\-ifsmvx\fR] \fIfile1 file2\fR .br \fBmv [\fB\-ifsvx\fR] \fIfile\fR ... \fIdirectory\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-i" "Prompt before removing existing files" .FL "\-f" "Do not prompt before removing existing files" .FL "\-s" "Do not clear any mode bits if owner can't be set" .FL "\-m" "Merge directory trees" .FL "\-v" "Tell what mv is doing" .FL "\-x" "Do not cross device boundaries" .SH EXAMPLES .EX "mv oldname newname" "Move \fIoldname\fP to \fInewname\fP" .EX "mv file1 file2 /user/ast" "Move two files to \fI/user/ast\fP" .SH DESCRIPTION .PP .I Mv moves one or more files from one place in the file system to another. If the old path and new path are on the same device, it is done by renaming otherwise by copying. If you're not superuser, the copy will destroy the file's owner, group and setuid/setgid bits. .I mv will prompt before removing non-writable files if \fBstdin\fR is a terminal or the \fB\-i\fR flag was specified. .SH "SEE ALSO" .BR cp (1), .BR rename (2). .TH NM 1 .SH NAME nm \- print name list .SH SYNOPSIS \fBnm\fR [\fB\-dgnopru\fR]\fR [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-d" "Print the offsets in decimal instead of in hex" .FL "\-g" "Print only external symbols" .FL "\-n" "Sort numerically rather than alphabetically" .FL "\-o" "Prepend file name to each line rather than only once" .FL "\-p" "Do not sort, print in symbol-table order" .FL "\-r" "Sort in reverse order" .FL "\-u" "Print only undefined symbols" .SH EXAMPLES .EX "nm \-n a.out" "Print all symbols in numerical order" .EX "nm \-dg a.out" "Print globals alphabetically in decimal" .SH DESCRIPTION .PP \fINm\fR prints the symbol table of executable files when it is available. If no file is given, the symbols in \fIa.out\fR are used. The format of the table is somewhat compatible with the one produced by \fIasld\fR when used with the \fB\-s\fR option. The symbol table can be added with \fIast\fR. Assembly language files do not have symbol tables. .SH "SEE ALSO" .BR anm (1), .BR asize (1), .BR ar (1), .BR size (1). .TH OD 1 .SH NAME od \- octal dump .SH SYNOPSIS \fBod\fR [\fB\-bcdhox\fR]\fR [\fIfile\fR] [ [\fB+\fR] \fIoffset\fR [\fB.\fR][\fBb\fR]\fR ]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-b" "Dump bytes in octal" .FL "\-c" "Dump bytes as ASCII characters" .FL "\-d" "Dump words in decimal" .FL "\-h" "Print addresses in hex (default is octal)" .FL "\-o" "Dump words in octal (default)" .FL "\-v" "Verbose (list duplicate lines)" .FL "\-x" "Dump words in hex" .SH EXAMPLES .EX "od \-ox file" "Dump \fIfile\fP in octal and hex" .EX "od \-d file +1000" "Dump \fIfile\fP starting at byte 01000" .EX "od \-c file +10.b" "Dump \fIfile\fP starting at block 10" .SH DESCRIPTION .PP .I Od dumps a file in one or more formats. If \fIfile\fP is missing, \fIstdin\fR is dumped. The \fIoffset\fP argument tells .I od to skip a certain number of bytes or blocks before starting. The offset is in octal bytes, unless it is followed by a \&'.\&' for decimal or \fBb\fP for blocks or both. .TH PASSWD 1 .SH NAME passwd, chfn, chsh \- change a login password, full name or shell .SH SYNOPSIS \fBpasswd\fR [\fIuser\fR]\fR .br \fBchfn\fR [\fIuser\fR] \fIfullname\fR\fR .br \fBchfn\fR [\fIuser\fR] \fIshell\fR\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "passwd" "Change current user's password" .EX "passwd ast" "Change ast's password (super\-user only)" .EX "chsh /usr/bin/mail" "For those who only read mail" .EX "chfn 'Jane Doe'" "Current user is Jane Doe" .SH DESCRIPTION .PP .I Passwd is used to change your password. It prompts for the old and new passwords. It asks for the new password twice, to reduce the effect of a typing error. .I Chfn changes the full name (GECOS field) in the password file. .I Chsh changes your login shell. Do not forget to copy the modified password file back to the root file system, or the changes will be lost when the system is rebooted. .SH "SEE ALSO" .BR login (1), .BR su (1), .BR crypt (3), .BR getpwent (3). .TH PASTE 1 .SH NAME paste \- paste multiple files together .SH SYNOPSIS \fBpaste\fR [\fB\-s\fR]\fR [\fB\-d\fI list\fR] \fIfile...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-d" "Set delimiter used to separate columns to \fIlist\fR. .FL "\-s" "Print files sequentially, file \fIk\fR on line \fIk\fR. .SH EXAMPLES .EX "paste file1 file2" "Print \fIfile1\fR in col 1, \fIfile2\fR in col 2" .EX "paste \-s f1 f2" "Print \fIf1\fR on line 1 and \fIf2\fR on line 2" .EX "paste -d : file1 file2" "Print the lines separated by a colon" .SH DESCRIPTION .PP \fIPaste\fR concatenates corresponding lines of the given input files and writes them to standard output. The lines of the different files are separated by the delimiters given with the option \-s\fR. If no list is given, a tab is substituted for every linefeed, except the last one. If end-of-file is hit on an input file, subsequent lines are empty. Suppose a set of \fIk\fR files each has one word per line. Then the \fIpaste\fR output will have \fIk\fR columns, with the contents of file \fIj\fR in column \fIj\fR. If the \fB\-s\fR flag is given, then the first file is on line 1, the second file on line 2, etc. In effect, \fB\-s\fR turns the output sideways. .PP If a list of delimiters is given, they are used in turn. The C escape sequences \\n, \\t, \\\\, and \\0 are used for linefeed, tab, backslash, and the null string, respectively. .\" -*- nroff -*- .rn '' }` '\" $Header: patch.man,v 2.0.1.2 88/06/22 20:47:18 lwall Locked $ '\" '\" $Log: patch.man,v $ '\" Revision 2.0.1.2 88/06/22 20:47:18 lwall '\" patch12: now avoids Bell System Logo '\" '\" Revision 2.0.1.1 88/06/03 15:12:51 lwall '\" patch10: -B switch was contributed. '\" '\" Revision 2.0 86/09/17 15:39:09 lwall '\" Baseline for netwide release. '\" '\" Revision 1.4 86/08/01 19:23:22 lwall '\" Documented -v, -p, -F. '\" Added notes to patch senders. '\" '\" Revision 1.3 85/03/26 15:11:06 lwall '\" Frozen. '\" '\" Revision 1.2.1.4 85/03/12 16:14:27 lwall '\" Documented -p. '\" '\" Revision 1.2.1.3 85/03/12 16:09:41 lwall '\" Documented -D. '\" '\" Revision 1.2.1.2 84/12/05 11:06:55 lwall '\" Added -l switch, and noted bistability bug. '\" '\" Revision 1.2.1.1 84/12/04 17:23:39 lwall '\" Branch for sdcrdcf changes. '\" '\" Revision 1.2 84/12/04 17:22:02 lwall '\" Baseline version. '\" .de Sh .br .ne 5 .PP \fB\\$1\fR .PP .. .de Sp .if t .sp .5v .if n .sp .. '\" '\" Set up \*(-- to give an unbreakable dash; '\" string Tr holds user defined translation string. '\" Bell System Logo is used as a dummy character. '\" '\" Shut up a groff -ww warning. '\".if \n(.g .if !dTr .ds Tr '\".ie n \{\ .tr \(*W-\*(Tr '\".ds -- \(*W- '\".if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch '\".if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch .ds L" "" .ds R" "" .ds L' ' .ds R' ' '\"'br \} '\".el \{\ .ds -- \(em\| .tr \*(Tr .ds L" `` .ds R" '' .ds L' ` .ds R' ' '\"'br\} .TH PATCH 1 LOCAL .SH NAME patch - apply a diff file to an original .SH SYNOPSIS .B patch [options] [origfile [patchfile]] [+ [options] [origfile]]... .sp but usually just .sp .B patch sets the maximum fuzz factor. This switch only applies to context diffs, and causes .I patch to ignore up to that many lines in looking for places to install a hunk. Note that a larger fuzz factor increases the odds of a faulty patch. The default fuzz factor is 2, and it may not be set to more than the number of lines of context in the context diff, ordinarily 3. .TP 5 .B \-l causes the pattern matching to be done loosely, in case the tabs and spaces have been munged in your input file. Any sequence of whitespace in the pattern line will match any sequence in the input file. Normal characters must still match exactly. Each line of the context must still match a line in the input file. .TP 5 .B \-n forces .I patch to interpret the patch file as a normal diff. .TP 5 .B \-N causes .I patch to ignore patches that it thinks are reversed or already applied. See also .B \-R . .TP 5 .B \-o causes the next argument to be interpreted as the output file name. .TP 5 .B \-p sets the pathname strip count, which controls how pathnames found in the patch file are treated, in case the you keep your files in a different directory than the person who sent out the patch. The strip count specifies how many slashes are to be stripped from the front of the pathname. (Any intervening directory names also go away.) For example, supposing the filename in the patch file was .sp /u/howard/src/blurfl/blurfl.c .sp setting .B \-p or .B \-p0 gives the entire pathname unmodified, .B \-p1 gives .sp u/howard/src/blurfl/blurfl.c .sp without the leading slash, .B \-p4 gives .sp blurfl/blurfl.c .sp and not specifying .B \-p at all just gives you "blurfl.c", unless all of the directories in the leading path (u/howard/src/blurfl) exist and that path is relative, in which case you get the entire pathname unmodified. Whatever you end up with is looked for either in the current directory, or the directory specified by the .B \-d switch. .TP 5 .B \-r causes the next argument to be interpreted as the reject file name. .TP 5 .B \-R tells .I patch that this patch was created with the old and new files swapped. (Yes, I'm afraid that does happen occasionally, human nature being what it is.) .I Patch will attempt to swap each hunk around before applying it. Rejects will come out in the swapped format. The .B \-R switch will not work with ed diff scripts because there is too little information to reconstruct the reverse operation. .Sp If the first hunk of a patch fails, .I patch will reverse the hunk to see if it can be applied that way. If it can, you will be asked if you want to have the .B \-R switch set. If it can't, the patch will continue to be applied normally. (Note: this method cannot detect a reversed patch if it is a normal diff and if the first command is an append (i.e. it should have been a delete) since appends always succeed, due to the fact that a null context will match anywhere. Luckily, most patches add or change lines rather than delete them, so most reversed normal diffs will begin with a delete, which will fail, triggering the heuristic.) .TP 5 .B \-s makes .I patch do its work silently, unless an error occurs. .TP 5 .B \-S causes .I patch to ignore this patch from the patch file, but continue on looking for the next patch in the file. Thus .sp patch -S + -S + sets internal debugging flags, and is of interest only to .I patch patchers. .SH AUTHOR Larry Wall .br with many other contributors. .SH ENVIRONMENT .TP .B TMPDIR Directory to put temporary files in; default is /tmp. .TP .B SIMPLE_BACKUP_SUFFIX Extension to use for backup file names instead of \*(L".orig\*(R" or \*(L"~\*(R". .TP .B VERSION_CONTROL Selects when numbered backup files are made. .SH FILES $TMPDIR/patch* .SH SEE ALSO diff(1) .SH NOTES FOR PATCH SENDERS There are several things you should bear in mind if you are going to be sending out patches. First, you can save people a lot of grief by keeping a patchlevel.h file which is patched to increment the patch level as the first diff in the patch file you send out. If you put a Prereq: line in with the patch, it won't let them apply patches out of order without some warning. Second, make sure you've specified the filenames right, either in a context diff header, or with an Index: line. If you are patching something in a subdirectory, be sure to tell the patch user to specify a .B \-p switch as needed. Third, you can create a file by sending out a diff that compares a null file to the file you want to create. This will only work if the file you want to create doesn't exist already in the target directory. Fourth, take care not to send out reversed patches, since it makes people wonder whether they already applied the patch. Fifth, while you may be able to get away with putting 582 diff listings into one file, it is probably wiser to group related patches into separate files in case something goes haywire. .SH DIAGNOSTICS Too many to list here, but generally indicative that .I patch couldn't parse your patch file. .PP The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in the patch file and that .I patch is attempting to intuit whether there is a patch in that text and, if so, what kind of patch it is. .PP .I Patch will exit with a non-zero status if any reject files were created. When applying a set of patches in a loop it behooves you to check this exit status so you don't apply a later patch to a partially patched file. .SH CAVEATS .I Patch cannot tell if the line numbers are off in an ed script, and can only detect bad line numbers in a normal diff when it finds a \*(L"change\*(R" or a \*(L"delete\*(R" command. A context diff using fuzz factor 3 may have the same problem. Until a suitable interactive interface is added, you should probably do a context diff in these cases to see if the changes made sense. Of course, compiling without errors is a pretty good indication that the patch worked, but not always. .PP .I Patch usually produces the correct results, even when it has to do a lot of guessing. However, the results are guaranteed to be correct only when the patch is applied to exactly the same version of the file that the patch was generated from. .SH BUGS Could be smarter about partial matches, excessively \&deviant offsets and swapped code, but that would take an extra pass. .PP If code has been duplicated (for instance with #ifdef OLDCODE ... #else ... #endif), .I patch is incapable of patching both versions, and, if it works at all, will likely patch the wrong one, and tell you that it succeeded to boot. .PP If you apply a patch you've already applied, .I patch will think it is a reversed patch, and offer to un-apply the patch. This could be construed as a feature. .rn }` '' .TH PATHCHK 1 .SH NAME pathchk \- check pathname .SH SYNOPSIS \fBpathchk [\fB\-p\fR] \fIpath\fR ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-p" "Check against POSIX rules" .SH EXAMPLES .EX "pathchk /usr/src/file.c" "Check the accessibility of \fIfile.c\fP" .EX "pathchk \-p file" "Check posix compliance of \fIfile\fR" .SH DESCRIPTION .PP .I Pathchk verifies path names and display error if paths are too long, contain names that are too long, go thru a non-searchable directory or contain an invalid character in names. If the \fB\-p\fR flag is specified, the POSIX rules apply instead of the rules of the current file system. .TH POSTMORT 1 .SH NAME postmort \- perform post-mortem on PC Minix core files .SH SYNOPSIS \fBpostmort\fR [\fB\-dpt\fR] \fB\-c \fIcorefile \fB\-s \fIsymbfile\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-c" "Use the named corefile" .FL "\-d" "Dump all text symbols and segment data" .FL "\-p" "Display the kernel process table" .FL "\-s" "Use the named symbol file" .FL "\-t" "Display a stack backtrace" .SH EXAMPLES .EX "postmort" "display the data from the file 'core'" .SH DESCRIPTION .PP .I Postmort does a simple static analysis of a PC Minix core file; By default, it looks for the file 'core' in the local directory and loads that for analysis; it also searches for the file 'symbol.out', and if that fails 'a.out', expecting them to contain symbol information for the core file. It is not a fatal error if the symbol files don't exist. .PP The stack backtrace is slightly tricky, and may go on longer than is really justified, since there's no easy way for it to know when to stop. Treat its results with caution. .TH PR 1 .SH NAME pr \- print a file .SH SYNOPSIS \fBpr\fR [\fB\-Mfnt\fR]\fR [\fB\-h \fIn\fR] [\fB\-l \fIn\fR] [\fB\-w \fIn\fR] [\fB\-\fRcolumns\fR] [\fB+\fIpage\fR] [\fIfile\fR] ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS .FL "\-M" "Use MINIX style line number" .FL "\-f" "Do not fold long lines" .FL "\-h" "Take next argument as page header" .FL "\-l" "Sets page length in lines" .FL "\-n" "Number the output lines" .FL "\-t" "Do not print page header or trailer" .FL "\-w" "Sets line length in characters" .SH EXAMPLES .EX "pr \-w85 \-l60 file" "Use 85 character line, 60 line page" .EX "pr \-3 file" "List \fIfile\fP three columns to a page" .EX "pr +4 file" "Start printing with page 4" .SH DESCRIPTION .PP .I Pr formats one or more files for printing. If no files are specified, \fIstdin\fR is printed. Options are provided for setting the width and height of the page, the number of columns to use (default 1), and the page to start with, among others. .SH "SEE ALSO" .BR lp (1). .TH PREP 1 .SH NAME prep \- prepare a text file for statistical analysis .SH SYNOPSIS \fBprep\fR [\fIfile\fR]\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH OPTIONS (none) .SH EXAMPLES .EX "prep infile >outfile" "Prepare \fIinfile\fR" .SH DESCRIPTION .PP \fIPrep\fR strips off most of the troff commands from a text file and then outputs all the words, one word per line, in the order they occur in the file. This file can then be sorted and compared to a dictionary (as a spelling checker), or used for statistical analyses. .SH "SEE ALSO" .BR nroff (1), .BR spell (1). .TH PRETTY 1 .SH NAME pretty \- MINIX pretty printer .SH SYNOPSIS \fBpretty \fIfile ...\fR .br .de FL .TP \\fB\\$1\\fR \\$2 .. .de EX .TP 20 \\fB\\$1\\fR # \\$2 .. .SH EXAMPLES .EX "pretty file1 file2" "Convert two files to \s-2MINIX\s0 layout" .SH DESCRIPTION .PP \fIPretty\fR converts one or more C source files to \s-2MINIX\s+2 format by changing their layout. Running this program does not affect the resulting binary programs. Actually, \fIpretty\fR is a postprocessor for \fIindent\fR, which must be installed in \fI/bin\fR or \fI/usr/bin\fR. Although the output is not bad, it is not entirely consistent with the book or even with itself.