From cfa37a7b1131abbab2e7d339b451f5f0e3198cc8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sat, 10 Apr 2004 18:53:55 +0000 Subject: Lots of man pages. --- man/man1/9nm.1 | 104 ++++++ man/man1/9sed.1 | 385 +++++++++++++++++++++ man/man1/acme.1 | 683 ++++++++++++++++++++++++++++++++++++ man/man1/ascii.1 | 161 +++++++++ man/man1/basename.1 | 35 ++ man/man1/cal.1 | 46 +++ man/man1/calendar.1 | 53 +++ man/man1/cat.1 | 86 +++++ man/man1/cleanname.1 | 32 ++ man/man1/cmp.1 | 57 +++ man/man1/comm.1 | 47 +++ man/man1/date.1 | 58 ++++ man/man1/dc.1 | 257 ++++++++++++++ man/man1/deroff.1 | 117 +++++++ man/man1/dict.1 | 163 +++++++++ man/man1/diff.1 | 155 +++++++++ man/man1/echo.1 | 26 ++ man/man1/ed.1 | 683 ++++++++++++++++++++++++++++++++++++ man/man1/factor.1 | 66 ++++ man/man1/fmt.1 | 90 +++++ man/man1/fortune.1 | 23 ++ man/man1/freq.1 | 40 +++ man/man1/grep.1 | 103 ++++++ man/man1/hoc.1 | 144 ++++++++ man/man1/idiff.1 | 72 ++++ man/man1/join.1 | 148 ++++++++ man/man1/ls.1 | 162 +++++++++ man/man1/mc.1 | 40 +++ man/man1/mkdir.1 | 35 ++ man/man1/plumb.1 | 92 +++++ man/man1/rc.1 | 959 +++++++++++++++++++++++++++++++++++++++++++++++++++ man/man1/rm.1 | 28 ++ man/man1/sam.1 | 885 +++++++++++++++++++++++++++++++++++++++++++++++ man/man1/seq.1 | 75 ++++ man/man1/sleep.1 | 31 ++ man/man1/sort.1 | 260 ++++++++++++++ man/man1/spell.1 | 96 ++++++ man/man1/split.1 | 82 +++++ man/man1/strings.1 | 28 ++ man/man1/sum.1 | 77 +++++ man/man1/tail.1 | 87 +++++ man/man1/tar.1 | 118 +++++++ man/man1/tee.1 | 28 ++ man/man1/test.1 | 211 ++++++++++++ man/man1/time.1 | 21 ++ man/man1/touch.1 | 35 ++ man/man1/tr.1 | 97 ++++++ man/man1/uniq.1 | 59 ++++ man/man1/wc.1 | 53 +++ man/man1/xd.1 | 87 +++++ man/man1/yacc.1 | 167 +++++++++ 51 files changed, 7647 insertions(+) create mode 100644 man/man1/9nm.1 create mode 100644 man/man1/9sed.1 create mode 100644 man/man1/acme.1 create mode 100644 man/man1/ascii.1 create mode 100644 man/man1/basename.1 create mode 100644 man/man1/cal.1 create mode 100644 man/man1/calendar.1 create mode 100644 man/man1/cat.1 create mode 100644 man/man1/cleanname.1 create mode 100644 man/man1/cmp.1 create mode 100644 man/man1/comm.1 create mode 100644 man/man1/date.1 create mode 100644 man/man1/dc.1 create mode 100644 man/man1/deroff.1 create mode 100644 man/man1/dict.1 create mode 100644 man/man1/diff.1 create mode 100644 man/man1/echo.1 create mode 100644 man/man1/ed.1 create mode 100644 man/man1/factor.1 create mode 100644 man/man1/fmt.1 create mode 100644 man/man1/fortune.1 create mode 100644 man/man1/freq.1 create mode 100644 man/man1/grep.1 create mode 100644 man/man1/hoc.1 create mode 100644 man/man1/idiff.1 create mode 100644 man/man1/join.1 create mode 100644 man/man1/ls.1 create mode 100644 man/man1/mc.1 create mode 100644 man/man1/mkdir.1 create mode 100644 man/man1/plumb.1 create mode 100644 man/man1/rc.1 create mode 100644 man/man1/rm.1 create mode 100644 man/man1/sam.1 create mode 100644 man/man1/seq.1 create mode 100644 man/man1/sleep.1 create mode 100644 man/man1/sort.1 create mode 100644 man/man1/spell.1 create mode 100644 man/man1/split.1 create mode 100644 man/man1/strings.1 create mode 100644 man/man1/sum.1 create mode 100644 man/man1/tail.1 create mode 100644 man/man1/tar.1 create mode 100644 man/man1/tee.1 create mode 100644 man/man1/test.1 create mode 100644 man/man1/time.1 create mode 100644 man/man1/touch.1 create mode 100644 man/man1/tr.1 create mode 100644 man/man1/uniq.1 create mode 100644 man/man1/wc.1 create mode 100644 man/man1/xd.1 create mode 100644 man/man1/yacc.1 (limited to 'man/man1') diff --git a/man/man1/9nm.1 b/man/man1/9nm.1 new file mode 100644 index 00000000..f9faad54 --- /dev/null +++ b/man/man1/9nm.1 @@ -0,0 +1,104 @@ +.TH NM 1 +.SH NAME +nm \- name list (symbol table) +.SH SYNOPSIS +.B nm +[ +.B -aghnsu +] +.I file ... +.SH DESCRIPTION +.I Nm +prints the name list of each executable or object +.I file +in the argument list. +If the +.I file +is an archive +(see +.IR ar (1)), +the name list of each file in the archive is printed. +If more than one file is given in the argument list, +the name of each file is printed at the beginning of each line. +.PP +Each symbol name is preceded by its hexadecimal +value (blanks if undefined) +and one of the letters +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.TP +.B z +source file name +.TP +.B Z +source file line offset +.TP +.B f +source file name components +.PD +.PP +The output is sorted alphabetically. +.PP +Options are: +.TP +.B -a +Print all symbols; normally only user-defined text, data, +and bss segment symbols are printed. +.TP +.B -g +Print only global +.RB ( T , +.BR L , +.BR D , +.BR B ) +symbols. +.TP +.B -h +Do not print file name headers with output lines. +.TP +.B -n +Sort according to the address of the symbols. +.TP +.B -s +Don't sort; print in symbol-table order. +.TP +.B -u +Print only undefined symbols. +.SH SOURCE +.B /sys/src/cmd/nm.c +.SH SEE ALSO +.IR ar (1), +.IR 2l (1), +.IR db (1), +.IR acid (1), +.IR a.out (6) + diff --git a/man/man1/9sed.1 b/man/man1/9sed.1 new file mode 100644 index 00000000..3b5ac181 --- /dev/null +++ b/man/man1/9sed.1 @@ -0,0 +1,385 @@ +.TH SED 1 +.SH NAME +sed \- stream editor +.SH SYNOPSIS +.B sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the flag +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (6), +with the added convention that +.L \en +matches a +newline embedded in the pattern space. +.PP +A command line with no addresses selects every pattern space. +.PP +A command line with +one address selects each pattern space that matches the address. +.PP +A command line with +two addresses selects the inclusive range from the first +pattern space that matches the first address through +the next pattern space that matches +the second. +(If the second address is a number less than or equal +to the line number first selected, only one +line is selected.) +Thereafter the process is repeated, looking again for the +first address. +.PP +Editing commands can be applied to non-selected pattern +spaces by use of the negation function +.L ! +(below). +.PP +An argument denoted +.I text +consists of one or more lines, +all but the last of which end with +.L \e +to hide the +newline. +Backslashes in text are treated like backslashes +in the replacement string of an +.L s +command, +and may be used to protect initial blanks and tabs +against the stripping that is done on +every script line. +.PP +An argument denoted +.I rfile +or +.I wfile +must terminate the command +line and must be preceded by exactly one blank. +Each +.I wfile +is created before processing begins. +There can be at most 120 distinct +.I wfile +arguments. +.TP \w'\fL!\ \fIfunction\fLXXX'u +.B a\e +.br +.ns +.TP +.I text +Append. +Place +.I text +on the output before +reading the next input line. +.TP +.BI b " label" +Branch to the +.B : +command bearing the +.IR label . +If +.I label +is empty, branch to the end of the script. +.TP +.B c\e +.br +.ns +.TP +.I text +Change. +Delete the pattern space. +With 0 or 1 address or at the end of a 2-address range, place +.I text +on the output. +Start the next cycle. +.TP +.B d +Delete the pattern space. +Start the next cycle. +.TP +.B D +Delete the initial segment of the +pattern space through the first newline. +Start the next cycle. +.TP +.B g +Replace the contents of the pattern space +by the contents of the hold space. +.TP +.B G +Append the contents of the hold space to the pattern space. +.TP +.B h +Replace the contents of the hold space by the contents of the pattern space. +.TP +.B H +Append the contents of the pattern space to the hold space. +.ne 3 +.TP +.B i\e +.br +.ns +.TP +.I text +Insert. +Place +.I text +on the standard output. +.TP +.B n +Copy the pattern space to the standard output. +Replace the pattern space with the next line of input. +.TP +.B N +Append the next line of input to the pattern space +with an embedded newline. +(The current line number changes.) +.TP +.B p +Print. +Copy the pattern space to the standard output. +.TP +.B P +Copy the initial segment of the pattern space through +the first newline to the standard output. +.TP +.B q +Quit. +Branch to the end of the script. +Do not start a new cycle. +.TP +.BI r " rfile" +Read the contents of +.IR rfile . +Place them on the output before reading +the next input line. +.TP +.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags +Substitute the +.I replacement +string for instances of the +.I regular-expression +in the pattern space. +Any character may be used instead of +.LR / . +For a fuller description see +.IR regexp (6). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /sys/src/cmd/sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (6) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed. diff --git a/man/man1/acme.1 b/man/man1/acme.1 new file mode 100644 index 00000000..5cae0036 --- /dev/null +++ b/man/man1/acme.1 @@ -0,0 +1,683 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -c +.I ncol +] +[ +.B -b +] +[ +.B -l +.I file +| +.I file +\&... ] +.LP +.B win +[ +.I command +] +.LP +.B awd +[ +.I label +] +.SH DESCRIPTION +.I Acme +manages windows of text that may be edited interactively or by external programs. +The interactive interface uses the keyboard and mouse; external programs +use a set of files served by +.IR acme ; +these are discussed in +.IR acme (4). +.PP +Any named +.I files +are read into +.I acme +windows before +.I acme +accepts input. +With the +.B -l +option, the state of the entire system is loaded +from +.IR file , +which should have been created by a +.B Dump +command (q.v.), +and subsequent +.I file +names are ignored. +Plain files display as text; directories display as columnated lists of the +names of their components, as in +.B "ls -p directory|mc +except that the names of subdirectories have a slash appended. +.PP +The +.B -f +.RB ( -F ) +option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); +the default is +.B /lib/font/bit/lucidasans/euro.8.font +.RB ( \&.../lucm/unicode.9.font ). +Tab intervals are set to the width of 4 (or the value of +.BR $tabstop ) +numeral zeros in the appropriate font. +.PP +.SS Windows +.I Acme +windows are in two parts: a one-line +.I tag +above a multi-line +.IR body . +The body typically contains an image of a file, as in +.IR sam (1), +or the output of a +program, as in an +.IR rio (1) +window. +The tag contains a number of +blank-separated words, followed by a vertical bar character, followed by anything. +The first word is the name of the window, typically the name of the associated +file or directory, and the other words are commands available in that window. +Any text may be added after the bar; examples are strings to search for or +commands to execute in that window. +Changes to the text left of the bar will be ignored, +unless the result is to change the name of the +window. +.PP +If a window holds a directory, the name (first word of the tag) will end with +a slash. +.SS Scrolling +Each window has a scroll bar to the left of the body. +The scroll bar behaves much as in +.IR sam (1) +or +.IR rio (1) +except that scrolling occurs when the button is pressed, rather than released, +and continues +as long as the mouse button is held down in the scroll bar. +For example, to scroll slowly through a file, +hold button 3 down near the top of the scroll bar. Moving the mouse +down the scroll bar speeds up the rate of scrolling. +.SS Layout +.I Acme +windows are arranged in columns. By default, it creates two columns when starting; +this can be overridden with the +.B -c +option. +Placement is automatic but may be adjusted +using the +.I layout box +in the upper left corner of each window and column. +Pressing and holding any mouse button in the box drags +the associated window or column. +For windows, just +clicking in the layout box grows the window in place: button 1 +grows it a little, button 2 grows it as much as it can, still leaving all other +tags in that column visible, and button 3 takes over the column completely, +temporarily hiding other windows in the column. +(They will return +.I en masse +if any of them needs attention.) +The layout box in a window is normally white; when it is black in the center, +it records that the file is `dirty': +.I Acme +believes it is modified from its original +contents. +.PP +Tags exist at the top of each column and across the whole display. +.I Acme +pre-loads them with useful commands. +Also, the tag across the top maintains a list of executing long-running commands. +.SS Typing +The behavior of typed text is similar to that in +.IR rio (1) +except that the characters are delivered to the tag or body under the mouse; there is no +`click to type'. +(The experimental option +.B -b +causes typing to go to the most recently clicked-at or made window.) +The usual backspacing conventions apply. +As in +.IR sam (1) +but not +.IR rio , +the ESC key selects the text typed since the last mouse action, +a feature particularly useful when executing commands. +A side effect is that typing ESC with text already selected is identical +to a +.B Cut +command +.RI ( q.v. ). +.PP +Most text, including the names of windows, may be edited uniformly. +The only exception is that the command names to the +left of the bar in a tag are maintained automatically; changes to them are repaired +by +.IR acme . +.SS "Directory context +Each window's tag names a directory: explicitly if the window +holds a directory; implicitly if it holds a regular file +(e.g. the directory +.B /adm +if the window holds +.BR /adm/users ). +This directory provides a +.I context +for interpreting file names in that window. +For example, the string +.B users +in a window labeled +.B /adm/ +or +.B /adm/keys +will be interpreted as the file name +.BR /adm/users . +The directory is defined purely textually, so it can be a non-existent +directory or a real directory associated with a non-existent file +(e.g. +.BR /adm/not-a-file ). +File names beginning with a slash +are assumed to be absolute file names. +.SS Errors +Windows whose names begin with +.B - +or +.B + +conventionally hold diagnostics and other data +not directly associated with files. +A window labeled +.B +Errors +receives all diagnostics produced by +.I acme +itself. +Diagnostics from commands run by +.I acme +appear in a window named +.IB directory /+Errors +where +.I directory +is identified by the context of the command. +These error windows are created when needed. +.SS "Mouse button 1 +Mouse button 1 selects text just as in +.IR sam (1) +or +.IR rio (1) , +including the usual double-clicking conventions. +.SS "Mouse button 2 +By an +action similar to selecting text with button 1, +button 2 indicates text to execute as a command. +If the indicated text has multiple white-space-separated words, +the first is the command name and the second and subsequent +are its arguments. +If button 2 is `clicked'\(emindicates a null string\(em\c +.I acme +.I expands +the indicated text to find a command to run: +if the click is within button-1-selected text, +.I acme +takes that selection as the command; +otherwise it takes the largest string of valid file name characters containing the click. +Valid file name characters are alphanumerics and +.B _ +.B . +.B - +.B + +.BR / . +This behavior is similar to double-clicking with button 1 but, +because a null command is meaningless, only a single click is required. +.PP +Some commands, all by convention starting with a capital letter, are +.I built-ins +that are executed directly by +.IR acme : +.TP +.B Cut +Delete most recently selected text and place in snarf buffer. +.TP +.B Del +Delete window. If window is dirty, instead print a warning; a second +.B Del +will succeed. +.TP +.B Delcol +Delete column and all its windows, after checking that windows are not dirty. +.TP +.B Delete +Delete window without checking for dirtiness. +.TP +.B Dump +Write the state of +.I acme +to the file name, if specified, or +.B $home/acme.dump +by default. +.TP +.B Edit +Treat the argument as a text editing command in the style of +.IR sam (1). +The full +.B Sam +language is implemented except for the commands +.BR k , +.BR n , +.BR q , +and +.BR ! . +The +.B = +command is slightly different: it includes the file name and +gives only the line address unless the command is explicitly +.BR =# . +The `current window' for the command is the body of the window in which the +.B Edit +command is executed. +Usually the +.B Edit +command would be typed in a tag; longer commands may be prepared in a +scratch window and executed, with +.B Edit +itself in the current window, using the 2-1 chord described below. +.TP +.B Exit +Exit +.I acme +after checking that windows are not dirty. +.TP +.B Font +With no arguments, change the font of the associated window from fixed-spaced to +proportional-spaced or +.I vice +.IR versa . +Given a file name argument, change the font of the window to that stored in the named file. +If the file name argument is prefixed by +.B var +.RB ( fix ), +also set the default proportional-spaced (fixed-spaced) font for future use to that font. +Other existing windows are unaffected. +.TP +.B Get +Load file into window, replacing previous contents (after checking for dirtiness as in +.BR Del ). +With no argument, use the existing file name of the window. +Given an argument, use that file but do not change the window's file name. +.TP +.B ID +Print window ID number +.RI ( q.v. ). +.TP +.B Incl +When opening `include' files +(those enclosed in +.BR <> ) +with button 3, +.I acme +searches in directories +.B /$objtype/include +and +.BR /sys/include . +.B Incl +adds its arguments to a supplementary list of include directories, analogous to +the +.B -I +option to the compilers. +This list is per-window and is inherited when windows are created by actions in that window, so +.I Incl +is most usefully applied to a directory containing relevant source. +With no arguments, +.I Incl +prints the supplementary list. +This command is largely superseded by plumbing +(see +.IR plumb (6)). +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.TP +.B Local +When prefixed to a command +run the +command in the same file name space and environment variable group as +.IR acme . +The environment of the command +is restricted but is sufficient to run +.IR bind (1), +.IR 9fs +(see +.IR srv (4)), +.IR import (4), +etc., +and to set environment variables such as +.BR $objtype . +.TP +.B Load +Restore the state of +.I acme +from a file (default +.BR $home/acme.dump ) +created by the +.B Dump +command. +.TP +.B Look +Search in body for occurrence of literal text indicated by the argument or, +if none is given, by the selected text in the body. +.TP +.B New +Make new window. With arguments, load the named files into windows. +.TP +.B Newcol +Make new column. +.TP +.B Paste +Replace most recently selected text with contents of snarf buffer. +.TP +.B Put +Write window to the named file. +With no argument, write to the file named in the tag of the window. +.TP +.B Putall +Write all dirty windows whose names indicate existing regular files. +.TP +.B Redo +Complement of +.BR Undo . +.TP +.B Send +Append selected text or snarf buffer to end of body; used mainly with +.IR win . +.TP +.B Snarf +Place selected text in snarf buffer. +.TP +.B Sort +Arrange the windows in the column from top to bottom in lexicographical +order based on their names. +.TP +.B Tab +Set the width of tab stops for this window to the value of the argument, in units of widths of the zero +character. +With no arguments, it prints the current value. +.TP +.B Undo +Undo last textual change or set of changes. +.TP +.B Zerox +Create a copy of the window containing most recently selected text. +.PP +A common place to store text for commands is in the tag; in fact +.I acme +maintains a set of commands appropriate to the state of the window +to the left of the bar in the tag. +.PP +If the text indicated with button 2 is not a recognized built-in, it is executed as +a shell command. For example, indicating +.B date +with button 2 runs +.IR date (1). +The standard +and error outputs of commands are sent to the error window associated with +the directory from which the command was run, which will be created if +necessary. +For example, in a window +.B /adm/users +executing +.B pwd +will produce the output +.B /adm +in a (possibly newly-created) window labeled +.BR /adm/+Errors ; +in a window containing +.B /sys/src/cmd/sam/sam.c +executing +.B mk +will run +.IR mk (1) +in +.BR /sys/src/cmd/sam , +producing output in a window labeled +.BR /sys/src/cmd/sam/+Errors . +The environment of such commands contains the variable +.B $% +with value set to the filename of the window in which the command is run. +.SS "Mouse button 3 +Pointing at text with button 3 instructs +.I acme +to locate or acquire the file, string, etc. described by the indicated text and +its context. +This description follows the actions taken when +button 3 is released after sweeping out some text. +In the description, +.I text +refers to the text of the original sweep or, if it was null, the result of +applying the same expansion rules that apply to button 2 actions. +.PP +If the text names an existing window, +.I acme +moves the mouse cursor to the selected text in the body of that window. +If the text names an existing file with no associated window, +.I acme +loads the file into a new window and moves the mouse there. +If the text is a file name contained in angle brackets, +.I acme +loads the indicated include file from the directory appropriate to the +suffix of the file name of the window holding the text. +(The +.B Incl +command adds directories to the standard list.) +.PP +If the text begins with a colon, it is taken to be an address, in +the style of +.IR sam (1), +within the body of the window containing the text. +The address is evaluated, the resulting text highlighted, and the mouse moved to it. +Thus, in +.IR acme , +one must type +.B :/regexp +or +.B :127 +not just +.B /regexp +or +.BR 127 . +(There is an easier way to locate literal text; see below.) +.PP +If the text is a file name followed by a colon and an address, +.I acme +loads the file and evaluates the address. For example, clicking button 3 anywhere +in the text +.B file.c:27 +will open +.BR file.c , +select line +27, and put the mouse at the beginning of the line. The rules about Error +files, directories, and so on all combine to make this an efficient way to +investigate errors from compilers, etc. +.PP +If the text is not an address or file, it is taken to +be literal text, which is then searched for in the body of the window +in which button 3 was clicked. If a match is found, it is selected and the mouse is +moved there. Thus, to search for occurrences of a word in a file, +just click button 3 on the word. Because of the rule of using the +selection as the button 3 action, subsequent clicks will find subsequent +occurrences without moving the mouse. +.PP +In all these actions, the mouse motion is not done if the text is a null string +within a non-null selected string in the tag, so that (for example) complex regular expressions +may be selected and applied repeatedly to the +body by just clicking button 3 over them. +.SS "Chords of mouse buttons +Several operations are bound to multiple-button actions. +After selecting text, with button 1 still down, pressing button 2 +executes +.B Cut +and button 3 executes +.BR Paste . +After clicking one button, the other undoes +the first; thus (while holding down button 1) 2 followed by 3 is a +.B Snarf +that leaves the file undirtied; +3 followed by 2 is a no-op. +These actions also apply to text selected by double-clicking because +the double-click expansion is made when the second +click starts, not when it ends. +.PP +Commands may be given extra arguments by a mouse chord with buttons 2 and 1. +While holding down button 2 on text to be executed as a command, clicking button 1 +appends the text last pointed to by button 1 as a distinct final argument. +For example, to search for literal +.B text +one may execute +.B Look text +with button 2 or instead point at +.B text +with button 1 in any window, release button 1, +then execute +.BR Look , +clicking button 1 while 2 is held down. +.PP +When an external command (e.g. +.IR echo (1)) +is executed this way, the extra argument is passed as expected and an +environment variable +.B $acmeaddr +is created that holds, in the form interpreted by button 3, +the fully-qualified address of the extra argument. +.SS "Support programs +.I Win +creates a new +.I acme +window and runs a +.I command +(default +.BR /bin/rc ) +in it, turning the window into something analogous to an +.IR rio (1) +window. +Executing text in a +.I win +window with button +2 is similar to using +.BR Send . +.PP +.I Awd +loads the tag line of its window with the directory in which it's running, suffixed +.BI - label +(default +.BR rc ); +it is +intended to be executed by a +.B cd +function for use in +.I win +windows. An example definition is +.EX + fn cd { builtin cd $1 && awd $sysname } +.EE +.SS "Applications and guide files +In the directory +.B /acme +live several subdirectories, each corresponding to a program or +set of related programs that employ +.I acme's +user interface. +Each subdirectory includes source, binaries, and a +.B readme +file for further information. +It also includes a +.BR guide , +a text file holding sample commands to invoke the programs. +The idea is to find an example in the guide that best matches +the job at hand, edit it to suit, and execute it. +.PP +Whenever a command is executed by +.IR acme , +the default search path includes the directory of the window containing +the command and its subdirectory +.BR $cputype . +The program directories in +.B /acme +contain appropriately labeled subdirectories of binaries, +so commands named +in the guide files will be found automatically when run. +Also, +.I acme +binds the directories +.B /acme/bin +and +.B /acme/bin/$cputype +to the end of +.B /bin +when it starts; this is where +.IR acme -specific +programs such as +.I win +and +.I awd +reside. +.SH FILES +.TF $home/acme.dump +.TP +.B $home/acme.dump +default file for +.B Dump +and +.BR Load ; +also where state is written if +.I acme +dies or is killed unexpectedly, e.g. by deleting its window. +.TP +.B /acme/*/guide +template files for applications +.TP +.B /acme/*/readme +informal documentation for applications +.TP +.B /acme/*/src +source for applications +.TP +.B /acme/*/mips +MIPS-specific binaries for applications +.SH SOURCE +.B /sys/src/cmd/acme +.br +.B /acme/bin/source/win +.br +.B /sys/src/cmd/awd.c +.SH SEE ALSO +.IR acme (4) +.br +Rob Pike, +.I +Acme: A User Interface for Programmers. +.SH BUGS +With the +.B -l +option or +.B Load +command, +the recreation of windows under control of external programs +such as +.I win +is just to rerun the command; information may be lost. diff --git a/man/man1/ascii.1 b/man/man1/ascii.1 new file mode 100644 index 00000000..47fd3550 --- /dev/null +++ b/man/man1/ascii.1 @@ -0,0 +1,161 @@ +.TH ASCII 1 +.SH NAME +ascii, unicode \- interpret ASCII, Unicode characters +.SH SYNOPSIS +.B ascii +[ +.B -8 +] +[ +.BI -oxdb n +] +[ +.B -nct +] +[ +.I text +] +.PP +.B unicode +[ +.B -nt +] +.IB hexmin - hexmax +.PP +.B unicode +[ +.B -t +] +.I hex +[ +\&... +] +.PP +.B unicode +[ +.B -n +] +.I characters +.PP +.B look +.I hex +.B /lib/unicode +.SH DESCRIPTION +.I Ascii +prints the +.SM ASCII +values corresponding to characters and +.I vice +.IR versa ; +under the +.B -8 +option, the +.SM ISO +Latin-1 extensions (codes 0200-0377) are included. +The values are interpreted in a settable numeric base; +.B -o +specifies octal, +.B -d +decimal, +.B -x +hexadecimal (the default), and +.BI -b n +base +.IR n . +.PP +With no arguments, +.I ascii +prints a table of the character set in the specified base. +Characters of +.I text +are converted to their +.SM ASCII +values, one per line. If, however, the first +.I text +argument is a valid number in the specified base, conversion +goes the opposite way. +Control characters are printed as two- or three-character mnemonics. +Other options are: +.TP +.B -n +Force numeric output. +.TP +.B -c +Force character output. +.TP +.B -t +Convert from numbers to running text; do not interpret +control characters or insert newlines. +.PP +.I Unicode +is similar; it converts between +.SM UTF +and character values from the Unicode Standard (see +.IR utf (6)). +If given a range of hexadecimal numbers, +.I unicode +prints a table of the specified Unicode characters \(em their values and +.SM UTF +representations. +Otherwise it translates from +.SM UTF +to numeric value or vice versa, +depending on the appearance of the supplied text; +the +.B -n +option forces numeric output to avoid ambiguity with numeric characters. +If converting to +.SM UTF , +the characters are printed one per line unless the +.B -t +flag is set, in which case the output is a single string +containing only the specified characters. +Unlike +.IR ascii , +.I unicode +treats no characters specially. +.PP +The output of +.I ascii +and +.I unicode +may be unhelpful if the characters printed are not available in the current font. +.PP +The file +.B /lib/unicode +contains a +table of characters and descriptions, sorted in hexadecimal order, +suitable for +.IR look (1) +on the lower case +.I hex +values of characters. +.SH EXAMPLES +.TP +.B "ascii -d" +Print the +.SM ASCII +table base 10. +.TP +.B "unicode p" +Print the hex value of `p'. +.TP +.B "unicode 2200-22f1" +Print a table of miscellaneous mathematical symbols. +.TP +.B "look 039 /lib/unicode" +See the start of the Greek alphabet's encoding in the Unicode Standard. +.SH FILES +.TF /lib/unicode +.TP +.B /lib/unicode +table of characters and descriptions. +.SH SOURCE +.B /sys/src/cmd/ascii.c +.br +.B /sys/src/cmd/unicode.c +.SH "SEE ALSO" +.IR look (1) +.IR tcs (1), +.IR utf (6), +.IR font (6) diff --git a/man/man1/basename.1 b/man/man1/basename.1 new file mode 100644 index 00000000..c72638f1 --- /dev/null +++ b/man/man1/basename.1 @@ -0,0 +1,35 @@ +.TH BASENAME 1 +.SH NAME +basename \- strip file name affixes +.SH SYNOPSIS +.B basename +[ +.B -d +] +.I string +[ +.I suffix +] +.SH DESCRIPTION +.PP +.I Basename +deletes any prefix ending in slash +.RB ( / ) +and the +.IR suffix , +if present in +.IR string , +from +.IR string , +and prints the result on the standard output. +.PP +The +.B -d +option instead prints the directory component, +that is, +.I string +up to but not including the final slash. +If the string contains no slash, +a period and newline are printed. +.SH SOURCE +.B /sys/src/cmd/basename.c diff --git a/man/man1/cal.1 b/man/man1/cal.1 new file mode 100644 index 00000000..7ac5b996 --- /dev/null +++ b/man/man1/cal.1 @@ -0,0 +1,46 @@ +.TH CAL 1 +.SH NAME +cal \- print calendar +.SH SYNOPSIS +.B cal +[ +.I month +] +[ +.I year +] +.SH DESCRIPTION +.I Cal +prints a calendar. +.I Month +is either a number from 1 to 12, +a lower case month name, +or a lower case three-letter prefix of a month name. +.I Year +can be between 1 +and 9999. +If either +.I month +or +.I year +is omitted, the current month or year is used. +If only one argument is given, and it is a number larger than 12, +a calendar for all twelve months of the given year is produced; +otherwise a calendar for just one month is printed. +The calendar +produced is that for England and her colonies. +.PP +Try +.EX + cal sep 1752 +.EE +.SH SOURCE +.B /sys/src/cmd/cal.c +.SH BUGS +The year is always considered to start in January even though this +is historically naive. +.br +Beware that +.L "cal 90" +refers to the early Christian era, +not the 20th century. diff --git a/man/man1/calendar.1 b/man/man1/calendar.1 new file mode 100644 index 00000000..e6832d3c --- /dev/null +++ b/man/man1/calendar.1 @@ -0,0 +1,53 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- print upcoming events +.SH SYNOPSIS +.B calendar +[ +.B \-y +] +[ +.B \-p days +] +[ +.I file ... +] +.SH DESCRIPTION +.I Calendar +reads the named files, default +.BR /usr/$user/lib/calendar , +and writes to standard output any lines +containing today's or tomorrow's date. +Examples of recognized date formats are +"4/11", +"April 11", +"Apr 11", +"11 April", +and +"11 Apr". +All comparisons are case insensitive. +.PP +If the +.B \-y +flag is given, an attempt is made to match on year too. In this case, +dates of the forms listed above will be accepted if they are followed +by the current year (or last two digits thereof) or not a year — +digits not followed by white space or non-digits. +.PP +If the +.B \-p +flag is given, its argument is the number of days ahead to match +dates. This flag is not repeatable, and it performs no special +processing at the end of the week. +.PP +On Friday and Saturday, events through Monday are printed. +.PP +To have your calendar mailed to you every day, use +.IR cron (8). +.SH FILES +.TF /usr/$user/lib/calendar +.TP +.B /usr/$user/lib/calendar +personal calendar +.SH SOURCE +.B /sys/src/cmd/calendar.c diff --git a/man/man1/cat.1 b/man/man1/cat.1 new file mode 100644 index 00000000..eeb43bcc --- /dev/null +++ b/man/man1/cat.1 @@ -0,0 +1,86 @@ +.TH CAT 1 +.SH NAME +cat, read \- catenate files +.SH SYNOPSIS +.B cat +[ +.I file ... +] +.br +.B read +[ +.B -m +] [ +.B -n +.I nline +] [ +.I file ... +] +.SH DESCRIPTION +.I Cat +reads each +.I file +in sequence and writes it on the standard output. +Thus +.IP +.L +cat file +.LP +prints a file and +.IP +.L +cat file1 file2 >file3 +.LP +concatenates the first two files and places the result +on the third. +.PP +If no +.I file +is given, +.I cat +reads from the standard input. +Output is buffered in blocks matching the input. +.PP +.I Read +copies to standard output exactly one line from the named +.IR file , +default standard input. +It is useful in interactive +.IR rc (1) +scripts. +.PP +The +.B -m +flag causes it to continue reading and writing multiple lines until end of file; +.B -n +causes it to read no more than +.I nline +lines. +.PP +Read always executes a single +.B write +for each line of input, which can be helpful when +preparing input to programs that expect line-at-a-time data. +It never reads any more data from the input than it prints to the output. +.SH SOURCE +.B /sys/src/cmd/cat.c +.br +.B /sys/src/cmd/read.c +.SH SEE ALSO +.IR cp (1) +.SH DIAGNOSTICS +.I Read +exits with status +.B eof +on end of file or, in the +.B -n +case, if it doesn't read +.I nlines +lines. +.SH BUGS +Beware of +.L "cat a b >a" +and +.LR "cat a b >b" , +which +destroy input files before reading them. diff --git a/man/man1/cleanname.1 b/man/man1/cleanname.1 new file mode 100644 index 00000000..41c06c00 --- /dev/null +++ b/man/man1/cleanname.1 @@ -0,0 +1,32 @@ +.TH CLEANNAME 1 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B cleanname +[ +.B -d +.I pwd +] +.I names ... +.SH DESCRIPTION +For each file name argument, +.IR cleanname , +by lexical processing only, +prints the shortest equivalent string that names the same +(possibly hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically +interprets +.B . +and +.B .. +directory components in the name. +If the +.B -d +option is present, +unrooted names are prefixed with +.IB pwd / +before processing. +.SH SOURCE +.B /sys/src/cmd/cleanname.c +.SH SEE ALSO +.IR cleanname (2). diff --git a/man/man1/cmp.1 b/man/man1/cmp.1 new file mode 100644 index 00000000..e48d0766 --- /dev/null +++ b/man/man1/cmp.1 @@ -0,0 +1,57 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.B cmp +[ +.B -lsL +] +.I file1 file2 +[ +.I offset1 +[ +.I offset2 +] +] +.SH DESCRIPTION +The two files are +compared. +A diagnostic results if the contents differ, otherwise +there is no output. +.PP +The options are: +.TP +.B l +Print the byte number (decimal) and the +differing bytes (hexadecimal) for each difference. +.TP +.B s +Print nothing for differing files, +but set the exit status. +.TP +.B L +Print the line number of the first differing byte. +.PP +If offsets are given, +comparison starts at the designated byte position +of the corresponding file. +Offsets that begin with +.B 0x +are hexadecimal; +with +.BR 0 , +octal; with anything else, decimal. +.SH SOURCE +.B /sys/src/cmd/cmp.c +.SH "SEE ALSO" +.IR diff (1) +.SH DIAGNOSTICS +If a file is inaccessible or missing, the exit status is +.LR open . +If the files are the same, the exit status is empty (true). +If they are the same except that one is longer than the other, the exit status is +.LR EOF . +Otherwise +.I cmp +reports the position of the first disagreeing byte and the exit status is +.LR differ . diff --git a/man/man1/comm.1 b/man/man1/comm.1 new file mode 100644 index 00000000..2fd883c0 --- /dev/null +++ b/man/man1/comm.1 @@ -0,0 +1,47 @@ +.TH COMM 1 +.CT 1 files +.SH NAME +comm \- select or reject lines common to two sorted files +.SH SYNOPSIS +.B comm +[ +.B -123 +] +.I file1 file2 +.SH DESCRIPTION +.I Comm +reads +.I file1 +and +.IR file2 , +which are in lexicographical order, +and produces a three column output: lines only in +.IR file1 ; +lines only in +.IR file2 ; +and lines in both files. +The file name +.L - +means the standard input. +.PP +Flag +.LR 1 , +.LR 2 , +or +.LR 3 +suppresses printing of the corresponding +column. +.SH EXAMPLE +.TP +.EX +comm -12 file1 file2 +.EE +.IP +Print lines common to two sorted files. +.SH SOURCE +.B /sys/src/cmd/comm.c +.SH "SEE ALSO" +.IR sort (1), +.IR cmp (1), +.IR diff (1), +.IR uniq (1) diff --git a/man/man1/date.1 b/man/man1/date.1 new file mode 100644 index 00000000..3d232baa --- /dev/null +++ b/man/man1/date.1 @@ -0,0 +1,58 @@ +.TH DATE 1 +.SH NAME +date, clock \- date and time +.SH SYNOPSIS +.B date +[ +.I option +] [ +.I seconds +] +.br +.B clock +.SH DESCRIPTION +Print the date, in the format +.PP +.B + Tue Aug 16 17:03:52 CDT 1977 +.PP +The options are +.TP +.B -u +Report Greenwich Mean Time (GMT) rather than local time. +.TP +.B -n +Report the date as the number of seconds since the +epoch, 00:00:00 GMT, January 1, 1970. +.PP +The conversion from Greenwich Mean Time to local time depends on the +.B $timezone +environment variable; see +.IR ctime (2). +.PP +If the optional argument +.I seconds +is present, it is used as the time to convert rather than +the real time. +.SH FILES +.TF /adm/timezone/local +.TP +.B /env/timezone +Current timezone name and adjustments. +.TP +.B /adm/timezone +A directory containing timezone tables. +.TP +.B /adm/timezone/local +Default timezone file, copied by +.IR init (8) +into +.BR /env/timezone . +.PD +.PP +.I Clock +draws a simple analog clock in its window. +.SH SOURCE +.B /sys/src/cmd/date.c +.br +.B /sys/src/cmd/clock.c diff --git a/man/man1/dc.1 b/man/man1/dc.1 new file mode 100644 index 00000000..0f2c13a5 --- /dev/null +++ b/man/man1/dc.1 @@ -0,0 +1,257 @@ +.TH DC 1 +.SH NAME +dc \- desk calculator +.SH SYNOPSIS +.B dc +[ +.I file +] +.SH DESCRIPTION +.I Dc +is an arbitrary precision desk calculator. +Ordinarily it operates on decimal integers, +but one may specify an input base, output base, +and a number of fractional digits to be maintained. +The overall structure of +.I dc +is +a stacking (reverse Polish) calculator. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +The following constructions are recognized: +.TP +number +The value of the number is pushed on the stack. +A number is an unbroken string of the digits +.B 0-9A-F +or +.BR 0-9a-f . +A hexadecimal number beginning with a lower case +letter must be preceded by a zero to distinguish it +from the command associated with the letter. +It may be preceded by an underscore +.B _ +to input a +negative number. +Numbers may contain decimal points. +.TP +.L ++ - / * % ^ +Add +.LR + , +subtract +.LR - , +multiply +.LR * , +divide +.LR / , +remainder +.LR % , +or exponentiate +.L ^ +the top two values on the stack. +The two entries are popped off the stack; +the result is pushed on the stack in their place. +Any fractional part of an exponent is ignored. +.TP +.BI s x +.br +.ns +.TP +.BI S x +Pop the top of the stack and store into +a register named +.IR x , +where +.I x +may be any character. +Under operation +.B S +register +.I x +is treated as a stack and the value is pushed on it. +.TP +.BI l x +.br +.ns +.TP +.BI L x +Push the value in register +.I x +onto the stack. +The register +.I x +is not altered. +All registers start with zero value. +Under operation +.B L +register +.I x +is treated as a stack and its top value is popped onto the main stack. +.TP +.B d +Duplicate the +top value on the stack. +.TP +.B p +Print the top value on the stack. +The top value remains unchanged. +.B P +interprets the top of the stack as an +text +string, +removes it, and prints it. +.TP +.B f +Print the values on the stack. +.TP +.B q +.br +.ns +.TP +.B Q +Exit the program. +If executing a string, the recursion level is +popped by two. +Under operation +.B Q +the top value on the stack is popped and the string execution level is popped +by that value. +.TP +.B x +Treat the top element of the stack as a character string +and execute it as a string of +.I dc +commands. +.TP +.B X +Replace the number on the top of the stack with its scale factor. +.TP +.B "[ ... ]" +Put the bracketed +text +string on the top of the stack. +.TP +.PD0 +.BI < x +.TP +.BI > x +.TP +.BI = x +.PD +Pop and compare the +top two elements of the stack. +Register +.I x +is executed if they obey the stated +relation. +.TP +.B v +Replace the top element on the stack by its square root. +Any existing fractional part of the argument is taken +into account, but otherwise the scale factor is ignored. +.TP +.B ! +Interpret the rest of the line as a shell command. +.TP +.B c +Clear the stack. +.TP +.B i +The top value on the stack is popped and used as the +number base for further input. +.TP +.B I +Push the input base on the top of the stack. +.TP +.B o +The top value on the stack is popped and used as the +number base for further output. +In bases larger than 10, each `digit' prints as a group of decimal digits. +.TP +.B O +Push the output base on the top of the stack. +.TP +.B k +Pop the top of the stack, and use that value as +a non-negative scale factor: +the appropriate number of places +are printed on output, +and maintained during multiplication, division, and exponentiation. +The interaction of scale factor, +input base, and output base will be reasonable if all are changed +together. +.TP +.B z +Push the stack level onto the stack. +.TP +.B Z +Replace the number on the top of the stack with its length. +.TP +.B ? +A line of input is taken from the input source (usually the terminal) +and executed. +.TP +.B "; :" +Used by +.I bc +for array operations. +.PP +The scale factor set by +.B k +determines how many digits are kept to the right of +the decimal point. +If +.I s +is the current scale factor, +.I sa +is the scale of the first operand, +.I sb +is the scale of the second, +and +.I b +is the (integer) second operand, +results are truncated to the following scales. +.IP +.nf +\fL+\fR,\fL-\fR max(\fIsa,sb\fR) +\fL*\fR min(\fIsa\fR+\fIsb \fR, max\fR(\fIs,sa,sb\fR)) +\fL/\fI s +\fL%\fR so that dividend = divisor*quotient + remainder; remainder has sign of dividend +\fL^\fR min(\fIsa\fR\(mu|\fIb\fR|, max(\fIs,sa\fR)) +\fLv\fR max(\fIs,sa\fR) +.fi +.SH EXAMPLES +.EX +[la1+dsa*pla10>y]sy +0sa1 +lyx +.EE +.ns +.IP +Print the first ten values of +.IR n ! +.SH SOURCE +.B /sys/src/cmd/dc.c +.SH "SEE ALSO" +.IR bc (1), +.IR hoc (1) +.SH DIAGNOSTICS +.I x +.LR "is unimplemented" , +where +.I x +is an octal number: an internal error. +.br +`Out of headers' +for too many numbers being kept around. +.br +`Nesting depth' +for too many levels of nested execution. +.SH BUGS +When the input base exceeds 16, +there is no notation for digits greater than +.BR F . +.PP +Past its time. diff --git a/man/man1/deroff.1 b/man/man1/deroff.1 new file mode 100644 index 00000000..f62b174d --- /dev/null +++ b/man/man1/deroff.1 @@ -0,0 +1,117 @@ +.TH DEROFF 1 +.SH NAME +deroff, delatex \- remove formatting requests +.SH SYNOPSIS +.B deroff +[ +.I option ... +] +.I file ... +.PP +.B delatex +.I file +.SH DESCRIPTION +.I Deroff +reads each file in sequence +and removes all +.I nroff +and +.IR troff (1) +requests and non-text arguments, backslash constructions, +and constructs of preprocessors such as +.IR eqn (1), +.IR pic (1), +and +.IR tbl (1). +Remaining text is written on the standard output. +.I Deroff +follows files included by +.L .so +and +.L .nx +commands; +if a file has already been included, a +.L .so +for that file is ignored and a +.L .nx +terminates execution. +If no input file is given, +.I deroff +reads from standard input. +.PP +The options are +.TP +.B -w +Output a word list, one `word' (string of letters, digits, and +properly embedded ampersands and apostrophes, +beginning with a letter) per line. +Other characters are skipped. +Otherwise, the output follows the original, with the deletions mentioned above. +.TP +.B -_ +Like +.BR -w , +but consider underscores to be alphanumeric rather than punctuation. +.TP +.B -i +Ignore +.L .so +and +.L .nx +requests. +.TP +.BR -ms +.PD0 +.TP +.B -mm +Remove titles, attachments, etc., as well as ordinary +.IR troff +constructs, from +.IR ms (6) +or +.I mm +documents. +.PD +.TP +.B -ml +Same as +.BR -mm , +but remove lists as well. +.PP +.I Delatex +does for +.I tex +and +.I latex +(see +.IR tex (1)) +files what +.B deroff -wi +does for +.I troff +files. +.SH SOURCE +.B /sys/src/cmd/deroff.c +.br +.B /sys/src/cmd/tex/local/delatex.c +.SH "SEE ALSO" +.IR troff (1), +.IR tex (1), +.IR spell (1) +.SH BUGS +These filters are not complete interpreters of +.I troff +or +.IR tex . +For example, macro definitions containing +.L \e$ +cause chaos in +.IR deroff +when the popular +.L $$ +delimiters for +.I eqn +are in effect. +.br +Text inside macros is emitted at place of +definition, not place of call. diff --git a/man/man1/dict.1 b/man/man1/dict.1 new file mode 100644 index 00000000..5fc47634 --- /dev/null +++ b/man/man1/dict.1 @@ -0,0 +1,163 @@ +.TH DICT 7 +.SH NAME +dict \- dictionary browser +.SH SYNOPSIS +.B dict +[ +.B -k +] +[ +.B -d +.I dictname +] +[ +.B -c +.I command +] +[ +.I pattern +] +.SH DESCRIPTION +.I Dict +is a dictionary browser. +If a +.I pattern +is given on the command line, +.I dict +prints all matching entries; +otherwise it repeatedly accepts and executes commands. +The options are +.TF -d\ \fIdictname\fP +.TP +.BI -d " dictname" +Use the given dictionary. +The default is +.BR oed , +the second edition of the Oxford English Dictionary. +A list of available dictionaries is printed by option +.BR -d? . +.TP +.BI -c " command" +Execute one command and quit. +The command syntax is described below. +.TP +.B -k +Print a pronunciation key. +.PD +.PP +Patterns are regular expressions (see +.IR regexp (6)), +with an implicit leading +.L ^ +and trailing +.LR $ . +Patterns are matched against an index of headwords and variants, +to form a `match set'. +By default, both patterns and the index are folded: +upper case characters are mapped into their lower case equivalents, +and Latin accented characters are mapped into their non-accented +equivalents. +In interactive mode, there is always a `current match set' +and a `current entry' within the match set. +Commands can change either or both, as well as print the entries +or information about them. +.PP +Commands have an address followed by a command letter. +Addresses have the form: +.TF /\fIre\fP/.\fIn\fP +.TP +.BI / re / +Set the match set to all entries matching the regular expression +.IR re , +sorted in dictionary order. +Set the current entry to the first of the match set. +.TP +.BI ! re ! +Like +.BI / re / +but use exact matching, i.e., without case and accent folding. +.TP +.I n +An integer +.I n +means change the current entry to the +.IR n th +of the current match set. +.TP +.BI # n +The integer +.I n +is an absolute byte offset into the raw dictionary. +(See the +.B A +command, below.) +.TP +.IB addr + +After setting the match set and current entry according to +.IR addr , +change the match set and current entry to be the next entry +in the dictionary (not necessarily in the match set) after +the current entry. +.TP +.IB addr - +Like +.IB addr + +but go to previous dictionary entry. +.PD +.PP +The command letters come in pairs: a lower case and the +corresponding upper case letter. +The lower case version prints something about the current +entry only, and advances the current entry to the next +in the match set (wrapping around to the beginning after +the last). +The upper case version prints something about all of the +match set and resets the current entry to the beginning of +the set. +.TF \fLa,A\fP +.TP +.BR p , P +Print the whole entry. +.TP +.BR h , H +Print only the headword(s) of the entry. +.TP +.BR a , A +Print the dictionary byte offset of the entry. +.TP +.BR r , R +Print the whole entry in raw format (without translating +special characters, etc.). +.PD +.PP +If no command letter is given for the first command, +.B H +is assumed. +After an +.BR H , +the default command is +.BR p . +Otherwise, the default command is the previous command. +.SH FILES +.B /lib/dict/oed2 +.br +.B /lib/dict/oed2index +.br +Other files in +.BR /lib . +.SH "SEE ALSO" +.IR regexp (6) +.SH SOURCE +.B /sys/src/cmd/dict +.SH BUGS +A font with wide coverage of the Unicode Standard +should be used for best results. +(Try +.BR /lib/font/bit/pelm/unicode.9.font .) +.br +If the +.I pattern +doesn't begin with +a few literal characters, matching takes a long time. +.br +The dictionaries are not distributed outside Bell Labs. diff --git a/man/man1/diff.1 b/man/man1/diff.1 new file mode 100644 index 00000000..404c74f0 --- /dev/null +++ b/man/man1/diff.1 @@ -0,0 +1,155 @@ +.TH DIFF 1 +.SH NAME +diff \- differential file comparator +.SH SYNOPSIS +.B diff +[ +.B -efmnbwr +] file1 ... file2 +.SH DESCRIPTION +.I Diff +tells what lines must be changed in two files to bring them +into agreement. +If one file +is a directory, +then a file in that directory with basename the same as that of +the other file is used. +If both files are directories, similarly named files in the +two directories are compared by the method of +.I diff +for text +files and +.IR cmp (1) +otherwise. +If more than two file names are given, then each argument is compared +to the last argument as above. +The +.B -r +option causes +.I diff +to process similarly named subdirectories recursively. +When processing more than one file, +.I diff +prefixes file differences with a single line +listing the two differing files, in the form of +a +.I diff +command line. +The +.B -m +flag causes this behavior even when processing single files. +.PP +The normal output contains lines of these forms: +.IP "" 5 +.I n1 +.B a +.I n3,n4 +.br +.I n1,n2 +.B d +.I n3 +.br +.I n1,n2 +.B c +.I n3,n4 +.PP +These lines resemble +.I ed +commands to convert +.I file1 +into +.IR file2 . +The numbers after the letters pertain to +.IR file2 . +In fact, by exchanging `a' for `d' and reading backward +one may ascertain equally how to convert +.I file2 +into +.IR file1 . +As in +.IR ed , +identical pairs where +.I n1 += +.I n2 +or +.I n3 += +.I n4 +are abbreviated as a single number. +.PP +Following each of these lines come all the lines that are +affected in the first file flagged by `<', +then all the lines that are affected in the second file +flagged by `>'. +.PP +The +.B -b +option causes +trailing blanks (spaces and tabs) to be ignored +and other strings of blanks to compare equal. +The +.B -w +option causes all white-space to be removed from input lines +before applying the difference algorithm. +.PP +The +.B -n +option prefixes each range with +.IB file : \fR +and inserts a space around the +.BR a , +.BR c , +and +.B d +verbs. +The +.B -e +option produces a script of +.I "a, c" +and +.I d +commands for the editor +.IR ed , +which will recreate +.I file2 +from +.IR file1 . +The +.B -f +option produces a similar script, +not useful with +.IR ed , +in the opposite order. It may, however, be +useful as input to a stream-oriented post-processor. +.PP +Except in rare circumstances, +.I diff +finds a smallest sufficient set of file +differences. +.SH FILES +.B /tmp/diff[12] +.SH SOURCE +.B /sys/src/cmd/diff +.SH "SEE ALSO" +.IR cmp (1), +.IR comm (1), +.IR ed (1) +.SH DIAGNOSTICS +Exit status is the empty string +for no differences, +.L some +for some, +and +.L error +for trouble. +.SH BUGS +Editing scripts produced under the +.BR -e " or" +.BR -f " option are naive about" +creating lines consisting of a single `\fB.\fR'. +.br +When running +.I diff +on directories, the notion of what is a text +file is open to debate. diff --git a/man/man1/echo.1 b/man/man1/echo.1 new file mode 100644 index 00000000..86e6cd39 --- /dev/null +++ b/man/man1/echo.1 @@ -0,0 +1,26 @@ +.TH ECHO 1 +.SH NAME +echo \- print arguments +.SH SYNOPSIS +.B echo +[ +.B -n +] +[ +.I arg ... +] +.SH DESCRIPTION +.I Echo +writes its arguments separated by blanks and terminated by +a newline on the standard output. +Option +.B -n +suppresses the newline. +.SH SOURCE +.B /sys/src/cmd/echo.c +.SH DIAGNOSTICS +If +.I echo +draws an error while writing to standard output, the exit status is +.LR "write error" . +Otherwise the exit status is empty. diff --git a/man/man1/ed.1 b/man/man1/ed.1 new file mode 100644 index 00000000..adb79fb7 --- /dev/null +++ b/man/man1/ed.1 @@ -0,0 +1,683 @@ +.TH ED 1 +.SH NAME +ed \- text editor +.SH SYNOPSIS +.B ed +[ +.B - +] +[ +.B -o +] +[ +.I file +] +.SH DESCRIPTION +.I Ed +is a venerable text editor. +.PP +If a +.I file +argument is given, +.I ed +simulates an +.L e +command (see below) on that file: +it is read into +.I ed's +buffer so that it can be edited. +The options are +.TP +.B - +Suppress the printing +of character counts by +.LR e , +.LR r , +and +.L w +commands and of the confirming +.L ! +by +.L ! +commands. +.TP +.B -o +(for output piping) +Write all output to the standard error file except writing by +.L w +commands. +If no +.I file +is given, make +.B /fd/1 +the remembered file; see the +.L e +command below. +.PP +.I Ed +operates on a `buffer', a copy of the file it is editing; +changes made +in the buffer have no effect on the file until a +.L w +(write) +command is given. +The copy of the text being edited resides +in a temporary file called the +.IR buffer . +.PP +Commands to +.I ed +have a simple and regular structure: zero, one, or +two +.I addresses +followed by a single character +.IR command , +possibly +followed by parameters to the command. +These addresses specify one or more lines in the buffer. +Missing addresses are supplied by default. +.PP +In general, only one command may appear on a line. +Certain commands allow the +addition of text to the buffer. +While +.I ed +is accepting text, it is said +to be in +.I "input mode." +In this mode, no commands are recognized; +all input is merely collected. +Input mode is left by typing a period +.L . +alone at the +beginning of a line. +.PP +.I Ed +supports the +.I "regular expression" +notation described in +.IR regexp (6). +Regular expressions are used in addresses to specify +lines and in one command +(see +.I s +below) +to specify a portion of a line which is to be replaced. +If it is desired to use one of +the regular expression metacharacters as an ordinary +character, that character may be preceded by +.RB ` \e '. +This also applies to the character bounding the regular +expression (often +.LR / ) +and to +.L \e +itself. +.PP +To understand addressing in +.I ed +it is necessary to know that at any time there is a +.I "current line." +Generally, the current line is +the last line affected by a command; however, +the exact effect on the current line +is discussed under the description of +each command. +Addresses are constructed as follows. +.TP +1. +The character +.LR . , +customarily called `dot', +addresses the current line. +.TP +2. +The character +.L $ +addresses the last line of the buffer. +.TP +3. +A decimal number +.I n +addresses the +.IR n -th +line of the buffer. +.TP +4. +.BI \'x +addresses the line marked with the name +.IR x , +which must be a lower-case letter. +Lines are marked with the +.L k +command. +.TP +5. +A regular expression enclosed in slashes ( +.LR / ) +addresses +the line found by searching forward from the current line +and stopping at the first line containing a +string that matches the regular expression. +If necessary the search wraps around to the beginning of the +buffer. +.TP +6. +A regular expression enclosed in queries +.L ? +addresses +the line found by searching backward from the current line +and stopping at the first line containing +a string that matches the regular expression. +If necessary +the search wraps around to the end of the buffer. +.TP +7. +An address followed by a plus sign +.L + +or a minus sign +.L - +followed by a decimal number specifies that address plus +(resp. minus) the indicated number of lines. +The plus sign may be omitted. +.TP +8. +An address followed by +.L + +(or +.LR - ) +followed by a +regular expression enclosed in slashes specifies the first +matching line following (or preceding) that address. +The search wraps around if necessary. +The +.L + +may be omitted, so +.L 0/x/ +addresses the +.I first +line in the buffer with an +.LR x . +Enclosing the regular expression in +.L ? +reverses the search direction. +.TP +9. +If an address begins with +.L + +or +.L - +the addition or subtraction is taken with respect to the current line; +e.g.\& +.L -5 +is understood to mean +.LR .-5 . +.TP +10. +If an address ends with +.L + +or +.LR - , +then 1 is added (resp. subtracted). +As a consequence of this rule and rule 9, +the address +.L - +refers to the line before the current line. +Moreover, +trailing +.L + +and +.L - +characters +have cumulative effect, so +.L -- +refers to the current +line less 2. +.TP +11. +To maintain compatibility with earlier versions of the editor, +the character +.L ^ +in addresses is +equivalent to +.LR - . +.PP +Commands may require zero, one, or two addresses. +Commands which require no addresses regard the presence +of an address as an error. +Commands which accept one or two addresses +assume default addresses when insufficient are given. +If more addresses are given than a command requires, +the last one or two (depending on what is accepted) are used. +.PP +Addresses are separated from each other typically by a comma +.LR , . +They may also be separated by a semicolon +.LR ; . +In this case the current line +is set to +the previous address before the next address is interpreted. +If no address precedes a comma or semicolon, line 1 is assumed; +if no address follows, the last line of the buffer is assumed. +The second address of any two-address sequence +must correspond to a line following the line corresponding to the first address. +.PP +In the following list of +.I ed +commands, the default addresses +are shown in parentheses. +The parentheses are not part of +the address, but are used to show that the given addresses are +the default. +`Dot' means the current line. +.TP +.RB (\|\fL.\fP\|) \|a +.br +.ns +.TP + +.br +.ns +.TP +.B . +Read the given text +and append it after the addressed line. +Dot is left +on the last line input, if there +were any, otherwise at the addressed line. +Address +.L 0 +is legal for this command; text is placed +at the beginning of the buffer. +.TP +.RB (\|\fL.,.\fP\|) \|b [ +- ][\fIpagesize\fP][ pln\fR] +Browse. +Print a `page', normally 20 lines. +The optional +.L + +(default) or +.L - +specifies whether the next or previous +page is to be printed. +The optional +.I pagesize +is the number of lines in a page. +The optional +.LR p , +.LR n , +or +.L l +causes printing in the specified format, initially +.LR p . +Pagesize and format are remembered between +.L b +commands. +Dot is left at the last line displayed. +.TP +.RB (\|\fL.,.\fP\|) \|c +.br +.ns +.TP + +.br +.ns +.TP +.B . +Change. +Delete the addressed lines, then accept input +text to replace these lines. +Dot is left at the last line input; if there were none, +it is left at the line preceding the deleted lines. +.TP +.RB (\|\fL.,.\fP\|) \|d +Delete the addressed lines from the buffer. +Dot is set to the line following the last line deleted, or to +the last line of the buffer if the deleted lines had no successor. +.TP +.BI e " filename" +Edit. +Delete the entire contents of the buffer; +then read the named file into the buffer. +Dot is set to the last line of the buffer. +The number of characters read is typed. +The file name is remembered for possible use in later +.LR e , +.LR r , +or +.L w +commands. +If +.I filename +is missing, the remembered name is used. +.TP +.BI E " filename" +Unconditional +.LR e ; +see +.RL ` q ' +below. +.TP +.BI f " filename" +Print the currently remembered file name. +If +.I filename +is given, +the currently remembered file name is first changed to +.IR filename . +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/\fIcommand\ list\fP +.PD 0 +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/ +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP +.PD +Global. +First mark every line which matches +the given +.IR regular expression . +Then for every such line, execute the +.I command list +with dot initially set to that line. +A single command or the first of multiple commands +appears on the same line with the global command. +All lines of a multi-line list except the last line must end with +.LR \e . +The +.RB \&` \&. \&' +terminating input mode for an +.LR a , +.LR i , +.L c +command may be omitted if it would be on the +last line of the command list. +The commands +.L g +and +.L v +are not permitted in the command list. +Any character other than space or newline may +be used instead of +.L / +to delimit the regular expression. +The second and third forms mean +.BI g/ regular\ expression /p \f1. +.TP +.RB (\| .\| ) \|i +.PD 0 +.TP + +.TP +.B . +Insert the given text before the addressed line. +Dot is left at the last line input, or, if there were none, +at the line before the addressed line. +This command differs from the +.I a +command only in the placement of the +text. +.PD +.TP +.RB (\| .,.+1 \|) \|j +Join the addressed lines into a single line; +intermediate newlines are deleted. +Dot is left at the resulting line. +.TP +.RB (\|\fL.\fP\|) \|k\fIx\fP +Mark the addressed line with name +.IR x , +which must be a lower-case letter. +The address form +.BI \' x +then addresses this line. +.ne 2.5 +.TP +.RB (\|\fL.,.\fP\|) \|l +List. +Print the addressed lines in an unambiguous way: +a tab is printed as +.LR \et , +a backspace as +.LR \eb , +backslashes as +.LR \e\e , +and non-printing characters as +a backslash, an +.LR x , +and four hexadecimal digits. +Long lines are folded, +with the second and subsequent sub-lines indented one tab stop. +If the last character in the line is a blank, +it is followed by +.LR \en . +An +.L l +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|m\fIa +Move. +Reposition the addressed lines after the line +addressed by +.IR a . +Dot is left at the last moved line. +.TP +.RB (\|\fL.,.\fP\|) \|n +Number. +Perform +.LR p , +prefixing each line with its line number and a tab. +An +.L n +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|p +Print the addressed lines. +Dot is left at the last line printed. +A +.L p +appended to any non-I/O command causes the then current line +to be printed after the command is executed. +.TP +.RB (\|\fL.,.\fP\|) \|P +This command is a synonym for +.LR p . +.TP +.B q +Quit the editor. +No automatic write +of a file is done. +A +.L q +or +.L e +command is considered to be in error if the buffer has +been modified since the last +.LR w , +.LR q , +or +.L e +command. +.TP +.B Q +Quit unconditionally. +.TP +.RB ( $ )\|r\ \fIfilename\fP +Read in the given file after the addressed line. +If no +.I filename +is given, the remembered file name is used. +The file name is remembered if there were no +remembered file name already. +If the read is successful, the number of characters +read is printed. +Dot is left at the last line read from the file. +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/ +.PD 0 +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/g +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP +.PD +Substitute. +Search each addressed +line for an occurrence of the specified regular expression. +On each line in which +.I n +matches are found +.RI ( n +defaults to 1 if missing), +the +.IR n th +matched string is replaced by the replacement specified. +If the global replacement indicator +.L g +appears after the command, +all subsequent matches on the line are also replaced. +It is an error for the substitution to fail on all addressed lines. +Any character other than space or newline +may be used instead of +.L / +to delimit the regular expression +and the replacement. +Dot is left at the last line substituted. +The third form means +.BI s n / regular\ expression / replacement\fP/p\f1. +The second +.L / +may be omitted if the replacement is +empty. +.IP +An ampersand +.L & +appearing in the replacement +is replaced by the string matching the regular expression. +The characters +.BI \e n\f1, +where +.I n +is a digit, +are replaced by the text matched by the +.IR n -th +regular subexpression +enclosed between +.L ( +and +.LR ) . +When +nested parenthesized subexpressions +are present, +.I n +is determined by counting occurrences of +.L ( +starting from the left. +.IP +A literal +.LR & , +.LR / , +.L \e +or newline may be included in a replacement +by prefixing it with +.LR \e . +.TP +.RB (\|\fL.,.\fP\|) \|t\|\fIa +Transfer. +Copy the addressed lines +after the line addressed by +.IR a . +Dot is left at the last line of the copy. +.TP +.RB (\|\fL.,.\fP\|) \|u +Undo. +Restore the preceding contents +of the first addressed line (sic), which must be the last line +in which a substitution was made (double sic). +.TP +.RB (\|\fL1,$\fP\|) \|v/\fIregular\ expression\fP/\fIcommand\ list\fP +This command is the same as the global command +.L g +except that the command list is executed with +dot initially set to every line +.I except +those +matching the regular expression. +.TP +.RB (\|\fL1,$\fP\|) \|w " \fIfilename\fP" +Write the addressed lines to +the given file. +If the file does not exist, +it is created with mode 666 (readable and writable by everyone). +If no +.I filename +is given, the remembered file name, if any, is used. +The file name is remembered if there were no +remembered file name already. +Dot is unchanged. +If the write is successful, the number of characters written is +printed. +.TP +.RB (\|\fL1,$\fP\|) \|W " \fIfilename\fP" +Perform +.LR w , +but append to, instead of overwriting, any existing file contents. +.TP +.RB ( $ ) \|= +Print the line number of the addressed line. +Dot is unchanged. +.TP +.BI ! shell\ command +Send the remainder of the line after the +.L ! +to +.IR rc (1) +to be interpreted as a command. +Dot is unchanged. +.TP +.RB (\| .+1 )\| +An address without a command is taken as a +.L p +command. +A terminal +.L / +may be omitted from the address. +A blank line alone is equivalent to +.LR .+1p ; +it is useful +for stepping through text. +.PP +If an interrupt signal +.SM (DEL) +is sent, +.I ed +prints a +.L ? +and returns to its command level. +.PP +When reading a file, +.I ed +discards +.SM NUL +characters +and all characters after the last newline. +.SH FILES +.B /tmp/e* +.br +.B ed.hup +\ \ work is saved here if terminal hangs up +.SH SOURCE +.B /sys/src/cmd/ed.c +.SH "SEE ALSO" +.IR sam (1), +.IR sed (1), +.IR regexp (6) +.SH DIAGNOSTICS +.BI ? name +for inaccessible file; +.L ?TMP +for temporary file overflow; +.L ? +for errors in commands or other overflows. diff --git a/man/man1/factor.1 b/man/man1/factor.1 new file mode 100644 index 00000000..2d9b5a09 --- /dev/null +++ b/man/man1/factor.1 @@ -0,0 +1,66 @@ +.TH FACTOR 1 +.CT 1 numbers +.SH NAME +factor, primes \- factor a number, generate large primes +.SH SYNOPSIS +.B factor +[ +.I number +] +.PP +.B primes +[ +.I start +[ +.I finish +] +] +.SH DESCRIPTION +.I Factor +prints +.I number +and its prime factors, +each repeated the proper number of times. +The number must be positive and less than +.if n 2**54 +.if t 2\u\s754\s0\d +(about +.if n 1.8e16) +.if t 1.8\(mu10\u\s716\s0\d\|). +.PP +If no +.I number +is given, +.I factor +reads a stream of numbers from the standard input and factors them. +It exits on any input not a positive integer. +Maximum running time is proportional to +.if n sqrt(n). +.if t .I \(sr\o'n\(rn'\f1. +.PP +.PP +.I Primes +prints the prime numbers ranging from +.I start +to +.IR finish , +where +.I start +and +.I finish +are positive numbers less than +.if n 2**56. +.if t 2\u\s756\s0\d. +If +.I finish +is missing, +.I primes +prints without end; +if +.I start +is missing, it reads the starting number from the +standard input. +.SH SOURCE +.B /sys/src/cmd/factor.c +.br +.B /sys/src/cmd/primes.c diff --git a/man/man1/fmt.1 b/man/man1/fmt.1 new file mode 100644 index 00000000..51186001 --- /dev/null +++ b/man/man1/fmt.1 @@ -0,0 +1,90 @@ +.TH FMT 1 +.SH NAME +fmt, htmlfmt \- simple text formatters +.SH SYNOPSIS +.B fmt +[ +.I option ... +] +[ +.I file ... +] +.PP +.B htmlfmt +[ +.B -a +] [ +.B -c +.I charset +] [ +.B -u +.I url +] [ +.I file ... +] +.SH DESCRIPTION +.I Fmt +copies the given +.I files +(standard input by default) +to its standard output, filling and indenting lines. +The options are +.TP +.BI -l " n +Output line length is +.IR n , +including indent (default 70). +.TP +.BI -w " n +A synonym for +.BR -l . +.TP +.BI -i " n +Indent +.I n +spaces (default 0). +.TP +.BI -j +Do not join short lines: only fold long lines. +.PP +Empty lines and initial white space in input lines are preserved. +Empty lines are inserted between input files. +.PP +.I Fmt +is idempotent: it leaves already formatted text unchanged. +.PP +.I Htmlfmt +performs a similar service, but accepts as input text formatted with +HTML tags. +It accepts +.IR fmt 's +.B -l +and +.B -w +flags and also: +.TP +.BI -a +Normally +.I htmlfmt +suppresses the contents of form fields and anchors (URLs and image files); this flag +causes it to print them, in square brackets. +.TP +.BI -c " charset +change the default character set from iso-8859-1 to +.IR charset . +This is the character set assumed if there isn't one +specified by the html itself in a directive. +.TP +.BI -u " url +Use +.I url +as the base URL for the document when displaying anchors; sets +.BI -a . +.SH SOURCE +.B /sys/src/cmd/fmt.c +.PP +.B /sys/src/cmd/htmlfmt +.SH BUGS +.I Htmlfmt +makes no attempt to render the two-dimensional geometry of tables; +it just treats the table entries as plain, to-be-formatted text. diff --git a/man/man1/fortune.1 b/man/man1/fortune.1 new file mode 100644 index 00000000..dfae7186 --- /dev/null +++ b/man/man1/fortune.1 @@ -0,0 +1,23 @@ +.TH FORTUNE 1 +.SH NAME +fortune \- sample lines from a file +.SH SYNOPSIS +.B fortune +[ +.I file +] +.SH DESCRIPTION +.I Fortune +prints a one-line aphorism chosen at random. +If a +.I file +is specified, the saying is taken from that file; +otherwise it is selected from +.BR /sys/games/lib/fortunes . +.SH FILES +.B /sys/games/lib/fortunes +.br +.B /sys/games/lib/fortunes.index +\ \ fast lookup table, maintained automatically +.SH SOURCE +.B /sys/src/cmd/fortune.c diff --git a/man/man1/freq.1 b/man/man1/freq.1 new file mode 100644 index 00000000..eee4e295 --- /dev/null +++ b/man/man1/freq.1 @@ -0,0 +1,40 @@ +.TH FREQ 1 +.SH NAME +freq \- print histogram of character frequencies +.SH SYNOPSIS +.B freq +[ +.B -dxocr +] +[ +.I file ... +] +.SH DESCRIPTION +.I Freq +reads the given files (default standard input) +and prints histograms of the character frequencies. +By default, +.I freq +counts each byte as a character; +under the +.B -r +option it instead counts +.SM UTF +sequences, that is, runes. +.PP +Each non-zero entry of the table is printed preceded by the byte value, +in decimal, octal, hex, and +Unicode +character (if printable). +If any options are given, the +.BR -d , +.BR -x , +.BR -o , +.B -c +flags specify a subset of value formats: decimal, hex, octal, and +character, respectively. +.SH SOURCE +.B /sys/src/cmd/freq.c +.SH SEE ALSO +.IR utf (6), +.IR wc (1) diff --git a/man/man1/grep.1 b/man/man1/grep.1 new file mode 100644 index 00000000..a266c494 --- /dev/null +++ b/man/man1/grep.1 @@ -0,0 +1,103 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.B grep +[ +.I option ... +] +.I pattern +[ +.I file ... +] +.SH DESCRIPTION +.I Grep\^ +searches the input +.I files\^ +(standard input default) +for lines that match the +.IR pattern , +a regular expression as defined in +.IR regexp (6) +with the addition of a newline character as an alternative +(substitute for +.BR | ) +with lowest precedence. +Normally, each line matching the pattern is `selected', +and each selected line is copied to the standard output. +The options are +.TP +.B -c +Print only a count of matching lines. +.PD 0 +.TP +.B -h +Do not print file name tags (headers) with output lines. +.TP +.B -e +The following argument is taken as a +.IR pattern . +This option makes it easy to specify patterns that +might confuse argument parsing, such as +.BR -n . +.TP +.B -i +Ignore alphabetic case distinctions. The implementation +folds into lower case all letters in the pattern and input before +interpretation. Matched lines are printed in their original form. +.TP +.B -l +(ell) Print the names of files with selected lines; don't print the lines. +.TP +.B -L +Print the names of files with no selected lines; +the converse of +.BR -l . +.TP +.B -n +Mark each printed line with its line number counted in its file. +.TP +.B -s +Produce no output, but return status. +.TP +.B -v +Reverse: print lines that do not match the pattern. +.TP +.B -f +The pattern argument is the name of a file containing regular +expressions one per line. +.TP +.B -b +Don't buffer the output: write each output line as soon as it is discovered. +.PD +.PP +Output lines are tagged by file name when there is more than one +input file. +(To force this tagging, include +.B /dev/null +as a file name argument.) +.PP +Care should be taken when +using the shell metacharacters +.B $*[^|()=\e +and newline +in +.IR pattern ; +it is safest to enclose the +entire expression +in single quotes +.BR \&\|' \|.\|.\|.\| ' . +An expression starting with '*' +will treat the rest of the expression +as literal characters. +.SH SOURCE +.B /sys/src/cmd/grep +.SH SEE ALSO +.IR ed (1), +.IR awk (1), +.IR sed (1), +.IR sam (1), +.IR regexp (6) +.SH DIAGNOSTICS +Exit status is null if any lines are selected, +or non-null when no lines are selected or an error occurs. diff --git a/man/man1/hoc.1 b/man/man1/hoc.1 new file mode 100644 index 00000000..68a42a6a --- /dev/null +++ b/man/man1/hoc.1 @@ -0,0 +1,144 @@ +.TH HOC 1 +.SH NAME +hoc \- interactive floating point language +.SH SYNOPSIS +.B hoc +[ +.I file ... +] +[ +.B -e +.I expression +] +.SH DESCRIPTION +.I Hoc +interprets a simple language for floating point arithmetic, +at about the level of BASIC, with C-like syntax and +functions. +.PP +The named +.I files +are read and interpreted in order. +If no +.I file +is given or if +.I file +is +.L - +.I hoc +interprets the standard input. +The +.B -e +option allows input to +.I hoc +to be specified on the command line, to be treated as if it appeared in a file. +.PP +.I Hoc +input consists of +.I expressions +and +.IR statements . +Expressions are evaluated and their results printed. +Statements, typically assignments and function or procedure +definitions, produce no output unless they explicitly call +.IR print . +.PP +Variable names have the usual syntax, including +.LR _ ; +the name +.L _ +by itself contains the value of the last expression evaluated. +The variables +.BR E , +.BR PI , +.BR PHI , +.BR GAMMA +and +.B DEG +are predefined; the last is 59.25..., degrees per radian. +.PP +Expressions are formed with these C-like operators, listed by +decreasing precedence. +.TP +.B ^ +exponentiation +.TP +.B ! - ++ -- +.TP +.B * / % +.TP +.B + - +.TP +.B > >= < <= == != +.TP +.B && +.TP +.B || +.TP +.B = += -= *= /= %= +.PP +Built in functions are +.BR abs , +.BR acos , +.BR asin , +.B atan +(one argument), +.BR cos , +.BR cosh , +.BR exp , +.BR int , +.BR log , +.BR log10 , +.BR sin , +.BR sinh , +.BR sqrt , +.BR tan , +and +.BR tanh . +The function +.B read(x) +reads a value into the variable +.B x +and returns 0 at EOF; +the statement +.B print +prints a list of expressions that may include +string constants such as +\fL"hello\en"\f1.\fP +.PP +Control flow statements are +.BR if - else , +.BR while , +and +.BR for , +with braces for grouping. +Newline ends a statement. +Backslash-newline is equivalent to a space. +.PP +Functions and procedures are introduced by the words +.B func +and +.BR proc ; +.B return +is used to return with a value from a function. +.SH EXAMPLES +.EX +func gcd(a, b) { + temp = abs(a) % abs(b) + if(temp == 0) return abs(b) + return gcd(b, temp) +} +for(i=1; i<12; i++) print gcd(i,12) +.EE +.SH SOURCE +.B /sys/src/cmd/hoc +.SH "SEE ALSO" +.IR bc (1), +.IR dc (1) +.br +B. W. Kernighan and R. Pike, +.I +The Unix Programming Environment, +Prentice-Hall, 1984 +.SH BUGS +Error recovery is imperfect within function and procedure definitions. diff --git a/man/man1/idiff.1 b/man/man1/idiff.1 new file mode 100644 index 00000000..5cb22600 --- /dev/null +++ b/man/man1/idiff.1 @@ -0,0 +1,72 @@ +.TH IDIFF 1 +.SH NAME +idiff \- interactive diff +.SH SYNOPSIS +.B idiff +[ +.B -bw +] +.I file1 +.I file2 +.SH DESCRIPTION +.I Idiff +interactively +merges +.I file1 +and +.IR file2 . +Wherever +.I file1 +and +.I file2 +differ, +.I idiff +displays the differences in the style of +.RB `` diff +.RB -n '' +and prompts the user to select a chunk. +Valid responses are: +.TP +.B < +Use the chunk from +.IR file1 . +.TP +.B > +Use the chunk from +.IR file2 . +.TP +.B = +Use the diff output itself. +.TP +.BR q< ", " q> ", " q= +Use the given response for all future questions. +.TP +.BI ! cmd +Execute +.I cmd +and prompt again. +.PP +.I Idiff +invokes +.IR diff (1) +to compare the files. +The +.B -b +and +.B -w +flags +are simply +passed through to +.IR diff . +.SH FILES +.B /tmp/idiff.* +.SH SOURCE +.B /sys/src/cmd/idiff.c +.SH "SEE ALSO +.IR diff (1) +.br +Kernighan and Pike, +.IR "The Unix Programming Environment" , +Prentice-Hall, 1984. +.SH BUGS +This is a poorly-written manual page. diff --git a/man/man1/join.1 b/man/man1/join.1 new file mode 100644 index 00000000..379eec7f --- /dev/null +++ b/man/man1/join.1 @@ -0,0 +1,148 @@ +.TH JOIN 1 +.CT 1 files +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.B join +[ +.I options +] +.I file1 file2 +.SH DESCRIPTION +.I Join +forms, on the standard output, +a join +of the two relations specified by the lines of +.I file1 +and +.IR file2 . +If one of the file names is +.LR - , +the standard input is used. +.PP +.I File1 +and +.I file2 +must be sorted in increasing +.SM 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 +Input fields are normally separated spaces or tabs; +output fields by space. +In this case, multiple separators count as one, and +leading separators are discarded. +.PP +The following options are recognized, with POSIX syntax. +.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 -v " n +Like +.BR -a , +omitting output for paired lines. +.TP +.BI -e " s +Replace empty output fields by string +.IR s . +.TP +.BI -1 " m +.br +.ns +.TP +.BI -2 " m +Join on the +.IR m th +field of +.I file1 +or +.IR file2 . +.TP +.BI -j "n m" +Archaic equivalent for +.BI - n " m"\f1. +.TP +.BI -o fields +Each output line comprises the designated fields. +The comma-separated field designators are either +.BR 0 , +meaning the join field, or have the form +.IR n . m , +where +.I n +is a file number and +.I m +is a field number. +Archaic usage allows separate arguments for field designators. +.PP +.TP +.BI -t c +Use character +.I c +as the only separator (tab character) on input and output. +Every appearance of +.I c +in a line is significant. +.SH EXAMPLES +.TP +.L +sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +Add birthdays to the +.B /adm/users +file, leaving unknown +birthdays empty. +The layout of +.B /adm/users +is given in +.IR users (6); +.B bdays +contains sorted lines like +.LR "ken:Feb\ 4,\ 1953" . +.TP +.L +tr : ' ' temp +.br +.ns +.TP +.L +join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2' +Print all pairs of users with identical userids. +.SH SOURCE +.B /sys/src/cmd/join.c +.SH "SEE ALSO" +.IR sort (1), +.IR comm (1), +.IR awk (1) +.SH BUGS +With default field separation, +the collating sequence is that of +.BI "sort -b" +.BI -k y , y\f1; +with +.BR -t , +the sequence is that of +.BI "sort -t" x +.BI -k y , y\f1. +.br +One of the files must be randomly accessible. + diff --git a/man/man1/ls.1 b/man/man1/ls.1 new file mode 100644 index 00000000..e33f7273 --- /dev/null +++ b/man/man1/ls.1 @@ -0,0 +1,162 @@ +.TH LS 1 +.SH NAME +ls, lc \- list contents of directory +.SH SYNOPSIS +.B ls +[ +.B -dlmnpqrstuFQ +] +.I name ... +.PP +.B lc +[ +.B -dlmnqrstuFQ +] +.I name ... +.SH DESCRIPTION +For each directory argument, +.I ls +lists the contents of the directory; +for each file argument, +.I ls +repeats its name and any other information requested. +When no argument is given, the current directory is listed. +By default, the output is sorted alphabetically by name. +.PP +.I Lc +is the same as +.IR ls , +but sets the +.B -p +option and pipes the output through +.IR mc (1). +.PP +There are a number of options: +.TP +.B -d +If argument is a directory, list it, not +its contents. +.TP +.B -l +List in long format, giving mode (see below), file system type +(e.g., for devices, the +.B # +code letter that names it; see +.IR intro (3)), +the instance or subdevice number, owner, group, +size in bytes, and time of last modification +for each file. +.TP +.B -m +List the name of the user who most recently modified the file. +.TP +.B -n +Don't sort the listing. +.TP +.B -p +Print only the final path element of each file name. +.TP +.B -q +List the +.I qid +(see +.IR stat (2)) +of each file; the printed fields are in the order +path, version, and type. +.TP +.B -r +Reverse the order of sort. +.TP +.B -s +Give size in Kbytes for each entry. +.TP +.B -t +Sort by time modified (latest first) instead of +by name. +.TP +.B -u +Under +.B -t +sort by time of last access; +under +.B -l +print time of last access. +.TP +.B -F +Add the character +.B / +after all directory names +and the character +.B * +after all executable files. +.TP +.B -L +Print the character +.B t +before each file if it has the temporary flag set, and +.B - +otherwise. +.TP +.B -Q +By default, printed file names are quoted if they contain characters special to +.IR rc (1). +The +.B -Q +flag disables this behavior. +.PP +The mode printed under the +.B -l +option contains 11 characters, +interpreted +as follows: +the first character is +.TP +.B d +if the entry is a directory; +.PD 0 +.TP +.B a +if the entry is an append-only file; +.TP +.B - +if the entry is a plain file. +.PD +.PP +The next letter is +.B l +if the file is exclusive access (one writer or reader at a time). +.PP +The last 9 characters are interpreted +as three sets of three bits each. +The first set refers to owner permissions; +the next to permissions to others in the same user-group; +and the last to all others. +Within each set the three characters indicate +permission respectively to read, to write, or to +execute the file as a program. +For a directory, `execute' permission is interpreted +to mean permission to search the directory +for a specified file. +The permissions are indicated as follows: +.TP 3 +.B r +if the file is readable; +.PD 0 +.TP 3 +.B w +if the file is writable; +.TP 3 +.B x +if the file is executable; +.TP 3 +.B - +if none of the above permissions is granted. +.PD +.SH SOURCE +.B /sys/src/cmd/ls.c +.br +.B /rc/bin/lc +.SH SEE ALSO +.IR stat (2) +.IR mc (1) + diff --git a/man/man1/mc.1 b/man/man1/mc.1 new file mode 100644 index 00000000..c53bcca3 --- /dev/null +++ b/man/man1/mc.1 @@ -0,0 +1,40 @@ +.TH MC 1 +.SH NAME +mc \- multicolumn print +.SH SYNOPSIS +.B mc +[ +.B - +] +[ +.BI - N +] +[ +.I file ... +] +.SH DESCRIPTION +.I Mc +splits the input into as many columns as will fit in +.I N +print positions. +If run in a +.IR rio (1) +window, the default +.I N +is the number of blanks that will fit across the window; +otherwise the default +.I N +is 80. +Under option +.B - +each input line ending in a colon +.L : +is printed separately. +.SH SOURCE +.B /sys/src/cmd/mc.c +.SH "SEE ALSO" +.IR rio (1), +.IR pr (1), +.I lc +in +.IR ls (1) diff --git a/man/man1/mkdir.1 b/man/man1/mkdir.1 new file mode 100644 index 00000000..89e53eaa --- /dev/null +++ b/man/man1/mkdir.1 @@ -0,0 +1,35 @@ +.TH MKDIR 1 +.SH NAME +mkdir \- make a directory +.SH SYNOPSIS +.B mkdir +[ +.B -p +] +.I dirname ... +.SH DESCRIPTION +.I Mkdir +creates the specified directories. +It +requires write permission in the parent directory. +.PP +If the +.B -p +flag is given, +.I mkdir +creates any necessary parent directories +and does not complain if the target directory already exists. +.SH "SEE ALSO" +.IR rm (1) +.br +.IR cd +in +.IR rc (1) +.SH SOURCE +.B /sys/src/cmd/mkdir.c +.SH DIAGNOSTICS +.I Mkdir +returns null exit status if all directories were successfully made. +Otherwise it prints a diagnostic and returns +.B \&"error" +status. diff --git a/man/man1/plumb.1 b/man/man1/plumb.1 new file mode 100644 index 00000000..6c51d68b --- /dev/null +++ b/man/man1/plumb.1 @@ -0,0 +1,92 @@ +.TH PLUMB 1 +.SH NAME +plumb \- send message to plumber +.SH SYNOPSIS +.B plumb +[ +.B -p +.I plumbfile +] [ +.B -a +.I attributes +] [ +.B -s +.I source +] [ +.B -d +.I destination +] [ +.B -t +.I type +] [ +.B -w +.I directory +] +.B -i +| +.I data... +.SH DESCRIPTION +The +.I plumb +command formats and sends a plumbing message whose data +is, by default, the concatenation of the argument strings separated by blanks. +The options are: +.TP +.B -p +write the message to +.I plumbfile +(default +.BR /mnt/plumb/send ). +.TP +.B -a +set the +.B attr +field of the message (default is empty). +.TP +.B -s +set the +.B src +field of the message (default is +.BR plumb ). +.TP +.B -d +set the +.B dst +field of the message (default is empty). +.TP +.B -t +set the +.B type +field of the message (default is +.BR text ). +.TP +.B -w +set the +.B wdir +field of the message (default is the current working directory of +.IR plumb ). +.TP +.B -i +take the data from standard input rather than the argument strings. +If an +.B action= +attribute is not otherwise specified, +.I plumb +will add an +.B action=showdata +attribute to the message. +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.SH SOURCE +.B /sys/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (2), +.IR plumber (4), +.IR plumb (6) diff --git a/man/man1/rc.1 b/man/man1/rc.1 new file mode 100644 index 00000000..b296a48a --- /dev/null +++ b/man/man1/rc.1 @@ -0,0 +1,959 @@ +.TH RC 1 +.SH NAME +rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language +.SH SYNOPSIS +.B rc +[ +.B -srdiIlxepvV +] +[ +.B -c command +] +[ +.I file +[ +.I arg ... +]] +.SH DESCRIPTION +.I Rc +is the Plan 9 shell. +It executes command lines read from a terminal or a file or, with the +.B -c +flag, from +.I rc's +argument list. +.SS Command Lines +A command line is a sequence of commands, separated by ampersands or semicolons +.RB ( & +or +.BR ; ), +terminated by a newline. +The commands are executed in sequence +from left to right. +.I Rc +does not wait for a command followed by +.B & +to finish executing before starting +the following command. +Whenever a command followed by +.B & +is executed, its process id is assigned to the +.I rc +variable +.BR $apid . +Whenever a command +.I not +followed by +.B & +exits or is terminated, the +.I rc +variable +.B $status +gets the process's wait message (see +.IR wait (2)); +it will be the null string if the command was successful. +.PP +A long command line may be continued on subsequent lines by typing +a backslash +.RB ( \e ) +followed by a newline. +This sequence is treated as though it were a blank. +Backslash is not otherwise a special character. +.PP +A number-sign +.RB ( # ) +and any following characters up to (but not including) the next newline +are ignored, except in quotation marks. +.SS Simple Commands +A simple command is a sequence of arguments interspersed with I/O redirections. +If the first argument is the name of an +.I rc +function or of one of +.I rc's +built-in commands, it is executed by +.IR rc . +Otherwise if the name starts with a slash +.RB ( / ), +it must be the path name of the program to be executed. +Names containing no initial slash are searched for in +a list of directory names stored in +.BR $path . +The first executable file of the given name found +in a directory in +.B $path +is the program to be executed. +To be executable, the user must have execute permission (see +.IR stat (2)) +and the file must be either an executable binary +for the current machine's CPU type, or a shell script. +Shell scripts begin with a line containing the full path name of a shell +(usually +.BR /bin/rc ), +prefixed by +.LR #! . +.PP +The first word of a simple command cannot be a keyword unless it is +quoted or otherwise disguised. +The keywords are +.EX + for in while if not switch fn ~ ! @ +.EE +.SS Arguments and Variables +A number of constructions may be used where +.I rc's +syntax requires an argument to appear. +In many cases a construction's +value will be a list of arguments rather than a single string. +.PP +The simplest kind of argument is the unquoted word: +a sequence of one or more characters none of which is a blank, tab, +newline, or any of the following: +.EX + # ; & | ^ $ = ` ' { } ( ) < > +.EE +An unquoted word that contains any of the characters +.B * +.B ? +.B [ +is a pattern for matching against file names. +The character +.B * +matches any sequence of characters, +.B ? +matches any single character, and +.BI [ class ] +matches any character in the +.IR class . +If the first character of +.I class +is +.BR ~ , +the class is complemented. +The +.I class +may also contain pairs of characters separated by +.BR - , +standing for all characters lexically between the two. +The character +.B / +must appear explicitly in a pattern, as must the +first character of the path name components +.B . +and +.BR .. . +A pattern is replaced by a list of arguments, one for each path name matched, +except that a pattern matching no names is not replaced by the empty list, +but rather stands for itself. +Pattern matching is done after all other +operations. +Thus, +.EX + x=/tmp echo $x^/*.c +.EE +matches +.BR /tmp/*.c , +rather than matching +.B "/*.c +and then prefixing +.BR /tmp . +.PP +A quoted word is a sequence of characters surrounded by single quotes +.RB ( ' ). +A single quote is represented in a quoted word by a pair of quotes +.RB ( '' ). +.PP +Each of the following is an argument. +.PD 0 +.HP +.BI ( arguments ) +.br +The value of a sequence of arguments enclosed in parentheses is +a list comprising the members of each element of the sequence. +Argument lists have no recursive structure, although their syntax may +suggest it. +The following are entirely equivalent: +.EX + echo hi there everybody + ((echo) (hi there) everybody) +.EE +.HP +.BI $ argument +.HP +.BI $ argument ( subscript ) +.br +The +.I argument +after the +.B $ +is the name of a variable whose value is substituted. +Multiple levels +of indirection are possible, but of questionable utility. +Variable values +are lists of strings. +If +.I argument +is a number +.IR n , +the value is the +.IR n th +element of +.BR $* , +unless +.B $* +doesn't have +.I n +elements, in which case the value is empty. +If +.I argument +is followed by a parenthesized list of subscripts, the +value substituted is a list composed of the requested elements (origin 1). +The parenthesis must follow the variable name with no spaces. +Assignments to variables are described below. +.HP +.BI $# argument +.br +The value is the number of elements in the named variable. +A variable +never assigned a value has zero elements. +.HP +$"\c +.I argument +.br +The value is a single string containing the components of the named variable +separated by spaces. A variable with zero elements yields the empty string. +.HP +.BI `{ command } +.br +.I rc +executes the +.I command +and reads its standard output, splitting it into a list of arguments, +using characters in +.B $ifs +as separators. +If +.B $ifs +is not otherwise set, its value is +.BR "'\ \et\en'" . +.HP +.BI <{ command } +.HP +.BI >{ command } +.br +The +.I command +is executed asynchronously with its standard output or standard input +connected to a pipe. +The value of the argument is the name of a file +referring to the other end of the pipe. +This allows the construction of +non-linear pipelines. +For example, the following runs two commands +.B old +and +.B new +and uses +.B cmp +to compare their outputs +.EX + cmp <{old} <{new} +.EE +.HP +.IB argument ^ argument +.br +The +.B ^ +operator concatenates its two operands. +If the two operands +have the same number of components, they are concatenated pairwise. +If not, +then one operand must have one component, and the other must be non-empty, +and concatenation is distributive. +.PD +.SS Free Carets +In most circumstances, +.I rc +will insert the +.B ^ +operator automatically between words that are not separated by white space. +Whenever one of +.B $ +.B ' +.B ` +follows a quoted or unquoted word or an unquoted word follows a quoted word +with no intervening blanks or tabs, +a +.B ^ +is inserted between the two. +If an unquoted word immediately follows a +.BR $ +and contains a character other than an alphanumeric, underscore, +or +.BR * , +a +.B ^ +is inserted before the first such character. +Thus +.IP +.B cc -$flags $stem.c +.LP +is equivalent to +.IP +.B cc -^$flags $stem^.c +.SS I/O Redirections +The sequence +.BI > file +redirects the standard output file (file descriptor 1, normally the +terminal) to the named +.IR file ; +.BI >> file +appends standard output to the file. +The standard input file (file descriptor 0, also normally the terminal) +may be redirected from a file by the sequence +.BI < file \f1, +or from an inline `here document' +by the sequence +.BI << eof-marker\f1. +The contents of a here document are lines of text taken from the command +input stream up to a line containing nothing but the +.IR eof-marker , +which may be either a quoted or unquoted word. +If +.I eof-marker +is unquoted, variable names of the form +.BI $ word +have their values substituted from +.I rc's +environment. +If +.BI $ word +is followed by a caret +.RB ( ^ ), +the caret is deleted. +If +.I eof-marker +is quoted, no substitution occurs. +.PP +Redirections may be applied to a file-descriptor other than standard input +or output by qualifying the redirection operator +with a number in square brackets. +For example, the diagnostic output (file descriptor 2) +may be redirected by writing +.BR "cc junk.c >[2]junk" . +.PP +A file descriptor may be redirected to an already open descriptor by writing +.BI >[ fd0 = fd1 ] +or +.BI <[ fd0 = fd1 ]\f1. +.I Fd1 +is a previously opened file descriptor and +.I fd0 +becomes a new copy (in the sense of +.IR dup (2)) +of it. +A file descriptor may be closed by writing +.BI >[ fd0 =] +or +.BI <[ fd0 =]\f1. +.PP +Redirections are executed from left to right. +Therefore, +.B cc junk.c >/dev/null >[2=1] +and +.B cc junk.c >[2=1] >/dev/null +have different effects: the first puts standard output in +.BR /dev/null +and then puts diagnostic output in the same place, where the second +directs diagnostic output to the terminal and sends standard output to +.BR /dev/null . +.SS Compound Commands +A pair of commands separated by a pipe operator +.RB ( | ) +is a command. +The standard output of the left command is sent through a pipe +to the standard input of the right command. +The pipe operator may be decorated +to use different file descriptors. +.BI |[ fd ] +connects the output end of the pipe to file descriptor +.I fd +rather than 1. +.BI |[ fd0 = fd1 ] +connects output to +.I fd1 +of the left command and input to +.I fd0 +of the right command. +.PP +A pair of commands separated by +.B && +or +.B || +is a command. +In either case, the left command is executed and its exit status examined. +If the operator is +.B && +the right command is executed if the left command's status is null. +.B || +causes the right command to be executed if the left command's status is non-null. +.PP +The exit status of a command may be inverted (non-null is changed to null, null +is changed to non-null) by preceding it with a +.BR ! . +.PP +The +.B | +operator has highest precedence, and is left-associative (i.e. binds tighter +to the left than the right). +.B ! +has intermediate precedence, and +.B && +and +.B || +have the lowest precedence. +.PP +The unary +.B @ +operator, with precedence equal to +.BR ! , +causes its operand to be executed in a subshell. +.PP +Each of the following is a command. +.PD 0 +.HP +.B if ( +.I list +.B ) +.I command +.br +A +.I list +is a sequence of commands, separated by +.BR & , +.BR ; , +or newline. +It is executed and +if its exit status is null, the +.I command +is executed. +.HP +.B if not +.I command +.br +The immediately preceding command must have been +.BI if( list ) +.IR command . +If its condition was non-zero, the +.I command +is executed. +.HP +.BI for( name +.B in +.IB arguments ) +.I command +.HP +.BI for( name ) +.I command +.br +The +.I command +is executed once for each +.IR argument +with that argument assigned to +.IR name . +If the argument list is omitted, +.B $* +is used. +.HP +.BI while( list ) +.I command +.br +The +.I list +is executed repeatedly until its exit status is non-null. +Each time it returns null status, the +.I command +is executed. +An empty +.I list +is taken to give null status. +.HP +.BI "switch(" argument "){" list } +.br +The +.IR list +is searched for simple commands beginning with the word +.BR case . +(The search is only at the `top level' of the +.IR list . +That is, +.B cases +in nested constructs are not found.) +.I Argument +is matched against each word following +.B case +using the pattern-matching algorithm described above, except that +.B / +and the first characters of +.B . +and +.B .. +need not be matched explicitly. +When a match is found, commands in the list are executed up to the next +following +.B case +command (at the top level) or the closing brace. +.HP +.BI { list } +.br +Braces serve to alter the grouping of commands implied by operator +priorities. +The +.I body +is a sequence of commands separated by +.BR & , +.BR ; , +or newline. +.HP +.BI "fn " name { list } +.HP +.BI "fn " name +.br +The first form defines a function with the given +.IR name . +Subsequently, whenever a command whose first argument is +.I name +is encountered, the current value of +the remainder of the command's argument list will be assigned to +.BR $* , +after saving its current value, and +.I rc +will execute the +.IR list . +The second form removes +.IR name 's +function definition. +.HP +.BI "fn " note { list } +.br +.HP +.BI "fn " note +.br +A function with a special name will be called when +.I rc +receives a corresponding note; see +.IR notify (2). +The valid note names (and corresponding notes) are +.B sighup +.RB ( hangup ), +.B sigint +.RB ( interrupt ), +.BR sigalrm +.RB ( alarm ), +and +.B sigfpe +(floating point trap). +By default +.I rc +exits on receiving any signal, except when run interactively, +in which case interrupts and quits normally cause +.I rc +to stop whatever it's doing and start reading a new command. +The second form causes +.I rc +to handle a signal in the default manner. +.I Rc +recognizes an artificial note, +.BR sigexit , +which occurs when +.I rc +is about to finish executing. +.HP +.IB name = "argument command" +.br +Any command may be preceded by a sequence of assignments +interspersed with redirections. +The assignments remain in effect until the end of the command, unless +the command is empty (i.e. the assignments stand alone), in which case +they are effective until rescinded by later assignments. +.PD +.SS Built-in Commands +These commands are executed internally by +.IR rc , +usually because their execution changes or depends on +.IR rc 's +internal state. +.PD 0 +.HP +.BI . " file ..." +.br +Execute commands from +.IR file . +.B $* +is set for the duration to the remainder of the argument list following +.IR file . +.I File +is searched for using +.BR $path . +.HP +.BI builtin " command ..." +.br +Execute +.I command +as usual except that any function named +.I command +is ignored in favor of the built-in meaning. +.HP +.BI "cd [" dir "]" +.br +Change the current directory to +.IR dir . +The default argument is +.BR $home . +.I dir +is searched for in each of the directories mentioned in +.BR $cdpath . +.HP +.BI "eval [" "arg ..." "]" +.br +The arguments are concatenated separated by spaces into a single string, +read as input to +.IR rc , +and executed. +.HP +.BI "exec [" "command ..." "]" +.br +This instance of +.I rc +replaces itself with the given (non-built-in) +.IR command . +.HP +.BI "flag " f " [+-]" +.br +Either set +.RB ( + ), +clear +.RB ( - ), +or test (neither +.B + +nor +.BR - ) +the flag +.IR f , +where +.I f +is a single character, one of the command line flags (see Invocation, below). +.HP +.BI "exit [" status "]" +.br +Exit with the given exit status. +If none is given, the current value of +.B $status +is used. +.HP +.BR "rfork " [ nNeEsfFm ] +.br +Become a new process group using +.BI rfork( flags ) +where +.I flags +is composed of the bitwise OR of the +.B rfork +flags specified by the option letters +(see +.IR fork (2)). +If no +.I flags +are given, they default to +.BR ens . +The +.I flags +and their meanings are: +.B n +is +.BR RFNAMEG ; +.B N +is +.BR RFCNAMEG ; +.B e +is +.BR RFENVG ; +.B E +is +.BR RFCENVG ; +.B s +is +.BR RFNOTEG ; +.B f +is +.BR RFFDG ; +.B F +is +.BR RFCFDG ; +and +.B m +is +.BR RFNOMNT . +.HP +.BI "shift [" n "]" +.br +Delete the first +.IR n +(default 1) +elements of +.BR $* . +.HP +.BI "wait [" pid "]" +.br +Wait for the process with the given +.I pid +to exit. +If no +.I pid +is given, all outstanding processes are waited for. +.HP +.BI whatis " name ..." +.br +Print the value of each +.I name +in a form suitable for input to +.IR rc . +The output is +an assignment to any variable, +the definition of any function, +a call to +.B builtin +for any built-in command, or +the completed pathname of any executable file. +.HP +.BI ~ " subject pattern ..." +.br +The +.I subject +is matched against each +.I pattern +in sequence. +If it matches any pattern, +.B $status +is set to zero. +Otherwise, +.B $status +is set to one. +Patterns are the same as for file name matching, except that +.B / +and the first character of +.B . +and +.B .. +need not be matched explicitly. +The +.I patterns +are not subjected to +file name matching before the +.B ~ +command is executed, so they need not be enclosed in quotation marks. +.PD +.SS Environment +The +.I environment +is a list of strings made available to executing binaries by the +.B env +device +(see +.IR env (3)). +.I Rc +creates an environment entry for each variable whose value is non-empty, +and for each function. +The string for a variable entry has the variable's name followed by +.B = +and its value. +If the value has more than one component, these +are separated by ctrl-a +.RB ( '\e001' ) +characters. +The string for a function is just the +.I rc +input that defines the function. +The name of a function in the environment is the function name +preceded by +.LR fn# . +.PP +When +.I rc +starts executing it reads variable and function definitions from its +environment. +.SS Special Variables +The following variables are set or used by +.IR rc . +.PD 0 +.TP \w'\fL$promptXX'u +.B $* +Set to +.IR rc 's +argument list during initialization. +Whenever a +.B . +command or a function is executed, the current value is saved and +.B $* +receives the new argument list. +The saved value is restored on completion of the +.B . +or function. +.TP +.B $apid +Whenever a process is started asynchronously with +.BR & , +.B $apid +is set to its process id. +.TP +.B $home +The default directory for +.BR cd . +.TP +.B $ifs +The input field separators used in backquote substitutions. +If +.B $ifs +is not set in +.IR rc 's +environment, it is initialized to blank, tab and newline. +.TP +.B $path +The search path used to find commands and input files +for the +.B . +command. +If not set in the environment, it is initialized by +.BR "path=(.\ /bin)" . +Its use is discouraged; instead use +.IR bind (1) +to build a +.B /bin +containing what's needed. +.TP +.B $pid +Set during initialization to +.IR rc 's +process id. +.TP +.B $prompt +When +.I rc +is run interactively, the first component of +.B $prompt +is printed before reading each command. +The second component is printed whenever a newline is typed and more lines +are required to complete the command. +If not set in the environment, it is initialized by +.BR "prompt=('%\ '\ '\ ')" . +.TP +.B $status +Set to the wait message of the last-executed program. +(unless started with +.BR &). +.B ! +and +.B ~ +also change +.BR $status . +Its value is used to control execution in +.BR && , +.BR || , +.B if +and +.B while +commands. +When +.I rc +exits at end-of-file of its input or on executing an +.B exit +command with no argument, +.B $status +is its exit status. +.PD +.SS Invocation +If +.I rc +is started with no arguments it reads commands from standard input. +Otherwise its first non-flag argument is the name of a file from which +to read commands (but see +.B -c +below). +Subsequent arguments become the initial value of +.BR $* . +.I Rc +accepts the following command-line flags. +.PD 0 +.TP \w'\fL-c\ \fIstring\fLXX'u +.BI -c " string" +Commands are read from +.IR string . +.TP +.B -s +Print out exit status after any command where the status is non-null. +.TP +.B -e +Exit if +.B $status +is non-null after executing a simple command. +.TP +.B -i +If +.B -i +is present, or +.I rc +is given no arguments and its standard input is a terminal, +it runs interactively. +Commands are prompted for using +.BR $prompt . +.TP +.B -I +Makes sure +.I rc +is not run interactively. +.TP +.B -l +If +.B -l +is given or the first character of argument zero is +.BR - , +.I rc +reads commands from +.BR $home/lib/profile , +if it exists, before reading its normal input. +.TP +.B -p +A no-op. +.TP +.B -d +A no-op. +.TP +.B -v +Echo input on file descriptor 2 as it is read. +.TP +.B -x +Print each simple command before executing it. +.TP +.B -r +Print debugging information (internal form of commands +as they are executed). +.PD +.SH SOURCE +.B /sys/src/cmd/rc +.SH "SEE ALSO" +Tom Duff, +``Rc \- The Plan 9 Shell''. +.SH BUGS +There should be a way to match patterns against whole lists rather than +just single strings. +.br +Using +.B ~ +to check the value of +.B $status +changes +.BR $status . +.br +Functions that use here documents don't work. +.br +Free carets don't get inserted next to keywords. diff --git a/man/man1/rm.1 b/man/man1/rm.1 new file mode 100644 index 00000000..c5786f92 --- /dev/null +++ b/man/man1/rm.1 @@ -0,0 +1,28 @@ +.TH RM 1 +.SH NAME +rm \- remove files +.SH SYNOPSIS +.B rm +[ +.B -fr +] +.I file ... +.SH DESCRIPTION +.I Rm +removes files or directories. +A directory is removed only if it is empty. +Removal of a file requires write permission in its directory, +but neither read nor write permission on the file itself. +The options are +.TP +.B -f +Don't report files that can't be removed. +.TP +.B -r +Recursively delete the +entire contents of a directory +and the directory itself. +.SH SOURCE +.B /sys/src/cmd/rm.c +.SH "SEE ALSO" +.IR remove (2) diff --git a/man/man1/sam.1 b/man/man1/sam.1 new file mode 100644 index 00000000..0ba20335 --- /dev/null +++ b/man/man1/sam.1 @@ -0,0 +1,885 @@ +.TH SAM 1 +.ds a \fR*\ \fP +.SH NAME +sam, B, sam.save \- screen editor with structural regular expressions +.SH SYNOPSIS +.B sam +[ +.I option ... +] [ +.I files +] +.PP +.B sam +.B -r +.I machine +.PP +.B sam.save +.PP +.B B +[ +.BI -nnnn +] +.I file ... +.SH DESCRIPTION +.I Sam +is a multi-file editor. +It modifies a local copy of an external file. +The copy is here called a +.IR file . +The files are listed in a menu available through mouse button 3 +or the +.B n +command. +Each file has an associated name, usually the name of the +external file from which it was read, and a `modified' bit that indicates whether +the editor's file agrees with the external file. +The external file is not read into +the editor's file until it first becomes the current file\(emthat to +which editing commands apply\(emwhereupon its menu entry is printed. +The options are +.TF -rmachine +.TP +.B -d +Do not `download' the terminal part of +.IR sam . +Editing will be done with the command language only, as in +.IR ed (1). +.TP +.BI -r " machine +Run the host part remotely +on the specified machine, the terminal part locally. +.TP +.BI -s " path +Start the host part from the specified file on the remote host. +Only meaningful with the +.BI -r +option. +.TP +.BI -t " path +Start the terminal part from the specified file. Useful +for debugging. +.PD +.SS Regular expressions +Regular expressions are as in +.IR regexp (6) +with the addition of +.BR \en +to represent newlines. +A regular expression may never contain a literal newline character. +The empty +regular expression stands for the last complete expression encountered. +A regular expression in +.I sam +matches the longest leftmost substring formally +matched by the expression. +Searching in the reverse direction is equivalent +to searching backwards with the catenation operations reversed in +the expression. +.SS Addresses +An address identifies a substring in a file. +In the following, `character +.IR n ' +means the null string +after the +.IR n -th +character in the file, with 1 the +first character in the file. +`Line +.IR n ' +means the +.IR n -th +match, +starting at the beginning of the file, of the regular expression +.LR .*\en? . +All files always have a current substring, called dot, +that is the default address. +.SS Simple Addresses +.PD 0 +.TP +.BI # n +The empty string after character +.IR n ; +.B #0 +is the beginning of the file. +.TP +.I n +Line +.IR n ; +.B 0 +is the beginning of the file. +.TP +.BI / regexp / +.PD 0 +.TP +.BI ? regexp ? +The substring that matches the regular expression, +found by looking toward the end +.RB ( / ) +or beginning +.RB ( ? ) +of the file, +and if necessary continuing the search from the other end to the +starting point of the search. +The matched substring may straddle +the starting point. +When entering a pattern containing a literal question mark +for a backward search, the question mark should be +specified as a member of a class. +.PD +.TP +.B 0 +The string before the first full line. +This is not necessarily +the null string; see +.B + +and +.B - +below. +.TP +.B $ +The null string at the end of the file. +.TP +.B . +Dot. +.TP +.B \&' +The mark in the file (see the +.B k +command below). +.TP +\fB"\f2regexp\fB"\f1\f1 +Preceding a simple address (default +.BR . ), +refers to the address evaluated in the unique file whose menu line +matches the regular expression. +.PD +.SS Compound Addresses +In the following, +.I a1 +and +.I a2 +are addresses. +.TF a1+a2 +.TP +.IB a1 + a2 +The address +.I a2 +evaluated starting at the end of +.IR a1 . +.TP +.IB a1 - a2 +The address +.I a2 +evaluated looking in the reverse direction +starting at the beginning of +.IR a1 . +.TP +.IB a1 , a2 +The substring from the beginning of +.I a1 +to the end of +.IR a2 . +If +.I a1 +is missing, +.B 0 +is substituted. +If +.I a2 +is missing, +.B $ +is substituted. +.TP +.IB a1 ; a2 +Like +.IB a1 , a2\f1, +but with +.I a2 +evaluated at the end of, and dot set to, +.IR a1 . +.PD +.PP +The operators +.B + +and +.B - +are high precedence, while +.B , +and +.B ; +are low precedence. +.PP +In both +.B + +and +.B - +forms, if +.I a2 +is a line or character address with a missing +number, the number defaults to 1. +If +.I a1 +is missing, +.L . +is substituted. +If both +.I a1 +and +.I a2 +are present and distinguishable, +.B + +may be elided. +.I a2 +may be a regular +expression; if it is delimited by +.LR ? 's, +the effect of the +.B + +or +.B - +is reversed. +.PP +It is an error for a compound address to represent a malformed substring. +Some useful idioms: +.IB a1 +- +\%(\f2a1\fB-+\f1) +selects the line containing +the end (beginning) of a1. +.BI 0/ regexp / +locates the first match of the expression in the file. +(The form +.B 0;// +sets dot unnecessarily.) +.BI ./ regexp /// +finds the second following occurrence of the expression, +and +.BI .,/ regexp / +extends dot. +.SS Commands +In the following, text demarcated by slashes represents text delimited +by any printable +character except alphanumerics. +Any number of +trailing delimiters may be elided, with multiple elisions then representing +null strings, but the first delimiter must always +be present. +In any delimited text, +newline may not appear literally; +.B \en +may be typed for newline; and +.B \e/ +quotes the delimiter, here +.LR / . +Backslash is otherwise interpreted literally, except in +.B s +commands. +.PP +Most commands may be prefixed by an address to indicate their range +of operation. +Those that may not are marked with a +.L * +below. +If a command takes +an address and none is supplied, dot is used. +The sole exception is +the +.B w +command, which defaults to +.BR 0,$ . +In the description, `range' is used +to represent whatever address is supplied. +Many commands set the +value of dot as a side effect. +If so, it is always set to the `result' +of the change: the empty string for a deletion, the new text for an +insertion, etc. (but see the +.B s +and +.B e +commands). +.br +.ne 1.2i +.SS Text commands +.PD 0 +.TP +.BI a/ text / +.TP +or +.TP +.B a +.TP +.I lines of text +.TP +.B . +Insert the text into the file after the range. +Set dot. +.PD +.TP +.B c\fP +.br +.ns +.TP +.B i\fP +Same as +.BR a , +but +.B c +replaces the text, while +.B i +inserts +.I before +the range. +.TP +.B d +Delete the text in the range. +Set dot. +.TP +.BI s/ regexp / text / +Substitute +.I text +for the first match to the regular expression in the range. +Set dot to the modified range. +In +.I text +the character +.B & +stands for the string +that matched the expression. +Backslash behaves as usual unless followed by +a digit: +.BI \e d +stands for the string that matched the +subexpression begun by the +.IR d -th +left parenthesis. +If +.I s +is followed immediately by a +number +.IR n , +as in +.BR s2/x/y/ , +the +.IR n -th +match in the range is substituted. +If the +command is followed by a +.BR g , +as in +.BR s/x/y/g , +all matches in the range +are substituted. +.TP +.BI m " a1 +.br +.ns +.TP +.BI t " a1 +Move +.RB ( m ) +or copy +.RB ( t ) +the range to after +.IR a1 . +Set dot. +.SS Display commands +.PD 0 +.TP +.B p +Print the text in the range. +Set dot. +.TP +.B = +Print the line address and character address of the range. +.TP +.B =# +Print just the character address of the range. +.PD +.SS File commands +.PD 0 +.TP +.BI \*ab " file-list +Set the current file to the first file named in the list +that +.I sam +also has in its menu. +The list may be expressed +.BI < "Plan 9 command" +in which case the file names are taken as words (in the shell sense) +generated by the Plan 9 command. +.TP +.BI \*aB " file-list +Same as +.BR b , +except that file names not in the menu are entered there, +and all file names in the list are examined. +.TP +.B \*an +Print a menu of files. +The format is: +.RS +.TP 11 +.BR ' " or blank +indicating the file is modified or clean, +.TP 11 +.BR - " or \&" + +indicating the file is unread or has been read +(in the terminal, +.B * +means more than one window is open), +.TP 11 +.BR . " or blank +indicating the current file, +.TP 11 +a blank, +.TP 11 +and the file name. +.RE +.TP 0 +.BI \*aD " file-list +Delete the named files from the menu. +If no files are named, the current file is deleted. +It is an error to +.B D +a modified file, but a subsequent +.B D +will delete such a file. +.PD +.SS I/O Commands +.PD 0 +.TP +.BI \*ae " filename +Replace the file by the contents of the named external file. +Set dot to the beginning of the file. +.TP +.BI r " filename +Replace the text in the range by the contents of the named external file. +Set dot. +.TP +.BI w " filename +Write the range (default +.BR 0,$ ) +to the named external file. +.TP +.BI \*af " filename +Set the file name and print the resulting menu entry. +.PP +If the file name is absent from any of these, the current file name is used. +.B e +always sets the file name; +.B r +and +.B w +do so if the file has no name. +.TP +.BI < " Plan 9-command +Replace the range by the standard output of the +Plan 9 command. +.TP +.BI > " Plan 9-command +Send the range to the standard input of the +Plan 9 command. +.TP +.BI | " Plan 9-command +Send the range to the standard input, and replace it by +the standard output, of the +Plan 9 command. +.TP +.BI \*a! " Plan 9-command +Run the +Plan 9 command. +.TP +.BI \*acd " directory +Change working directory. +If no directory is specified, +.B $home +is used. +.PD +.PP +In any of +.BR < , +.BR > , +.B | +or +.BR ! , +if the +.I Plan 9 command +is omitted the last +.I Plan 9 command +(of any type) is substituted. +If +.I sam +is +.I downloaded +(using the mouse and raster display, i.e. not using option +.BR -d ), +.B ! +sets standard input to +.BR /dev/null , +and otherwise +unassigned output +.RB ( stdout +for +.B ! +and +.BR > , +.B stderr +for all) is placed in +.B /tmp/sam.err +and the first few lines are printed. +.SS Loops and Conditionals +.PD 0 +.TP +.BI x/ regexp / " command +For each match of the regular expression in the range, run the command +with dot set to the match. +Set dot to the last match. +If the regular +expression and its slashes are omitted, +.L /.*\en/ +is assumed. +Null string matches potentially occur before every character +of the range and at the end of the range. +.TP +.BI y/ regexp / " command +Like +.BR x , +but run the command for each substring that lies before, between, +or after +the matches that would be generated by +.BR x . +There is no default regular expression. +Null substrings potentially occur before every character +in the range. +.TP +.BI \*aX/ regexp / " command +For each file whose menu entry matches the regular expression, +make that the current file and +run the command. +If the expression is omitted, the command is run +in every file. +.TP +.BI \*aY/ regexp / " command +Same as +.BR X , +but for files that do not match the regular expression, +and the expression is required. +.TP +.BI g/ regexp / " command +.br +.ns +.TP +.BI v/ regexp / " command +If the range contains +.RB ( g ) +or does not contain +.RB ( v ) +a match for the expression, +set dot to the range and run the command. +.PP +These may be nested arbitrarily deeply, but only one instance of either +.B X +or +.B Y +may appear in a \%single command. +An empty command in an +.B x +or +.B y +defaults to +.BR p ; +an empty command in +.B X +or +.B Y +defaults to +.BR f . +.B g +and +.B v +do not have defaults. +.PD +.SS Miscellany +.TF (empty) +.TP +.B k +Set the current file's mark to the range. Does not set dot. +.TP +.B \*aq +Quit. +It is an error to quit with modified files, but a second +.B q +will succeed. +.TP +.BI \*au " n +Undo the last +.I n +(default 1) +top-level commands that changed the contents or name of the +current file, and any other file whose most recent change was simultaneous +with the current file's change. +Successive +.BR u 's +move further back in time. +The only commands for which u is ineffective are +.BR cd , +.BR u , +.BR q , +.B w +and +.BR D . +If +.I n +is negative, +.B u +`redoes,' undoing the undo, going forwards in time again. +.TP +(empty) +If the range is explicit, set dot to the range. +If +.I sam +is downloaded, the resulting dot is selected on the screen; +otherwise it is printed. +If no address is specified (the +command is a newline) dot is extended in either direction to +line boundaries and printed. +If dot is thereby unchanged, it is set to +.B .+1 +and printed. +.PD +.SS Grouping and multiple changes +Commands may be grouped by enclosing them in braces +.BR {} . +Commands within the braces must appear on separate lines (no backslashes are +required between commands). +Semantically, an opening brace is like a command: +it takes an (optional) address and sets dot for each sub-command. +Commands within the braces are executed sequentially, but changes made +by one command are not visible to other commands (see the next +paragraph). +Braces may be nested arbitrarily. +.PP +When a command makes a number of changes to a file, as in +.BR x/re/c/text/ , +the addresses of all changes to the file are computed in the original file. +If the changes are in sequence, +they are applied to the file. +Successive insertions at the same address are catenated into a single +insertion composed of the several insertions in the order applied. +.SS The terminal +What follows refers to behavior of +.I sam +when downloaded, that is, when +operating as a display editor on a raster display. +This is the default +behavior; invoking +.I sam +with the +.B -d +(no download) option provides access +to the command language only. +.PP +Each file may have zero or more windows open. +Each window is equivalent +and is updated simultaneously with changes in other windows on the same file. +Each window has an independent value of dot, indicated by a highlighted +substring on the display. +Dot may be in a region not within +the window. +There is usually a `current window', +marked with a dark border, to which typed text and editing +commands apply. +Text may be typed and edited as in +.IR rio (1); +also the escape key (ESC) selects (sets dot to) text typed +since the last mouse button hit. +.PP +The button 3 menu controls window operations. +The top of the menu +provides the following operators, each of which uses one or +more +.IR rio -like +cursors to prompt for selection of a window or sweeping +of a rectangle. +`Sweeping' a null rectangle gets a large window, disjoint +from the command window or the whole screen, depending on +where the null rectangle is. +.TF resize +.TP +.B new +Create a new, empty file. +.TP +.B zerox +Create a copy of an existing window. +.TP +.B resize +As in +.IR rio . +.TP +.B close +Delete the window. +In the last window of a file, +.B close +is equivalent to a +.B D +for the file. +.TP +.B write +Equivalent to a +.B w +for the file. +.PD +.PP +Below these operators is a list of available files, starting with +.BR ~~sam~~ , +the command window. +Selecting a file from the list makes the most recently +used window on that file current, unless it is already current, in which +case selections cycle through the open windows. +If no windows are open +on the file, the user is prompted to open one. +Files other than +.B ~~sam~~ +are marked with one of the characters +.B -+* +according as zero, one, or more windows +are open on the file. +A further mark +.L . +appears on the file in the current window and +a single quote, +.BR ' , +on a file modified since last write. +.PP +The command window, created automatically when +.B sam +starts, is an ordinary window except that text typed to it +is interpreted as commands for the editor rather than passive text, +and text printed by editor commands appears in it. +The behavior is like +.IR rio , +with an `output point' that separates commands being typed from +previous output. +Commands typed in the command window apply to the +current open file\(emthe file in the most recently +current window. +.SS Manipulating text +Button 1 changes selection, much like +.IR rio . +Pointing to a non-current window with button 1 makes it current; +within the current window, button 1 selects text, thus setting dot. +Double-clicking selects text to the boundaries of words, lines, +quoted strings or bracketed strings, depending on the text at the click. +.PP +Button 2 provides a menu of editing commands: +.TF /regexp +.TP +.B cut +Delete dot and save the deleted text in the snarf buffer. +.TP +.B paste +Replace the text in dot by the contents of the snarf buffer. +.TP +.B snarf +Save the text in dot in the snarf buffer. +.TP +.B plumb +Send the text in the selection as a plumb +message. If the selection is empty, +the white-space-delimited block of text is sent as a plumb message +with a +.B click +attribute defining where the selection lies (see +.IR plumb (6)). +.TP +.B look +Search forward for the next occurrence of the literal text in dot. +If dot is the null string, the text in the snarf buffer is +used. +The snarf buffer is unaffected. +.TP +.B +Exchange snarf buffers with +.IR rio . +.TP +.BI / regexp +Search forward for the next match of the last regular expression +typed in a command. +(Not in command window.) +.TP +.B send +Send the text in dot, or the snarf buffer if +dot is the null string, as if it were typed to the command window. +Saves the sent text in the snarf buffer. +(Command window only.) +.PD +.SS External communication +.I Sam +listens to the +.B edit +plumb port. +If plumbing is not active, +on invocation +.I sam +creates a named pipe +.BI /srv/sam. user +which acts as an additional source of commands. Characters written to +the named pipe are treated as if they had been typed in the command window. +.PP +.I B +is a shell-level command that causes an instance of +.I sam +running on the same terminal to load the named +.IR files . +.I B +uses either plumbing or the named pipe, whichever service is available. +If plumbing is not enabled, +the option allows a line number to be specified for +the initial position to display in the last named file +(plumbing provides a more general mechanism for this ability). +.SS Abnormal termination +If +.I sam +terminates other than by a +.B q +command (by hangup, deleting its window, etc.), modified +files are saved in an +executable file, +.BR $home/sam.save . +This program, when executed, asks whether to write +each file back to a external file. +The answer +.L y +causes writing; anything else skips the file. +.SH FILES +.TF /sys/src/cmd/samterm +.TP +.B $home/sam.save +.TP +.B $home/sam.err +.TP +.B /sys/lib/samsave +the program called to unpack +.BR $home/sam.save . +.SH SOURCE +.TF /sys/src/cmd/samterm +.TP +.B /sys/src/cmd/sam +source for +.I sam +itself +.TP +.B /sys/src/cmd/samterm +source for the separate terminal part +.TP +.B /rc/bin/B +.SH SEE ALSO +.IR ed (1), +.IR sed (1), +.IR grep (1), +.IR rio (1), +.IR regexp (6). +.PP +Rob Pike, +``The text editor sam''. diff --git a/man/man1/seq.1 b/man/man1/seq.1 new file mode 100644 index 00000000..60d1f12a --- /dev/null +++ b/man/man1/seq.1 @@ -0,0 +1,75 @@ +.TH SEQ 1 +.SH NAME +seq \- print sequences of numbers +.SH SYNOPSIS +.B seq +[ +.B -w +] +[ +.BI -f format +] +[ +.I first +[ +.I incr +] +] +.I last +.SH DESCRIPTION +.I Seq +prints a sequence of numbers, one per line, from +.I first +(default 1) to as near +.I last +as possible, in increments of +.I incr +(default 1). +The loop is: +.sp +.EX + for(val = min; val <= max; val += incr) print val; +.EE +.sp +The numbers are interpreted as floating point. +.PP +Normally integer values are printed as decimal integers. +The options are +.TP "\w'\fL-f \fIformat\fLXX'u" +.BI -f format +Use the +.IR print (2)-style +.I format +.IR print +for printing each (floating point) number. +The default is +.LR %g . +.TP +.B -w +Equalize the widths of all numbers by padding with +leading zeros as necessary. +Not effective with option +.BR -f , +nor with numbers in exponential notation. +.SH EXAMPLES +.TP +.L +seq 0 .05 .1 +Print +.BR "0 0.05 0.1" +(on separate lines). +.TP +.L +seq -w 0 .05 .1 +Print +.BR "0.00 0.05 0.10" . +.SH SOURCE +.B /sys/src/cmd/seq.c +.SH BUGS +Option +.B -w +always surveys every value in advance. +Thus +.L +seq -w 1000000000 +is a painful way to get an `infinite' sequence. diff --git a/man/man1/sleep.1 b/man/man1/sleep.1 new file mode 100644 index 00000000..61169e96 --- /dev/null +++ b/man/man1/sleep.1 @@ -0,0 +1,31 @@ +.TH SLEEP 1 +.SH NAME +sleep \- suspend execution for an interval +.SH SYNOPSIS +.B sleep +.I time +.SH DESCRIPTION +.I Sleep +suspends execution for +.I time +seconds. +.SH EXAMPLES +Execute a command +100 seconds hence. +.IP +.EX +{sleep 100; command}& +.EE +.PP +Repeat a command every 30 seconds. +.IP +.EX +while (){ + command + sleep 30 +} +.EE +.SH SOURCE +.B /sys/src/cmd/sleep.c +.SH "SEE ALSO" +.IR sleep (2) diff --git a/man/man1/sort.1 b/man/man1/sort.1 new file mode 100644 index 00000000..6dded61a --- /dev/null +++ b/man/man1/sort.1 @@ -0,0 +1,260 @@ +.TH SORT 1 +.SH NAME +sort \- sort and/or merge files +.SH SYNOPSIS +.B sort +[ +.BI -cmuMbdf\&inrwt x +] +[ +.BI + pos1 +[ +.BI - pos2 +] ... +] ... +[ +.B -k +.I pos1 +[ +.I ,pos2 +] +] ... +[ +.B -o +.I output +] +[ +.B -T +.I dir +\&... +] +[ +.I option +\&... +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Sort\^ +sorts +lines of all the +.I files +together and writes the result on +the standard output. +If no input files are named, the standard input is sorted. +.PP +The default sort key is an entire line. +Default ordering is +lexicographic by runes. +The ordering is affected globally by the following options, +one or more of which may appear. +.TP +.B -M +Compare as months. +The first three +non-white space characters +of the field +are folded +to upper case +and compared +so that +.L JAN +precedes +.LR FEB , +etc. +Invalid fields +compare low to +.LR JAN . +.TP +.B -b +Ignore leading white space (spaces and tabs) in field comparisons. +.TP +.B -d +`Phone directory' order: +only letters, +accented letters, +digits and white space +are significant in comparisons. +.TP +.B -f +Fold lower case +letters onto upper case. +Accented characters are folded to their +non-accented upper case form. +.TP +.B -i +Ignore characters outside the +.SM ASCII +range 040-0176 +in non-numeric comparisons. +.TP +.B -w +Like +.BR -i , +but ignore only tabs and spaces. +.TP +.B -n +An initial numeric string, +consisting of optional white space, +optional plus or minus sign, +and zero or more digits with optional decimal point, +is sorted by arithmetic value. +.TP +.B -g +Numbers, like +.B -n +but with optional +.BR e -style +exponents, are sorted by value. +.TP +.B -r +Reverse the sense of comparisons. +.TP +.BI -t x\^ +`Tab character' separating fields is +.IR x . +.PP +The notation +.BI + "pos1\| " - pos2\^ +restricts a sort key to a field beginning at +.I pos1\^ +and ending just before +.IR pos2 . +.I Pos1\^ +and +.I pos2\^ +each have the form +.IB m . n\f1, +optionally followed by one or more of the flags +.BR Mbdfginr , +where +.I m\^ +tells a number of fields to skip from the beginning of the line and +.I n\^ +tells a number of characters to skip further. +If any flags are present they override all the global +ordering options for this key. +A missing +.BI \&. n\^ +means +.BR \&.0 ; +a missing +.BI - pos2\^ +means the end of the line. +Under the +.BI -t x\^ +option, fields are strings separated by +.IR x ; +otherwise fields are +non-empty strings separated by white space. +White space before a field +is part of the field, except under option +.BR -b . +A +.B b +flag may be attached independently to +.IR pos1 +and +.IR pos2. +.PP +The notation +.B -k +.IR pos1 [, pos2 ] +is how POSIX +.I sort +defines fields: +.I pos1 +and +.I pos2 +have the same format but different meanings. +The value of +.I m\^ +is origin 1 instead of origin 0 +and a missing +.BI \&. n\^ +in +.I pos2 +is the end of the field. +.PP +When there are multiple sort keys, later keys +are compared only after all earlier keys +compare equal. +Lines that otherwise compare equal are ordered +with all bytes significant. +.PP +These option arguments are also understood: +.TP \w'\fL-z\fIrecsize\fLXX'u +.B -c +Check that the single input file is sorted according to the ordering rules; +give no output unless the file is out of sort. +.TP +.B -m +Merge; assume the input files are already sorted. +.TP +.B -u +Suppress all but one in each +set of equal lines. +Ignored bytes +and bytes outside keys +do not participate in +this comparison. +.TP +.B -o +The next argument is the name of an output file +to use instead of the standard output. +This file may be the same as one of the inputs. +.TP +.BI -T dir +Put temporary files in +.I dir +rather than in +.BR /tmp . +.ne 4 +.SH EXAMPLES +.TP +.L sort -u +0f +0 list +Print in alphabetical order all the unique spellings +in a list of words +where capitalized words differ from uncapitalized. +.TP +.L sort -t: +1 /adm/users +Print the users file +sorted by user name +(the second colon-separated field). +.TP +.L sort -umM dates +Print the first instance of each month in an already sorted file. +Options +.B -um +with just one input file make the choice of a +unique representative from a set of equal lines predictable. +.TP +.L +grep -n '^' input | sort -t: +1f +0n | sed 's/[0-9]*://' +A stable sort: input lines that compare equal will +come out in their original order. +.SH FILES +.BI /tmp/sort. . +.SH SOURCE +.B /sys/src/cmd/sort.c +.SH SEE ALSO +.IR uniq (1), +.IR look (1) +.SH DIAGNOSTICS +.I Sort +comments and exits with non-null status for various trouble +conditions and for disorder discovered under option +.BR -c . +.SH BUGS +An external null character can be confused +with an internally generated end-of-field character. +The result can make a sub-field not sort +less than a longer field. +.PP +Some of the options, e.g. +.B -i +and +.BR -M , +are hopelessly provincial. diff --git a/man/man1/spell.1 b/man/man1/spell.1 new file mode 100644 index 00000000..8298452c --- /dev/null +++ b/man/man1/spell.1 @@ -0,0 +1,96 @@ +.TH SPELL 1 +.SH NAME +spell, sprog \- find spelling errors +.SH SYNOPSIS +.B spell +[ +.I options +] +\&... +[ +.I file +] +\&... +.PP +.B sprog +[ +.I options +] +[ +.B -f +.I file +] +.SH DESCRIPTION +.I Spell +looks up words from the named +.I files +(standard input default) +in a spelling list and places +possible misspellings\(emwords +not sanctioned there\(emon the standard output. +.PP +.I Spell +ignores constructs of +.IR troff (1) +and its standard preprocessors. +It understands these options: +.TP +.B -b +Check British spelling. +.TP +.B -v +Print all words not literally in the spelling list, with +derivations. +.TP +.B -x +Print, marked with +.LR = , +every stem as it is looked up in the spelling list, +along with its affix classes. +.PP +As a matter of policy, +.I spell +does not admit multiple spellings of the same word. +Variants that follow general rules are preferred +over those that don't, even when the unruly spelling is +more common. +Thus, in American usage, `modelled', `sizeable', and `judgment' are +rejected in favor of `modeled', `sizable', and `judgement'. +Agglutinated variants are shunned: `crewmember' and `backyard' +cede to `crew member' and `back yard' (noun) or `back-yard' +(adjective). +.SH FILES +.TF /sys/lib/brspell +.TP +.B /sys/lib/amspell +American spelling list +.TP +.B /sys/lib/brspell +British spelling list +.TP +.B /bin/aux/sprog +The actual spelling checker. +It expects one word per line on standard input, +and takes the same arguments as +.IR spell . +.SH SOURCE +.TF /sys/src/cmd/spell +.TP +.B /rc/bin/spell +the script +.TP +.B /sys/src/cmd/spell +source for +.I sprog +.SH SEE ALSO +.IR deroff (1) +.SH BUGS +The heuristics of +.IR deroff (1) +used to excise formatting information are imperfect. +.br +The spelling list's coverage is uneven; +in particular biology, medicine, and chemistry, and +perforce proper names, +not to mention languages other than English, +are covered very lightly. diff --git a/man/man1/split.1 b/man/man1/split.1 new file mode 100644 index 00000000..ffb012d7 --- /dev/null +++ b/man/man1/split.1 @@ -0,0 +1,82 @@ +.TH SPLIT 1 +.CT 1 files +.SH NAME +split \- split a file into pieces +.SH SYNOPSIS +.B split +[ +.I option ... +] +[ +.I file +] +.SH DESCRIPTION +.I Split +reads +.I file +(standard input by default) +and writes it in pieces of 1000 +lines per output file. +The names of the +output files are +.BR xaa , +.BR xab , +and so on to +.BR xzz . +The options are +.TP +.BI -n " n" +Split into +.IR n -line +pieces. +.TP +.BI -l " n" +Synonym for +.B -n +.IR n , +a nod to Unix's syntax. +.TP +.BI -e " expression" +File divisions occur at each line +that matches a regular +.IR expression ; +see +.IR regexp (6). +Multiple +.B -e +options may appear. +If a subexpression of +.I expression +is contained in parentheses +.BR ( ... ) , +the output file name is the portion of the +line which matches the subexpression. +.TP +.BI -f " stem +Use +.I stem +instead of +.B x +in output file names. +.TP +.BI -s " suffix +Append +.I suffix +to names identified under +.BR -e . +.TP +.B -x +Exclude the matched input line from the output file. +.TP +.B -i +Ignore case in option +.BR -e ; +force output file names (excluding the suffix) +to lower case. +.SH SOURCE +.B /sys/src/cmd/split.c +.SH SEE ALSO +.IR sed (1), +.IR awk (1), +.IR grep (1), +.IR regexp (6) diff --git a/man/man1/strings.1 b/man/man1/strings.1 new file mode 100644 index 00000000..d72ffbb1 --- /dev/null +++ b/man/man1/strings.1 @@ -0,0 +1,28 @@ +.TH STRINGS 1 +.SH NAME +strings \- extract printable strings +.SH SYNOPSIS +.B strings +[ +.I file ... +] +.SH DESCRIPTION +.I Strings +finds and prints strings containing 6 or more +consecutive printable UTF-encoded characters +in a (typically) binary file, default +standard input. +Printable characters are taken to be +.SM ASCII +characters from blank through tilde (hexadecimal 20 through 7E), inclusive, +and +all other characters from value 00A0 to FFFF. +Strings reports +the decimal offset within the file at which the string starts and the text +of the string. If the string is longer than 70 runes the line is +terminated by three dots and the printing is resumed on the next +line with the offset of the continuation line. +.SH SOURCE +.B /sys/src/cmd/strings.c +.SH SEE ALSO +.IR nm (1) diff --git a/man/man1/sum.1 b/man/man1/sum.1 new file mode 100644 index 00000000..d981c8c7 --- /dev/null +++ b/man/man1/sum.1 @@ -0,0 +1,77 @@ +.TH SUM 1 +.SH NAME +sum, md5sum, sha1sum \- sum and count blocks in a file +.SH SYNOPSIS +.B sum +[ +.B -5r +] +[ +.I file ... +] +.PP +.B md5sum +[ +.I file ... +] +.PP +.B sha1sum +[ +.I file ... +] +.SH DESCRIPTION +By default, +.I sum +calculates and prints a 32-bit hexadecimal checksum, +a byte count, +and the name of +each +.IR file . +The checksum is also a function of the input length. +If no files are given, +the standard input is +summed. +Other summing algorithms are available. +The options are +.TP +.B -r +Sum with the algorithm of System V's +.B "sum -r" +and print the length (in 1K blocks) of the input. +.TP +.B -5 +Sum with System V's default algorithm +and print the length (in 512-byte blocks) of the input. +.PP +.I Sum +is typically used to look for bad spots, +to validate a file communicated over +some transmission line or +as a quick way to determine if two files on different machines might be the same. +.PP +.B Md5sum +computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm +described in RFC1321. +If no +.I files +are given, +the standard input is +summed. +.PP +.B Sha1sum +computes the 40 hex digit National Institute of Standards and Technology SHA1 secure hash algorithm +described in FIPS PUB 180-1. +If no +.I files +are given, +the standard input is +summed. +.SH SOURCE +.B /sys/src/cmd/sum.c +.br +.B /sys/src/cmd/md5sum.c +.br +.B /sys/src/cmd/sha1sum.c +.SH "SEE ALSO" +.IR cmp (1), +.IR wc (1) diff --git a/man/man1/tail.1 b/man/man1/tail.1 new file mode 100644 index 00000000..b2d880b6 --- /dev/null +++ b/man/man1/tail.1 @@ -0,0 +1,87 @@ +.TH TAIL 1 +.SH NAME +tail \- deliver the last part of a file +.SH SYNOPSIS +.B tail +[ +.BR +- \fInumber\fP[ lbc ][ rf ] +] +[ +.I file +] +.PP +.B tail +[ +.B -fr +] +[ +.B -n +.I nlines +] +[ +.B -c +.I nbytes +] +[ +.I file +] +.SH DESCRIPTION +.I Tail +copies the named file to the standard output beginning +at a designated place. +If no file is named, the standard input is copied. +.PP +Copying begins at position +.BI + number +measured from the beginning, or +.BI - number +from the end of the input. +.I Number +is counted in lines, 1K blocks or bytes, +according to the appended flag +.LR l , +.LR b , +or +.LR c . +Default is +.B -10l +(ten ell). +.PP +The further flag +.L r +causes tail to print lines from the end of the file in reverse order; +.L f +(follow) causes +.IR tail , +after printing to the end, to keep watch and +print further data as it appears. +.PP +The second syntax is that promulgated by POSIX, where +the +.I numbers +rather than the options are signed. +.SH EXAMPLES +.TP +.B tail file +Print the last 10 lines of a file. +.TP +.B tail +0f file +Print a file, and continue to watch +data accumulate as it grows. +.TP +.B sed 10q file +Print the first 10 lines of a file. +.SH SOURCE +.B /sys/src/cmd/tail.c +.SH BUGS +Tails relative to the end of the file +are treasured up in a buffer, and thus +are limited in length. +.br +According to custom, option +.BI + number +counts lines from 1, and counts +blocks and bytes from 0. +.br +.I Tail +is ignorant of UTF. diff --git a/man/man1/tar.1 b/man/man1/tar.1 new file mode 100644 index 00000000..8ef56d06 --- /dev/null +++ b/man/man1/tar.1 @@ -0,0 +1,118 @@ +.TH TAR 1 +.SH NAME +tar \- archiver +.SH SYNOPSIS +.B tar +.I key +[ +.I file ... +] +.SH DESCRIPTION +.PP +.I Tar +saves and restores file trees. +It is most often used to transport a tree of files from one +system to another. +The +.I key +is a string that contains +at most one function letter plus optional modifiers. +Other arguments to the command are names of +files or directories to be dumped or restored. +A directory name implies all the contained +files and subdirectories (recursively). +.PP +The function is one of the following letters: +.TP +.B c +Create a new archive with the given files as contents. +.TP +.B x +Extract the named files from the archive. +If a file is a directory, the directory is extracted recursively. +Modes are restored if possible. +If no file argument is given, extract the entire archive. +If the archive contains multiple entries for a file, +the latest one wins. +.TP +.B t +List all occurrences of each +.I file +in the archive, or of all files if there are no +.I file +arguments. +.TP +.B r +The named files +are appended to the archive. +.PP +The modifiers are: +.TP +.B v +(verbose) +Print the name of each file treated +preceded by the function letter. +With +.BR t , +give more details about the +archive entries. +.TP +.B f +Use the next argument as the name of the archive instead of +the default standard input (for keys +.B x +and +.BR t ) +or standard output (for keys +.B c +and +.BR r ). +.TP +.B u +Use the next (numeric) argument as the user id for files in +the output archive. This is only useful when moving files to +a non-Plan 9 system. +.TP +.B g +Use the next (numeric) argument as the group id for files in +the output archive. +.TP +.B p +Create archive in POSIX ustar format, +which raises the maximum pathname length from 100 to 256 bytes. +Ustar archives are recognised automatically by +.I tar +when reading archives. +.TP +.B R +When extracting, ignore leading slash on file names, +i.e., extract all files relative to the current directory. +.TP +.B T +Modifies the behavior of +.B x +to set the mode and modified time +of each file to that specified in the archive. +.SH EXAMPLES +.I Tar +can be used to copy hierarchies thus: +.IP +.EX +@{cd fromdir && tar cp .} | @{cd todir && tar xT} +.EE +.SH SOURCE +.B /sys/src/cmd/tar.c +.SH SEE ALSO +.IR ar (1), +.IR bundle (1), +.IR tapefs (1) +.SH BUGS +There is no way to ask for any but the last +occurrence of a file. +.br +File path names are limited to +100 characters +(256 when using ustar format). +.br +The tar format allows specification of links and symbolic links, +concepts foreign to Plan 9: they are ignored. diff --git a/man/man1/tee.1 b/man/man1/tee.1 new file mode 100644 index 00000000..d237fb7f --- /dev/null +++ b/man/man1/tee.1 @@ -0,0 +1,28 @@ +.TH TEE 1 +.SH NAME +tee \- pipe fitting +.SH SYNOPSIS +.B tee +[ +.B -i +] +[ +.B -a +] +.I files +.SH DESCRIPTION +.I Tee +transcribes the standard input to the standard +output and makes copies in the +.IR files . +The options are +.TP +.B -i +Ignore interrupts. +.TP +.B -a +Append the output to the +.I files +rather than rewriting them. +.SH SOURCE +.B /sys/src/cmd/tee.c diff --git a/man/man1/test.1 b/man/man1/test.1 new file mode 100644 index 00000000..86f0cd34 --- /dev/null +++ b/man/man1/test.1 @@ -0,0 +1,211 @@ +.TH TEST 1 +.SH NAME +test \- set status according to condition +.SH SYNOPSIS +.B test +.I expr +.SH DESCRIPTION +.I Test +evaluates the expression +.IR expr . +If the value is true the exit status is null; otherwise the +exit status is non-null. +If there are no arguments the exit status is non-null. +.PP +The following primitives are used to construct +.IR expr . +.TP "\w'\fIn1 \fL-eq \fIn2\fLXX'u" +.BI -r " file" +True if the file exists (is accessible) and is readable. +.PD0 +.TP +.BI -w " file" +True if the file exists and is writable. +.TP +.BI -x " file" +True if the file exists and has execute permission. +.TP +.BI -e " file +True if the file exists. +.TP +.BI -f " file" +True if the file exists and is a plain file. +.TP +.BI -d " file" +True if the file exists and is a directory. +.TP +.BI -s " file" +True if the file exists and has a size greater than zero. +.TP +.BI -t " fildes +True if the open file whose file descriptor number is +.I fildes +(1 by default) +is the same file as +.BR /dev/cons . +.TP +.BI -A " file" +True if the file exists and is append-only. +.TP +.BI -L " file" +True if the file exists and is exclusive-use. +.TP +.BI -T "file" +True if the file exists and is temporary. +.TP +.IB s1 " = " s2 +True +if the strings +.I s1 +and +.I s2 +are identical. +.TP +.IB s1 " != " s2 +True +if the strings +.I s1 +and +.I s2 +are not identical. +.TP +s1 +True if +.I s1 +is not the null string. +(Deprecated.) +.TP +.BI -n " s1" +True if the length of string +.I s1 +is non-zero. +.TP +.BI -z " s1" +True if the length of string +.I s1 +is zero. +.TP +.IB n1 " -eq " n2 +True if the integers +.I n1 +and +.I n2 +are arithmetically equal. +Any of the comparisons +.BR -ne , +.BR -gt , +.BR -ge , +.BR -lt , +or +.BR -le +may be used in place of +.BR -eq . +The (nonstandard) construct +.BI -l " string\f1, +meaning the length of +.IR string , +may be used in place of an integer. +.TP +.IB a " -nt " b +True if file +.I a +is newer than (modified after) file +.IR b . +.TP +.IB a " -ot " b +True if file +.I a +is older than (modified before) file +.IR b . +.TP +.IB f " -older " t +True if file +.I f +is older than (modified before) time +.IR t . +If +.I t +is a integer followed by the letters +.BR y (years), +.BR M (months), +.BR d (days), +.BR h (hours), +.BR m (minutes), +or +.BR s (seconds), +it represents current time minus the specified time. +If there is no letter, it represents seconds since +epoch. +You can also concatenate mixed units. For example, +.B 3d12h +means three days and twelve hours ago. +.PD +.PP +These primaries may be combined with the +following operators: +.TP "\w'\fL( \fIexpr\fL )XX'u" +.B ! +unary negation operator +.PD0 +.TP +.B -o +binary +.I or +operator +.TP +.B -a +binary +.I and +operator; higher precedence than +.BR -o +.TP +.BI "( " expr " )" +parentheses for grouping. +.PD +.PP +The primitives +.BR -b , +.BR -u , +.BR -g , +and +.BR -s +return false; they are recognized for compatibility with POSIX. +.PP +Notice that all the operators and flags are separate +arguments to +.IR test . +Notice also that parentheses and equal signs are meaningful +to +.I rc +and must be enclosed in quotes. +.SH EXAMPLES +.I Test +is a dubious way to check for specific character strings: +it uses a process to do what an +.IR rc (1) +match or switch statement can do. +The first example is not only inefficient but wrong, because +.I test +understands the purported string +.B \&"-c" +as an option. +.IP +.EX +if (test $1 '=' "-c") echo OK # wrong! +.EE +.LP +A better way is +.IP +.EX +if (~ $1 -c) echo OK +.EE +.PP +Test whether +.L abc +is in the current directory. +.IP +.B test -f abc -o -d abc +.SH SOURCE +.B /sys/src/cmd/test.c +.SH "SEE ALSO" +.IR rc (1) diff --git a/man/man1/time.1 b/man/man1/time.1 new file mode 100644 index 00000000..2c6b834b --- /dev/null +++ b/man/man1/time.1 @@ -0,0 +1,21 @@ +.TH TIME 1 +.SH NAME +time \- time a command +.SH SYNOPSIS +.B time +.I command +[ +.I arg ... +] +.SH DESCRIPTION +The +.I command +is executed with the given arguments; after it is complete, +.I time +reports on standard error the program's elapsed user time, +system time, and real time, in seconds, +followed by the command line. +.SH SOURCE +.B /sys/src/cmd/time.c +.SH "SEE ALSO" +.IR prof (1) diff --git a/man/man1/touch.1 b/man/man1/touch.1 new file mode 100644 index 00000000..ac5937ec --- /dev/null +++ b/man/man1/touch.1 @@ -0,0 +1,35 @@ +.TH TOUCH 1 +.SH NAME +touch \- set modification date of a file +.SH SYNOPSIS +.B touch +[ +.B -c +] +[ +.B -t +.I time +] +.I file ... +.SH DESCRIPTION +.I Touch +attempts to set the modification time of the +.I files +to +.I time +(by default, the current time). +If a +.I file +does not exist, +it will be created unless option +.B -c +is present. +.SH SOURCE +.B /sys/src/cmd/touch.c +.SH SEE ALSO +.IR ls (1), +.IR stat (2), +.IR chmod (1) +.SH BUGS +.I Touch +will not touch directories. diff --git a/man/man1/tr.1 b/man/man1/tr.1 new file mode 100644 index 00000000..0e11f5b9 --- /dev/null +++ b/man/man1/tr.1 @@ -0,0 +1,97 @@ +.TH TR 1 +.SH NAME +tr \- translate characters +.SH SYNOPSIS +.B tr +[ +.B -cds +] +[ +.I string1 +[ +.I string2 +] +] +.SH DESCRIPTION +.I Tr +copies the standard input to the standard output with +substitution or deletion of selected characters (runes). +Input characters found in +.I string1 +are mapped into the corresponding characters of +.IR string2 . +When +.I string2 +is short it is padded to the length of +.I string1 +by duplicating its last character. +Any combination of the options +.B -cds +may be used: +.TP +.B -c +Complement +.IR string1 : +replace it with a lexicographically ordered +list of all other characters. +.TP +.B -d +Delete from input all characters in +.IR string1 . +.TP +.B -s +Squeeze repeated output characters that occur in +.I string2 +to single characters. +.PP +In either string a noninitial sequence +.BI - x\f1, +where +.I x +is any character (possibly quoted), stands for +a range of characters: +a possibly empty sequence of codes running from +the successor of the previous code up through +the code for +.IR x . +The character +.L \e +followed by 1, 2 or 3 octal digits stands for the +character whose +16-bit +value is given by those digits. +The character sequence +.L \ex +followed by 1, 2, 3, or 4 hexadecimal digits stands +for the character whose +16-bit value is given by those digits. +A +.L \e +followed by any other character stands +for that character. +.SH EXAMPLES +Replace all upper-case +.SM ASCII +letters by lower-case. +.IP +.EX +tr A-Z a-z lower +.EE +.PP +Create a list of all +the words in +.L file1 +one per line in +.LR file2 , +where a word is taken to be a maximal string of alphabetics. +.I String2 +is given as a quoted newline. +.IP +.EX +tr -cs A-Za-z ' +\&' file2 +.EE +.SH SOURCE +.B /sys/src/cmd/tr.c +.SH "SEE ALSO" +.IR sed (1) diff --git a/man/man1/uniq.1 b/man/man1/uniq.1 new file mode 100644 index 00000000..65fcd49f --- /dev/null +++ b/man/man1/uniq.1 @@ -0,0 +1,59 @@ +.TH UNIQ 1 +.SH NAME +uniq \- report repeated lines in a file +.SH SYNOPSIS +.B uniq +[ +.B -udc +[ +.BI +- num +] +] +[ +.I file +] +.SH DESCRIPTION +.I Uniq +copies the input +.IR file , +or the standard input, to the +standard output, comparing adjacent lines. +In the normal case, the second and succeeding copies +of repeated lines are +removed. +Repeated lines must be adjacent +in order to be found. +.TP +.B -u +Print unique lines. +.TP +.B -d +Print (one copy of) duplicated lines. +.TP +.B -c +Prefix a repetition count and a tab to each output line. +Implies +.B -u +and +.BR -d . +.TP +.BI - num +The first +.IR num +fields +together with any blanks before each are ignored. +A field is defined as a string of non-space, non-tab characters +separated by tabs and spaces from its neighbors. +.TP +.BI + num +The first +.IR num +characters are ignored. +Fields are skipped before characters. +.SH SOURCE +.B /sys/src/cmd/uniq.c +.SH "SEE ALSO" +.IR sort (1) +.SH BUGS +Field selection and comparison should be compatible with +.IR sort (1). diff --git a/man/man1/wc.1 b/man/man1/wc.1 new file mode 100644 index 00000000..1c9768fc --- /dev/null +++ b/man/man1/wc.1 @@ -0,0 +1,53 @@ +.TH WC 1 +.SH NAME +wc \- word count +.SH SYNOPSIS +.B wc +[ +.B -lwrbc +] +[ +.I file ... +] +.SH DESCRIPTION +.I Wc +counts lines, words, runes, syntactically-invalid +.SM UTF +codes and bytes in the named +.IR files , +or in the standard input if no file is named. +A word is a maximal string of characters +delimited by spaces, tabs or newlines. +The count of runes includes invalid codes. +.PP +If the optional argument is present, +just the specified counts (lines, words, runes, broken +.SM UTF +codes or bytes) +are selected by the letters +.BR l , +.BR w , +.BR r , +.BR b , +or +.BR c . +Otherwise, lines, words and bytes +.RB ( -lwc ) +are reported. +.SH SOURCE +.B /sys/src/cmd/wc.c +.SH BUGS +The Unicode Standard has many blank characters scattered through it, +but +.I wc +looks for only +.SM ASCII +space, tab and newline. +.br +.I Wc +should have options to count suboptimal +.SM UTF +codes +and bytes that cannot occur in any +.SM UTF +code. diff --git a/man/man1/xd.1 b/man/man1/xd.1 new file mode 100644 index 00000000..cc2d394f --- /dev/null +++ b/man/man1/xd.1 @@ -0,0 +1,87 @@ +.TH XD 1 +.SH NAME +xd \- hex, octal, decimal, or ASCII dump +.SH SYNOPSIS +.B xd +[ +.I option ... +] +[ +.BI - "format ... +] [ +.I file ... +] +.SH DESCRIPTION +.I Xd +concatenates and dumps the +.I files +(standard input by default) +in one or more formats. +Groups of 16 bytes are printed in each of the named formats, one +format per line. +Each line of output is prefixed by its address (byte offset) +in the input file. +The first line of output for each group is zero-padded; subsequent are blank-padded. +.PP +Formats other than +.B -c +are specified by pairs of characters telling size and style, +.L 4x +by default. +The sizes are +.TP \w'2\ or\ w\ \ \ 'u +.BR 1 " or " b +1-byte units. +.PD0 +.TP +.BR 2 " or " w +2-byte big-endian units. +.TP +.BR 4 " or " l +4-byte big-endian units. +.TP +.BR 8 " or " v +8-byte big-endian units. +.PD +.PP +The styles are +.TP 0 +.B o +Octal. +.PD0 +.TP +.B x +Hexadecimal. +.TP +.B d +Decimal. +.PD +.PP +Other options are +.TP \w'\fL-a\fIstyle\fLXX'u +.B -c +Format as +.B 1x +but print +.SM ASCII +representations or C escape sequences where possible. +.TP +.BI -a style +Print file addresses in the given style (and size 4). +.TP +.B -u +(Unbuffered) Flush the output buffer after each 16-byte sequence. +.TP +.B -s +Reverse (swab) the order of bytes in each group of 4 before printing. +.TP +.B -r +Print repeating groups of identical 16-byte sequences as the first group +followed by an asterisk. +.SH SOURCE +.B /sys/src/cmd/xd.c +.SH "SEE ALSO" +.IR db (1) +.SH BUGS +The various output formats don't line up properly in the output of +.IR xd . diff --git a/man/man1/yacc.1 b/man/man1/yacc.1 new file mode 100644 index 00000000..a965f953 --- /dev/null +++ b/man/man1/yacc.1 @@ -0,0 +1,167 @@ +.TH YACC 1 +.SH NAME +yacc \- yet another compiler-compiler +.SH SYNOPSIS +.B yacc +[ +.I option ... +] +.I grammar +.SH DESCRIPTION +.I Yacc +converts a context-free grammar and translation code +into a set of +tables for an LR(1) parser and translator. +The grammar may be ambiguous; +specified precedence rules are used to break ambiguities. +.PP +The output file, +.BR y.tab.c , +must be compiled by the C compiler +to produce a program +.LR yyparse . +This program must be loaded with a lexical analyzer function, +.B yylex(void) +(often generated by +.IR lex (1)), +with a +.B main(int argc, char *argv[]) +program, and with an error handling routine, +.BR yyerror(char*) . +.PP +The options are +.TP "\w'\fL-o \fIoutput\fLXX'u" +.BI -o " output +Direct output to the specified file instead of +.BR y.tab.c . +.TP +.BI -D n +Create file +.BR y.debug , +containing diagnostic messages. +To incorporate them in the parser, compile it with preprocessor symbol +.B yydebug +defined. +The amount of +diagnostic output from the parser is regulated by +value +.IR n . +The value 0 reports errors; 1 reports reductions; +higher values (up to 4) include more information about +state transitions. +.TP +.B -v +Create file +.BR y.output , +containing a description of the parsing tables and of +conflicts arising from ambiguities in the grammar. +.TP +.B -d +Create file +.BR y.tab.h , +containing +.B #define +statements that associate +.IR yacc -assigned +`token codes' with user-declared `token names'. +Include it in source files other than +.B y.tab.c +to give access to the token codes. +.TP +.BI -s " stem +Change the prefix +.L y +of the file names +.BR y.tab.c , +.BR y.tab.h , +.BR y.debug , +and +.B y.output +to +.IR stem . +.TP +.B -S +Write a parser that uses +Stdio +instead of the +.B print +routines in libc. +.PP +The specification of +.I yacc +itself is essentially the same as the UNIX version +described in the references mentioned below. +Besides the +.B -D +option, the main relevant differences are: +.IP +The interface to the C environment is by default through +.B +rather than +.BR ; +the +.B -S +option reverses this. +.IP +The parser accepts +.SM UTF +input text (see +.IR utf (6)), +which has a couple of effects. +First, the return value of +.B yylex() +no longer fits in a +.BR short ; +second, the starting value for non-terminals is now 0xE000 rather than 257. +.IP +The generated parser can be recursive: actions can call +.IR yyparse , +for example to implement a sort of +.B #include +statement in an interpreter. +.IP +Finally, some undocumented inner workings of the parser have been +changed, which may affect programs that know too much about its structure. +.SH FILES +.TF /sys/lib/yaccpars +.TP +.B y.output +.TP +.B y.tab.c +.TP +.B y.tab.h +.TP +.B y.debug +.TP +.B y.tmp.* +temporary file +.TP +.B y.acts.* +temporary file +.TP +.B /sys/lib/yaccpar +parser prototype +.TP +.B /sys/lib/yaccpars +parser prototype using stdio +.SH SOURCE +.B /sys/src/cmd/yacc.c +.SH "SEE ALSO" +.IR lex (1) +.br +S. C. Johnson and R. Sethi, +``Yacc: A parser generator'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 +.br +B. W. Kernighan and Rob Pike, +.I +The UNIX Programming Environment, +Prentice Hall, 1984 +.SH BUGS +The parser may not have full information when it writes to +.B y.debug +so that the names of the tokens returned by +.L yylex +may be missing. -- cgit v1.2.3