From b41b9034225ab3e49980d9de55c141011b6383b0 Mon Sep 17 00:00:00 2001 From: Taru Karttunen Date: Wed, 30 Mar 2011 16:49:47 +0300 Subject: Import sources from 2011-03-30 iso image - sys/man --- sys/man/1/0intro | 397 ++++++++++++++++++++ sys/man/1/2a | 60 +++ sys/man/1/2c | 497 ++++++++++++++++++++++++ sys/man/1/2l | 220 +++++++++++ sys/man/1/INDEX | 329 ++++++++++++++++ sys/man/1/INDEX.html | 665 +++++++++++++++++++++++++++++++++ sys/man/1/abaco | 75 ++++ sys/man/1/acid | 492 ++++++++++++++++++++++++ sys/man/1/acme | 727 +++++++++++++++++++++++++++++++++++ sys/man/1/ap | 16 + sys/man/1/ar | 182 +++++++++ sys/man/1/ascii | 158 ++++++++ sys/man/1/awk | 560 +++++++++++++++++++++++++++ sys/man/1/basename | 35 ++ sys/man/1/bc | 290 ++++++++++++++ sys/man/1/bind | 215 +++++++++++ sys/man/1/bitsyload | 146 ++++++++ sys/man/1/bundle | 53 +++ sys/man/1/cal | 46 +++ sys/man/1/calendar | 62 +++ sys/man/1/cat | 87 +++++ sys/man/1/cb | 46 +++ sys/man/1/chgrp | 36 ++ sys/man/1/chmod | 106 ++++++ sys/man/1/cleanname | 32 ++ sys/man/1/cmp | 57 +++ sys/man/1/col | 55 +++ sys/man/1/colors | 72 ++++ sys/man/1/comm | 47 +++ sys/man/1/con | 315 ++++++++++++++++ sys/man/1/cp | 130 +++++++ sys/man/1/cpp | 119 ++++++ sys/man/1/cpu | 204 ++++++++++ sys/man/1/crop | 153 ++++++++ sys/man/1/date | 58 +++ sys/man/1/db | 1018 ++++++++++++++++++++++++++++++++++++++++++++++++++ sys/man/1/dc | 257 +++++++++++++ sys/man/1/dd | 196 ++++++++++ sys/man/1/delkey | 42 +++ sys/man/1/deroff | 117 ++++++ sys/man/1/diff | 176 +++++++++ sys/man/1/doc2txt | 161 ++++++++ sys/man/1/doctype | 63 ++++ sys/man/1/du | 137 +++++++ sys/man/1/echo | 26 ++ sys/man/1/ecp | 141 +++++++ sys/man/1/ed | 683 +++++++++++++++++++++++++++++++++ sys/man/1/emacs | 17 + sys/man/1/eqn | 339 +++++++++++++++++ sys/man/1/expect | 172 +++++++++ sys/man/1/faces | 124 ++++++ sys/man/1/factor | 64 ++++ sys/man/1/fedex | 27 ++ sys/man/1/file | 112 ++++++ sys/man/1/filter | 320 ++++++++++++++++ sys/man/1/fmt | 90 +++++ sys/man/1/fortune | 23 ++ sys/man/1/freq | 40 ++ sys/man/1/games | 312 ++++++++++++++++ sys/man/1/grap | 416 +++++++++++++++++++++ sys/man/1/graph | 155 ++++++++ sys/man/1/grep | 109 ++++++ sys/man/1/gs | 280 ++++++++++++++ sys/man/1/gview | 204 ++++++++++ sys/man/1/gzip | 210 +++++++++++ sys/man/1/hget | 86 +++++ sys/man/1/history | 102 +++++ sys/man/1/hoc | 144 +++++++ sys/man/1/htmlroff | 119 ++++++ sys/man/1/idiff | 73 ++++ sys/man/1/join | 147 ++++++++ sys/man/1/jpg | 263 +++++++++++++ sys/man/1/kbmap | 35 ++ sys/man/1/kill | 70 ++++ sys/man/1/ktrace | 62 +++ sys/man/1/leak | 235 ++++++++++++ sys/man/1/lens | 45 +++ sys/man/1/lex | 81 ++++ sys/man/1/lock | 61 +++ sys/man/1/look | 85 +++++ sys/man/1/lp | 189 ++++++++++ sys/man/1/ls | 160 ++++++++ sys/man/1/mail | 164 ++++++++ sys/man/1/man | 122 ++++++ sys/man/1/marshal | 173 +++++++++ sys/man/1/mc | 44 +++ sys/man/1/mk | 655 ++++++++++++++++++++++++++++++++ sys/man/1/mkdir | 43 +++ sys/man/1/mlmgr | 139 +++++++ sys/man/1/mp3dec | 47 +++ sys/man/1/mp3enc | 209 +++++++++++ sys/man/1/ms2html | 78 ++++ sys/man/1/mtime | 13 + sys/man/1/mug | 56 +++ sys/man/1/nedmail | 340 +++++++++++++++++ sys/man/1/netstat | 51 +++ sys/man/1/news | 63 ++++ sys/man/1/nm | 107 ++++++ sys/man/1/ns | 44 +++ sys/man/1/p | 33 ++ sys/man/1/page | 271 ++++++++++++++ sys/man/1/passwd | 59 +++ sys/man/1/patch | 158 ++++++++ sys/man/1/pcc | 185 +++++++++ sys/man/1/pic | 344 +++++++++++++++++ sys/man/1/pipefile | 101 +++++ sys/man/1/plot | 61 +++ sys/man/1/plumb | 92 +++++ sys/man/1/pr | 110 ++++++ sys/man/1/prof | 167 +++++++++ sys/man/1/proof | 134 +++++++ sys/man/1/ps | 113 ++++++ sys/man/1/ps2pdf | 90 +++++ sys/man/1/pump | 119 ++++++ sys/man/1/pwd | 38 ++ sys/man/1/ratrace | 57 +++ sys/man/1/rc | 993 ++++++++++++++++++++++++++++++++++++++++++++++++ sys/man/1/replica | 341 +++++++++++++++++ sys/man/1/resample | 58 +++ sys/man/1/rio | 537 ++++++++++++++++++++++++++ sys/man/1/rm | 28 ++ sys/man/1/rwd | 161 ++++++++ sys/man/1/sam | 891 +++++++++++++++++++++++++++++++++++++++++++ sys/man/1/secstore | 225 +++++++++++ sys/man/1/sed | 389 +++++++++++++++++++ sys/man/1/seq | 75 ++++ sys/man/1/size | 28 ++ sys/man/1/sleep | 33 ++ sys/man/1/sort | 262 +++++++++++++ sys/man/1/spell | 96 +++++ sys/man/1/spin | 331 ++++++++++++++++ sys/man/1/split | 82 ++++ sys/man/1/src | 83 ++++ sys/man/1/ssh | 346 +++++++++++++++++ sys/man/1/stop | 36 ++ sys/man/1/strings | 36 ++ sys/man/1/strip | 31 ++ sys/man/1/sum | 94 +++++ sys/man/1/syscall | 77 ++++ sys/man/1/tail | 87 +++++ sys/man/1/tar | 202 ++++++++++ sys/man/1/tbl | 285 ++++++++++++++ sys/man/1/tcs | 172 +++++++++ sys/man/1/tee | 28 ++ sys/man/1/tel | 49 +++ sys/man/1/test | 218 +++++++++++ sys/man/1/thesaurus | 11 + sys/man/1/time | 21 ++ sys/man/1/touch | 35 ++ sys/man/1/tr | 97 +++++ sys/man/1/trace | 84 +++++ sys/man/1/troff | 237 ++++++++++++ sys/man/1/troff2html | 99 +++++ sys/man/1/tweak | 167 +++++++++ sys/man/1/uniq | 59 +++ sys/man/1/units | 107 ++++++ sys/man/1/uptime | 21 ++ sys/man/1/vac | 176 +++++++++ sys/man/1/venti | 153 ++++++++ sys/man/1/vi | 170 +++++++++ sys/man/1/vnc | 237 ++++++++++++ sys/man/1/vt | 135 +++++++ sys/man/1/wc | 53 +++ sys/man/1/weather | 35 ++ sys/man/1/who | 22 ++ sys/man/1/winwatch | 46 +++ sys/man/1/xd | 87 +++++ sys/man/1/yacc | 167 +++++++++ sys/man/1/yesterday | 156 ++++++++ 169 files changed, 27859 insertions(+) create mode 100755 sys/man/1/0intro create mode 100755 sys/man/1/2a create mode 100755 sys/man/1/2c create mode 100755 sys/man/1/2l create mode 100755 sys/man/1/INDEX create mode 100755 sys/man/1/INDEX.html create mode 100755 sys/man/1/abaco create mode 100755 sys/man/1/acid create mode 100755 sys/man/1/acme create mode 100755 sys/man/1/ap create mode 100755 sys/man/1/ar create mode 100755 sys/man/1/ascii create mode 100755 sys/man/1/awk create mode 100755 sys/man/1/basename create mode 100755 sys/man/1/bc create mode 100755 sys/man/1/bind create mode 100755 sys/man/1/bitsyload create mode 100755 sys/man/1/bundle create mode 100755 sys/man/1/cal create mode 100755 sys/man/1/calendar create mode 100755 sys/man/1/cat create mode 100755 sys/man/1/cb create mode 100755 sys/man/1/chgrp create mode 100755 sys/man/1/chmod create mode 100755 sys/man/1/cleanname create mode 100755 sys/man/1/cmp create mode 100755 sys/man/1/col create mode 100755 sys/man/1/colors create mode 100755 sys/man/1/comm create mode 100755 sys/man/1/con create mode 100755 sys/man/1/cp create mode 100755 sys/man/1/cpp create mode 100755 sys/man/1/cpu create mode 100755 sys/man/1/crop create mode 100755 sys/man/1/date create mode 100755 sys/man/1/db create mode 100755 sys/man/1/dc create mode 100755 sys/man/1/dd create mode 100755 sys/man/1/delkey create mode 100755 sys/man/1/deroff create mode 100755 sys/man/1/diff create mode 100755 sys/man/1/doc2txt create mode 100755 sys/man/1/doctype create mode 100755 sys/man/1/du create mode 100755 sys/man/1/echo create mode 100755 sys/man/1/ecp create mode 100755 sys/man/1/ed create mode 100755 sys/man/1/emacs create mode 100755 sys/man/1/eqn create mode 100755 sys/man/1/expect create mode 100755 sys/man/1/faces create mode 100755 sys/man/1/factor create mode 100755 sys/man/1/fedex create mode 100755 sys/man/1/file create mode 100755 sys/man/1/filter create mode 100755 sys/man/1/fmt create mode 100755 sys/man/1/fortune create mode 100755 sys/man/1/freq create mode 100755 sys/man/1/games create mode 100755 sys/man/1/grap create mode 100755 sys/man/1/graph create mode 100755 sys/man/1/grep create mode 100755 sys/man/1/gs create mode 100755 sys/man/1/gview create mode 100755 sys/man/1/gzip create mode 100755 sys/man/1/hget create mode 100755 sys/man/1/history create mode 100755 sys/man/1/hoc create mode 100755 sys/man/1/htmlroff create mode 100755 sys/man/1/idiff create mode 100755 sys/man/1/join create mode 100755 sys/man/1/jpg create mode 100755 sys/man/1/kbmap create mode 100755 sys/man/1/kill create mode 100755 sys/man/1/ktrace create mode 100755 sys/man/1/leak create mode 100755 sys/man/1/lens create mode 100755 sys/man/1/lex create mode 100755 sys/man/1/lock create mode 100755 sys/man/1/look create mode 100755 sys/man/1/lp create mode 100755 sys/man/1/ls create mode 100755 sys/man/1/mail create mode 100755 sys/man/1/man create mode 100755 sys/man/1/marshal create mode 100755 sys/man/1/mc create mode 100755 sys/man/1/mk create mode 100755 sys/man/1/mkdir create mode 100755 sys/man/1/mlmgr create mode 100755 sys/man/1/mp3dec create mode 100755 sys/man/1/mp3enc create mode 100755 sys/man/1/ms2html create mode 100755 sys/man/1/mtime create mode 100755 sys/man/1/mug create mode 100755 sys/man/1/nedmail create mode 100755 sys/man/1/netstat create mode 100755 sys/man/1/news create mode 100755 sys/man/1/nm create mode 100755 sys/man/1/ns create mode 100755 sys/man/1/p create mode 100755 sys/man/1/page create mode 100755 sys/man/1/passwd create mode 100755 sys/man/1/patch create mode 100755 sys/man/1/pcc create mode 100755 sys/man/1/pic create mode 100755 sys/man/1/pipefile create mode 100755 sys/man/1/plot create mode 100755 sys/man/1/plumb create mode 100755 sys/man/1/pr create mode 100755 sys/man/1/prof create mode 100755 sys/man/1/proof create mode 100755 sys/man/1/ps create mode 100755 sys/man/1/ps2pdf create mode 100755 sys/man/1/pump create mode 100755 sys/man/1/pwd create mode 100755 sys/man/1/ratrace create mode 100755 sys/man/1/rc create mode 100755 sys/man/1/replica create mode 100755 sys/man/1/resample create mode 100755 sys/man/1/rio create mode 100755 sys/man/1/rm create mode 100755 sys/man/1/rwd create mode 100755 sys/man/1/sam create mode 100755 sys/man/1/secstore create mode 100755 sys/man/1/sed create mode 100755 sys/man/1/seq create mode 100755 sys/man/1/size create mode 100755 sys/man/1/sleep create mode 100755 sys/man/1/sort create mode 100755 sys/man/1/spell create mode 100755 sys/man/1/spin create mode 100755 sys/man/1/split create mode 100755 sys/man/1/src create mode 100755 sys/man/1/ssh create mode 100755 sys/man/1/stop create mode 100755 sys/man/1/strings create mode 100755 sys/man/1/strip create mode 100755 sys/man/1/sum create mode 100755 sys/man/1/syscall create mode 100755 sys/man/1/tail create mode 100755 sys/man/1/tar create mode 100755 sys/man/1/tbl create mode 100755 sys/man/1/tcs create mode 100755 sys/man/1/tee create mode 100755 sys/man/1/tel create mode 100755 sys/man/1/test create mode 100755 sys/man/1/thesaurus create mode 100755 sys/man/1/time create mode 100755 sys/man/1/touch create mode 100755 sys/man/1/tr create mode 100755 sys/man/1/trace create mode 100755 sys/man/1/troff create mode 100755 sys/man/1/troff2html create mode 100755 sys/man/1/tweak create mode 100755 sys/man/1/uniq create mode 100755 sys/man/1/units create mode 100755 sys/man/1/uptime create mode 100755 sys/man/1/vac create mode 100755 sys/man/1/venti create mode 100755 sys/man/1/vi create mode 100755 sys/man/1/vnc create mode 100755 sys/man/1/vt create mode 100755 sys/man/1/wc create mode 100755 sys/man/1/weather create mode 100755 sys/man/1/who create mode 100755 sys/man/1/winwatch create mode 100755 sys/man/1/xd create mode 100755 sys/man/1/yacc create mode 100755 sys/man/1/yesterday (limited to 'sys/man/1') diff --git a/sys/man/1/0intro b/sys/man/1/0intro new file mode 100755 index 000000000..873fc2b87 --- /dev/null +++ b/sys/man/1/0intro @@ -0,0 +1,397 @@ +.TH INTRO 1 +.SH NAME +intro \- introduction to Plan 9 +.SH DESCRIPTION +Plan 9 is a distributed computing environment assembled from +separate machines acting as terminals, +CPU servers, and file servers. +A user works at a terminal, running a window system on a raster display. +Some windows are connected to CPU servers; the intent is that heavy computing +should be done in those windows but it is also possible to compute on the terminal. +A separate file server provides file storage for terminals and +CPU servers alike. +.SS Name Spaces +In Plan 9, almost all objects look like files. +The object retrieved by a given name is determined by a mapping called the +.IR "name space" . +A quick tour of the standard name space is in +.IR namespace (4). +Every program running in Plan 9 belongs to a +.I process group +(see +.I rfork +in +.IR fork (2)), +and the name space for each process group can be independently +customized. +.PP +A name space is hierarchically structured. +A full file name (also called a +.IR "full path name" ) +has the form +.IP +.RI / e1 / e2 /.../ en +.PP +This represents an object in a tree of files: the tree has a root, +represented by the first +.LR / ; +the root has a child file named +.IR e1 , +which in turn has child +.IR e2 , +and so on; the descendent +.I en +is the object represented by the path name. +.PP +There are a number of Plan 9 +.I services +available, each of which provides a tree of files. +A name space is built by +.I binding +services (or subtrees of services) to names in the name-space-so-far. +Typically, a user's home file server is bound to the root of the name space, +and other services are bound to conventionally named subdirectories. +For example, there is a service resident in the operating system for accessing +hardware devices and that is bound to +.B /dev +by convention. +Kernel services have names (outside the name space) that are a +.L # +sign followed by a single letter; +for example, +.B #c +is conventionally bound to +.BR /dev . +.PP +Plan 9 has +.IR "union directories" : +directories made of several directories all bound to the +same name. +The directories making up a union directory are ordered in a list. +When the bindings are made +(see +.IR bind (1)), +flags specify whether a newly bound member goes at the head or the tail of the list +or completely replaces the list. +To look up a name in a union directory, each member directory is searched +in list order until the name is found. +A bind +flag specifies whether file creation is allowed in a member directory: +a file created in the union directory goes in +the first member directory in list order that allows creation, if any. +.PP +The glue that holds Plan 9 together is a network protocol called +.IR 9P , +described in section 5 of this manual. +All Plan 9 servers read and respond to 9P requests to navigate through +a file tree and to perform operations such as reading and writing +files within the tree. +.SS Booting +When a terminal is powered on or reset, +it must be told the name of a file server to boot from, +the operating system kernel to boot, +and a user name and password. +How this dialog proceeds is environment- and machine-dependent. +Once it is complete, +the terminal loads a Plan 9 kernel, +which sets some environment variables (see +.IR env (3)) +and builds an initial name space. +See +.IR namespace (4), +.IR boot (8), +and +.IR init (8) +for details, but some important aspects of the initial name space are: +.IP \(bu +The environment variable +.B $cputype +is set to the name of the kernel's CPU's architecture: one of +.BR alpha , +.BR mips , +.BR sparc , +.B power +(Power PC), +.BR 386 +(386, 486, Pentium, ...) +etc. +The environment variable +.B $objtype +is initially the same as +.BR $cputype . +.IP \(bu +The environment variable +.B $terminal +is set to a description of the machine running the kernel, +such as +.BR "generic pc" . +Sometimes the middle word of +.B $terminal +encodes the file from which the kernel is booted; +e.g. +.B "alpha apc axp +is bootstrapped from +.BR /alpha/bapc . +.IP \(bu +The environment variable +.B $service +is set to +.BR terminal . +(Other ways of accessing Plan 9 may set +.B $service +to one of +.BR cpu , +.BR con , +or +.BR rx .) +.IP \(bu +The environment variable +.B $user +is set to the name of the user who booted the terminal. +The environment variable +.B $home +is set to that user's home directory. +.IP \(bu +.B /$cputype/bin +and +.B /rc/bin +are unioned into +.BR /bin . +.PD +.PP +After booting, the terminal runs the command interpreter, +.IR rc (1), +on +.B /usr/$user/lib/profile +after moving to the user's home directory. +.PP +Here is a typical profile: +.IP +.EX +bind -a $home/bin/rc /bin +bind -a $home/bin/$cputype /bin +bind -c $home/tmp /tmp +font = /lib/font/bit/pelm/euro.9.font +upas/fs +switch($service){ +case terminal + plumber + prompt=('term% ' ' ') + exec rio -f $font +case cpu + bind /mnt/term/dev/cons /dev/cons + bind /mnt/term/dev/consctl /dev/consctl + bind -a /mnt/term/mnt/wsys /dev + prompt=('cpu% ' ' ') + news +case con + prompt=('cpu% ' ' ') + news +} +.EE +.PD +.PP +The first three lines replace +.B /tmp +with a +.B tmp +in the user's home directory +and union personal +.B bin +directories with +.BR /bin , +to be searched after the standard +.B bin +directories. +The next starts the mail file system; see +.IR mail (1). +Then different things happen, depending on the +.B $service +environment variable, +such as running the window system +.IR rio (1) +on a terminal. +.PP +To do heavy work such as compiling, the +.IR cpu (1) +command connects a window to a CPU server; +the same environment variables are set (to different values) +and the same profile is run. +The initial directory is the current directory in the terminal window +where +.I cpu +was typed. +The value of +.B $service +will be +.BR cpu , +so the second arm of the profile switch is executed. +The root of the terminal's name space is accessible through +.BR /mnt/term , +so the +.I bind +is a way of making the window system's graphics interface (see +.IR draw (3)) +available to programs running on the CPU server. +The +.IR news (1) +command reports current Plan 9 affairs. +.PP +The third possible service type, +.BR con , +is set when the CPU server is called from a non-Plan-9 machine, +such as through +.I telnet +(see +.IR con (1)). +.SS Using Plan 9 +The user commands of Plan 9 are reminiscent of those in Research Unix, version 10. +There are a number of differences, however. +.PP +The standard shell is +.IR rc (1), +not the Bourne shell. +The most noticeable differences appear only when programming and macro processing. +.PP +The character-delete character is backspace, and the line-kill character is +control-U; these cannot be changed. +.PP +DEL is the interrupt character: typing it sends an interrupt to processes running in that window. +See +.IR keyboard (6) +for instructions on typing characters like DEL on the various keyboards. +.PP +If a program dies with something like an address error, it enters a `Broken' +state. It lingers, available for debugging with +.IR db (1) +or +.IR acid (1). +.I Broke +(see +.IR kill (1)) +cleans up broken processes. +.PP +The standard editor is one of +.IR acme (1) +or +.IR sam (1). +There is a variant of +.I sam +that permits running the file-manipulating part of +.I sam +on a non-Plan-9 system: +.IP +.EX +sam -r tcp!kremvax +.EE +.PP +For historical reasons, +.I sam +uses a tab stop setting of 8 spaces, while the other editors and window systems use 4 spaces. +These defaults can be overridden by setting the value of the environment variable +.B $tabstop +to the desired number of spaces per tab. +.PP +Machine names may be prefixed by the network name, +here +.BR tcp ; +and +.B net +for the system default. +.PP +Login connections and remote execution on non-Plan-9 machines are usually +done by saying, for example, +.IP +.EX +con kremvax +.EE +.PP +or +.IP +.EX +rx deepthought chess +.EE +.PP +(see +.IR con (1)). +.PP +.I 9fs +connects to file systems of remote systems +(see +.IR srv (4)). +For example, +.IP +.EX +9fs kremvax +.EE +.PP +sets things up so that the root of +.BR kremvax 's +file tree is visible locally in +.BR /n/kremvax . +.PP +.IR Faces (1) +gives graphical notification of arriving mail. +.PP +The Plan 9 file server has an integrated backup facility. +The command +.IP +.EX +9fs dump +.EE +.PP +binds to +.B /n/dump +a tree containing the daily backups on the file server. +The dump tree has years as top level file names, and month-day +as next level file names. +For example, +.B /n/dump/2000/0120 +is the root of the file system as it appeared at dump time on +January 20, 2000. +If more than one dump is taken on the same day, dumps after +the first have an extra digit. +To recover the version of this file as it was on June 15, 1999, +.IP +.EX +cp /n/dump/1999/0615/sys/man/1/0intro . +.EE +.PP +or use +.IR yesterday (1). +.SH SEE ALSO +This section for general publicly accessible commands. +.br +Section (2) for library functions, including system calls. +.br +Section (3) for kernel devices (accessed via +.IR bind (1)). +.br +Section (4) for file services (accessed via +.IR mount ). +.br +Section (5) for the Plan 9 file protocol. +.br +Section (6) for file formats. +.br +Section (7) for databases and database access programs. +.br +Section (8) for things related to administering Plan 9. +.br +.B /sys/doc +for copies of papers referenced in this manual. +.PP +The back of this volume has a permuted index to aid searches. +.SH DIAGNOSTICS +Upon termination each program returns a string called the +.IR "exit status" . +It was either supplied by a call to +.IR exits (2) +or was written to the command's +.BI /proc/ pid /note +file +(see +.IR proc (3)), +causing an abnormal termination. +The empty string is customary for successful execution; +a non-empty string gives a clue to the failure of the command. diff --git a/sys/man/1/2a b/sys/man/1/2a new file mode 100755 index 000000000..75a92d17b --- /dev/null +++ b/sys/man/1/2a @@ -0,0 +1,60 @@ +.TH 2A 1 +.SH NAME +0a, 1a, 2a, 5a, 6a, 7a, 8a, ka, qa, va \- assemblers +.SH SYNOPSIS +.B 2a +[ +.I option ... +] +[ +.I name ... +] +.br +etc. +.SH DESCRIPTION +These programs +assemble the named files into object files +for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 1 , +.RB 2 , +etc.) that specifies it. +The assemblers handle the most common C preprocessor directives and the associated +command-line options +.BR -D +and +.BR -I . +Other options are: +.TP +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input path name, +strip any trailing +.BR .s , +and append +.RI . O , +where +.I O +is first letter of the assembler's name. +.SH FILES +The directory +.B /sys/include +is searched for include files after +machine-dependent files in +.BR /$objtype/include . +.SH SOURCE +.BR /sys/src/cmd/2a , +etc. +.SH SEE ALSO +.IR 2c (1), +.IR 2l (1). +.PP +Rob Pike, ``A manual for the Plan 9 assembler'' +.SH BUGS +The list of assemblers given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. diff --git a/sys/man/1/2c b/sys/man/1/2c new file mode 100755 index 000000000..cb663e306 --- /dev/null +++ b/sys/man/1/2c @@ -0,0 +1,497 @@ +.TH 2C 1 +.SH NAME +0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc \- C compilers +.SH SYNOPSIS +.B 2c +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands compile the named C +.I files +into object files for the corresponding architecture. +If there are multiple C +.IR files , +the compilers will attempt to keep +.B $NPROC +compilations running concurrently. +Associated with each compiler is a string +.IR objtype , +for example +.TF "6c amd64 " +.PD +.TP +.B "0c spim +little-endian MIPS 3000 family +.TP +.B "1c 68000 +Motorola MC68000 +.TP +.B "2c 68020 +Motorola MC68020 +.TP +.B "5c arm +little-endian ARM +.TP +.B "6c amd64 +AMD64 and compatibles (e.g., Intel EM64T) +.TP +.B "7c alpha +Digital Alpha APX +.TP +.B "8c 386 +Intel i386, i486, Pentium, etc. +.TP +.B "kc sparc +Sun SPARC +.TP +.B "qc power +Power PC +.TP +.B "vc mips +big-endian MIPS 3000 family +.PP +The compilers handle most preprocessing directives themselves; a complete +preprocessor is available in +.IR cpp (1), +which must be run separately. +.PP +Let the first letter of the compiler name be +.IR O = +.BR 0 , +.BR 1 , +.BR 2 , +.BR 5 , +.BR 6 , +.BR 7 , +.BR 8 , +.BR k , +.BR q , +or +.BR v . +The output object files end in +.RI . O . +The letter is also the prefix of related programs: +.IB O a +is the assembler, +.IB O l +is the loader. +Plan 9 conventionally sets the +.B $objtype +environment variable to the +.I objtype +string appropriate to the current machine's type. +Plan 9 also conventionally has +.RI / objtype +directories, which contain among other things: +.BR include , +for machine-dependent include files; +.BR lib , +for public object code libraries; +.BR bin , +for public programs; +and +.BR mkfile , +for preconditioning +.IR mk (1). +.PP +The compiler options are: +.TF Dname +.PD +.TP +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input file name, +strip any trailing +.BR .c , +and append +.RI . O . +.TP +.B -w +Print warning messages about unused variables, etc. +.TP +.B -B +Accept functions without a new-style +ANSI C function prototype. +By default, the compilers reject functions +used without a defined prototype, +although ANSI C permits them. +.TP +.BI -D\*S name=def +.br +.ns +.TP +.BI -D \*Sname +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -F +Enable type-checking of calls to +.IR print (2) +and other formatted print routines. See the discussion +of extensions, below. +.TP +.BI -I \*Sdir +An +.L #include +file whose name does not begin with +slash +or is enclosed in double quotes +is always +sought first in the directory +of the +.I file +argument. If this fails, +the +.I -. +flag is given or the name is enclosed in +.BR <> , +it is then sought +in directories named in +.B -I +options, +then in +.BR /sys/include , +and finally in +.BR /$objtype/include . +.TP +.B -. +Suppress the automatic searching for include files in +the directory of the file argument. +.TP +.B -N +Suppress automatic registerization and optimization. +.TP +.B -S +Print an assembly language version of the object code +on standard output as well as generating the +.RI . O +file. +.TP +.B -T +Pass type signatures on all external and global entities. +The signature is based on the C +.B signof +operator. +See +.IR dynld (2). +.TP +.B -V +By default, the compilers are non-standardly lax about type equality between +.B void* +values and other pointers; this flag requires ANSI C conformance. +.TP +.B -p +Invoke a standard ANSI C preprocessor before compiling. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except suppress information about structures +declared in included header files. +.TP +.B -n +When used with +.B -a +or +.BR -aa , +places acid functions in +.IB file .acid +for input +.IB file .c , +and not on standard output. +.PP +The compilers support several extensions to ANSI C: +.TF \| +.PD +.TP +\- +A structure or union may contain unnamed substructures and subunions. +The fields of the substructures or +subunions can then be used as if they were members of the parent +structure or union (the resolution of a name conflict is unspecified). +When a pointer to the outer structure or union is used in a context +that is only legal for the unnamed substructure, the compiler promotes +the type and adjusts the pointer value to point at the substructure. +If the unnamed structure or union is of a type with a tag name specified by a +.B typedef +statement, +the unnamed structure or union can be explicitly referenced +by .. +.TP +\- +A structure value can be formed with an expression such as +.EX + (struct S){v1, v2, v3} +.EE +where the list elements are values for the fields of struct +.BR S . +.TP +\- +Array initializers can specify the indices of the array in square +brackets, as +.EX + int a[] = { [3] 1, [10] 5 }; +.EE +which initializes the third and tenth elements of the eleven-element array +.BR a . +.TP +\- +Structure initializers can specify the structure element by using the name +following a period, as +.EX + struct { int x; int y; } s = { .y 1, .x 5 }; +.EE +which initializes elements +.B y +and then +.B x +of the structure +.BR s . +These forms also accept the new ANSI C notation, which includes an equal sign: +.EX + int a[] = { [3] = 1, [10] = 5 }; + struct { int x; int y; } s = { .y = 1, .x = 5 }; +.EE +.TP +\- +A global variable can be dedicated to a register +by declaring it +.B "extern register" +in +.I all +modules and libraries. +.TP +\- +A +.B #pragma +of the form +.EX + #pragma lib "libbio.a" +.EE +records that the program needs to be loaded with file +.BR /$objtype/lib/libbio.a ; +such lines, typically placed in library header files, obviate the +.B -l +option of the loaders. To help identify files in non-standard directories, +within the file names in the +.B #pragmas +the string +.B $M +represents the name of the architecture +(e.g., +.BR mips ) +and +.B $O +represents its identifying character +(e.g., +.BR v ). +.TP +\- +A +.B #pragma +of the form +.EX + #pragma varargck argpos error 2 +.EE +tells the compiler that the second argument to +.B error +is a +.BR print -like +format string (see +.IR print (2)) +that identifies the handling of subsequent arguments. +The +.B #pragma +.EX + #pragma varargck type "s" char* +.EE +says that the format verb +.B s +processes an argument of type +.BR char *. +The +.B #pragma +.EX + #pragma varargck flag 'c' +.EE +says that +.B c +is a flag character. +These +.B #pragmas +are used, if the +.B -F +option is enabled, to type-check calls to +.B print +and other such routines. +.TP +\- +A +.B #pragma +with any of the following forms: +.EX + #pragma incomplete \fItype\fP + #pragma incomplete struct \fItag\fP + #pragma incomplete union \fItag\fP +.EE +where +.I type +is a +.BR typedef 'd +name for a structure or union type, and +.I tag +is a structure or union tag, +tells the compiler that +the corresponding type +should have its signature calculated as an incomplete type +even if it is subsequently fully defined. +This allows the type signature mechanism to work in the presence +of opaque types declared in header files, with their full definitions +visible only to the code which manipulates them. +With some imported software it might be necessary to turn off the +signature generation completely for a large body of code (typically +at the start and end of a particular include file). +If +.I type +is the word +.BR _off_ , +signature generation is turned off; if +.I type +is the word +.BR _on_ , +the compiler will generate signatures. +.TP +\- +The C++ comment +.RB ( // +to end of line) +is accepted as well as the normal +convention of +.B /* +.BR */ . +.TP +\- +The compilers accept +.B long +.B long +variables as a 64-bit type. +The standard header typedefs this to +.BR vlong . +Arithmetic on +.B vlong +values is usually emulated by a run-time library, +though in at least +.IR 8c , +only division and modulus use the run-time library +and the other operators generate in-line code +(and +.I uvlong-expression +.I divison-or-modulus +.BI "(1<<" constant ) +will turn into in-line bit operations, +as is done for shorter +.I unsigned +expressions). +.SH EXAMPLE +For the 68020, produce a program +.B prog +from C files +.BR main.c +and +.BR sub.c : +.IP +.EX +2c -FVw main.c sub.c +2l -o prog main.2 sub.2 +.EE +.SH FILES +.TF /$objtype/include +.TP +.B /sys/include +system area for machine-independent +.B #include +directives. +.TP +.B /$objtype/include +system area for machine-dependent +.B #include +directives. +.SH SOURCE +.TF /sys/src/cmd/2c,\ etc. +.TP +.B /sys/src/cmd/cc +machine-independent part +.TP +.BR /sys/src/cmd/2c ,\ etc. +machine-dependent part +.SH "SEE ALSO" +.IR 2a (1), +.IR 2l (1), +.IR cpp (1), +.IR mk (1), +.IR nm (1), +.IR pcc (1), +.IR db (1), +.IR acid (1) +.\" .IR ansitize (1) +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' +.SH BUGS +The list of compilers given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. +.PP +The default preprocessor only handles +.LR #define , +.LR #include , +.LR #undef , +.LR #ifdef , +.LR #line , +and +.LR #ifndef . +For a full ANSI preprocessor, use +the +.B p +option. +.PP +The default search order for include files +differs to that of +.IR cpp (1). +.PP +Some features of C99, the 1999 ANSI C standard, +are implemented. +.PP +.B switch +expressions may not be either signedness of +.B vlong +on 32-bit architectures +.RI ( 8c +at least). +.PP +The implementation of +.B vlong +assignment can use a static location +and this can be disturbed by interrupts +(e.g., notes) +.RI ( 8c +at least). diff --git a/sys/man/1/2l b/sys/man/1/2l new file mode 100755 index 000000000..f89b0e521 --- /dev/null +++ b/sys/man/1/2l @@ -0,0 +1,220 @@ +.TH 2L 1 +.SH NAME +0l, 1l, 2l, 5l, 6l, 7l, 8l, kl, ql, vl \- loaders +.SH SYNOPSIS +.B 2l +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands +load the named +.I files +into executable files for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 1 , +.RB 2 , +etc.) that specifies it. +The files should be object files or libraries (archives of object files) +for the appropriate architecture. +Also, a name like +.BI -l ext +represents the library +.BI lib ext .a +in +.BR /$objtype/lib , +where +.I objtype +is one of +.BR 68000 , +etc. as listed in +.IR 2c (1). +The libraries must have tables of contents +(see +.IR ar (1)). +.PP +In practice, +.B -l +options are rarely necessary as the header files for +the libraries cause their archives to be included automatically in the load +(see +.IR 2c (1)). +For example, any program that includes header file +.B libc.h +causes the loader +to search the C library +.BR /$objtype/lib/libc.a . +Also, the loader creates an undefined symbol +.B _main +(or +.B _mainp +if profiling is enabled) to force loading of the +startup linkage from the C library. +.PP +The order of search to resolve undefined symbols is to load all files and libraries +mentioned explicitly on the command line, and then to resolve remaining symbols +by searching in topological order +libraries mentioned in header files included by files already loaded. +When scanning such libraries, the algorithm is to scan each library repeatedly until +no new undefined symbols are picked up, then to start on the next library. Thus if library +.I A +needs +.I B +which needs +.I A +again, it may be necessary to mention +.I A +explicitly so it will be read a second time. +.PP +The loader options are: +.TP 0.75i +.B -l +(As a bare option.) +Suppress the default loading of the startup linkage and libraries +specified by header files. +.TP +.BI -o " out" +Place output in file +.IR out . +Default is +.IB O .out\f1, +where +.I O +is the first letter of the loader name. +.TP +.B -p +Insert profiling code into the executable output; no special action is needed +during compilation or assembly. +.TP +.B -e +Insert (\fLe\fPmbedded) tracing code into the executable output; no special action is needed +during compilation or assembly. +The added code calls +.L _tracein +at function entries +and +.L _traceout +at function exits. +.TP +.B -s +Strip the symbol tables from the output file. +.TP +.B -a +Print the object code in assembly language, with addresses. +.TP +.B -v +Print debugging output that annotates the activities of the load. +.TP +.BI -M +.RI ( Kl +only) Generate instructions rather than calls to emulation routines +for multiply and divide. +.TP +.BI -E symbol +The entry point for the binary is +.I symbol +(default +.BR _main ; +.B _mainp +under +.BR -p ). +.TP +.BI -x " [ file ]" +Produce an export table in the executable. +The optional +.I file +restricts the exported symbols to those listed in the file. +See +.IR dynld (2). +.TP +.BI -u " [ file ]" +Produce an export table, import table +and a dynamic load section in the executable. +The optional +.I file +restricts the imported symbols to those listed in the file. +See +.IR dynld (2). +.TP +.B -t +(\c +.I 5l +and +.I vl +only) +Move strings into the text segment. +.TP +.BI -H n +Executable header is type +.IR n . +The meaning of the types is architecture-dependent; typically +type 1 is Plan 9 boot format and type 2 is the +regular Plan 9 format, the default. These are reversed on the MIPS. +The Next boot format is 3. Type 4 in +.I vl +creates a MIPS executable for an SGI Unix system. +.TP +.BI -T t +The text segment starts at address +.IR t . +.TP +.BI -D d +The data segment starts at address +.IR d . +.TP +.BI -R r +The text segment is rounded to a multiple of +.I r +(if +.I r +is nonzero). +.PP +The numbers in the above options can begin with +.L 0x +or +.L 0 +to change the default base from decimal to hexadecimal or octal. +The defaults for the values depend on the compiler and the +header type. +.PP +The loaded image has several symbols inserted by the loader: +.B etext +is the address of the end of the text segment; +.B bdata +is the address of the beginning of the data segment; +.B edata +is the address of the end of the data segment; +and +.B end +is the address of the end of the bss segment, and of the program. +.SH FILES +.TF /$objtype/lib +.TP +.B /$objtype/lib +for +.BI -l lib +arguments. +.SH SOURCE +.B /sys/src/cmd/2l +etc. +.SH "SEE ALSO" +.IR 2c (1), +.IR 2a (1), +.IR ar (1), +.IR nm (1), +.IR db (1), +.IR prof (1) +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' +.SH BUGS +The list of loaders given above is only partial, +not all architectures are supported on all systems, +some have been retired and some +are provided by third parties. diff --git a/sys/man/1/INDEX b/sys/man/1/INDEX new file mode 100755 index 000000000..c62d577b3 --- /dev/null +++ b/sys/man/1/INDEX @@ -0,0 +1,329 @@ +0intro 0intro +intro 0intro +0a 2a +1a 2a +2a 2a +5a 2a +6a 2a +7a 2a +8a 2a +ka 2a +qa 2a +va 2a +0c 2c +1c 2c +2c 2c +5c 2c +6c 2c +7c 2c +8c 2c +kc 2c +qc 2c +vc 2c +0l 2l +1l 2l +2l 2l +5l 2l +6l 2l +7l 2l +8l 2l +kl 2l +ql 2l +vl 2l +abaco abaco +readweb abaco +acid acid +trump acid +truss acid +acme acme +awd acme +win acme +ap ap +ar ar +ascii ascii +unicode ascii +awk awk +basename basename +bc bc +bind bind +mount bind +unmount bind +bitsyload bitsyload +keyboard bitsyload +light bitsyload +params bitsyload +pencal bitsyload +prompter bitsyload +bundle bundle +cal cal +calendar calendar +cat cat +read cat +cb cb +chgrp chgrp +chmod chmod +cleanname cleanname +cmp cmp +col col +colors colors +getmap colors +comm comm +con con +hayes con +rx con +telnet con +xmr con +xms con +cp cp +fcp cp +mv cp +cpp cpp +cpu cpu +crop crop +iconv crop +clock date +date date +db db +dc dc +dd dd +delkey delkey +delatex deroff +deroff deroff +diff diff +doc2ps doc2txt +doc2txt doc2txt +msexceltables doc2txt +mswordstrings doc2txt +olefs doc2txt +wdoc2txt doc2txt +xls2txt doc2txt +doctype doctype +du du +echo echo +ecp ecp +ed ed +emacs emacs +eqn eqn +at expect +drain expect +expect expect +pass expect +faces faces +seemail faces +vwhois faces +factor factor +primes factor +fedex fedex +ups fedex +usps fedex +file file +deliver filter +filter filter +list filter +token filter +vf filter +fmt fmt +htmlfmt fmt +fortune fortune +freq freq +4s games +5s games +games games +juggle games +life games +mahjongg games +memo games +sokoban games +sudoku games +grap grap +graph graph +grep grep +gs gs +gview gview +bunzip2 gzip +bzip2 gzip +compress gzip +gunzip gzip +gzip gzip +uncompress gzip +unzip gzip +zip gzip +hget hget +history history +hoc hoc +htmlroff htmlroff +idiff idiff +join join +bmp jpg +gif jpg +ico jpg +jpg jpg +png jpg +ppm jpg +togif jpg +toico jpg +topng jpg +toppm jpg +v210 jpg +yuv jpg +kbmap kbmap +broke kill +kill kill +slay kill +ktrace ktrace +kmem leak +leak leak +umem leak +lens lens +lex lex +lock lock +look look +lp lp +lc ls +ls ls +go.fishing mail +mail mail +lookman man +man man +sig man +marshal marshal +mc mc +membername mk +mk mk +mkdir mkdir +ml mlmgr +mlmgr mlmgr +mlowner mlmgr +mp3dec mp3dec +mp3enc mp3enc +html2ms ms2html +ms2html ms2html +mtime mtime +mug mug +nedmail nedmail +netstat netstat +news news +nm nm +ns ns +p p +page page +netkey passwd +passwd passwd +patch patch +pcc pcc +pic pic +tpic pic +pipefile pipefile +plot plot +plumb plumb +pr pr +kprof prof +prof prof +tprof prof +proof proof +ps ps +psu ps +pdf2ps ps2pdf +ps2pdf ps2pdf +pump pump +pbd pwd +pwd pwd +. rc +cd rc +eval rc +exec rc +exit rc +flag rc +rc rc +rfork rc +shift rc +wait rc +whatis rc +~ rc +changes replica +pull replica +push replica +replica replica +scan replica +resample resample +label rio +rio rio +window rio +wloc rio +rm rm +conswdir rwd +rwd rwd +B sam +sam sam +sam.save sam +samterm sam +aescbc secstore +ipso secstore +secstore secstore +sed sed +seq seq +size size +sleep sleep +sort sort +spell spell +sprog spell +spin spin +split split +src src +scp ssh +ssh ssh +sshnet ssh +sshserve ssh +start stop +stop stop +strings strings +strip strip +md5sum sum +sha1sum sum +sum sum +syscall syscall +tail tail +dircp tar +tar tar +tbl tbl +tcs tcs +tee tee +iwhois tel +tel tel +test test +thesaurus thesaurus +time time +touch touch +tr tr +trace trace +dpost troff +nroff troff +troff troff +troff2html troff2html +tweak tweak +uniq uniq +units units +uptime uptime +unvac vac +vac vac +copy venti +read venti +venti venti +write venti +5i vi +ki vi +qi vi +vi vi +vnc vnc +vncs vnc +vncv vnc +vt vt +wc wc +weather weather +who who +whois who +winwatch winwatch +xd xd +yacc yacc +diffy yesterday +yesterday yesterday diff --git a/sys/man/1/INDEX.html b/sys/man/1/INDEX.html new file mode 100755 index 000000000..84c4100a0 --- /dev/null +++ b/sys/man/1/INDEX.html @@ -0,0 +1,665 @@ + +plan 9 man section 1 + + +[manual index] +

Plan 9 from Bell Labs - Section 1 - Commands

+
+
+
0intro +- introduction to Plan 9 +
intro + +
2a +- assemblers +
0a, 1a, 2a, 5a, 6a, 7a, 8a, ka, qa, va + +
2c +- C compilers +
0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc + +
2l +- loaders +
0l, 1l, 2l, 5l, 6l, 7l, 8l, kl, ql, vl + +
abaco +- browse the World-Wide Web +
abaco, readweb + +
acid +- debugger +
acid, truss, trump + +
acme +- interactive text windows +
acme, win, awd + +
ar +- archive and library maintainer +
ar + +
ascii +- interpret ASCII, Unicode characters +
ascii, unicode + +
awk +- pattern-directed scanning and processing language +
awk + +
basename +- strip file name affixes +
basename + +
bc +- arbitrary-precision arithmetic language +
bc + +
bind +- change name space +
bind, mount, unmount + +
bitsyload +- bitsy-specific utilities +
bitsyload, light, pencal, keyboard, params, prompter + +
bundle +- collect files for distribution +
bundle + +
cal +- print calendar +
cal + +
calendar +- print upcoming events +
calendar + +
cat +- catenate files +
cat, read + +
cb +- C program beautifier +
cb + +
chgrp +- change file group +
chgrp + +
chmod +- change mode +
chmod + +
cleanname +- clean a path name +
cleanname + +
cmp +- compare two files +
cmp + +
col +- column alignment +
col + +
colors +- display color map +
getmap, colors + +
comm +- select or reject lines common to two sorted files +
comm + +
con +- remote login, execution, and XMODEM file transfer +
con, telnet, rx, hayes, xms, xmr + +
cp +- copy, move files +
cp, fcp, mv + +
cpp +- C language preprocessor +
cpp + +
cpu +- connection to CPU server +
cpu + +
crop +- frame, crop, and convert image +
crop, iconv + +
date +- date and time +
date, clock + +
db +- debugger +
db + +
dc +- desk calculator +
dc + +
dd +- convert and copy a file +
dd + +
delkey +- delete keys from factotum +
delkey + +
deroff +- remove formatting requests +
deroff, delatex + +
diff +- differential file comparator +
diff + +
doc2txt +- extract printable text from Microsoft documents +
doc2txt, doc2ps, wdoc2txt, xls2txt, olefs, mswordstrings, msexceltables + +
doctype +- intuit command line for formatting a document +
doctype + +
du +- disk usage +
du + +
echo +- print arguments +
echo + +
ecp +- fast copy, handling errors +
ecp + +
ed +- text editor +
ed + +
emacs +- editor macros +
emacs + +
eqn +- typeset mathematics +
eqn + +
expect +- dialer scripting tools +
at, drain, expect, pass + +
faces +- mailbox interface +
faces, seemail, vwhois + +
factor +- factor a number, generate large primes +
factor, primes + +
fedex +- track shipments +
fedex, ups, usps + +
file +- determine file type +
file + +
filter +- filtering mail +
filter, list, deliver, token, vf + +
fmt +- simple text formatters +
fmt, htmlfmt + +
fortune +- sample lines from a file +
fortune + +
freq +- print histogram of character frequencies +
freq + +
grap +- pic preprocessor for drawing graphs +
grap + +
graph +- draw a graph +
graph + +
grep +- search a file for a pattern +
grep + +
gs +- Aladdin Ghostscript (PostScript and PDF language interpreter) +
gs + +
gview +- interactive graph viewer +
gview + +
gzip +- compress and expand data +
gzip, gunzip, bzip2, bunzip2, compress, uncompress, zip, unzip + +
hget +- retrieve a web page corresponding to a url +
hget + +
history +- print file names from the dump +
history + +
hoc +- interactive floating point language +
hoc + +
htmlroff +- HTML formatting and typesetting +
htmlroff + +
idiff +- interactive diff +
idiff + +
join +- relational database operator +
join + +
jpg +- view and convert pictures +
jpg, gif, png, ppm, bmp, v210, yuv, ico, togif, toppm, topng, toico + +
kbmap +- show a list of available keyboard maps and switch between them. +
kbmap + +
kill +- print commands to kill processes +
kill, slay, broke + +
ktrace +- interpret kernel stack dumps +
ktrace + +
leak +- help find memory leaks +
leak, kmem, umem + +
lens +- interactive screen magnifier +
lens + +
lex +- generator of lexical analysis programs +
lex + +
lock +- run a command under lock +
lock + +
look +- find lines in a sorted list +
look + +
lp +- printer output +
lp + +
ls +- list contents of directory +
ls, lc + +
mail +- mail and mailboxes +
mail, go.fishing + +
man +- print or find pages of this manual +
man, lookman, sig + +
marshal +- formatting and sending mail +
marshal + +
mc +- multicolumn print +
mc + +
mk +- maintain (make) related files +
mk, membername + +
mkdir +- make a directory +
mkdir + +
mlmgr +- unmoderated mailing lists +
ml, mlmgr, mlowner + +
mp3dec +- decode audio MPEG files (layers 1, 2 and 3) +
mp3dec + +
mp3enc +- create mp3 audio files +
mp3enc + +
ms2html +- convert between troff's ms macros and html +
ms2html, html2ms + +
mtime +- print file modification time +
mtime + +
mug +- convert an image to a face icon +
mug + +
nedmail +- reading mail +
nedmail + +
netstat +- summarize network connections +
netstat + +
news +- print news items +
news + +
nm +- name list (symbol table) +
nm + +
ns +- display name space +
ns + +
p +- paginate +
p + +
page +- view FAX, image, graphic, PostScript, PDF, and typesetter output files +
page + +
passwd +- change or verify user password +
passwd, netkey + +
patch +- simple patch creation and tracking system +
patch + +
pcc +- APE C compiler driver +
pcc + +
pic +- troff and tex preprocessors for drawing pictures +
pic, tpic + +
pipefile +- attach filter to file in name space +
pipefile + +
plot +- graphics filter +
plot + +
plumb +- send message to plumber +
plumb + +
pr +- print file +
pr + +
prof +- display profiling data +
prof, tprof, kprof + +
proof +- troff output interpreter +
proof + +
ps +- process status +
ps, psu + +
ps2pdf +- convert between PostScript and PDF +
ps2pdf, pdf2ps + +
pump +- copy asynchronously via a large circular buffer +
pump + +
pwd +- working directory +
pwd, pbd + +
rc +- command language +
rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ + +
replica +- client-server replica management +
changes, pull, push, scan + +
resample +- resample a picture +
resample + +
rio +- window system +
rio, label, window, wloc + +
rm +- remove files +
rm + +
rwd +- maintain remote working directory +
rwd, conswdir + +
sam +- screen editor with structural regular expressions +
sam, B, sam.save, samterm + +
secstore +- secstore commands +
aescbc, ipso, secstore + +
sed +- stream editor +
sed + +
seq +- print sequences of numbers +
seq + +
size +- print size of executable files +
size + +
sleep +- suspend execution for an interval +
sleep + +
sort +- sort and/or merge files +
sort + +
spell +- find spelling errors +
spell, sprog + +
spin +- verification tool for models of concurrent systems +
spin + +
split +- split a file into pieces +
split + +
src +- find source code for executable +
src + +
ssh +- secure login and file copy from/to Unix or Plan 9 +
ssh, sshnet, scp, sshserve + +
stop +- print commands to stop and start processes +
stop, start + +
strings +- extract printable strings +
strings + +
strip +- remove symbols from binary files +
strip + +
sum +- sum and count blocks in a file +
sum, md5sum, sha1sum + +
syscall +- test a system call +
syscall + +
tail +- deliver the last part of a file +
tail + +
tar +- archiver +
tar, dircp + +
tbl +- format tables for nroff or troff +
tbl + +
tcs +- translate character sets +
tcs + +
tee +- pipe fitting +
tee + +
tel +- look in phone book +
tel, iwhois + +
test +- set status according to condition +
test + +
thesaurus +- search online thesaurus +
thesaurus + +
time +- time a command +
time + +
touch +- set modification date of a file +
touch + +
tr +- translate characters +
tr + +
trace +- show (real-time) process behavior +
trace + +
troff +- text formatting and typesetting +
troff, nroff, dpost + +
troff2html +- convert troff output into HTML +
troff2html + +
tweak +- edit image files, subfont files, face files, etc. +
tweak + +
uniq +- report repeated lines in a file +
uniq + +
units +- conversion program +
units + +
uptime +- show how long the system has been running +
uptime + +
vac +- create, extract a vac archive on Venti +
vac, unvac + +
venti +- simple Venti clients +
read, write, copy + +
vi +- instruction simulators +
5i, ki, vi, qi + +
vnc +- remote frame buffer server and viewer for Virtual Network Computing (VNC) +
vncs, vncv + +
vt +- emulate a VT-100 or VT-220 terminal +
vt + +
wc +- word count +
wc + +
weather +- print weather report +
weather + +
who +- who is using the machine +
who, whois + +
winwatch +- monitor rio windows +
winwatch + +
xd +- hex, octal, decimal, or ASCII dump +
xd + +
yacc +- yet another compiler-compiler +
yacc + +
yesterday +- print file names from the dump +
yesterday, diffy + +
diff --git a/sys/man/1/abaco b/sys/man/1/abaco new file mode 100755 index 000000000..9a0182f21 --- /dev/null +++ b/sys/man/1/abaco @@ -0,0 +1,75 @@ +.TH ABACO 1 +.SH NAME +abaco, readweb \- browse the World-Wide Web +.SH SYNOPSIS +.B abaco +[ +.B -p +] [ +.B -c +.I ncols +] [ +.B -m +.I mtpt +] [ +.B -t +.I charset +] [ +.I url +] +.PP +.B readweb +[ +.I url +] +.SH DESCRIPTION +.I Abaco +is a lightweight web browser with the appearance of +.IR acme (1) +with +.I ncols +columns (one by default). +Given a +.IR url , +it will start by displaying that page. +Clicking mouse button 3 on a link +opens it in a new +.I abaco +window. +.B -t +selects an alternate character set; +.B -m +an alternate mount point for +.IR webfs . +Normally the standard error of subshells is closed, +but +.B -p +prevents this. +.PP +.I Readweb +imports the outside network, if necessary, +starts +.I webfs +and +.I webcookies +and finally +.IR abaco . +.\" .SH EXAMPLES +.SH FILES +.TP 15 +.B /mnt/web +default +.I webfs +mount point +.SH SOURCE +.B /sys/src/cmd/abaco +.br +.B /rc/bin/readweb +.SH SEE ALSO +.IR vnc (1), +.IR webcookies (4), +.IR webfs (4), +.SH BUGS +.I Abaco +is a work in progress; +many features of giant web browsers are absent. diff --git a/sys/man/1/acid b/sys/man/1/acid new file mode 100755 index 000000000..bfe671e54 --- /dev/null +++ b/sys/man/1/acid @@ -0,0 +1,492 @@ +.TH ACID 1 +.SH NAME +acid, truss, trump \- debugger +.SH SYNOPSIS +.B acid +[ +.B -kqw +] +[ +.BI -l " library +] [ +.B -m +.I machine +] [ +.I pid +] +[ +.I textfile +] +.PP +.B acid +.B -l +.B truss +.I textfile +.PP +.B acid +.B -l +.B trump +[ +.I pid +] +[ +.I textfile +] +.SH DESCRIPTION +.I Acid +is a programmable symbolic debugger. +It can inspect one or more processes that share an address space. +A program to be debugged may be specified by the process id of +a running or defunct process, +or by the name of the program's text file +.RB ( 8.out +by default). +At the prompt, +.I acid +will store function definitions or print the value of expressions. +Options are +.TP .9i +.B -w +Allow the textfile to be modified. +.TP +.B -q +Print variable renamings at startup. +.TP +.BI -l " library +Load from +.I library +at startup; see below. +.TP +.BI -m " machine +Assume instructions are for the given CPU type +(one of +.BR alpha , +.BR 386 , +etc., as listed in +.IR 2c (1), +or +.B sunsparc +or +.B mipsco +for the manufacturer-defined instruction notation for those processors) +instead of using the magic number to select +the CPU type. +.TP +.BI -k +Debug the kernel state for the process, rather than the user state. +.PP +At startup, +.I acid +obtains standard function definitions from the library file +.BR /sys/lib/acid/port , +architecture-dependent functions from +.BR /sys/lib/acid/$objtype , +user-specified functions from +.BR $home/lib/acid , +and further functions from +.B -l +files. +Definitions in any file may override previously defined functions. +If the function +.IR acidinit () +is defined, it will be invoked after all libraries have been loaded. +See +.IR 2c (1) +for information about creating +.I acid +functions for examining data structures. +.SS Language +Symbols of the program being debugged become integer +variables whose values are addresses. +Contents of addresses are obtained by indirection. +Local variables are qualified by +function name, for example +.BR main:argv . +When program symbols conflict with +.I acid +words, distinguishing +.B $ +signs are prefixed. +Such renamings are reported at startup if the option +.B -q +is enabled. +.PP +Variable types +.RI ( "integer, float, list, string" ) +and formats are inferred from assignments. +Truth values false/true are attributed to zero/nonzero +integers or floats and to empty/nonempty lists or strings. +Lists are sequences of expressions surrounded by +.BR {\^} +and separated by commas. +.PP +Expressions are much as in C, +but yield both a value and a format. +Casts to complex types are allowed. +Lists admit the following operators, with +subscripts counted from 0. +.IP +.BI head " list +.br +.BI tail " list +.br +.BI append " list", " element +.br +.BI delete " list", " subscript +.PP +Format codes are the same as in +.IR db (1). +Formats may be attached to (unary) expressions with +.BR \e , +e.g. +.BR (32*7)\eD . +There are two indirection operators, +.B * +to address a core image, +.B @ +to address a text file. +The type and format of the result are determined by the format of the operand, +whose type must be integer. +.PP +Statements are +.IP +.BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR] +.br +.BI while " expr " do " statement +.br +.BI loop " expr" , " expr " do " statement +.br +.BI defn " name" ( args ") {" " statement \fP} +.br +.BI defn " name" +.br +.IB name ( args ) +.br +.BI builtin " name" ( args ) +.br +.BI local " name +.br +.BI return " expr +.br +.BR whatis " [ \fI name \fP] +.PP +The statement +.B defn +.I name +clears the definition for +.IR name . +A +.B defn +may override a built-in function; +prefixing a function call with +.B builtin +ignores any overriding +.BR defn , +forcing the use of the built-in function. +.PP +Here is a partial list of functions; see the manual for a complete list. +.TF asm(address) +.TP +.B stk() +Print a stack trace for current process. +.TP +.B lstk() +Print a stack trace with values of local variables. +.TP +.B gpr() +Print general registers. +Registers can also be accessed by name, for example +.BR *R0 . +.TP +.B spr() +Print special registers such as program counter and stack pointer. +.TP +.B fpr() +Print floating-point registers. +.TP +.B regs() +Same as +.BR spr();gpr() . +.TP +.BI fmt( expr , format ) +Expression +.I expr +with format given by the character value of expression +.IR format . +.TP +.BI src( address ) +Print 10 lines of source around the program address. +.TP +.BI Bsrc( address ) +Get the source line for the program address +into a window of a running +.IR sam (1) +and select it. +.TP +.BI line( address ) +Print source line nearest to the program address. +.TP +.B source() +List current source directories. +.TP +.BI addsrcdir( string ) +Add a source directory to the list. +.TP +.BI filepc( where ) +Convert a string of the form +.IB sourcefile : linenumber +to a machine address. +.TP +.BI pcfile( address ) +Convert a machine address to a source file name. +.TP +.BI pcline( address ) +Convert a machine address to a source line number. +.TP +.BI bptab() +List breakpoints set in the current process. +.TP +.BI bpset( address ) +Set a breakpoint in the current process at the given address. +.TP +.BI bpdel( address ) +Delete a breakpoint from the current process. +.TP +.B cont() +Continue execution of current process and wait for it to stop. +.TP +.B step() +Execute a single machine instruction in the current process. +.TP +.B func() +Step repeatedly until after a function return. +.TP +.BI stopped( pid ) +This replaceable function is called automatically when the given process +stops. +It normally prints the program counter and returns to the prompt. +.TP +.BI asm( address ) +Disassemble 30 machine instructions beginning at the given address. +.TP +.BI mem( address , string ) +Print a block of memory +interpreted according to a string of format codes. +.TP +.BI dump( address , n , string\fP) +Like +.BR mem (), +repeated for +.I n +consecutive blocks. +.TP +.BI print( expr , ... ) +Print the values of the expressions. +.TP +.BI newproc( arguments ) +Start a new process with arguments given as a string +and halt at the first instruction. +.TP +.B new() +Like +.IR newproc (), +but take arguments (except +.BR argv[0] ) +from string variable +.BR progargs . +.TP +.B win() +Like +.IR new (), +but run the process in a separate window. +.TP +.BI start( pid ) +Start a stopped process. +.TP +.BI kill( pid ) +Kill the given process. +.TP +.BI setproc( pid ) +Make the given process current. +.TP +.BI rc( string ) +Escape to the shell, +.IR rc (1), +to execute the command string. +.SS Libraries +There are a number of +.I acid +`libraries' that provide higher-level debugging facilities. Two notable +examples are +.I truss +and +.IR trump , +which use +.I acid +to trace system calls +.RI ( truss ) +and memory allocation +.RI ( trump ). +Both require starting +.I acid +on the program, either by attaching to a running process or by +executing +.B new() +on a binary (perhaps after setting +.BR progargs ), +stopping the process, and then running +.B truss() +or +.B trump() +to execute the program under the scaffolding. +The output will be a trace of the system calls +.RI ( truss ) +or memory allocation and free calls +.RI ( trump ) +executed by the program. +When finished tracing, stop the process and execute +.B untruss() +or +.B untrump() +followed by +.B cont() +to resume execution. +.SH EXAMPLES +Start to debug +.BR /bin/ls ; +set some breakpoints; run up to the first one: +.IP +.EX +% acid /bin/ls +/bin/ls: mips plan 9 executable +/sys/lib/acid/port +/sys/lib/acid/mips +acid: new() +70094: system call _main ADD $-0x14,R29 +70094: breakpoint main+0x4 MOVW R31,0x0(R29) +acid: pid +70094 +acid: argv0 = **main:argv\es +acid: whatis argv0 +integer variable format s +acid: *argv0 +/bin/ls +acid: bpset(ls) +acid: cont() +70094: breakpoint ls ADD $-0x16c8,R29 +acid: +.EE +.PP +Display elements of a linked list of structures: +.IP +.EX +complex Str { 'D' 0 val; 'X' 4 next; }; +complex Str s; +s = *headstr; +while s != 0 do{ + print(s.val, "\en"); + s = s.next; +} +.EE +.PP +Note the use of the +.B . +operator instead of +.BR -> . +.PP +Display an array of bytes declared in C as +.BR "char array[]" . +.IP +.EX +*(array\es) +.EE +.PP +This example gives +.B array +string format, then prints the string beginning at the address (in +.I acid +notation) +.BR *array . +.PP +Trace the system calls executed by +.IR ls (1): +.IP +.EX +% acid -l truss /bin/ls +/bin/ls:386 plan 9 executable + +/sys/lib/acid/port +/sys/lib/acid/kernel +/sys/lib/acid/truss +/sys/lib/acid/386 +acid: progargs = "-l lib/profile" +acid: new() +acid: truss() +open("#c/pid", 0) + return value: 3 +pread(3, 0x7fffeeac, 20, -1) + return value: 12 + data: " 166 " +\&... +stat("lib/profile", 0x0000f8cc, 113) + return value: 65 +open("/env/timezone", 0) + return value: 3 +pread(3, 0x7fffd7c4, 1680, -1) + return value: 1518 + data: "EST -18000 EDT -14400 + 9943200 25664400 41392800 57718800 73447200 89168400 + 104896800 ..." +close(3) + return value: 0 +pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile +", 54, -1) +--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile + return value: 54 +\&... +166: breakpoint _exits+0x5 INTB $0x40 +acid: cont() +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.br +.B /sys/lib/acid/$objtype +.br +.B /sys/lib/acid/port +.br +.B /sys/lib/acid/kernel +.br +.B /sys/lib/acid/trump +.br +.B /sys/lib/acid/truss +.br +.B $home/lib/acid +.SH SOURCE +.B /sys/src/cmd/acid +.SH "SEE ALSO" +.IR 2a (1), +.IR 2c (1), +.IR 2l (1), +.IR mk (1), +.IR db (1) +.br +Phil Winterbottom, +``Acid Manual''. +.SH DIAGNOSTICS +At termination, kill commands are proposed +for processes that are still active. +.SH BUGS +There is no way to redirect the standard input and standard output +of a new process. +.br +Source line selection near the beginning of a file may pick +an adjacent file. +.br +With the extant stepping commands, one cannot step through instructions +outside the text segment and it is hard to debug across process forks. diff --git a/sys/man/1/acme b/sys/man/1/acme new file mode 100755 index 000000000..f01ee38fd --- /dev/null +++ b/sys/man/1/acme @@ -0,0 +1,727 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -ab +] +[ +.B -c +.I ncol +] +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -l +.I loadfile +| +.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 loadfile , +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 . +.PP +When a window is in autoindent mode +(see the +.B Indent +command below) and a newline character is typed, +acme copies leading white space on the current line to the new line. +The option +.B -a +causes each window to start in +autoindent mode. +.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 Indent +Set the autoindent mode according to the argument: +.B on +and +.B off +set the mode for the current window; +.B ON +and +.B OFF +set the mode for all existing and future windows. +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.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 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 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. +.TP +.B <|> +If a regular shell command is preceded by a +.BR < , +.BR | , +or +.B > +character, the selected text in the body of the window is affected by the +I/O from the command. +The +.B < +character causes the selection to be replaced by the standard output +of the command; +.B > +causes the selection to be sent as standard input to the command; and +.B | +does both at once, `piping' the selection through the command and +replacing it with the output. +.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, +and +.B $winid +set to the window's id number +(see +.IR acme (4)). +.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 beginning 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/sys/man/1/ap b/sys/man/1/ap new file mode 100755 index 000000000..1b717f35f --- /dev/null +++ b/sys/man/1/ap @@ -0,0 +1,16 @@ +.TH AP 1 +.SH NAME +ap \- fetch Associated Press news articles +.SH SYNOPSIS +.B ap +[ +.BI article-name +] +.SH DESCRIPTION +.I ap +fetches Associated Press news articles from http://www.newsday.com. +Without any arguments it provides a two column list of article keys and descriptions. +When invoked with an article key it fetches that article. +.PP +.SH SOURCE +.B /rc/bin/ap diff --git a/sys/man/1/ar b/sys/man/1/ar new file mode 100755 index 000000000..4e2e91b48 --- /dev/null +++ b/sys/man/1/ar @@ -0,0 +1,182 @@ +.TH AR 1 +.SH NAME +ar \- archive and library maintainer +.SH SYNOPSIS +.B ar +.I key +[ +.I posname +] +.I afile +[ +.I file ... +] +.SH DESCRIPTION +.I Ar +maintains groups of files +combined into a single archive file, +.IR afile . +The main use of +.I ar +is to create and update library files for the loaders +.IR 2l (1), +etc. +It can be used, though, for any similar purpose. +.PP +.I Key +is one character from the set +.BR drqtpmx , +optionally concatenated with +one or more of +.BR vuaibclo . +The +.I files +are constituents of the archive +.IR afile . +The meanings of the +.I key +characters are: +.TP +.B d +Delete +.I files +from the archive file. +.TP +.B r +Replace +.I files +in the archive file, or add them if missing. +Optional modifiers are +.RS +.PD0 +.TP +.B u +Replace only files with +modified dates later than that of +the archive. +.TP +.B a +Place new files after +.I posname +in the archive rather than at the end. +.TP +.BR b " or " i +Place new files before +.I posname +in the archive. +.RE +.PD +.TP +.B q +Quick. Append +.I files +to the end of the archive without checking for duplicates. +Avoids quadratic behavior in +.LR "for (i in *.v) ar r lib.a $i" . +.TP +.B t +List a table of contents of the archive. +If names are given, only those files are listed. +.TP +.B p +Print the named files in the archive. +.TP +.B m +Move the named files to the end or elsewhere, +specified as with +.LR r . +.TP +.B o +Preserve the access and modification times of files +extracted with the +.B x +command. +.TP +.B x +Extract the named files. +If no names are given, all files in the archive are +extracted. +In neither case does +.B x +alter the archive file. +.TP +.B v +Verbose. +Give a file-by-file +description of the making of a +new archive file from the old archive and the constituent files. +With +.BR p , +precede each file with a name. +With +.BR t , +give a long listing of all information about the files, +somewhat like a listing by +.IR ls (1), +showing +.br +.ns +.IP +.B + mode uid/gid size date name +.\" .TP +.\" .B c +.\" Create. +.\" Normally +.\" .I ar +.\" will create a new archive when +.\" .I afile +.\" does not exist, and give a warning. +.\" Option +.\" .B c +.\" discards any old contents and suppresses the warning. +.TP +.B l +Local. +Normally +.I ar +places its temporary files in the directory +.BR /tmp . +This option causes them to be placed in the local directory. +.PP +When a +.BR d , +.BR r , +or +.BR m +.I key +is specified and all members of the archive are valid object files for +the same architecture, +.I ar +inserts a table of contents, required by the loaders, at +the front of the library. +The table of contents is +rebuilt whenever the archive is modified, except +when the +.B q +.I key +is specified or when the table of contents is +explicitly moved or deleted. +.SH EXAMPLE +.TP +.L +ar cr lib.a *.v +Replace the contents of library +.L lib.a +with the object files in the current directory. +.SH FILES +.TF /tmp/vxxxx +.TP +.B /tmp/v* +temporaries +.SH SOURCE +.B /sys/src/cmd/ar.c +.SH "SEE ALSO" +.IR 2l (1), +.IR ar (6) +.SH BUGS +If the same file is mentioned twice in an argument list, +it may be put in the archive twice. +.br +This command predates Plan 9 and makes some invalid assumptions, +for instance that user id's are numeric. diff --git a/sys/man/1/ascii b/sys/man/1/ascii new file mode 100755 index 000000000..de5cd77cf --- /dev/null +++ b/sys/man/1/ascii @@ -0,0 +1,158 @@ +.TH ASCII 1 +.SH NAME +ascii, unicode \- interpret ASCII, Unicode characters +.SH SYNOPSIS +.B ascii +[ +.B -8cnt +] +[ +.B -dox +| +.B -b +.I n +] +[ +.I text +] +.PP +.B unicode +.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 \fL/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/sys/man/1/awk b/sys/man/1/awk new file mode 100755 index 000000000..d79b963c4 --- /dev/null +++ b/sys/man/1/awk @@ -0,0 +1,560 @@ +.TH AWK 1 +.SH NAME +awk \- pattern-directed scanning and processing language +.SH SYNOPSIS +.B awk +[ +.B -F +.I fs +] +[ +.B -d +] +[ +.BI -mf +.I n +] +[ +.B -mr +.I n +] +[ +.B -safe +] +[ +.B -v +.I var=value +] +[ +.B -f +.I progfile +| +.I prog +] +[ +.I file ... +] +.SH DESCRIPTION +.I Awk +scans each input +.I file +for lines that match any of a set of patterns specified literally in +.I prog +or in one or more files +specified as +.B -f +.IR progfile . +With each pattern +there can be an associated action that will be performed +when a line of a +.I file +matches the pattern. +Each line is matched against the +pattern portion of every pattern-action statement; +the associated action is performed for each matched pattern. +The file name +.L - +means the standard input. +Any +.IR file +of the form +.I var=value +is treated as an assignment, not a file name, +and is executed at the time it would have been opened if it were a file name. +The option +.B -v +followed by +.I var=value +is an assignment to be done before the program +is executed; +any number of +.B -v +options may be present. +.B -F +.IR fs +option defines the input field separator to be the regular expression +.IR fs . +.PP +An input line is normally made up of fields separated by white space, +or by regular expression +.BR FS . +The fields are denoted +.BR $1 , +.BR $2 , +\&..., while +.B $0 +refers to the entire line. +If +.BR FS +is null, the input line is split into one field per character. +.PP +To compensate for inadequate implementation of storage management, +the +.B -mr +option can be used to set the maximum size of the input record, +and the +.B -mf +option to set the maximum number of fields. +.PP +The +.B -safe +option causes +.I awk +to run in +``safe mode,'' +in which it is not allowed to +run shell commands or open files +and the environment is not made available +in the +.B ENVIRON +variable. +.PP +A pattern-action statement has the form +.IP +.IB pattern " { " action " } +.PP +A missing +.BI { " action " } +means print the line; +a missing pattern always matches. +Pattern-action statements are separated by newlines or semicolons. +.PP +An action is a sequence of statements. +A statement can be one of the following: +.PP +.EX +.ta \w'\fLdelete array[expression]'u +if(\fI expression \fP)\fI statement \fP\fR[ \fPelse\fI statement \fP\fR]\fP +while(\fI expression \fP)\fI statement\fP +for(\fI expression \fP;\fI expression \fP;\fI expression \fP)\fI statement\fP +for(\fI var \fPin\fI array \fP)\fI statement\fP +do\fI statement \fPwhile(\fI expression \fP) +break +continue +{\fR [\fP\fI statement ... \fP\fR] \fP} +\fIexpression\fP #\fR commonly\fP\fI var = expression\fP +print\fR [ \fP\fIexpression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +printf\fI format \fP\fR[ \fP,\fI expression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +return\fR [ \fP\fIexpression \fP\fR]\fP +next #\fR skip remaining patterns on this input line\fP +nextfile #\fR skip rest of this file, open next, start at top\fP +delete\fI array\fP[\fI expression \fP] #\fR delete an array element\fP +delete\fI array\fP #\fR delete all elements of array\fP +exit\fR [ \fP\fIexpression \fP\fR]\fP #\fR exit immediately; status is \fP\fIexpression\fP +.EE +.DT +.PP +Statements are terminated by +semicolons, newlines or right braces. +An empty +.I expression-list +stands for +.BR $0 . +String constants are quoted \&\fL"\ "\fR, +with the usual C escapes recognized within. +Expressions take on string or numeric values as appropriate, +and are built using the operators +.B + \- * / % ^ +(exponentiation), and concatenation (indicated by white space). +The operators +.B +! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?: +are also available in expressions. +Variables may be scalars, array elements +(denoted +.IB x [ i ] ) +or fields. +Variables are initialized to the null string. +Array subscripts may be any string, +not necessarily numeric; +this allows for a form of associative memory. +Multiple subscripts such as +.B [i,j,k] +are permitted; the constituents are concatenated, +separated by the value of +.BR SUBSEP . +.PP +The +.B print +statement prints its arguments on the standard output +(or on a file if +.BI > file +or +.BI >> file +is present or on a pipe if +.BI | cmd +is present), separated by the current output field separator, +and terminated by the output record separator. +.I file +and +.I cmd +may be literal names or parenthesized expressions; +identical string values in different statements denote +the same open file. +The +.B printf +statement formats its expression list according to the format +(see +.IR fprintf (2)) . +The built-in function +.BI close( expr ) +closes the file or pipe +.IR expr . +The built-in function +.BI fflush( expr ) +flushes any buffered output for the file or pipe +.IR expr . +If +.IR expr +is omitted or is a null string, all open files are flushed. +.PP +The mathematical functions +.BR exp , +.BR log , +.BR sqrt , +.BR sin , +.BR cos , +and +.BR atan2 +are built in. +Other built-in functions: +.TF length +.TP +.B length +If its argument is a string, the string's length is returned. +If its argument is an array, the number of subscripts in the array is returned. +If no argument, the length of +.B $0 +is returned. +.TP +.B rand +random number on (0,1) +.TP +.B srand +sets seed for +.B rand +and returns the previous seed. +.TP +.B int +truncates to an integer value +.TP +.B utf +converts its numerical argument, a character number, to a +.SM UTF +string +.TP +.BI substr( s , " m" , " n\fL) +the +.IR n -character +substring of +.I s +that begins at position +.IR m +counted from 1. +.TP +.BI index( s , " t" ) +the position in +.I s +where the string +.I t +occurs, or 0 if it does not. +.TP +.BI match( s , " r" ) +the position in +.I s +where the regular expression +.I r +occurs, or 0 if it does not. +The variables +.B RSTART +and +.B RLENGTH +are set to the position and length of the matched string. +.TP +.BI split( s , " a" , " fs\fL) +splits the string +.I s +into array elements +.IB a [1]\f1, +.IB a [2]\f1, +\&..., +.IB a [ n ]\f1, +and returns +.IR n . +The separation is done with the regular expression +.I fs +or with the field separator +.B FS +if +.I fs +is not given. +An empty string as field separator splits the string +into one array element per character. +.TP +.BI sub( r , " t" , " s\fL) +substitutes +.I t +for the first occurrence of the regular expression +.I r +in the string +.IR s . +If +.I s +is not given, +.B $0 +is used. +.TP +.B gsub +same as +.B sub +except that all occurrences of the regular expression +are replaced; +.B sub +and +.B gsub +return the number of replacements. +.TP +.BI sprintf( fmt , " expr" , " ...\fL) +the string resulting from formatting +.I expr ... +according to the +.I printf +format +.I fmt +.TP +.BI system( cmd ) +executes +.I cmd +and returns its exit status +.TP +.BI tolower( str ) +returns a copy of +.I str +with all upper-case characters translated to their +corresponding lower-case equivalents. +.TP +.BI toupper( str ) +returns a copy of +.I str +with all lower-case characters translated to their +corresponding upper-case equivalents. +.PD +.PP +The ``function'' +.B getline +sets +.B $0 +to the next input record from the current input file; +.B getline +.BI < file +sets +.B $0 +to the next record from +.IR file . +.B getline +.I x +sets variable +.I x +instead. +Finally, +.IB cmd " | getline +pipes the output of +.I cmd +into +.BR getline ; +each call of +.B getline +returns the next line of output from +.IR cmd . +In all cases, +.B getline +returns 1 for a successful input, +0 for end of file, and \-1 for an error. +.PP +Patterns are arbitrary Boolean combinations +(with +.BR "! || &&" ) +of regular expressions and +relational expressions. +Regular expressions are as in +.IR regexp (6). +Isolated regular expressions +in a pattern apply to the entire line. +Regular expressions may also occur in +relational expressions, using the operators +.BR ~ +and +.BR !~ . +.BI / re / +is a constant regular expression; +any string (constant or variable) may be used +as a regular expression, except in the position of an isolated regular expression +in a pattern. +.PP +A pattern may consist of two patterns separated by a comma; +in this case, the action is performed for all lines +from an occurrence of the first pattern +though an occurrence of the second. +.PP +A relational expression is one of the following: +.IP +.I expression matchop regular-expression +.br +.I expression relop expression +.br +.IB expression " in " array-name +.br +.BI ( expr , expr,... ") in " array-name +.PP +where a +.I relop +is any of the six relational operators in C, +and a +.I matchop +is either +.B ~ +(matches) +or +.B !~ +(does not match). +A conditional is an arithmetic expression, +a relational expression, +or a Boolean combination +of these. +.PP +The special patterns +.B BEGIN +and +.B END +may be used to capture control before the first input line is read +and after the last. +.B BEGIN +and +.B END +do not combine with other patterns. +.PP +Variable names with special meanings: +.TF FILENAME +.TP +.B CONVFMT +conversion format used when converting numbers +(default +.BR "%.6g" ) +.TP +.B FS +regular expression used to separate fields; also settable +by option +.BI \-F fs\f1. +.TP +.BR NF +number of fields in the current record +.TP +.B NR +ordinal number of the current record +.TP +.B FNR +ordinal number of the current record in the current file +.TP +.B FILENAME +the name of the current input file +.TP +.B RS +input record separator (default newline) +.TP +.B OFS +output field separator (default blank) +.TP +.B ORS +output record separator (default newline) +.TP +.B OFMT +output format for numbers (default +.BR "%.6g" ) +.TP +.B SUBSEP +separates multiple subscripts (default 034) +.TP +.B ARGC +argument count, assignable +.TP +.B ARGV +argument array, assignable; +non-null members are taken as file names +.TP +.B ENVIRON +array of environment variables; subscripts are names. +.PD +.PP +Functions may be defined (at the position of a pattern-action statement) thus: +.IP +.L +function foo(a, b, c) { ...; return x } +.PP +Parameters are passed by value if scalar and by reference if array name; +functions may be called recursively. +Parameters are local to the function; all other variables are global. +Thus local variables may be created by providing excess parameters in +the function definition. +.SH EXAMPLES +.TP +.L +length($0) > 72 +Print lines longer than 72 characters. +.TP +.L +{ print $2, $1 } +Print first two fields in opposite order. +.PP +.EX +BEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 } +.EE +.ns +.IP +Same, with input fields separated by comma and/or blanks and tabs. +.PP +.EX + { s += $1 } +END { print "sum is", s, " average is", s/NR } +.EE +.ns +.IP +Add up first column, print sum and average. +.TP +.L +/start/, /stop/ +Print all lines between start/stop pairs. +.PP +.EX +BEGIN { # Simulate echo(1) + for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i] + printf "\en" + exit } +.EE +.SH SOURCE +.B /sys/src/cmd/awk +.SH SEE ALSO +.IR sed (1), +.IR regexp (6), +.br +A. V. Aho, B. W. Kernighan, P. J. Weinberger, +.I +The AWK Programming Language, +Addison-Wesley, 1988. ISBN 0-201-07981-X +.SH BUGS +There are no explicit conversions between numbers and strings. +To force an expression to be treated as a number add 0 to it; +to force it to be treated as a string concatenate +\&\fL""\fP to it. +.br +The scope rules for variables in functions are a botch; +the syntax is worse. +.br +UTF is not always dealt with correctly, +though +.I awk +does make an attempt to do so. +The +.I split +function with an empty string as final argument now copes +with UTF in the string being split. diff --git a/sys/man/1/basename b/sys/man/1/basename new file mode 100755 index 000000000..c72638f13 --- /dev/null +++ b/sys/man/1/basename @@ -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/sys/man/1/bc b/sys/man/1/bc new file mode 100755 index 000000000..87c2b1148 --- /dev/null +++ b/sys/man/1/bc @@ -0,0 +1,290 @@ +.TH BC 1 +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.B bc +[ +.B -cdls +] +[ +.I file ... +] +.SH DESCRIPTION +.I Bc +is an interactive processor for a language that resembles +C but provides arithmetic on numbers of arbitrary length with up +to 100 digits right of the decimal point. +It takes input from any files given, then reads +the standard input. +.PP +The +.B -d +option enables debugging output. +The +.B -l +option stands for the name +of an arbitrary precision math library. +The +.B -s +option suppresses the automatic display +of calculation results; all output is via the +.B print +command. +.PP +The following syntax for +.I bc +programs is like that of C; +.I L +means letter +.BR a - z , +.I E +means expression, +.I S +means statement. +.TF length(E) +.TP +Lexical +.RS +.HP +comments are enclosed in +.B /* */ +.HP +newlines end statements +.RE +.TP +Names +.IP +simple variables: +.I L +.br +array elements: +.IB L [ E ] +.br +The words +.BR ibase , +.BR obase , +and +.B scale +.TP +Other operands +.IP +arbitrarily long numbers with optional sign and decimal point. +.RS +.TP +.BI ( E ) +.TP +.BI sqrt( E ) +.TP +.BI length( E ) +number of significant decimal digits +.TP +.BI scale( E ) +number of digits right of decimal point +.TP +.IB L ( E , ... ,\fIE\fP) +function call +.RE +.TP +Operators +.RS +.HP +.B "+ - * / % ^\ " +.RB ( % +is remainder; +.B ^ +is power) +.HP +.B "++ --\ " +.TP +.B "== <= >= != < >" +.TP +.B "= += -= *= /= %= ^=" +.RE +.TP +Statements +.RS +.br +.I E +.br +.B { +.I S +.B ; +\&... +.B ; +.I S +.B } +.br +.B "print" +.I E +.br +.B "if (" +.I E +.B ) +.I S +.br +.B "while (" +.I E +.B ) +.I S +.br +.B "for (" +.I E +.B ; +.I E +.B ; +.I E +.B ")" +.I S +.br +null statement +.br +.B break +.br +.B quit +.br +\fL"\fRtext\fL"\fR +.RE +.TP +Function definitions +.RS +.br +.B define +.I L +.B ( +.I L +.B , +\&... +.B , +.I L +.B ){ +.PD0 +.br +.B auto +.I L +.B , +\&... +.B , +.I L +.br +.I S +.B ; +\&... +.B ; +.I S +.br +.B return +.I E +.LP +.B } +.RE +.TP +Functions in +.B -l +math library +.RS +.TP +.BI s( x ) +sine +.TP +.BI c( x ) +cosine +.TP +.BI e( x ) +exponential +.TP +.BI l( x ) +log +.TP +.BI a( x ) +arctangent +.TP +.BI j( "n, x" ) +Bessel function +.RE +.PP +.DT +All function arguments are passed by value. +.PD +.PP +The value of an expression at the top level is printed +unless the main operator is an assignment or the +.B -s +command line argument is given. +Text in quotes, which may include newlines, is always printed. +Either semicolons or newlines may separate statements. +Assignment to +.B scale +influences the number of digits to be retained on arithmetic +operations in the manner of +.IR dc (1). +Assignments to +.B ibase +or +.B obase +set the input and output number radix respectively. +.PP +The same letter may be used as an array, a function, +and a simple variable simultaneously. +All variables are global to the program. +Automatic variables are pushed down during function calls. +In a declaration of an array as a function argument +or automatic variable +empty square brackets must follow the array name. +.PP +.I Bc +is actually a preprocessor for +.IR dc (1), +which it invokes automatically, unless the +.B -c +(compile only) +option is present. +In this case the +.I dc +input is sent to the standard output instead. +.SH EXAMPLE +Define a function to compute an approximate value of +the exponential. +Use it to print 10 values. +(The exponential function in the library gives better answers.) +.PP +.EX +scale = 20 +define e(x) { + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for(i=1; 1; i++) { + a *= x + b *= i + c = a/b + if(c == 0) return s + s += c + } +} +for(i=1; i<=10; i++) print e(i) +.EE +.SH FILES +.B /sys/lib/bclib +mathematical library +.SH SOURCE +.B /sys/src/cmd/bc.y +.SH "SEE ALSO" +.IR dc (1), +.IR hoc (1) +.SH BUGS +No +.LR && , +.LR || , +or +.L ! +operators. +.PP +A +.L for +statement must have all three +.LR E s. +.PP +A +.L quit +is interpreted when read, not when executed. diff --git a/sys/man/1/bind b/sys/man/1/bind new file mode 100755 index 000000000..7994f7192 --- /dev/null +++ b/sys/man/1/bind @@ -0,0 +1,215 @@ +.TH BIND 1 +.SH NAME +bind, mount, unmount \- change name space +.SH SYNOPSIS +.B bind +[ +.I option ... +] +.I new old +.PP +.B mount +[ +.I option ... +] +.I servename old +[ +.I spec +] +.PP +.B unmount +[ +.I new +] +.I old +.SH DESCRIPTION +.I Bind +and +.I mount +modify the file name space of the current process +and other processes in the same name space group +(see +.IR fork (2)). +For both calls, +.I old +is the name of an existing file or directory in the +current name space where the modification is to be made. +.PP +For +.IR bind , +.I new +is the name of another (or possibly the same) +existing file or directory in +the current name space. +After a successful +.IR bind , +the file name +.I old +is an alias for the object originally named by +.IR new ; +if the modification doesn't hide it, +.I new +will also still refer to its original file. +The evaluation of +.I new +(see +.IR intro (2)) +happens at the time of the +.IR bind , +not when the binding is later used. +.PP +The +.I servename +argument to +.I mount +is the name of a file that, when opened, yields an +existing connection to a file server. +Almost always, +.I servename +will be a file in +.B /srv +(see +.IR srv (3)). +In the discussion below, +.I new +refers to the file named by the +.I new +argument to +.I bind +or the root directory of the service +available in +.I servename +after a +.IR mount . +Either both +.I old +and +.I new +files must be directories, +or both must not be directories. +.PP +Options control aspects of the modification to the name space: +.TP 10 +(none) +Replace the +.I old +file by the new one. +Henceforth, an evaluation of +.I old +will be translated to the new file. +If they are directories (for +.IR mount , +this condition is true by definition), +.I old +becomes a +.I "union directory" +consisting of one directory (the new file). +.TP +.B -b +Both files must be directories. +Add the new directory to the beginning +of the union directory represented by the old file. +.TP +.B -a +Both files must be directories. +Add the new directory to the end +of the union directory represented by the old file. +.TP +.B -c +This can be used in addition to any of the above to permit +creation in a union directory. +When a new file is created in a union directory, +it is placed in the first element of the union that has been bound or mounted with the +.B -c +flag. +If that directory does not have write permission, the create fails. +.TP +.B -C +(Only in +.IR mount .) +By default, file contents are always retrieved from the server. +With this option, the kernel may instead use a local cache to satisfy +.IR read (5) +requests for files accessible through this mount point. +The currency of cached data for a file is verified at each +.IR open (5) +of the file from this client machine. +.TP +.B -q +Exit silently if the +.B bind +or +.B mount +operation fails. +.PD +.PP +.I Mount +takes two additional options. +The first, +.B -k +.IR keypattern , +constrains the set of +.IR factotum (4) +keys used for an authenticated mount. +The second, +.BR -n , +causes +.I mount +to skip authentication entirely. +.PP +The +.I spec +argument to +.I mount +is passed in the +.IR attach (5) +message to the server, and selects among different +file trees served by the server. +.PP +The +.IR srv (3) +service registry device, normally bound to +.BR /srv , +is a convenient rendezvous point for services that can be mounted. +After bootstrap, the file +.B /srv/boot +contains the communications port to the file system from which +the system was loaded. +.PP +The effects of +.I bind +and +.I mount +can be undone with the +.I unmount +command. +If two arguments are given to +.IR unmount , +the effect is to undo a +.I bind +or +.I mount +with the same arguments. +If only one argument is given, +everything bound to or mounted upon +.I old +is unmounted. +.SH EXAMPLES +To compile a program with the C library from July 16, 1992: +.IP +.EX +mount /srv/boot /n/dump dump +bind /n/dump/1992/0716/mips/lib/libc.a /mips/lib/libc.a +mk +.EE +.SH SOURCE +.B /sys/src/cmd/bind.c +.br +.B /sys/src/cmd/mount.c +.br +.B /sys/src/cmd/unmount.c +.SH SEE ALSO +.IR bind (2), +.IR open (2), +.IR srv (3), +.IR srv (4) diff --git a/sys/man/1/bitsyload b/sys/man/1/bitsyload new file mode 100755 index 000000000..e9c464614 --- /dev/null +++ b/sys/man/1/bitsyload @@ -0,0 +1,146 @@ +.TH BITSYLOAD 1 +.SH NAME +bitsyload, light, pencal, keyboard, params, prompter \- bitsy-specific utilities +.SH SYNOPSIS +.PP +.B bitsy/bitsyload +.B k|r +[ +.I file +] +.PP +.B bitsy/light +[ +.I intensity +] +.PP +.B bitsy/params +[ +.B \-f +] +.PP +.B bitsy/pencal +.PP +.B bitsy/keyboard +[ +.B \-n +] +.PP +.B bitsy/prompter +[ +.B \-n +] +.I file +.SH DESCRIPTION +.PP +.I Bitsyload +erases a section of flash memory on the Bitsy (iPAQ 3650 or 3830) +and copies new +information into it, using the format required by the Compaq +boot loader. The required first argument is the destination, either +.B k +for +.B /dev/flash/kernel +or +.B r +for +.BR /dev/flash/ramdisk . +The optional second argument is the name of the file +to load. The default kernel file is +.B /sys/src/9/bitsy/9bitsy +and the default ramdisk file is +.BR /sys/src/9/bitsy/ramdisk . +.PP +.I Light +sets the intensity of the display backlight. +The +values for +.I intensity +are: +.IP on +set intensity to maximum, the default +.IP off +turn off backlight +.IP \fIn\fP +sets the intensity to +.IR n , +where +.I n +is a value between 0 and 128. Intensity 0 doesn't +turn off the backlight, it just sets it to the dimmest +value. +.PP +.I Pencal +calibrates the display with the touch screen on a Bitsy. +It loops prompting the user with crosses whose center that the user +must touch with the stylus. After a consistent set of touches, +it writes the calibration both to the kernel and to standard out. +It is normally called by the bitsy's +.BR /bin/cpurc . +.PP +.I Params +copies the contents of the file +.BR /dev/tmpparams , +into the flash partition, +.BR /dev/flash/params , +or if the +.B -f +flag it set copies in the opposite direction. +.PP +.I Keyboard +creates a virtual on-screen keyboard and, unless the +.B -n +option is specified, a scribble area. +A user inputs characters by tapping the keys or +by drawing characters in the +scribble area (see +.IR scribble (2)). +It is usually run as the keyboard command for +.IR rio (1) +using +.BR rio 's +.B -k +option. +.PP +.I Prompter +is a small editor used to configure parameters when a Bitsy boots. +It displays the file and starts up a keyboard and scribble pad for +input. +Clicking with the stylus in the text selects where input characters will go. +Pressing Button 5 (top left side of the Bitsy) or typing the +.B Esc +key on the keyboard causes +.I prompter +to write back the updated file and exit; +.B Del +causes +.I prompter +to exit without writing the file. +The +.B -n +flag suppresses the scribble area. +.SH EXAMPLE +.PP +.IR Prompter , +.IR params , +and +.I calibrate +are used in only one place, the Bitsy's +.BR /rc/bin/cpurc : +.sp +.EX +# set variables +ramfs +bitsy/params -f +if(! grep -s '^calibrate=' /tmp/tmpparams) + bitsy/pencal >>/tmp/tmpparams +if not { + eval `{grep '^calibrate=' /tmp/tmpparams} + echo calibrate $calibrate > '#m/mousectl' +} +bitsy/prompter /tmp/tmpparams +bitsy/params +. /tmp/tmpparams +.EE +.SH SOURCE +.B /sys/src/cmd/bitsy diff --git a/sys/man/1/bundle b/sys/man/1/bundle new file mode 100755 index 000000000..272d32530 --- /dev/null +++ b/sys/man/1/bundle @@ -0,0 +1,53 @@ +.TH BUNDLE 1 +.SH NAME +bundle \- collect files for distribution +.SH SYNOPSIS +.B bundle +.I file ... +.SH DESCRIPTION +.I Bundle +writes on its standard output a shell script for +.IR rc (1) +or a Bourne shell +which, when executed, +will recreate the original +.IR files . +Its main use is for distributing small numbers of text files by +.IR mail (1). +.PP +Although less refined than standard archives from +.IR ar (1) +or +.IR tar (1), +a +.IR bundle +file +is self-documenting and complete; little preparation is required on +the receiving machine. +.SH EXAMPLES +.TP +.L +bundle mkfile *.[ch] | mail kremvax!boris +Send a makefile to Boris together with related +.L .c +and +.L .h +files. +Upon receiving the mail, Boris may save the file sans postmark, +say in +.BR gift/horse , +then do +.TP +.L +cd gift; rc horse; mk +.SH SOURCE +.B /rc/bin/bundle +.SH SEE ALSO +.IR ar (1), +.IR tar (1), +.IR mail (1) +.SH BUGS +.I Bundle +will not create directories and is unsatisfactory for non-text files. +.PP +Beware of gift horses. diff --git a/sys/man/1/cal b/sys/man/1/cal new file mode 100755 index 000000000..a821f1e5c --- /dev/null +++ b/sys/man/1/cal @@ -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. +.PP +Beware that +.L "cal 90" +refers to the early Christian era, +not the 20th century. diff --git a/sys/man/1/calendar b/sys/man/1/calendar new file mode 100755 index 000000000..c671dedf9 --- /dev/null +++ b/sys/man/1/calendar @@ -0,0 +1,62 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- print upcoming events +.SH SYNOPSIS +.B calendar +[ +.B -dy +] +[ +.B -p +.I 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". +A special form may be used to represent weekly and +monthly events: +"Every Tuesday" +"The third Wednesday" +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 +The +.B -d +flag enables debugging output. +.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/sys/man/1/cat b/sys/man/1/cat new file mode 100755 index 000000000..837feb7ae --- /dev/null +++ b/sys/man/1/cat @@ -0,0 +1,87 @@ +.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 +.I 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/sys/man/1/cb b/sys/man/1/cb new file mode 100755 index 000000000..b5eed691e --- /dev/null +++ b/sys/man/1/cb @@ -0,0 +1,46 @@ +.TH CB 1 +.SH NAME +cb \- C program beautifier +.SH SYNOPSIS +.B cb +[ +.B -js +] +[ +.B -l +.I length +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Cb +reads syntactically correct C programs from +from its input or the given files, and writes them to its stdout +with a more visually pleasing spacing and indentation. +.I Cb +understands no C++ syntax bar newline-terminated comments; +and by default all user new-lines are preserved in the output. +.PP +The options are: +.TP +.B -j +Join split lines. +.TP +.B -s +Print code in the so-called K&R style used in +.IR "The C Programming Language" . +.TP +.B -l length +Split lines that are longer than +.IR length . +.PD +.SH SOURCE +.B /sys/src/cmd/cb +.SH BUGS +.I Cb +does not reformat structure initializers. +.br +Punctuation hidden in macros can cause +indentation errors. diff --git a/sys/man/1/chgrp b/sys/man/1/chgrp new file mode 100755 index 000000000..f1924773f --- /dev/null +++ b/sys/man/1/chgrp @@ -0,0 +1,36 @@ +.TH CHGRP 1 +.SH NAME +chgrp \- change file group +.SH SYNOPSIS +.B chgrp +[ +.B -ou +] +.I group file ... +.SH DESCRIPTION +The group of +each named file +is changed to +.IR group , +which should be a name known to the server holding the file. +.PP +A file's group can be changed by the file's owner, if the +owner is a member of the new group, +or by the leader of both +the file's current group and the new group. +.PP +The +.B -o +and +.B -u +option are synonyms; they specify that the +.I owner +is to be set, rather than the group. +They are ineffectual unless the file server is in the bootstrap +state that permits changing file ownership. +.SH SOURCE +.B /sys/src/cmd/chgrp.c +.SH "SEE ALSO" +.IR ls (1), +.IR chmod (1), +.IR stat (2) diff --git a/sys/man/1/chmod b/sys/man/1/chmod new file mode 100755 index 000000000..a5c80b677 --- /dev/null +++ b/sys/man/1/chmod @@ -0,0 +1,106 @@ +.TH CHMOD 1 +.SH NAME +chmod \- change mode +.SH SYNOPSIS +.B chmod +.I mode file ... +.SH DESCRIPTION +The mode of +each named file +is changed +according to +.IR mode, +which may be an octal number or a symbolic change to the existing mode. +A +.I mode +is an octal +number constructed +from the OR of the +following modes. +.TF 0000 +.TP +0400 +read by owner +.TP +0200 +write by owner +.TP +0100 +execute (search in directory) by owner +.TP +0070 +read, write, execute (search) by group +.TP +0007 +read, write, execute (search) by others +.PD +.PP +A symbolic +.I mode +has the form: +.IP +.RI [who] +.I op permission +.PP +The +.I who +part is a combination +of the letters +.B u +(for user's permissions), +.B g +(group) +and +.B o +(other). +The letter +.B a +stands for +.BR ugo . +If +.I who +is omitted, +the default is +.BR a . +.PP +.I Op +can be +.B + +to add +.I permission +to the file's mode, +.B - +to take away +.IR permission , +and +.B = +to assign +.I permission +absolutely +(all other bits will +be reset). +.PP +.I Permission +is any combination of the letters +.B r +(read), +.B w +(write), +.B x +(execute), +.B a +(append only), +.B l +(exclusive access), +and +.B t +(temporary file). +.PP +Only the owner of a file or the group leader of its group +may change the file's mode. +.SH SOURCE +.B /sys/src/cmd/chmod.c +.SH "SEE ALSO" +.IR ls (1), +.IR stat (2), +.IR stat (5) diff --git a/sys/man/1/cleanname b/sys/man/1/cleanname new file mode 100755 index 000000000..41c06c00e --- /dev/null +++ b/sys/man/1/cleanname @@ -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/sys/man/1/cmp b/sys/man/1/cmp new file mode 100755 index 000000000..55888ce97 --- /dev/null +++ b/sys/man/1/cmp @@ -0,0 +1,57 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.B cmp +[ +.B -lLs +] +.I file1 file2 +[ +.I offset1 +[ +.I offset2 +] +] +.SH DESCRIPTION +.I Cmp +compares the two files and prints +a message if the contents differ. +.PP +The options are: +.TP +.B -l +Print the byte number (decimal) and the +differing bytes (hexadecimal) for each difference. +.TP +.B -L +Print the line number of the first differing byte. +.TP +.B -s +Print nothing for differing files, +but set the exit status. +.PD +.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/sys/man/1/col b/sys/man/1/col new file mode 100755 index 000000000..6fb03081a --- /dev/null +++ b/sys/man/1/col @@ -0,0 +1,55 @@ +.TH COL 1 +.SH NAME +col \- column alignment +.SH SYNOPSIS +.B col +[ +.B -bfx +] +.SH DESCRIPTION +.I Col +overlays lines to expunge reverse line feeds +(ESC-7) +and half line feeds (ESC-9 and ESC-8) +as produced by +.I nroff +for .2C in +.IR ms (6) +or +.IR man (6) +and for +.IR tbl (1). +.I Col +is a pure filter. +It normally emits only full line feeds; +option +.B -f +(fine) allows half line feeds too. +Option +.B -b +removes backspaces, printing just one of each pile of overstruck +characters. +.I Col +normally converts white space to tabs; +option +.B -x +overrides this feature. +Other escaped characters and non-printing characters are ignored. +.SH EXAMPLES +.TP +.L +tbl file | nroff -ms | col | p +Format some tables for printing on typewriters; +use +.I col +to remove reverse line feeds, and +paginate the output. +.SH SEE ALSO +.IR pr (1) +.SH BUGS +.I Col +can't back up more than 128 lines or +handle more than 800 characters per line, +and understands +.L VT +(013) as reverse line feed. diff --git a/sys/man/1/colors b/sys/man/1/colors new file mode 100755 index 000000000..67a096a3d --- /dev/null +++ b/sys/man/1/colors @@ -0,0 +1,72 @@ +.TH COLORS 1 +.SH NAME +getmap, colors \- display color map +.SH SYNOPSIS +.PP +.B colors +[ +.B -rx +] +.PP +.B getmap +[ +.I colormap +] +.SH DESCRIPTION +.I Colors +presents a grid showing the colors in the current color map. +If the display is true color, +.I colors +shows a grid of the RGBV color map +(see +.IR color (6)). +.PP +Clicking mouse button 1 over a color in the grid will display the map index for that color, +its +red, green, and blue components, +and the 32-bit hexadecimal color value as defined in +.IR allocimage (2). +If the +.B -x +option is specified, the components will also be listed in hexadecimal. +.PP +The +.B -r +option instead shows, in the same form, a grey-scale ramp. +.PP +A menu on mouse button 3 contains a single entry, to exit the program. +.PP +On 8-bit color-mapped displays, +.I getmap +loads the display's color map (default +.BR rgbv ). +The named +.I colormap +can be a file in the current directory or in the standard repository +.BR /lib/cmap . +It can also be a string of the form +.B gamma +or +.BI gamma N\f1 , +where +.I N +is a floating point value for the gamma, defining the contrast for a monochrome map. +Similarly, +.B rgamma +and +.BI rgamma N +define a reverse-video monochrome map. +Finally, the names +.B screen +or +.B display +or +.B vga +are taken as synonyms for the current color map stored in the display hardware. +.SH FILES +.B /lib/cmap +directory of color map files +.SH SOURCE +.B /sys/src/cmd/colors.c +.SH SEE ALSO +.IR color (6) diff --git a/sys/man/1/comm b/sys/man/1/comm new file mode 100755 index 000000000..2fd883c05 --- /dev/null +++ b/sys/man/1/comm @@ -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/sys/man/1/con b/sys/man/1/con new file mode 100755 index 000000000..44c91b01b --- /dev/null +++ b/sys/man/1/con @@ -0,0 +1,315 @@ +.TH CON 1 +.SH NAME +con, telnet, rx, hayes, xms, xmr \- remote login, execution, and XMODEM file transfer +.SH SYNOPSIS +.B con +[ +.B -CdnrRsTv +] +[ +.B -b +.I baud +] +[ +.B -l +[ +.I user +] +] +[ +.B -S +.I svc +] +[ +.B -c +.I cmd +] +.RI [ net !] machine +.PP +.B telnet +[ +.B -dCrn +] +[ +.B -s +.I svc +] +.RI [ net !] machine +.PP +.B rx +[ +.B -eTr +] +[ +.B -l +.I user +] +.RI [ net !] machine +[ +.I command-word ... +] +.PP +.B hayes +[ +.B -pv +] +.I number +[ +.I device +] +.PP +.B xms +[ +.B -1p +] +.I file +.PP +.B xmr +.I file +.SH DESCRIPTION +.I Con +connects to the computer whose network address is +.IR net ! machine +and logs in if possible. +With no options, the account name used on the remote system is the same +as that on the local system. +Standard input and output go to the local machine. +.PP +Options are: +.TP +.B -b +sets the baud rate of a dial-up connection to +.IR baud . +.TP +.B -n +if the input is a file or pipe, do not hang up the connection when EOF is received, +but instead wait for the remote end to hang up. +.TP +.B -l +with an argument causes +.I user +to be used as the account name on the remote system +when performing BSD +.I rlogin +authentication. +Without an argument this option disables automatic login +and a normal login session ensues. +.TP +.B -C +forces cooked mode, that is, local echo. +.TP +.B -c +runs +.I cmd +as if it had been typed as a command from the escape mode. +.TP +.B -v +(verbose mode) causes information about connection attempts +to be output to standard error. This can be useful when +trying to debug network connectivity. +.TP +.B -d +causes debugging information to be output to standard error. +.TP +.B -r +suppresses printing of any carriage return followed by a new line. +This is useful since carriage return is a printable character in +Plan 9. +.TP +.B -R +translates newlines to carriage returns and +.IR "vice versa" . +.TP +.B -T +translates incoming carriage returns to newlines. +.TP +.B -s +strips received characters to 7 bits to forestall +misinterpretation of +.SM ASCII +with parity as +.SM UTF\c +\&. +.TP +.B -S +Post a pipe as +.BI /srv/ svc +and connect it to standard input and output. +This can be used with +.B -n +to create a standing connection that +.IR consolefs (4), +for example, +can then open. +For +.IR telnet , +this option is +.BR -s . +.PP +The +.RB control\- \e +character is a local escape. +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B i +Send a quit [sic] signal to the remote machine. +.PD0 +.TP +.B q +Exit. +.TP +.B b +Send a break. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +This is useful for transmitting and receiving files +over the connections using programs such as +.IR xms . +.TP +.B r +Toggle printing of carriage returns. +.PD +.PP +.I Telnet +is similar to con, but uses the +.I telnet +protocol to communicate with the remote machine. +It shares +.I con's +.BR -C , +.BR -d , +.BR -n , +and +.BR -r +options. +.PP +.I Rx +executes one shell command +on the remote machine as if logged in there, +but with local standard input and output. +A rudimentary shell environment is provided. +If the target is a Plan 9 machine, +.B $service +there will be +.BR rx . +Options are: +.TP +.B \-e +a zero length message will not be written to the +connection when standard input is closed. +.TP +.B \-l +runs as +.I user +on the remote machine if the remote is a BSD machine. +.TP +.B \-r +same as for +.I con +.TP +.B -T +same as for +.I con +.PD +.PP +Network addresses for both +.I con +and +.I rx +have the form +.IB network ! machine\f1. +Supported networks are those listed in +.BR /net . +.PP +.I Hayes +dials +.I number +on a Hayes-compatible modem, +.IR device . +Under +.BR -p , +it uses pulse dialing. +Upon connecting, +bytes are copied bidirectionally +between the connection and standard input and output. +.PP +The commands +.I xms +and +.I xmr +respectively send and receive a single file using the +XMODEM protocol. +They use standard input and standard output for communication +and are intended for use with +.IR con . +The +.B -1 +option to +.I xms +causes it to use kilobyte packet size of 1024 bytes. +The +.B -p +option causes it to print a progress +message every ten kilobytes. +.SH EXAMPLES +.TP +.L +rx kremvax cat file1 >file2 +Copy remote +.I file1 +to local +.IR file2 . +.TP +.L +rx kremvax cat file1 '>file2' +Copy remote +.I file1 +to remote +.IR file2. +.TP +.L +eqn paper | rx kremvax troff -ms | rx deepthought lp +Parallel processing: +do each stage of a pipeline on a different machine. +.SH SOURCE +.TF /sys/src/cmd/ip/telnet.c +.TP +.B /sys/src/cmd/rx.c +.TP +.B /sys/src/cmd/ip/telnet.c +.TP +.B /sys/src/cmd/con +for all other commands +.SH SEE ALSO +.IR cpu (1), +.IR ssh (1), +.IR telco (4) +.SH BUGS +.I Con +and +.I telnet +are merely obsolescent; +the other commands are obsolete and deprecated. +.PP +Under +.IR rx , +a program +that should behave specially towards terminals may not: e.g., +remote shells will not prompt. +Also under +.IR rx , +the remote standard error and standard output are combined +and go inseparably to the local standard output. +.I Rx +will consume its standard input by copying it to the remote system, +so redirect it from +.BR /dev/null +if that's not what you want. diff --git a/sys/man/1/cp b/sys/man/1/cp new file mode 100755 index 000000000..ba84be3a3 --- /dev/null +++ b/sys/man/1/cp @@ -0,0 +1,130 @@ +.TH CP 1 +.SH NAME +cp, fcp, mv \- copy, move files +.SH SYNOPSIS +.B cp +[ +.B -gux +] +.I file1 file2 +.br +.B cp +[ +.B -gux +] +.I file ... directory +.PP +.B fcp +[ +.B -gux +] +.I file1 file2 +.br +.B fcp +[ +.B -gux +] +.I file ... directory +.PP +.B mv +.I file1 file2 +.br +.B mv +.I file ... directory +.SH DESCRIPTION +In the first form +.I file1 +is any name and +.I file2 +is any name except an existing directory. +In the second form the commands +copy or move one or more +.I files +into a +.I directory +under their original file names, as if by a sequence of +commands in the first form. +Thus +.L "cp f1 f2 dir +is equivalent to +.LR "cp f1 dir/f1; cp f2 dir/f2" . +.PP +.I Cp +copies the contents of plain +.I file1 +to +.IR file2 . +The mode and owner of +.I file2 +are preserved if it already +exists; the mode of +.I file1 +is used otherwise. +The +.B -x +option sets the mode and modified time of +.I file2 +from +.IR file1 ; +.B -g +sets the group id; and +.B -u +sets the group id and user id (which is usually only possible if the file server is in an administrative mode). +.PP +.I Fcp +behaves like +.I cp +but transfers multiple blocks in parallel while copying; +it is noticeably faster than +.I cp +when the files involved are stored on servers connected over long-distance lines. +It is only appropriate to use +.I fcp +with file servers that respect the +.I offset +in +.IR read (5) +and +.I write +messages. +This includes the disk-based file systems and ramfs +but excludes most device file systems. +.PP +.I Mv +moves +.I file1 +to +.IR file2 . +If the files are in the same directory, +.I file1 +is just renamed; +otherwise +.I mv +behaves like +.I cp +.B -x +followed by +.B rm +.IR file1 . +.I Mv +will rename directories, +but it refuses to move a directory into another directory. +.SH SOURCE +.B /sys/src/cmd/cp.c +.br +.B /sys/src/cmd/fcp.c +.br +.B /sys/src/cmd/mv.c +.SH "SEE ALSO" +.IR cat (1), +.I dircp +in +.IR tar (1), +.IR stat (2), +.IR read (5) +.SH DIAGNOSTICS +.IR Cp , +.IR fcp , +and +.I mv +refuse to copy or move files onto themselves. diff --git a/sys/man/1/cpp b/sys/man/1/cpp new file mode 100755 index 000000000..3fc931585 --- /dev/null +++ b/sys/man/1/cpp @@ -0,0 +1,119 @@ +.TH CPP 1 +.SH NAME +cpp \- C language preprocessor +.SH SYNOPSIS +.B cpp +[ +.I option ... +] +[ +.I ifile +[ +.I ofile +] +] +.SH DESCRIPTION +.I Cpp\^ +interprets ANSI C preprocessor directives +and does macro substitution. +The input +.I ifile +and output +.I ofile +default to standard input and standard output respectively. +.PP +The options are: +.TP +.BI -D name\^ +.PD 0 +.TP +.BI -D name=def\^ +.TP +.BI -I dir\^ +Same as in +.IR 2c "(1): add +.I dir +to the search for +.CW search +directives. +.PD +.TP +.B -M +Generate no output except a list of include files +in a form suitable for specifying dependencies to +.IR mk (1). +Use twice to list files in angle brackets. +.TP +.B -N +Turn off default include directories. All must be +specified with +.BR -I , +or in the environment variable +.BR include . +Without this option, +.B /$objtype/include +and +.B /sys/include +are used as the last two searched directories for include directives, +where +.B $objtype +is read from the environment. +.TP +.B -V +Print extra debugging information. +.TP +.B -P +Do not insert +.RB `` #line '' +directives into the output. +.TP +.B -+ +Understand C++ comments. +.TP +.B -. +Inhibit include search in the source's directory. +.TP +.B -i +Print the list of directories searched when +.I #include +is found. +Last listed are searched first. +.PD +.PP +In the absence of the +.B -P +option, the processed text output is sprinkled +with lines that show the original input line numbering: +.IP +.B #line +.I linenumber +.L +"\fIifile\fP" +.PP +The command reads the environment variable +.IR include +and adds its (blank-separated) list of directories to +the standard search path for +.CW #include +directives. They are looked at before any directories specified with +.BR -I , +which are looked at before the default directories. +.PP +The input language is as described in the ANSI C standard. +The standard Plan 9 C compilers do not use +.IR cpp ; +they contain their own simple but adequate preprocessor, so +.I cpp +is usually superfluous. +.SH FILES +.TF /objtype/include +.TP +.B /sys/include +directory for machine-independent include files +.TP +.B /$objtype/include +directory for machine-dependent include files +.SH SOURCE +.B /sys/src/cmd/cpp +.SH SEE ALSO +.IR 2c (1) diff --git a/sys/man/1/cpu b/sys/man/1/cpu new file mode 100755 index 000000000..e408683bc --- /dev/null +++ b/sys/man/1/cpu @@ -0,0 +1,204 @@ +.TH CPU 1 +.SH NAME +cpu \- connection to CPU server +.SH SYNOPSIS +.B cpu +[ +.B -h +.I server +] [ +.B -u +.I user +] [ +.B -a +.I auth-method +] [ +.B -P +.I patternfile +] [ +.B -e +.I encryption-hash-algs +] [ +.B -k +.I keypattern +] [ +.B -c +.I cmd args ... +] +.PP +.B cpu +[ +.B -R +| +.B -O +] +.SH DESCRIPTION +.I Cpu +starts an +.IR rc (1) +running on the +.I server +machine, or the machine named in the +.B $cpu +environment variable if there is no +.B -h +option. +.IR Rc 's +standard input, output, and error files will be +.B /dev/cons +in the name space where the +.I cpu +command was invoked. +Normally, +.I cpu +is run in an +.IR rio (1) +window on a terminal, so +.IR rc +output goes to that window, and input comes from the keyboard +when that window is current. +.IR Rc 's +current directory is +the working directory of the +.I cpu +command itself. +.PP +The name space for the new +.I rc +is an analogue of the name space where the +.I cpu +command was invoked: +it is the same except for architecture-dependent bindings such as +.B /bin +and the use of fast paths to file servers, if available. +.PP +If a +.B -u +argument is present, +.I cpu +uses the argument as the remote user id. +.PP +If a +.B -c +argument is present, the remainder of the command line is executed by +.I rc +on the server, and then +.I cpu +exits. +.PP +If a +.B -P +argument is present, the +.I patternfile +is passed to +.IR exportfs (4) +to control how much of the local name space will be exported to +the remote system. +.PP +The +.B -a +command allows the user to specify the authentication mechanism used +when connecting to the remote system. The two possibilities for +.I auth-method +are: +.TF netkey +.TP +.B p9 +This is the default. Authentication is done using the standard Plan 9 +mechanisms, (see +.IR authsrv (6)). +No user interaction is required. +.TP +.B netkey +Authentication is done using challenge/response and a hand held +authenticator or the +.I netkey +program +(see +.IR passwd (1)). +The user must encrypt the challenge and type the encryption +back to +.IR cpu . +This is used if the local host is in a different protection domain than +the server or if the user wants to log into the server as a different +user. +.PD +.PP +The +.B -e +option specifies an encryption and/or hash algorithm to +use for the connection. If both are specified, they must +be space separated and comprise a single argument, so they +must be quoted if in a shell command. The default is +.L rc4_256 +encryption and +.L sha1 +hashing. See +.IR ssl (3) +for details on possible algorithms. The argument +.L clear +specifies no encryption algorithm and can be used to talk +to older versions of the +.I cpu +service. +.PP +The +.B -k +flag specifies a key pattern to use to restrict the keys +selected by the +.I auth_proxy +call used for authentication. +.PP +The name space is built by running +.B /usr/$user/lib/profile +with the root of the invoking name space bound to +.BR /mnt/term . +The +.B service +environment variable is set to +.BR cpu ; +the +.B cputype +and +.B objtype +environment variables reflect the server's architecture. +.PP +The +.B -R +flag causes +.I cpu +to run the server (remote) side of the protocol. +It is run from service files such as +.BR /bin/service/tcp17010 . +The +.B -O +flag is similar but simulates the pre-9P2000 version +of the +.I cpu +protocol. +.SH FILES +The name space of the terminal side of the +.I cpu +command is mounted, via +.IR exportfs (4), +on the CPU side on directory +.BR /mnt/term . +The files such as +.B /dev/cons +are bound to their standard locations from there. +.SH SOURCE +.B /sys/src/cmd/cpu.c +.SH SEE ALSO +.IR rc (1) , +.IR rio (1) , +.IR exportfs (4) +.SH BUGS +Binds and mounts done after the terminal +.B lib/profile +is run are not reflected in the new name space. +.PP +When using the +.B -a +option to `log in' as another user, be aware that +resources in the local name space will be made +available to that user. diff --git a/sys/man/1/crop b/sys/man/1/crop new file mode 100755 index 000000000..209cdcc06 --- /dev/null +++ b/sys/man/1/crop @@ -0,0 +1,153 @@ +.TH CROP 1 +.SH NAME +crop, iconv \- frame, crop, and convert image +.SH SYNOPSIS +.B crop +[ +.B -b +.I red +.I green +.I blue +] +[ +.BI -c +.I red +.I green +.I blue +] +[ +.B -i +.I n +| +.B -r +.I minx +.I miny +.I maxx +.I maxy +| +.B -x +.I dx +| +.B -y +.I dy +] +[ +.B -t +.I tx +.I ty +] +[ +.B -b +.I red +.I green +.I blue +] +[ +.I file +] +.PP +.B iconv +[ +.B -u +] [ +.B -c +.I chandesc +] +[ +.I file +] +.SH DESCRIPTION +.I Crop +reads an +.IR image (6) +file (default standard input), crops it, and writes it as a compressed +.IR image (6) +file to standard output. +There are two ways to specify a crop, by color value or by geometry. +They may be combined in a single run of +.IR crop , +in which case the color value crop will be done first. +.PP +The +.B -c +option takes a red-green-blue triplet as described in +.IR color (2). +(For example, white +is +.B 255 +.B 255 +.BR 255 .) +The corresponding color is used as a value to be cut from the outer +edge of the picture; that is, the image is cropped to remove the maximal +outside rectangular strip in which every pixel has the specified color. +.PP +The +.B -i +option insets the image rectangle by a constant amount, +.IR n , +which may be negative to generate extra space around the image. +The +.B -x +and +.B -y +options are similar, but apply only to the +.I x +or +.I y +coordinates of the image. +.PP +The +.B -r +option specifies an exact rectangle. +.PP +The +.B -t +option specifies that the image's coordinate system should +be translated by +.IR tx , +.IR ty +as the last step of processing. +.PP +The +.B -b +option specifies a background color to be used to fill around the image +if the cropped image is larger than the original, such as if the +.B -i +option is given a negative argument. +This can be used to draw a monochrome frame around the image. +The default color is black. +.PP +.I Iconv +changes the format of pixels in the image +.I file +(default standard input) and writes the resulting image to standard output. +Pixels in the image are converted according to the channel descriptor +.IR chandesc , +(see +.IR image (6)). +For example, to convert a 4-bit-per-pixel grey-scale image to an 8-bit-per-pixel +color-mapped image, +.I chandesc +should be +.BR m8 . +If +.I chandesc +is not given, the format is unchanged. +The output image is by default compressed; the +.B -u +option turns off the compression. +.SH EXAMPLE +To crop white edges off the picture and add a ten-pixel pink border, +.IP +.EX +crop -c 255 255 255 -i -10 -b 255 150 150 imagefile > cropped +.EE +.SH SOURCE +.B /sys/src/cmd/crop.c +.SH SEE ALSO +.IR image (6), +.IR color (2) +.SH BUGS +.I Iconv +should be able to do Floyd-Steinberg error diffusion or dithering +when converting to small image depths. diff --git a/sys/man/1/date b/sys/man/1/date new file mode 100755 index 000000000..705a95425 --- /dev/null +++ b/sys/man/1/date @@ -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. +.PP +.I Clock +draws a simple analog clock in its window. +.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 +.SH SOURCE +.B /sys/src/cmd/date.c +.br +.B /sys/src/cmd/clock.c diff --git a/sys/man/1/db b/sys/man/1/db new file mode 100755 index 000000000..34f1f4239 --- /dev/null +++ b/sys/man/1/db @@ -0,0 +1,1018 @@ +.TH DB 1 +.SH NAME +db \- debugger +.SH SYNOPSIS +.B db +[ +.I option ... +] +[ +.I textfile +] +[ +.I pid +] +.SH DESCRIPTION +.I Db +is a general purpose debugging program. +It may be used to examine files and to provide +a controlled environment for the execution +of Plan 9 programs. +.PP +A +.I textfile +is a file containing the text and initialized +data of an executable program. +A +.I memfile +is the memory image of an executing process. It is +usually accessed via the process id +.RI ( pid ) +of the process in +.BI /proc/ pid /mem\f1. +A +.I memfile +contains the text, data, and saved registers and +process state. A +.I map +associated with each +.I textfile +or +.I memfile +supports accesses to instructions and data in the file; +see `Addresses'. +.PP +An argument consisting entirely of digits is assumed +to be a process id; otherwise, it is the name of a +.IR textfile . +When a +.I textfile +is given, the textfile map +is associated with it. +If only a +.I pid +is given, the textfile map is +associated with +.BI /proc/ pid /text\f1. +When a +.I pid +is given, the memfile map is associated with +.BI /proc/ pid /mem\f1; +otherwise it is undefined and accesses to the +.I memfile +are not permitted. +.PP +Commands to +.I db +are read from the standard input and +responses are to the standard output. +The options are +.TP +.BI -k +Use the kernel stack of process +.IR pid +to debug the executing kernel process. +If +.I textfile +is not specified, file +.BI / $cputype /9 type +is used, where +.I type +is the second word in +.BR $terminal . +.TP +.B -w +Create +.I textfile +and +.I memfile +if they don't exist; open them for writing +as well as reading. +.TP +.BI -I path +Directory in which to look for relative path names in +.B $< +and +.B $<< +commands. +.TP +.BI -m machine +Assume instructions are for the given CPU type +(any standard architecture name, such as +.B alpha +or +.BR 386 , +plus +.B mipsco +and +.BR sunsparc , +which cause disassembly to the manufacturer's syntax) +instead of using the magic number to select +the CPU type. +.PP +Most +.I db +commands have the following form: +.IP +.RI [ address ] +.RB [ , +.IR count ] +.RI [ command ] +.PP +If +.I address +is present then the current position, called `dot', +is set to +.IR address . +Initially dot +is set to 0. +Most commands are repeated +.I count +times with +dot advancing between repetitions. +The default +.I count +is 1. +.I Address +and +.I count +are expressions. +Multiple commands on one line must be separated by +.LR ; . +.SS Expressions +Expressions are evaluated as long +.IR ints . +.TP 7.2n +.B . +The value of dot. +.TP 7.2n +.B + +The value of dot +incremented by the current increment. +.TP 7.2n +.B ^ +The value of dot +decremented by the current increment. +.TP 7.2n +.B \&" +The last +.I address +typed. +.TP 7.2n +.I integer +A number, in decimal radix by default. +The prefixes +.L 0 +and +.L 0o +and +.L 0O +(zero oh) force interpretation +in octal radix; the prefixes +.L 0t +and +.L 0T +force interpretation in +decimal radix; the prefixes +.LR 0x , +.LR 0X , +and +.L # +force interpretation in +hexadecimal radix. +Thus +.LR 020 , +.LR 0o20 , +.LR 0t16 , +and +.L #10 +all represent sixteen. +.TP 7.2n +.IB integer . fraction +A single-precision floating point number. +.TP 7.2n +.BI \' c\| \' +The +16-bit +value of a character. +.L \e +may be used to escape a +.LR \' . +.TP 7.2n +.BI < name +The value of +.IR name , +which is a register name. +The register names are +those printed by the +.B $r +command. +.TP 7.2n +.I symbol +A +.I symbol +is a sequence +of upper or lower case letters, underscores or +digits, not starting with a digit. +.L \e +may be used to escape other characters. +The location of the +.I symbol +is calculated from the symbol table +in +.IR textfile . +.TP 7.2n +.IB routine . name +The address of the variable +.I name +in the specified +C routine. +Both +.I routine +and +.I name +are +.IR symbols . +If +.I name +is omitted the value is the address of the +most recently activated stack frame +corresponding to +.IR routine ; +if +.I routine +is omitted, +the active procedure +is assumed. +.TP 7.2n +.IB file : integer +The address of the instruction corresponding +to the source statement at the indicated +line number of the file. If the source line contains +no executable statement, the address of the +instruction associated with the nearest +executable source line is returned. Files +begin at line 1. If multiple files of the same +name are loaded, an expression of this form resolves +to the first file encountered in the symbol table. +.TP 7.2n +.BI ( exp ) +The value of the expression +.IR exp . +.LP +.I Monadic operators +.RS +.TP 7.2n +.BI * exp +The contents of the location addressed +by +.I exp +in +.IR memfile . +.TP 7.2n +.BI @ exp +The contents of the location addressed by +.I exp +in +.IR textfile . +.TP 7.2n +.BI - exp +Integer negation. +.TP 7.2n +.BI ~ exp +Bitwise complement. +.TP 7.2n +.BI % exp +When used as an +.IR address , +.I exp +is an offset into the segment named +.IR ublock ; +see `Addresses'. +.RE +.LP +.I "Dyadic\ operators" +are left-associative +and are less binding than monadic operators. +.RS +.TP 7.2n +.IB e1 + e2 +Integer addition. +.TP 7.2n +.IB e1 - e2 +Integer subtraction. +.TP 7.2n +.IB e1 * e2 +Integer multiplication. +.TP 7.2n +.IB e1 % e2 +Integer division. +.TP 7.2n +.IB e1 & e2 +Bitwise conjunction. +.TP 7.2n +.IB e1 | e2 +Bitwise disjunction. +.TP 7.2n +.IB e1 # e2 +.I E1 +rounded up to the next multiple of +.IR e2 . +.RE +.DT +.SS Commands +Most commands have the following syntax: +.TP .5i +.BI ? f +Locations starting at +.I address +in +.I textfile +are printed according to the format +.IR f . +.TP +.BI / f +Locations starting at +.I address +in +.I memfile +are printed according to the format +.IR f . +.TP +.BI = f +The value of +.I address +itself is printed according to the format +.IR f . +.PP +A +.I format +consists of one or more characters that specify a style +of printing. +Each format character may be preceded by a decimal integer +that is a repeat count for the format character. +If no format is given then the last format is used. +.PP +Most format letters fetch some data, +print it, +and advance (a local copy of) dot +by the number of bytes fetched. +The total number of bytes in a format becomes the +.IR current increment . +.ta 2.5n .5i +.RS +.TP +.PD 0 +.B o +Print two-byte integer in octal. +.TP +.B O +Print four-byte integer in octal. +.TP +.B q +Print two-byte integer in signed octal. +.TP +.B Q +Print four-byte integer in signed octal. +.TP +.B d +Print two-byte integer in decimal. +.TP +.B D +Print four-byte integer in decimal. +.TP +.B V +Print eight-byte integer in decimal. +.TP +.B Z +Print eight-byte integer in unsigned decimal. +.TP +.B x +Print two-byte integer in hexadecimal. +.TP +.B X +Print four-byte integer in hexadecimal. +.TP +.B Y +Print eight-byte integer in hexadecimal. +.TP +.B u +Print two-byte integer in unsigned decimal. +.TP +.B U +Print four-byte integer in unsigned decimal. +.TP +.B f +Print +as a single-precision floating point number. +.TP +.B F +Print double-precision floating point. +.TP +.B b +Print the addressed byte in hexadecimal. +.TP +.B c +Print the addressed byte as an +.SM ASCII +character. +.TP +.B C +Print the addressed byte as a character. +Printable +.SM ASCII +characters +are represented normally; others +are printed in the form +.BR \exnn . +.TP +.B s +Print the addressed characters, as a +.SM UTF +string, until a zero byte +is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B S +Print a string using +the escape convention (see +.B C +above). +.TP +.B r +Print as +.SM UTF +the addressed two-byte integer (rune). +.TP +.B R +Print as +.SM UTF +the addressed two-byte integers as runes +until a zero rune is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B i +Print as machine instructions. Dot is +incremented by the size of the instruction. +.TP +.B I +As +.B i +above, but print the machine instructions in +an alternate form if possible: +.B sunsparc +and +.B mipsco +reproduce the manufacturers' syntax. +.TP +.B M +Print the addressed machine instruction in a +machine-dependent hexadecimal form. +.TP +.B a +Print the value of dot +in symbolic form. +Dot is unaffected. +.TP +.B A +Print the value of dot +in hexadecimal. +Dot is unaffected. +.TP +.B z +Print the function name, source file, and line number +corresponding to dot (textfile only). Dot is unaffected. +.TP +.B p +Print the addressed value in symbolic form. +Dot is advanced by the size of a machine address. +.TP +.B t +When preceded by an integer, tabs to the next +appropriate tab stop. +For example, +.B 8t +moves to the next 8-space tab stop. +Dot is unaffected. +.TP +.B n +Print a newline. +Dot is unaffected. +.tr '" +.TP +.BR ' ... ' +Print the enclosed string. +Dot is unaffected. +.br +.tr '' +.TP +.B ^ +Dot is decremented by the current increment. +Nothing is printed. +.TP +.B + +Dot is incremented by 1. +Nothing is printed. +.TP +.B - +Dot is decremented by 1. +Nothing is printed. +.RE +.PD +.LP +Other commands include: +.TP +newline +Update dot by the current increment. +Repeat the previous command with a +.I count +of 1. +.TP +.RB [ ?/ ] l "\fI value mask\fR" +Words starting at dot +are masked with +.I mask +and compared with +.I value +until +a match is found. +If +.B l +is used, +the match is for a two-byte integer; +.B L +matches four bytes. +If no match is found then dot +is unchanged; otherwise dot +is set to the matched location. +If +.I mask +is omitted then ~0 is used. +.TP +.RB [ ?/ ] w "\fI value ...\fR" +Write the two-byte +.I value +into the addressed +location. +If the command is +.BR W , +write four bytes. +.TP +.RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR] +.br +New values for +.RI ( b,\ e,\ f ) +in the segment named +.I s +are recorded. Valid segment names are +.IR text , +.IR data , +or +.IR ublock . +If less than three address expressions are given, +the remaining parameters are left unchanged. +If the list is terminated by +.L ? +or +.L / +then the file +.RI ( textfile +or +.I memfile +respectively) is used +for subsequent requests. +For example, +.L /m? +causes +.L / +to refer to +.IR textfile . +.TP +.BI > name +Dot is assigned to the variable or register named. +.TP +.B ! +The rest of the line is passed to +.IR rc (1) +for execution. +.TP +.BI $ modifier +Miscellaneous commands. +The available +.I modifiers +are: +.RS +.TP +.PD 0 +.BI < f +Read commands from the file +.IR f . +If this command is executed in a file, further commands +in the file are not seen. +If +.I f +is omitted, the current input stream is terminated. +If a +.I count +is given, and is zero, the command is ignored. +.TP +.BI << f +Similar to +.B < +except it can be used in a file of commands without +causing the file to be closed. +There is a (small) limit to the number of +.B << +files that can be open at once. +.br +.ns +.TP +.BI > f +Append output to the file +.IR f , +which is created if it does not exist. +If +.I f +is omitted, output is returned to the terminal. +.TP +.B ? +Print process id, the condition which caused stopping or termination, +the registers and the instruction addressed by +.BR pc . +This is the default if +.I modifier +is omitted. +.TP +.B r +Print the general registers and +the instruction addressed by +.BR pc . +Dot is set to +.BR pc . +.TP +.B R +Like +.BR $r , +but include miscellaneous processor control registers +and floating point registers. +.TP +.B f +Print floating-point register values as +single-precision floating point numbers. +.TP +.B F +Print floating-point register values as +double-precision floating point numbers. +.TP +.B b +Print all breakpoints +and their associated counts and commands. `B' produces the same results. +.TP +.B c +Stack backtrace. +If +.I address +is given, it specifies the address of a pair of 32-bit +values containing the +.B sp +and +.B pc +of an active process. This allows selecting +among various contexts of a multi-threaded +process. +If +.B C +is used, the names and (long) values of all +parameters, +automatic +and static variables are printed for each active function. +If +.I count +is given, only the first +.I count +frames are printed. +.TP +.B a +Attach to the running process whose pid +is contained in +.IR address . +.TP +.B e +The names and values of all +external variables are printed. +.TP +.B w +Set the page width for output to +.I address +(default 80). +.TP +.B q +Exit from +.IR db . +.TP +.B m +Print the address maps. +.TP +.B k +Simulate kernel memory management. +.TP +.BI M machine +Set the +.I machine +type used for disassembling instructions. +.PD +.RE +.TP +.BI : modifier +Manage a subprocess. +Available modifiers are: +.RS +.TP +.PD 0 +.BI h +Halt +an asynchronously running process to allow breakpointing. +Unnecessary for processes created under +.IR db , +e.g. by +.BR :r . +.TP +.BI b c +Set breakpoint at +.IR address . +The breakpoint is executed +.IR count \-1 +times before +causing a stop. +Also, if a command +.I c +is given it is executed at each +breakpoint and if it sets dot to zero +the breakpoint causes a stop. +.TP +.B d +Delete breakpoint at +.IR address . +.TP +.B r +Run +.I textfile +as a subprocess. +If +.I address +is given the +program is entered at that point; otherwise +the standard entry point is used. +.I Count +specifies how many breakpoints are to be +ignored before stopping. +Arguments to the subprocess may be supplied on the +same line as the command. +An argument starting with < or > causes the standard +input or output to be established for the command. +.TP +.BI c s +The subprocess is continued. +If +.I s +is omitted +or nonzero, +the subprocess +is sent the note that caused it to stop. +If 0 +is specified, +no note is sent. +(If the stop was due to a breakpoint or single-step, +the corresponding note is elided before continuing.) +Breakpoint skipping is the same +as for +.BR r . +.TP +.BI s s +As for +.B c +except that +the subprocess is single stepped for +.I count +machine instructions. +If a note is pending, +it is received +before the first instruction is executed. +If there is no current subprocess then +.I textfile +is run +as a subprocess as for +.BR r . +In this case no note can be sent; the remainder of the line +is treated as arguments to the subprocess. +.TP +.BI S s +Identical to +.B s +except the subprocess is single stepped for +.I count +lines of C source. In optimized code, the correspondence +between C source and the machine instructions is +approximate at best. +.TP +.BI x +The current subprocess, if any, is released by +.I db +and allowed to continue executing normally. +.TP +.B k +The current subprocess, if any, is terminated. +.TP +.BI n c +Display the pending notes for the process. +If +.I c +is specified, first delete +.I c'th +pending note. +.PD +.RE +.SS Addresses +The location in a file or memory image associated with +an address is calculated from a map +associated with the file. +Each map contains one or more quadruples +.RI ( "t, b, e, f" ), +defining a segment named +.I t +(usually, +.IR text , +.IR data , +or +.IR ublock ) +mapping addresses in the range +.I b +through +.I e +to the part of the file +beginning at +offset +.IR f . +The memory model of a Plan 9 process assumes +that segments are disjoint. There +can be more than one segment of a given type (e.g., a process +may have more than one text segment) but segments +may not overlap. +An address +.I a +is translated +to a file address +by finding a segment +for which +.IR b ≤ a < e ; +the location in the file +is then +.IR address + f \- b . +.PP +Usually, +the text and initialized data of a program +are mapped by segments called +.I text +and +.IR data . +Since a program file does not contain bss, stack or ublock data, +these data are +not mapped by the data segment. +The text segment is mapped similarly in +a normal (i.e., non-kernel) +.IR memfile . +However, the segment called +.I data +maps memory from the beginning of the program's data space to +the base of the ublock. +This region contains the program's static data, the bss, the +heap and the stack. A segment +called +.I ublock +maps the page containing its registers and process state. +.PP +Sometimes it is useful to define a map with a single segment +mapping the region from 0 to 0xFFFFFFFF; a map of this type +allows the entire file to be examined +without address translation. +.PP +Registers are saved at a machine-dependent offset in the ublock. +It is usually not necessary to know this offset; the +.BR $r , +.BR $R , +.BR $f , +and +.BR $F +commands calculate it and display the register contents. +.PP +The +.B $m +command dumps the currently active maps. The +.B ?m +and +.B /m +commands modify the segment parameters in the +.I textfile +and +.I memfile +maps, respectively. +.SH EXAMPLES +To set a breakpoint at the beginning of +.B write() +in extant process 27: +.IP +.EX +% db 27 +:h +write:b +:c +.EE +.PP +To examine the Plan 9 kernel stack for process 27: +.IP +.EX +% db -k 27 +$C +.EE +.PP +Similar, but using a kernel named +.BR test : +.IP +.EX +% db -k test 27 +$C +.EE +.PP +To set a breakpoint at the entry of function +.B parse +when the local variable +.B argc +in +.B main +is equal to 1: +.IP +.EX +parse:b *main.argc-1=X +.EE +.PP +This prints the value of +.B argc-1 +which as a side effect sets dot; when +.B argc +is one the breakpoint will fire. +Beware that local variables may be stored in registers; see the +BUGS section. +.PP +Debug process 127 on remote machine +.BR kremvax : +.IP +.EX +% import kremvax /proc +% db 127 +$C +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.SH "SEE ALSO" +.IR acid (1), +.IR nm (1), +.IR proc (3) +.SH SOURCE +.B /sys/src/cmd/db +.SH DIAGNOSTICS +Exit status is null, unless the last command failed or +returned non-null status. +.SH BUGS +Examining a local variable with +.I routine.name +returns the contents of the memory allocated for the variable, but +with optimization (suppressed by the +.B -N +compiler flag) variables often reside in registers. +Also, on some architectures, the first argument is always +passed in a register. +.PP +Variables and parameters that have been +optimized away do not appear in the +symbol table, returning the error +.IR "bad local variable" +when accessed by +.IR db . +.PP +Because of alignment incompatibilities, Motorola 68000 +series machines can not be debugged remotely from a +processor of a different type. +.PP +Breakpoints should not be set on instructions scheduled +in delay slots. When a program stops on such a breakpoint, +it is usually impossible to continue its execution. diff --git a/sys/man/1/dc b/sys/man/1/dc new file mode 100755 index 000000000..7032a2bff --- /dev/null +++ b/sys/man/1/dc @@ -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 +.LP +Print the first ten values of +.IR n ! +.IP +.EX +[la1+dsa*pla10>y]sy +0sa1 +lyx +.EE +.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/sys/man/1/dd b/sys/man/1/dd new file mode 100755 index 000000000..afd296b1f --- /dev/null +++ b/sys/man/1/dd @@ -0,0 +1,196 @@ +.TH DD 1 +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.B dd +[ +.I option value +] +\&... +.SH DESCRIPTION +.I Dd\^ +copies the specified input file +to the specified output with +possible conversions. +The standard input and output are used by default. +The input and output block size may be +specified to take advantage of raw physical I/O. +The options are +.TP \w'\fLoseek\ \ \fIn'u +.BI -if\ f +Open file +.I f +for input. +.TP +.BI -of\ f +Open file +.I f +for output. +.TP +.BI -ibs\ n\^ +Set input block size to +.I n\^ +bytes (default 512). +.TP +.BI -obs\ n\^ +Set output block size (default 512). +.TP +.BI -bs\ n\^ +Set both input and output block size, +superseding +.I ibs\^ +and +.IR obs . +If no conversion is specified, +preserve the input block size instead of packing short blocks +into the output buffer. +This is particularly efficient since no in-core copy need be done. +.TP +.BI -cbs\ n\^ +Set conversion buffer size. +.TP +.BI -skip\ n\^ +Skip +.I n +input records before copying. +.TP +.BI -iseek\ n\^ +Seek +.I n +records forward on input file +before copying. +.TP +.BI -files\ n\^ +Catenate +.I n +input files (useful only for magnetic tape or similar input device). +.TP +.BI -oseek\ n\^ +Seek +.I n\^ +records from beginning of output file before copying. +.TP +.BI -count\ n\^ +Copy only +.I n +input records. +.TP +.BI -trunc\ n\^ +By default, +.I dd +truncates the output file when it opens it; +.B -trunc +.B 0 +opens it without truncation. +.TP +.BI -quiet\ n\^ +By default, +.I dd +prints the number of blocks read and written +once it is finished. +.B -quiet +.B 1 +silences this summary. +.HP +\fL-conv\ ascii\ \ \ \ \fRConvert +.SM EBCDIC +to +.SM ASCII. +.PD0 +.RS "\w'\fLconv\ \fP'u" +.TP "\w'\fLunblock\ \ \fP'u" +.B ebcdic +Convert +.SM ASCII +to +.SM EBCDIC. +.TP +.B ibm +Like +.B ebcdic +but with a slightly different character map. +.TP +.B block +Convert variable length +.SM ASCII +records to fixed length. +.TP +.B unblock +Convert fixed length +.SM ASCII +records to variable length. +.TP +.B lcase +Map alphabetics to lower case. +.TP +.B ucase +Map alphabetics to upper case. +.TP +.B swab +Swap every pair of bytes. +.TP +.B noerror +Do not stop processing on an error. +.TP +.B sync +Pad every input record to +.I ibs\^ +bytes. +.RE +.PD +.PP +.fi +Where sizes are specified, +a number of bytes is expected. +A number may end with +.L k +or +.LR b +to specify multiplication by +1024 or 512 respectively; +a pair of numbers may be separated by +.L x +to indicate a product. +Multiple conversions may be specified in the style: +.LR "-conv ebcdic,ucase" . +.PP +.L Cbs\^ +is used only if +.LR ascii\^ , +.LR unblock\^ , +.LR ebcdic\^ , +.LR ibm\^ , +or +.L block\^ +conversion is specified. +In the first two cases, +.I n +characters are copied into the conversion buffer, any specified +character mapping is done, +trailing blanks are trimmed and new-line is added +before sending the line to the output. +In the latter three cases, characters are read into the +conversion buffer and blanks are added to make up an +output record of size +.IR n . +If +.L cbs\^ +is unspecified or zero, the +.LR ascii\^ , +.LR ebcdic\^ , +and +.L ibm\^ +options convert the character set without changing the block +structure of the input file; the +.L unblock\^ +and +.L block\^ +options become a simple file copy. +.SH SOURCE +.B /sys/src/cmd/dd.c +.SH "SEE ALSO" +.IR cp (1) +.SH DIAGNOSTICS +.I Dd +reports the number of full + partial input and output +blocks handled. diff --git a/sys/man/1/delkey b/sys/man/1/delkey new file mode 100755 index 000000000..2f8bbd039 --- /dev/null +++ b/sys/man/1/delkey @@ -0,0 +1,42 @@ +.TH DELKEY 1 +.SH NAME +delkey \- delete keys from factotum +.SH SYNOPSIS +.B delkey +[ +.B -f +] +.I pattern +.SH DESCRIPTION +.I Delkey +shows the user each key stored in +.IR factotum (4) +and matching the +.IR pattern , +prompting for whether the key should be deleted. +At each prompt, typing a response beginning with +.B y +deletes the key, typing a response beginning with +.B q +aborts the listing, +and any other response skips over the key. +.PP +The +.B -f +option disables the prompting; all keys matching the pattern are deleted. +.PP +When run on a CPU server, +.I delkey +uses the terminal's factotum, if present, instead of the server's factotum. +.SH FILES +.TP +.B /mnt/term/mnt/factotum +First choice for +.I factotum +to use +.TP +.B /mnt/factotum +Second choice +.PP +.SH SOURCE +.B /rc/bin/delkey diff --git a/sys/man/1/deroff b/sys/man/1/deroff new file mode 100755 index 000000000..ff94859fe --- /dev/null +++ b/sys/man/1/deroff @@ -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. +.PP +Text inside macros is emitted at place of +definition, not place of call. diff --git a/sys/man/1/diff b/sys/man/1/diff new file mode 100755 index 000000000..91d3d491a --- /dev/null +++ b/sys/man/1/diff @@ -0,0 +1,176 @@ +.TH DIFF 1 +.SH NAME +diff \- differential file comparator +.SH SYNOPSIS +.B diff +[ +.B -abcefmnrw +] +.I 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 +The +.B -c +option includes three lines of context around each +change, merging changes whose contexts overlap. +In this mode, +.I diff +prints +.L - +and +.L + +instead of +.L < +and +.L > +because the former are easier to distinguish when mixed. +The +.B -a +flag displays the entire file as context. +.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), +.IR idiff (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'. +.PP +When running +.I diff +on directories, the notion of what is a text +file is open to debate. diff --git a/sys/man/1/doc2txt b/sys/man/1/doc2txt new file mode 100755 index 000000000..9b85e9f8f --- /dev/null +++ b/sys/man/1/doc2txt @@ -0,0 +1,161 @@ +.TH DOC2TXT 1 +.SH NAME +doc2txt, doc2ps, wdoc2txt, xls2txt, olefs, mswordstrings, msexceltables +\- extract printable text from Microsoft documents +.SH SYNOPSIS +.B doc2txt +[ +.I file.doc +] +.br +.B doc2ps +[ +.I file.doc +] +.br +.B wdoc2txt +[ +.I file.doc +] +.br +.B xls2txt +[ +.I file.xls +] +.br +.B aux/olefs +[ +.B -m +.I mtpt +] +.I file.doc +.br +.B aux/mswordstrings +.IB mtpt /WordDocument +.br +.B aux/msexceltables +[ +.B -qaDnt +] [ +.B -d +.I delim +] [ +.B -c +.I column-range +] [ +.B -w +.I worksheet-range +] +.IB mtpt /Workbook +.SH DESCRIPTION +.I Doc2txt +is an +.IR rc (1) +script that uses +.I olefs +and +.I mswordstrings +to extract the printable text from the body of a Microsoft Word document +and write it on the standard output. +.I Doc2ps +is similar, but emits PostScript corresponding to the document. +.I Wdoc2txt +is similar to +.IR doc2txt , +but uses +.IR plumb (1) +to send the output to a new +.IR acme (1) +window instead. +.I Xls2txt +performs a similar function for Microsoft Excel documents. +.PP +Microsoft Office documents are stored in OLE (Object Linking and Embedding) +format, which is a scaled down version of Microsoft's FAT file system. +.I Olefs +presents the contents of an MS Office document as a file system +on +.IR mtpt , +which defaults to +.BR /mnt/doc . +.I Mswordstrings +or +.I msexceltables +may then be used to parse the files inside, extracting +a text stream. +.I Msexceltables +may be given options to control the formatting of its output. +.TF "\fL-d \fIdelim" +.TP +.B -a +Attempt conversion of non-tabular sheets in the workbook (charts). +.TP +.BI -d " delim +Sets the inter-field delimiter to the string +.IR delim , +by default a single space. +.TP +.B -D +Enables debugging output. +.TP +.BI -c " range +.I Range +is a comma-separated list of column numbers and ranges. +Ranges are separated by dashes. +Limit processing to just those columns named; +by default all columns are output. +.TP +.B -n +Disables field padding to column width. +.TP +.B -q +Disable quoting of textural fields (see +.IR quote (2).) +.TP +.B -t +Truncate fields to the column width. +.TP +.BI -w " range +.I Range +is a comma-separated list of worksheet numbers and ranges, this +limits the sheets output using the same syntax as the +.B -c +option above. +Suppressed chart pages are always included in the sheet count. +.SH EXAMPLE +Extract pieces of an MS Excel spreadsheet. +.PD 0 +.IP +.EX +.SM +aux/olefs report.xls +msexceltables -q -w 1,7,9-14 -c 3-5 -n -d '@' /mnt/doc/Workbook > rpt.txt +unmount /mnt/doc +.EE +.PD +.SH SOURCE +.TF "\fL/sys/src/cmd/aux " +.TP +.B /rc/bin +.BR doc2txt , +.BR doc2ps , +.BR wdoc2txt, +and +.BR xls2txt +.TP +.B /sys/src/cmd/aux +the others +.fi +.PD +.SH SEE ALSO +.IR strings (1) +.br +``Microsoft Word 97 Binary File Format'', +at Microsoft's developer (MSDN) home page. +.br +``LAOLA Binary Structures'', +.B http://user.cs.tu-berlin.de/~schwartz/pmh +.br +``OpenOffice.Org's Excel Documentation'', +.br +.B http://sc.openoffice.org/excelfileformat.pdf diff --git a/sys/man/1/doctype b/sys/man/1/doctype new file mode 100755 index 000000000..7811f8e92 --- /dev/null +++ b/sys/man/1/doctype @@ -0,0 +1,63 @@ +.TH DOCTYPE 1 +.SH NAME +doctype \- intuit command line for formatting a document +.SH SYNOPSIS +.B doctype +[ +.B -n +] +[ +.B -T +.I dev +] +[ +.I file +] +\&... +.SH DESCRIPTION +.I Doctype +examines a +.IR troff (1) +input file to deduce the appropriate text formatting command +and prints it on standard output. +.I Doctype +recognizes input for +.IR troff (1), +related preprocessors like +.IR eqn (1), +and the +.IR ms (6) +and +.I mm +macro packages. +.PP +Option +.B -n +invokes +.I nroff +instead of +.IR troff . +The +.B -T +option is passed to +.IR troff . +.SH EXAMPLES +.TP +.L +eval `{doctype chapter.?} | lp +Typeset files named +.BR chapter.0 , +.BR chapter.1 , +\&... +.SH SOURCE +.B /rc/bin/doctype +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR ms (6), +.IR man (6) +.SH BUGS +In true A.I. style, its best guesses are inspired rather than accurate. diff --git a/sys/man/1/du b/sys/man/1/du new file mode 100755 index 000000000..c7ecc71e6 --- /dev/null +++ b/sys/man/1/du @@ -0,0 +1,137 @@ +.TH DU 1 +.SH NAME +du \- disk usage +.SH SYNOPSIS +.B du +[ +.B -aefhnqstu +] [ +.B -b +.I size +] [ +.B -p +.I SI-prefix +] [ +.I file ... +] +.SH DESCRIPTION +.I Du +gives the number of Kbytes allocated to data blocks +of named +.I files +and, recursively, of files in named directories. +It assumes storage is quantized in units of 1024 bytes (Kbytes) by default. +Other values can be set by the +.B -b +option; +.I size +is the number of bytes, optionally suffixed +.B k +to specify multiplication by 1024. +If +.I file +is missing, +the current directory is used. +The count for a directory includes the counts of the +contained files and directories. +.PP +The +.B -a +option prints the number of blocks +for every file in a directory. +Normally counts are printed only for contained directories. +.PP +The +.B -f +option suppresses the printing of warning messages. +.PP +The +.B -n +option prints the size in bytes and the name of each file; it sets +.BR -a . +.PP +The +.B -t +option prints, in the format of +.B du +.BR -n , +the modified time of +each file rather than the size. +If the options +.B -tu +are specified then the accessed time is printed. +.PP +The +.B -q +option prints, in the format of +.B du +.BR -n , +the QID path of +each file rather than the size. +.PP +The +.B -s +option causes +.I du +to descend the hierarchy as always, but to print only a summary line +for each +.IR file . +.PP +The +.B -e +option causes +.I du +to print values (sizes, times or QID paths) +in `scientific notation' via +.IR print (2)'s +.BR %g . +.PP +The +.B -h +option causes +.I du +to print values (sizes, times or QID paths) +in scientific notation, +scaled to less than 1024, and with a suitable SI prefix +(e.g., +.L G +for binary gigabytes). +.PP +The +.B -p +option causes +.I du +to print values (sizes, times or QID paths) +in units of +.IR SI-prefix . +Case is ignored when looking up +.IR SI-prefix . +An empty +.IR SI-prefix +corresponds to a scale factor of 1 (e.g., print sizes in bytes). +.\" .PP +.\" The +.\" .B -r +.\" option causes +.\" .I du +.\" to read and discard every byte of every file encountered. +.SH EXAMPLES +Print the size of +.L /tmp +in fractional binary gigabytes: +.IP +.EX +% du -sepg /tmp +\&.6960154 /tmp +.EE +.LP +Print the size of +.L /tmp +in bytes and in scientific notation: +.IP +.EX +% du -sep '' /tmp +7.473408e+08 /tmp +.EE +.SH SOURCE +.B /sys/src/cmd/du.c diff --git a/sys/man/1/echo b/sys/man/1/echo new file mode 100755 index 000000000..86e6cd39b --- /dev/null +++ b/sys/man/1/echo @@ -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/sys/man/1/ecp b/sys/man/1/ecp new file mode 100755 index 000000000..6be90dfc3 --- /dev/null +++ b/sys/man/1/ecp @@ -0,0 +1,141 @@ +.TH ECP 1 +.SH NAME +ecp \- fast copy, handling errors +.SH SYNOPSIS +.in +.5i +.ti -.5i +.B ecp +[ +.B \-bcprvZ +] [ +.B \-B +.I block-size +] [ +.B \-e +.I max-errors +] [ +.B \-i +.I issect +] [ +.B \-o +.I ossect +] [ +.B \-s +.I sector-size +] +.I sectors +.I input +.I output +.SH DESCRIPTION +.I Ecp +copies +.I sectors +disk sectors of the specified +.I input +file to the specified +.I output +file. +.I Ecp +copies multiple sectors (a `block') at a time for speed. +When +.I ecp +encounters an I/O error, +it transfers the current block again, +assuming the file is seekable, +one sector at a time, +prints the sector number(s) of the error(s), +and continues copying. +.PP +Options are: +.TP 4 +.B \-b +reblock +.IR input +on short reads; +this was used mainly when reading a pipe on standard input +on 4.2+BSD systems. +.TP +.B \-B +sets the block size (16,384 bytes by default) to +.IR block-size . +.TP +.B \-c +ask for confirmation on +.B /dev/cons +before starting the copy. +.TP +.B \-e +sets a maximum number of consecutive I/O errors to permit +at the beginning of the copy before quitting to +.IR max-errors . +Lots of consecutive errors may indicate a deeper problem, +such as missing media. +By default there is no limit. +.TP +.B \-i +seeks to sector +.I issect +(assuming zero-origin) +before beginning input. +.TP +.B \-o +seeks to sector +.I ossect +(assuming zero-origin) +before beginning output. +.TP +.B \-p +print reassuring progress reports; +helpful mainly when dealing with cranky hardware. +.TP +.B \-r +copy sector groups in reverse order, +assuming the files are seekable; +this is most useful when +.I input +and +.I output +overlap. +.TP +.B \-s +sets the sector size (512 bytes by default) to +.IR sector-size . +.TP +.B \-v +verify the copy by rereading the +.I input +and +.I output +files after copying all sectors. +This is intended to force the disk to deliver the actual +data written on it rather than some cached copy. +The locations of any differences are printed. +.TP +.B \-Z +`Swizzle' the input: stir the bits around in some fashion. +Intended for diagnosing bad disks by copying a disk to itself +a few times with swizzling on (to defeat caching in operating systems +or disk controllers). +.SH "SEE ALSO" +.I fcp +in +.IR cp (1), +.IR dd (1), +.IR dup (3) +.SH BUGS +.BR \-i , +.BR \-o , +.BR \-r , +.B \-v +and error retries only work on devices capable of seeking. +.PP +The set of options reflects decades of experience +dealing with troublesome hardware. +.PP +If the input file is a tape and +the last record on the tape before a file mark is less than +.I blocksize +bytes long, +then +.I ecp +will read through past the file mark and into the next file. diff --git a/sys/man/1/ed b/sys/man/1/ed new file mode 100755 index 000000000..adb79fb72 --- /dev/null +++ b/sys/man/1/ed @@ -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/sys/man/1/emacs b/sys/man/1/emacs new file mode 100755 index 000000000..3854c528f --- /dev/null +++ b/sys/man/1/emacs @@ -0,0 +1,17 @@ +.TH EMACS 1 +.SH NAME +emacs \- editor macros +.SH SYNOPSIS +.B emacs +[ +.I options +] +.SH DESCRIPTION +This page intentionally left blank. +.SH SOURCE +MIT +.SH SEE ALSO +.IR sam (1), +.IR vi (1) +.SH BUGS +Yes. diff --git a/sys/man/1/eqn b/sys/man/1/eqn new file mode 100755 index 000000000..7c917cdbe --- /dev/null +++ b/sys/man/1/eqn @@ -0,0 +1,339 @@ +.TH EQN 1 +.EQ +delim $$ +.EN +.SH NAME +eqn \- typeset mathematics +.SH SYNOPSIS +.B eqn +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Eqn +is a +.IR troff (1) +preprocessor +for typesetting mathematics +on a typesetter. +Usage is almost always +.IP +.L +eqn file ... | troff +.PP +If no files are specified, +.I eqn +reads from the standard input. +.I Eqn +prepares output for the typesetter +named in the +.BI -T dest +option (default +.BR -Tutf ; +see +.IR troff (1)). +When run with other preprocessor filters, +.I eqn +usually comes last. +.PP +A line beginning with +.B .EQ +marks the start of an equation; +the end of an equation +is marked by a line beginning with +.BR .EN . +Neither of these lines is altered, +so they may be defined in macro packages +to get +centering, numbering, etc. +It is also possible to set two characters +as `delimiters'; +text between delimiters is also +.I eqn +input. +Delimiters may be set to characters +.I x +and +.I y +with the option +.BI -d xy +or (more commonly) with +.B delim +.I xy +between +.B .EQ +and +.BR .EN . +Left and right delimiters may be identical. +(They are customarily taken to be +$font L "$$" )$. +Delimiters are turned off by +.LR "delim off" . +All text that is neither between delimiters nor between +.B .EQ +and +.B .EN +is passed through untouched. +.PP +Tokens within +.I eqn +are separated by +spaces, tabs, newlines, braces, double quotes, +tildes or circumflexes. +Braces {} are used for grouping; +generally speaking, +anywhere a single character like +.L x +could appear, a complicated construction +enclosed in braces may be used instead. +Tilde +.L ~ +represents a full space in the output, +circumflex +.L ^ +half as much. +.PP +.vs 13p +Subscripts and superscripts are produced with the keywords +.B sub +and +.BR sup . +Thus +.L "x sub i" +makes +$x sub i$, +.L "a sub i sup 2" +produces +$a sub i sup 2$, +and +.L "e sup {x sup 2 + y sup 2}" +gives +$e sup {x sup 2 + y sup 2}$. +.PP +.B Over +makes fractions: +.L "a over b" +yields $a over b$. +.PP +.B Sqrt +produces square roots: +.L "1 over sqrt {ax sup 2 +bx+c}" +results in +$1 over sqrt {ax sup 2 +bx+c}$ . +.PP +The keywords +.B from +and +.B to +introduce lower and upper +limits on arbitrary things: +$lim from {n -> inf} sum from 0 to n x sub i$ +is made with +.LR "lim from {n -> inf} sum from 0 to n x sub i" . +.PP +Left and right brackets, braces, etc., of the right height are made with +.B left +and +.BR right : +.L "left [ x sup 2 + y sup 2 over alpha right ] ~=~1" +produces +$left [ x sup 2 + y sup 2 over alpha right ] ~=~1$. +The +.B right +clause is optional. +Legal characters after +.B left +and +.B right +are braces, brackets, bars, +.B c +and +.B f +for ceiling and floor, +and +.B +"" +for nothing at all (useful for a right-side-only bracket). +.PP +Vertical piles of things are made with +.BR pile , +.BR lpile , +.BR cpile , +and +.BR rpile : +.L "pile {a above b above c}" +produces +$pile {a above b above c}$. +There can be an arbitrary number of elements in a pile. +.B lpile +left-justifies, +.B pile +and +.B cpile +center, with different vertical spacing, +and +.B rpile +right justifies. +.PP +Matrices are made with +.BR matrix : +.L "matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }" +produces +$matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }$. +In addition, there is +.B rcol +for a right-justified column. +.PP +.vs 12p +Diacritical marks are made with +.BR prime , +.BR dot , +.BR dotdot , +.BR hat , +.BR tilde , +.BR bar , +.BR under , +.BR vec , +.BR dyad , +and +.BR under : +.L "x sub 0 sup prime = f(t) bar + g(t) under" +is +$x sub 0 sup prime = f(t) bar + g(t) under$, +and +.L "x vec = y dyad" +is +$x vec = y dyad$. +.PP +Sizes and fonts can be changed with prefix operators +.B size +.IR n , +.B size +.BI ± n \f1, +.BR fat , +.BR roman , +.BR italic , +.BR bold , +or +.BR font +.IR n . +Size and fonts can be changed globally in a document by +.B gsize +.I n +and +.B gfont +.IR n , +or by the command-line arguments +.BI -s n +and +.BI -f n\f1. +.PP +Normally subscripts and superscripts are reduced by +3 point sizes from the previous size; +this may be changed by the command-line argument +.BI -p n\f1. +.PP +Successive display arguments can be lined up. +Place +.B mark +before the desired lineup point in the first equation; +place +.B lineup +at the place that is to line up vertically in subsequent equations. +.PP +Shorthands may be defined +or existing keywords redefined with +.BR define : +.L define +.I thing +.L % +.I replacement +.L % +defines a new token called +.I thing +which will be replaced by +.I replacement +whenever it appears thereafter. +The +.L % +may be any character that does not occur in +.LR replacement . +.PP +Keywords like +.L sum +.EQ +( sum ), +.EN +.L int +.EQ +( int ), +.EN +.L inf +.EQ +( inf ), +.EN +and shorthands like +.L >= +.EQ +(>=), +.EN +.L -> +.EQ +(->), +.EN +and +.L != +.EQ +( != ) +.EN +are recognized. +Greek letters are spelled out in the desired case, as in +.L alpha +or +.LR GAMMA . +Mathematical words like +.LR sin , +.LR cos , +.L log +are made Roman automatically. +.IR Troff (1) +four-character escapes like +.L \e(lh +(\(lh) can be used anywhere. +Strings enclosed in double quotes " " +are passed through untouched; +this permits keywords to be entered as text, +and can be used to communicate +with +.I troff +when all else fails. +.SH FILES +.TF /sys/lib/troff/font/devutf +.TP +.B /sys/lib/troff/font/devutf +font descriptions for PostScript +.SH SOURCE +.B /sys/src/cmd/eqn +.SH "SEE ALSO" +.IR troff (1), +.IR tbl (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual''. +.br +B. W. Kernighan and L. L. Cherry, +``Typesetting Mathematics\(emUser's Guide'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH BUGS +To embolden digits, parens, etc., +it is necessary to quote them, +as in +.LR bold\ "12.3" . +.EQ +delim off +.EN diff --git a/sys/man/1/expect b/sys/man/1/expect new file mode 100755 index 000000000..95ea52b30 --- /dev/null +++ b/sys/man/1/expect @@ -0,0 +1,172 @@ +.TH EXPECT 1 +.SH NAME +at, drain, expect, pass \- dialer scripting tools +.SH SYNOPSIS +.B dial/at +[ +.B -q +] [ +.B -t +.I seconds +] +atcommand +.br +.B dial/expect +[ +.B -iq +] [ +.B -t +.I seconds +] +.I goodstring +[ +.IR badstring ... +] +.br +.B dial/drain +.br +.B dial/pass +[ +.B -q +] +.SH DESCRIPTION +These commands are used to write telephone dialing +scripts, mostly for PPP sessions. They all expect standard input and +output to be connected to a communications device, e.g, +a serial line to a modem. They communicate with the user using +.BR /dev/cons . +.PP +.I At +sends +.B atcommand +to the modem prefixed with the string +.BR at . +It then reads from the modem expecting an AT response. +.I At +will return success if it gets and +.B OK +of +.B CONNECT +response. Otherwise it will return the response as an +error status. The options are: +.TP +.B -t +set the timeout to +.IR seconds . +The default is 300. +.TP +.B -q +don't write to +.B /dev/cons +what is read from standard in. The default is +to copy everything through. +.PD +.PP +.I Expect +reads standard input looking for one of the strings given +as arguments. Reading the first string causes a successul exit +status. Reading any of the others causes an exit status equal to +the string. The command also terminates on a timeout. The options +are: +.TP +.B -t +set the timeout to +.IR seconds . +The default is 300. +.TP +.B -i +ignore case when doing the matches. +.TP +.B -q +don't write to +.B /dev/cons +what is read from standard in. The default is +to copy everything through. +.PD +.PP +.I Pass +copies input from +.B /dev/cons +to standard output. +It terminates on a newline. The only flag is +.B -q +and means the same as it does for +.IR expect . +.PP +.I Drain +discards any input waiting on standard input. It +is used to sync up the stream at the start of dialing +or after an error. +.SH EXAMPLE +The following +.B rc +script dials out through a Hayes compatible modem on +.B /dev/eia1 +and lets the user type in a user name and password +before starting +.BR ppp . +.EX +#!/bin/rc +dev=/dev/eia1 +telno=18005551212 + +fn initfn { + dial/drain + echo +++ + dial/at zh0 +} + +fn dialfn { + dial/drain + dial/at dt^$telno +} +{ + # set up uart + if( test -e $dev^ctl ){ + echo -n b^$baud + echo -n m1 # cts/rts flow control + echo -n q64000 # big buffer + echo -n n1 # nonblocking writes + echo -n r1 # rts on + echo -n d1 # dtr on + echo -n c1 # handup when we lose dcd + } > $dev^ctl + + # get the modem's attention + while( ! initfn ) + sleep 1 + + # dial + while( ! dialfn ) + sleep 30 + + if( ! dial/expect -it 60 'username:' ){ + echo can''t connect >[1=2] + exit connect + } + dial/pass + if( ! dial/expect -it 60 'password:' ){ + echo can''t connect >[1=2] + exit connect + } + dial/pass + if( ! dial/expect -t 60 'ppp or telnet:' ){ + echo can''t connect >[1=2] + exit connect + } + echo ppp + dial/expect -t 5 something + echo connected >[1=2] + + # start ppp + ip/ppp $primary -f +} < $dev > $dev +.EE +.SH FILES +.B /rc/bin/ipconf/* +example dialer scripts for ppp +.SH SOURCE +.B /sys/src/cmd/dial/*.c +.SH SEE ALSO +.IR ppp (8), +.IR telco (4) diff --git a/sys/man/1/faces b/sys/man/1/faces new file mode 100755 index 000000000..633fb688b --- /dev/null +++ b/sys/man/1/faces @@ -0,0 +1,124 @@ +.TH FACES 1 +.SH NAME +faces, seemail, vwhois \- mailbox interface +.SH SYNOPSIS +.B faces +[ +.B -ih +] [ +.B -m +.I maildir +] +.br +.B seemail +.br +.B vwhois +.I person +\&... +.SH DESCRIPTION +The +.I faces +command monitors incoming mail and +displays in its window a representation of the user's mail box +using a small image for each message. +The image is typically a portrait of the sender. Which image to +display is determined by two directories /usr/$user/lib/face +and /lib/face. Entries in /usr/$user/lib/face take priority over +those in /lib/face. See +.IR face (6), +for how these directories are organised. +.PP +If the user is running +.IR plumber (4), +.I faces +reacts to plumb messages to the +.B seemail +port, +typically from +.BR upas/fs , +and is thus notified of message additions and deletions. +.PP +Right-clicking on a message icon causes that message to be `plumbed' to +.BR showmail . +A typical plumb action will be to display the message, such as by +the rule +.EX + plumb start window mail -s $0 +.EE +The +.IR acme (1) +mail reader listens to the +.B showmail +port automatically. +.PP +If the user is not running +.IR plumber , +.I faces +reads the log file +.F /sys/log/mail +and right-clicking has no effect. +.PP +If arrows are visible, clicking on them will scroll the display. +Middle-clicking on the arrows scrolls to the end. +.PP +Starting +.B faces +with the +.B -i +flag causes +.B faces +to read the messages in +.BR /mail/fs/mbox +— or the mailboxes specified with the +.B -m +flag — +upon startup. +.PP +The +.B -m +option directs +.I faces +to watch for messages arriving in +.I maildir +instead of +.BR /mail/fs/mbox . +Multiple +.B -m +flags may be used to watch multiple mailboxes. +.PP +The +.B -h +flag causes a different, venerable behavior in which +the window displays the history of messages received +rather than the current state of the mail box. +In particular, faces are not removed from the screen when messages are deleted. +Also, in this mode clicking button 1 in the display will clear the window. +.PP +.I Seemail +is an +.IR rc (1) +script that invokes +.B faces +.BR -h . +.PP +.I Vwhois +tells +.I faces +to display the icons of the named +.IR persons , +without sending a message. +.SH FILES +.BR /mail/fs/mbox " mail directory. +.SH SOURCE +.B /sys/src/cmd/faces +.br +.B /rc/bin/seemail +.br +.B /rc/bin/vwhois +.SH "SEE ALSO" +.IR mail (1), +.IR marshal (1), +.IR nedmail (1), +.IR plumber (4), +.IR face (6), +.IR plumb (6) diff --git a/sys/man/1/factor b/sys/man/1/factor new file mode 100755 index 000000000..10baf9960 --- /dev/null +++ b/sys/man/1/factor @@ -0,0 +1,64 @@ +.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/sys/man/1/fedex b/sys/man/1/fedex new file mode 100755 index 000000000..0434382ec --- /dev/null +++ b/sys/man/1/fedex @@ -0,0 +1,27 @@ +.TH FEDEX 1 +.SH NAME +fedex, ups, usps \- track shipments +.SH SYNOPSIS +.B fedex +.I tracking-number +.br +.B ups +.I tracking-number +.br +.B usps +.I tracking-number +.SH DESCRIPTION +.I Fedex +writes available shipment details for the given Federal Express 12-digit +.I tracking-number +on the standard output. +.I Ups +is similar, but takes a United Parcel Service 18-digit +.IR tracking-number . +.I Usps +takes a US Post Office +.IR tracking-number . +.SH SOURCE +.B /rc/bin +.SH BUGS +Redesigns of the source website can break these programs. diff --git a/sys/man/1/file b/sys/man/1/file new file mode 100755 index 000000000..40b0d3b64 --- /dev/null +++ b/sys/man/1/file @@ -0,0 +1,112 @@ +.TH FILE 1 +.SH NAME +file \- determine file type +.SH SYNOPSIS +.B file +[ +.B -m +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I File +performs a series of tests on its argument +.I files +in an attempt to classify their contents by language or purpose. +If no arguments are given, the classification is performed +on standard input. +.PP +If the +.B -m +flag is given, +.I file +outputs an +appropriate MIME +.B Content-Type +specification describing the +.B type +and +.B subtype +of each file. +.PP +The file types it looks for include +directory, +device file, +zero-filled file, +empty file, +Plan 9 executable, +PAC audio file, +.B cpio +archive, +.B tex +.B dvi +file, +archive symbol table, +archive, +.B rc +script, +.B sh +script, +PostScript, +.B troff +output file for various devices, +mail box, +GIF, +FAX, +object code, +C and Alef source, +assembler source, +compressed files, +encrypted file, +English text, +compressed image, +image, +subfont, +and +font. +.PP +If a file has no apparent format, +.I file +looks at the character set it uses to classify it according to +.SM ASCII\c +, +extended +.SM ASCII\c +, Latin +.SM ASCII\c +, or +.SM UTF +holding one or more of the following blocks of the Unicode Standard: +Extended Latin, +Greek, +Cyrillic, +Armenian, +Hebrew, +Arabic, +Devanagari, +Bengali, +Gurmukhi, +Gujarati, +Oriya, +Tamil, +Telugu, +Kannada, +Malayalam, +Thai, +Lao, +Tibetan, +Georgian, +Japanese, +Chinese, +or Korean. +.PP +If all else fails, +.I file +decides its input is +binary. +.SH SOURCE +.B /sys/src/cmd/file.c +.SH BUGS +It can make mistakes. diff --git a/sys/man/1/filter b/sys/man/1/filter new file mode 100755 index 000000000..ae86aa336 --- /dev/null +++ b/sys/man/1/filter @@ -0,0 +1,320 @@ +.TH FILTER 1 +.SH NAME +filter, list, deliver, token, vf \- filtering mail +.SH SYNOPSIS +.B upas/filter +[ +.B -bh +] +.I rcvr +.I mailbox +[ +.I "regexp file +] ... +.PP +.B upas/list +[ +.B -d +] +.B add|check +.I patternfile +.I addressfile ... +.PP +.B upas/deliver +.I recipient +.I fromfile +.I mbox +.PP +.B upas/token +.I key +[ +.I tokenfile +] +.PP +.B upas/vf +[ +.B -r +] +[ +.B -s +.I savefile +] +.SH DESCRIPTION +A user may filter all incoming mail by creating +a world readable/executable file +.BI /mail/box/ username /pipeto. +If the file is a shell script, it can use the +commands described here to implement a filter. +.PP +.I Filter +provides simple mail filtering. +The first two arguments are the recipient's address and mailbox, that is, +the same arguments provided to +.BR pipeto . +The remaining arguments are all pairs of a regular expression and a file name. +With no flags, the sender's address is matched against each +regular expression starting with the first. If the expression +matches, then the message is delivered to the file whose name +follows the expression. The file must be world writable and should +be append only. +A message that matches none of the expressions is delivered into +the user's standard mail box. +.PP +By default, +.I filter +matches each regular expression against the message's sender. +The +.B -h +flag causes +.I filter +to match against the entire header, +and the +.B -b +flag causes +.I filter +to match against the entire message (header and body). +.PP +For example, to delete any messages of precedence bulk, place in +your +.B pipeto +file: +.IP +.EX +/bin/upas/filter -h $1 $2 'Precedence: bulk' /dev/null +.EE +.PP +Three other commands exist which, combined by an +.IR rc (1) +script, allow you to build your own filter. +.PP +.I List +takes two verbs; +.B check +and +.BR add . +.B Check +directs +.I list +to check each address contained in the +.IR addressfile s +against a list of patterns in +.IR patternfile . +Patterns come in four forms: +.TF ~\fIregular-expression\fP +.PD +.TP +.B ~\fIregular-expression\fP +If any address matches the regular expression, +.I list +returns successfully. +.TP +.BR =\fIstring\fP . +If any address exactly matches +.IR string , +.I list +returns successfully. +.TP +.B !~\fIregular-expression\fP +If any address matches the regular expression +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.TP +.B !=\fIstring\fP +If any address exactly matches +.I string +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.PP +If no addresses match a pattern, +.I list +returns "no match". +.PP +The pattern file may also contain lines of the form +.IP +.EX +#include filename +.EE +.LP +to allow pattern files to include other pattern files. +All pattern matches are case insensitive. +.I List +searches the pattern file (and its includes) in order. +The first matching pattern determines the action. +.PP +.I List +.B add +directs +.I list +to add a pattern to +.I patternfile +for each address in the +.I addressfiles +that doesh't already match a pattern. +.PP +.IR Token , +with only one argument, prints to standard output a unique token +created from the current date and +.IR key . +With two arguments, it checks +.I token +against tokens created over the last 10 days with +.IR key . +If a match is found, it returns successfully. +.PP +.I Deliver +delivers into mail box +.I mbox +the message read from standard input. +It obeys standard mail file locking and logging +conventions. +.PP +.B /sys/src/cmd/upas/filterkit/pipeto.sample +is a sample +.B pipeto +using the filter kit. +.PP +A sample +.BR pipefrom , +.BR /sys/src/cmd/upas/filterkit/pipefrom.sample , +is provided which adds all addresses of your outgoing +mail to your pattern file. +You should copy it into a directory that normally gets +bound by your profile onto +.BR /bin . +.PP +.I Vf +(virus filter) +takes a mail message as standard input +and searches for executable MIME attachments, +either rewriting them to be non-executable or +rejecting the message. +The behavior depends on the attachment's file name +extension and MIME content type. +.B /sys/lib/mimetype +contains the list of known extensions and MIME content types. +The fifth field of each line specifies the +safety of a particular file type: +.B y +(yes), +.B m +(maybe; treated same as yes), +.B n +(no), +.B p +(previous), +or +.B r +(reject). +.I Vf +allows attachments with safety +.B y +or +.B m +to pass through unaltered. +Attachments with safety +.B n +both are wrapped in extra MIME headers +and have +.B .suspect +appended to their file names, to avoid +automatic execution by mail readers. +Attachments with safety +.B r +(currently, +.BR .bat , +.BR .com , +.BR .exe , +and +.BR .scr , +all Microsoft executable extensions) +are taken as +cause for the entire message to be rejected. +A safety of +.B p +(used for the +.B x-gunzip +mime type) +causes the previous extension to be tested, +so that +.B x.tar.gz +is treated the same as +.BR x.tar . +.PP +If +.B /mail/lib/validateattachment +exists and is executable, +.B vf +runs it on all attachments with safety +.B n +(attachments it would normally sanitize). +If +.IR validateattachment 's +exit status contains the string +.LR discard , +.I vf +rejects the entire message. +If the status contains the string +.LR accept , +.I vf +does not sanitize the attachment. +Otherwise, +.I vf +sanitizes the attachment as before. +The standard +.I validateattachment +uses +.IR file (1) +to determine the file type. +It accepts text and image files +and discards messages containing +executables or +.I zip +(see +.IR gzip (1)) +archives of executables. +.PP +The +.B -r +option causes +.I vf +not to sanitize MIME attachments, but instead to +reject messages it determines to be viruses. +The +.B -s +option causes +.I vf +to log all attachments of safety +.B r +in the mail box +.IR savefile . +.SH FILES +.TF /mail/lib/validateattachment +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /sys/lib/mimetype +MIME content types +.TP +.B /mail/lib/validateattachment +attachment checker +.SH SOURCE +.B /sys/src/cmd/upas/send +.br +.B /sys/src/cmd/upas/filterkit +.br +.B /sys/src/cmd/upas/vf +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR mail (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/fmt b/sys/man/1/fmt new file mode 100755 index 000000000..511860018 --- /dev/null +++ b/sys/man/1/fmt @@ -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/sys/man/1/fortune b/sys/man/1/fortune new file mode 100755 index 000000000..dfae7186a --- /dev/null +++ b/sys/man/1/fortune @@ -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/sys/man/1/freq b/sys/man/1/freq new file mode 100755 index 000000000..e6b5086f6 --- /dev/null +++ b/sys/man/1/freq @@ -0,0 +1,40 @@ +.TH FREQ 1 +.SH NAME +freq \- print histogram of character frequencies +.SH SYNOPSIS +.B freq +[ +.B -cdorx +] +[ +.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/sys/man/1/games b/sys/man/1/games new file mode 100755 index 000000000..c5a23cb30 --- /dev/null +++ b/sys/man/1/games @@ -0,0 +1,312 @@ +.TH GAMES 1 +.SH NAME +4s, 5s, festoon, juggle, life, mahjongg, memo, sokoban, sudoku \- time wasters +.SH SYNOPSIS +.B games/4s +.br +.B games/5s +.br +.B games/festoon +[ +.B -pet +] [ +.I sentences +[ +.I percent-invented-nouns +] ] +.br +.B games/juggle +[ +.B -d +.I delay +] [ +.B -h +.I hands +] [ +.I start +] +.I pattern +.br +.B games/life +.I startfile +.br +.B games/mahjongg +[ +.B -c +] [ +.B -f +] [ +.B -b +.I background +] [ +.B -t +.I tileset +] [ +.B -l +.I layout +] +.br +.B games/memo +[ +.B -h +] +.br +.B games/sokoban +[ +.I level +] +.br +.B games/sudoku +.SH DESCRIPTION +There are a few games in +.BR /bin/games : +.TF mahjongg +.PD +.TP +.BR 4s , " 5s" +Try to fill complete rows using 4-square or 5-square tiles. +Move tiles left or right by moving the mouse. +Rotate tiles with buttons 1 and 3. +Drop tiles for more points with button 2 or the space bar. +Keys +.LR a +and +.LR j +move left, +.LR s +and +.LR k +rotate left, +.LR d +and +.LR l +rotate right, +.LR f +and +.LR ; +move right. +.LR z , +.LR p +and +.LR Esc +toggle suspend/resume. +.LR q , +.LR Del +and +.LR control-D +quit. +.TP +.B festoon +Generate an official-looking but utterly nonsensical bureaucratic report as +.L "pic | eqn | tbl | troff -mm" +input. +Options +.BR -p , +.B -e +and +.B -t +add gibberish diagrams, equations and tables. +.TP +.B juggle +Display the juggling +.I pattern +using the optional initial +.I start +pattern. +The number of hands involved (default 2) can be specified with +.BR -h , +and +.I delay +can be used to speed up or slow down the action (default is 20). +Try the pattern 333333441333333 or 333353505151512333333 +or YWUSQOMKIGECA +(see +.BR http://seehuhn.de/jong/theory.html ). +.TP +.B life +Play the game of Life, given an initial position. +There is a library of interesting initial positions; +the library is consulted if +.I startfile +cannot be found. +.TP +.B mahjongg +Remove all tiles +from the board. Click on tiles with the same face that +are not blocked by others. A blocked tile is one that is partially or +fully covered on top or has neighbouring tiles to the left and right. +The game finishes when either all tiles are gone or there are no +more moves left. The arguments are for changing background +.RB (-b), +tile +.RB (-t) +and layout +.RB (-l) +images; +.RB -c +selects a true-color buffer image, for use with +drawterm or in case selecting a tile obscures it completely; +.RB -f +causes mahjongg to indicate non-blocked tiles on mouse-over. +The +.LR N +key will generate a new level, +.LR R +restarts the current one. +.LR Q +and +.LR Del +quit, +.LR H +gives a hint, either trying to match the currently selected tile, or if no tile is +selected finding out the first available tile. +.LR U +and +.LR Bksp +undo the last move, +.LR C +tries to solve the level. +.TP +.B memo +Remove all tiles from the board. +At first, pictures of various Bell Labs employees, Lucent Technologies' logo, and Glenda will appear. +Memorize the sequence, then click to hide them and begin. +Use the mouse to select two tiles. +If they are the same, the tiles will disappear, otherwise the tiles will flip back and you will get a chance to try again. +Button 3 generates a memu allowing you to restart, switch between easy and hard modes, and exit. +The +.B -h +option sets the game to hard mode. +Once the game has been completed, a message pops up with how long it took to win. +Use the button 3 menu to choose a mode, or click to play again. +.TP +.B sokoban +Guide Glenda through a room full of walls, pebbles and holes to put +the pebbles in. Your goal is to arrange all pebbles into holes by +pushing them around, but you can only push a pebble if there is no +wall or another pebble blocking the way. +Arrow keys move Glenda up-down-left-right. +.LR N +and +.LR P +keys switch between +the next and previous levels, +.LR R +restarts the current level. +.LR Del +and +.LR Q +quit. Button 3 invokes a menu to restart the current level, load different level sets, and en- and disable animation of multi-step moves. +Button 2 lets you change between levels. +Button 1 lets you do multi-step moves and pushes, +by clicking it on the destination where you want Glenda to go. +Glenda will only move if it can reach the destination. +For a multi-step push the pebble must be next to Glenda, +the destination must be on the same row or column, +and there must be a free place next to the destination +where the pebble can be pushed to. +Otherwise, if possible, Glenda will walk to the destination without pushing the pebble. +.I Sokoban +accepts a level file as its argument. +.TP +.B sudoku +.I Sudoku +is a puzzle game from Japan. The goal of the game is to +fill the numbers 1 to 9 in all squares of the 9x9 board following a +few simple rules: no digit should repeat on the same row and column, +and no digit should repeat in the same 3x3 boxes outlined with thicker +lines. The board is initially filled with a partial solution which +can be used for inferring digits for the empty squares. The top row +of the board contains the digits 1 through 9, clicking on one of those +digits selects that number for placement on the board, clicking it +again will deselect that digit. Clicking on an empty square will then +affix the square with the selected digit or, if no digit is selected +empty the square. +.IP +Button 3 presents a menu with the following options: +.RS \w'\fLfireworksXX'u +.TP \w'\fLOffsetXX'u +.B New +autogenerate a new, random board +.TP +.B Check +mark in red any digits not placed according to the rules +.TP +.B Solve +present the board's solution +.TP +.B Clear +clear the board to its starting (or last loaded) state +.TP +.B Save +save the current board to +.B /tmp/sudoku-save +.TP +.B Load +load the last saved board from +.B /tmp/sudoku-save +.TP +.B Print +print the current board and solution in a format +suitable for addition in the +.I sudoku +library to +.B /tmp/sudoku-board +.TP +.B Offline +pretty-print the board for off-line solving to +.B /tmp/sudoku-print +.TP +.B Exit +quit the game +.RE +.IP +Button 2 presents a list of +.I sudoku +boards of varying degrees of difficulty from +.BR /sys/games/lib/sudoku/boards . +.IP +Pressing the +.B Q +key quits +.IR sudoku . +.SH FILES +.TF /sys/games/lib/mahjongg/* +.TP +.B /sys/games/lib/[45]scores +score files of +.I 4s +and +.I 5s +.TP +.B /sys/games/lib/life/* +interesting starting positions +.TP +.B /sys/games/lib/mahjongg/* +image sprites, levels and backgrounds used by +.I mahjongg +.TP +.B /lib/face/* +tiles for +.I memo +.TP +.B /sys/games/lib/sokoban/* +image sprites and levels used by +.I sokoban +.TP +.B /sys/games/lib/sudoku/* +images and boards used by +.I sudoku +.SH SOURCE +.B /sys/src/games +.SH BUGS +In +.I 4s +and +.IR 5s , +mouse warping (when the game is resumed, +and when a new tile appears) does not happen when +the mouse cursor is outside the game window. +Those who prefer to use the keyboard without the mouse +cursor blocking the view (or being warped all the time) +may consider this a feature. diff --git a/sys/man/1/grap b/sys/man/1/grap new file mode 100755 index 000000000..b098f8220 --- /dev/null +++ b/sys/man/1/grap @@ -0,0 +1,416 @@ +.TH GRAP 1 +.SH NAME +grap \- pic preprocessor for drawing graphs +.SH SYNOPSIS +.B grap +[ +.I file ... +] +.SH DESCRIPTION +.I Grap +is a +.IR pic (1) +preprocessor for drawing graphs on a typesetter. +Graphs are surrounded by the +.I troff +`commands' +.B \&.G1 +and +.BR \&.G2 . +Data are scaled and plotted, +with tick marks supplied automatically. +Commands exist to modify the frame, +add labels, override the default ticks, +change the plotting style, +define coordinate ranges and transformations, +and include data from files. +In addition, +.I grap +provides the same loops, conditionals, and macro processing that +.I pic +does. +.PP +.BI frame +.B ht +.I e +.B wid +.I e +.B top +.B dotted +.IR ... : +Set the frame around the graph to specified +.B ht +and +.BR wid ; +default is 2 by 3 (inches). +The line +.I styles +.RB ( dotted , +.BR dashed , +.BR invis , +.BR solid +(default)) +of the +.I sides +.RB ( top , +.BR bot , +.BR left , +.BR right ) +of the frame can be set +independently. +.PP +.B label +.I side +.B \&"a label" +.B \&"as a set of strings" +.IR adjust : +Place label on specified side; default side is bottom. +.I adjust +is +.B up +(or +.B down +.B left +.BR right ) +.I expr +to shift default position; +.B width +.I expr +sets the width explicitly. +.PP +.BI ticks +.I side +.B in +.B at +.IR "optname expr, expr, ..." : +Put ticks on +.I side +at +.I "expr, ..., +and label with +.I \&"expr"\f1. +If any +.I expr +is followed by "...", label tick with "...", +and turn off all automatic labels. +If "..." contains +.BR %f 's, +they will be interpreted as +.B printf +formatting instructions for the tick value. +Ticks point +.B in +or +.B out +(default out). +Tick iterator: instead of +.B at +.IR \&... , +use +.BI from +.I expr +.B to +.I expr +.B by +.I "op expr +where +.I op +is optionally +.B +-*/ +for additive or multiplicative steps. +.B by +can be omitted, to give steps of size 1. +If no ticks are requested, they are supplied automatically; +suppress this with +.B ticks +.BR off . +Automatic ticks normally +leave a margin of 7% on each side; set this to anything by +.B margin +.B = +.IR expr . +.PP +.B grid +.I "side linedesc" +.B at +.IR "optname expr, expr, ..." : +Draw grids perpendicular to +.I side +in style +.I linedesc +at +.I "expr, ....\& +Iterators and labels work as with ticks. +.PP +.B coord +.I optname +.B x +.I "min, max" +.B y +.I "min, max" +.B "log x +.BR " log y" : +Set range of coords and optional log scaling on either or both. +This overrides computation of data range. +Default value of +.I optname +is current coordinate system +(each +.B coord +defines a new coordinate system). +.PP +.B plot +.I \&"str" +.B at +.IR point ; +.B +.I \&"str" +.B at +.IR point : +Put +.I str +at +.IR point . +Text position can be qualified with +.BR rjust , +.BR ljust , +.BR above , +.BR below +after "...". +.PP +.B line +.B from +.I point +.B to +.IR "point linedesc" : +Draw line from here to there. +.B arrow +works in place of +.BR line . +.PP +.B next +.I optname +.B at +.IR "point linedesc" : +Continue plot of data in +.I optname to +.IR point ; +default is current. +.PP +.BI draw +.IR "optname linedesc ..." : +Set mode for +.BR next : +use this style from now on, +and plot "..." at each point (if given). +.PP +.BI new +.IR "optname linedesc ..." : +Set mode for +.BR next , +but disconnect from previous. +.PP +A list of numbers +.I "x y1 y2 y3 ... +is treated as +.B plot +.B bullet +.B at +.IR x,y1 ; +.B plot +.B bullet +.B at +.IR x,y2 ; +etc., or as +.B next +.B at +.I x,y1 +etc., if +.B draw +is specified. +Abscissae of 1,2,3,... are provided if there is only one input number per line. +.PP +A +point +.I "optname expr, expr +maps the point to the named coordinate system. +A +.I linedesc +is one of +.B dot +.B dash +.B invis +.B solid +optionally followed by an expression. +.PP +.BI define +.I name +.BI { whatever } \f1: +Define a macro. +There are macros already defined for standard plotting +symbols like +.BR bullet , +.BR circle , +.BR star , +.BR plus , +etc., in +.BR /sys/lib/grap.defines , +which is included if it exists. +.PP +.I var +.B = +.IR expr : +Evaluate an expression. +Operators are +.B= +.B + +.B - +.B * +and +.BR / . +Functions are +.B log +and +.B exp +(both base 10), +.BR sin , +.BR cos , +.BR sqrt ; +.B rand +returns random number on [0,1); +.BI max( e , e )\f1, +.BI min( e , e )\f1, +.BI int( e )\f1. +.PP +.B print +.IR expr ; +.B print +\fL"\f2...\fL"\f1: +As a debugging aid, print +.I expr +or +.I string +on the standard error. +.PP +.B copy +\fL"\fIfile name\fL"\fR: +Include this file right here. +.PP +.B copy +.B thru +.IR macro : +Pass rest of input (until +.BR \&.G2 ) +through +.IR macro , +treating each field (non-blank, or "...") as an argument. +.I macro +can be the name of a macro previously defined, +or the body of one in place, like +.BR "/plot $1 at $2,$3/" . +.PP +.B copy +.B thru +.I macro +.B until +\fL"\fIstring\fL"\fR: +Stop copy when input is +.I string +(left-justified). +.PP +.BI pic +.IR "remainder of line" : +Copy to output with leading blanks removed. +.PP +.BI graph +.IR "Name pic-position" : +Start a new frame, place it at specified position, +e.g., +.B graph +.B Thing2 +.BR "with .sw at Thing1.se + (0.1,0)" . +.I Name +must be capitalized to keep +.I pic +happy. +.PP +.BI \&. "anything at beginning of +.IR line : +Copied verbatim. +.PP +.B sh +.BI % anything +.BR % : +Pass everything between the +.BR % 's +to the shell; +as with macros, +.B % +may be any character and +.I anything +may include newlines. +.PP +.B # +.IR anything : +A comment, which is discarded. +.PP +Order is mostly irrelevant; no category is mandatory. +Any arguments on the +.B \&.G1 +line are placed on the generated +.B \&.PS +line for +.IR pic . +.SH EXAMPLES +.EX +.ps -1 +.vs -1 +\&.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +\&.G2 +.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +.G2 +.ps +.vs +.EE +.SH FILES +.TF /sys/lib/grap.defines +.TP +.B /sys/lib/grap.defines +definitions of standard plotting characters, e.g., bullet +.SH SOURCE +.B /sys/src/cmd/grap +.SH "SEE ALSO" +.IR pic (1), +.IR troff (1) +.br +J. L. Bentley and B. W. Kernighan, +``GRAP\(emA Language for Typesetting Graphs'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/graph b/sys/man/1/graph new file mode 100755 index 000000000..c2c24366c --- /dev/null +++ b/sys/man/1/graph @@ -0,0 +1,155 @@ +.TH GRAPH 1 +.CT 1 numbers graphics +.SH NAME +graph \- draw a graph +.SH SYNOPSIS +.B graph +[ +.I option ... +] +.SH DESCRIPTION +.I Graph +with no options takes pairs of numbers from the +standard input as abscissas +.RI ( x -values) +and ordinates +.RI ( y -values) +of a graph. +Successive points are connected by straight lines. +The graph is encoded on the standard output +for display by +.IR plot (1) +filters. +.PP +If an ordinate is followed by +a nonnumeric string, that string is printed as a +label beginning on the point. +Labels may be surrounded with quotes +.L +" " +in which case they may be empty or contain blanks +and numbers; +labels never contain newlines. +.PP +The following options are recognized, +each as a separate argument. +.TP +.B -a +Supply abscissas automatically; no +.IR x -values +appear in the input. +Spacing is given by the next +argument (default 1). +A second optional argument is the starting point for +automatic abscissas (default 0, or 1 +with a log scale in +.IR x , +or the lower limit given by +.BR -x ). +.TP +.B -b +Break (disconnect) the graph after each label in the input. +.TP +.B -c +Character string given by next argument +is default label for each point. +.TP +.B -g +Next argument is grid style, +0 no grid, 1 frame with ticks, 2 full grid (default). +.TP +.B -l +Next argument is a legend to title the graph. +Grid ranges +are automatically printed as part +of the title unless a +.B -s +option is present. +.TP +.B -m +Next argument is mode (style) +of connecting lines: +0 disconnected, 1 connected. +Some devices give distinguishable line styles +for other small integers. +Mode \-1 (default) begins with style 1 and +rotates styles for successive curves under option +.BR -o . +.TP +.B -o +(Overlay.) +The ordinates for +.I n +superposed curves appear in the input +with each abscissa value. +The next argument is +.IR n . +.TP +.B -p +Next argument is one or more of the characters +.B bcgkmrwy, +choosing pen colors by their initial letter, as in +.IR plot (6). +Successive curves will cycle through the colors in the given order. +.TP +.B -s +Save screen; no new page for this graph. +.TP +.B -x l +If +.B l +is present, +.IR x -axis +is logarithmic. +Next 1 (or 2) arguments are lower (and upper) +.I x +limits. +Third argument, if present, is grid spacing on +.I x +axis. +Normally these quantities are determined automatically. +.TP +.B -y l +Similarly for +.IR y . +.TP +.B -e +Make automatically determined +.I x +and +.I y +scales equal. +.TP +.B -h +Next argument is fraction of space for height. +.TP +.B -w +Similarly for width. +.TP +.B -r +Next argument is fraction of space to move right before plotting. +.TP +.B -u +Similarly to move up before plotting. +.TP +.B -t +Transpose horizontal and vertical axes. +(Option +.B -a +now applies to the vertical axis.) +.PP +If a specified lower limit exceeds the upper limit, +the axis +is reversed. +.SH SOURCE +.B /sys/src/cmd/graph +.SH "SEE ALSO" +.IR plot (1), +.IR grap (1) +.SH BUGS +Segments that run out of bounds are dropped, not windowed. +Logarithmic axes may not be reversed. +Option +.B -e +actually makes automatic limits, rather than automatic scaling, +equal. diff --git a/sys/man/1/grep b/sys/man/1/grep new file mode 100755 index 000000000..8bf2455ee --- /dev/null +++ b/sys/man/1/grep @@ -0,0 +1,109 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.B grep +[ +.B -bchiLlnsv +] +[ +.B -e +] +.I pattern +| +.B -f +.I patternfile +[ +.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/sys/man/1/gs b/sys/man/1/gs new file mode 100755 index 000000000..a65e3e236 --- /dev/null +++ b/sys/man/1/gs @@ -0,0 +1,280 @@ +.TH GS 1 +.\" This file is an edited version of /sys/src/cmd/gs/man/gs.1, to +.\" document the local installation and remove needless background. +.de TQ +.br +.ns +.TP \\$1 +.. +.SH NAME +gs \- Aladdin Ghostscript (PostScript and PDF language interpreter) +.SH SYNOPSIS +.B gs +[ +.I options +] [ +.I files +] ... +.br +.SH DESCRIPTION +Ghostscript is a programming language similar to Adobe Systems' +PostScript and PDF languages, which are in turn similar to Forth. +.I Gs +reads +.I files +in sequence and executes them as Ghostscript programs. +After doing this, it reads further input from the standard input. +If the +.I file +.B - +is named, however, it represents the standard input, which is read +in order and not after the files on the command line. +Each line is interpreted separately. +The `quit' command, or end-of-file, exits the interpreter. +.PP +The interpreter recognizes several switches described below, which may appear +anywhere in the command line and apply to all files thereafter. +.PP +The +.B -h +or +.B -? +options give help and list the available devices; the default is +.BR plan9 , +which produces compressed image files suitable for viewing with +.IR page (1) +(but note that +.IR page (1) +will invoke +.I gs +automatically; see its manual). +.PP +Ghostscript may be built with multiple output devices. Ghostscript +normally opens the first one and directs output to it. To use device xyz +as the initial output device, include the switch +.EX + -sDEVICE=xyz +.EE +in the command line. This switch must precede the first PostScript +file and only its first invocation has any effect. +Output devices can also be selected by the word +.B selectdevice +in the input language, or by setting the environment variable +.BR GS_DEVICE . +The order of precedence for +these alternatives, highest to lowest, is: +.EX + selectdevice + \f1(command line)\fP + GS_DEVICE + plan9 +.EE +.PP +Normally, output goes +directly to a scratch file. +To send the output to a series of files +.BR foo1.xyz , +.BR foo2.xyz , +etc., use the switch +.EX + -sOutputFile=foo%d.xyz +.EE +The %d may be any +.I printf +(see +.IR fprintf (2)) +format specification. Each file will receive one page of output. +If the file name begins with a pipe character, +the output will be sent as standard input to the following pipeline. +For example, +.EX + -sOutputFile=|lp +.EE +Specifying the file +.B - +will send the files to standard output; this also requires enabling the +.B -q +option. +.SS "Initialization files" +When looking for the initialization files +.RB ( gs_*.ps ), +the files related +to fonts, or the file for the +.B run +operator, Ghostscript first looks for the file (if +it doesn't start with a slash) in the current directory, then in these +directories in the following order: +.TP +1. +Any directories specified by +.B -I +switches in the command +line (see below); +.TP +2. +Any directories specified by the +.B GS_LIB +environment variable; +.TP +3. +The directories +.BR /sys/lib/ghostscript , +.BR /sys/lib/ghostscript/font , +and +.BR /sys/lib/postscript/font . +.PP +The +.B GS_LIB +or +.B -I +parameters may be +a single directory or a colon-separated list. +.SS Options +.TP +.BI -- " filename arg1 ..." +Take the next argument as a file name as usual, but take all +remaining arguments (even if they have the syntactic form of switches) +and define the name ARGUMENTS in userdict (not systemdict) as an +array of those strings, +.I before +running the file. When Ghostscript +finishes executing the file, it exits back to the shell. +.TP +.BI -D name = token +.TQ +.BI -d name = token +Define a name in systemdict with the given definition. The token must +be exactly one token (as defined by the `token' operator) and must not +contain any white space. +.TP +.BI -D name +.TQ +.BI -d name +Define a name in systemdict with value=null. +.TP +.BI -S name = string +.TQ +.BI -s name = string +Define a name in systemdict with a given string as value. This is +different from +.BR -d . +For example, +.B -dname=35 +is equivalent to the +program fragment +.EX + /name 35 def +.EE +whereas +.B -sname=35 +is equivalent to +.EX + /name (35) def +.EE +.TP +.B -q +Quiet startup: suppress normal startup messages, and also do the +equivalent of +.BR -dQUIET . +.TP +.BI -g number1 x number2 +Equivalent to +.BI -dDEVICEWIDTH= number1 +and +.BI -dDEVICEHEIGHT= number2\f1. +This is for the benefit of devices, such as windows, +that allow width and height to be specified. +.TP +.BI -r number +.TQ +.BI -r number1 x number2 +Equivalent to +.BI -dDEVICEXRESOLUTION= number1 +and +\fL-dDEVICE\%YRESOLUTION= \f2\%number2\f1. +This is for the benefit of devices, such as printers, +that support multiple X and Y resolutions. +If only one number is given, it is used for both X and Y resolutions. +.TP +.BI -I directories +Adds the designated list of directories at the head of the +search path for library files. +.PP +Note that gs_init.ps makes systemdict read-only, so the values of names +defined with -D/d/S/s cannot be changed (although, of course, they can be +superseded by definitions in userdict or other dictionaries.) +.SS "Special names" +.TP +.B -dBATCH +Exit after the last file has been processed. +This is equivalent to listing +.I quit.ps +at the end of the list of files. +.TP +.B -dDISKFONTS +Causes individual character outlines to be loaded from the disk +the first time they are encountered. (Normally Ghostscript loads all the +character outlines when it loads a font.) This may allow loading more +fonts into RAM, at the expense of slower rendering. +.TP +.B -dNOCACHE +Disables character caching. Only useful for debugging. +.TP +.B -dNOBIND +Disables the `bind' operator. Only useful for debugging. +.TP +.B -dNODISPLAY +Suppresses the normal initialization of the output device. +This may be useful when debugging. +.TP +.B -dNOPAUSE +Disables the prompt and pause at the end of each page. +This may be desirable for applications where another program +(e.g. +.IR page (1)) +is +`driving' Ghostscript. +.TP +.B -dSAFER +Disables the +.B deletefile +and +.B renamefile +operators, and the +ability to open files in any mode other than read-only. This may be +desirable for spoolers or other sensitive environments. +Files in the +.B /fd +directory may still be opened for writing. +.TP +.B -dWRITESYSTEMDICT +Leaves systemdict writable. This is necessary when running +special utility programs such as font2c and pcharstr, which must bypass +normal PostScript access protection. +.TP +.BI -sDEVICE= device +Selects an alternate initial output device, as described above. +.TP +.BI -sOutputFile= filename +Selects an alternate output file (or pipe) for the initial output +device, as described above. +.SH FILES +.TP +.B /sys/lib/ghostscript/* +Startup-files, utilities, examples, and basic font definitions. +.TP +.B /sys/lib/ghostscript/fonts/* +Additional font definitions. +.SH SOURCE +.B /sys/src/cmd/gs +.SH "SEE ALSO" +.IR page (1), +.IR ps2pdf (1) +.br +The Ghostscript document files in +.B doc +and +.B man +subdirectories of the source directory. +.SH BUGS +The treatment of standard input is non-standard. diff --git a/sys/man/1/gview b/sys/man/1/gview new file mode 100755 index 000000000..1777a3f7d --- /dev/null +++ b/sys/man/1/gview @@ -0,0 +1,204 @@ +.TH GVIEW 1 +.SH NAME +gview \- interactive graph viewer +.SH SYNOPSIS +.B gview +[ +.B -mp +] +[ +.B -l +.I logfile +] +[ +.I files +] +.SH DESCRIPTION +.I Gview +reads polygonal lines or a polygonal line drawing from an +.B ASCII +input file (which defaults to standard input), and views it interactively, +with commands to zoom in and out, perform simple editing operations, and +display information about points and polylines. (Multiple input files are +allowed if you want to overlay several line drawings.) The editing commands can +change the color and thickness of the polylines, delete (or undelete) +some of them, and optionally rotate and move them. It is also possible to +generate an output file that reflects these changes and is in the same format +as the input. +.PP +Since the +.B move +and +.B rotate +commands are undesirable when just viewing a graph, they are only enabled if +.I gview +is invoked with the +.B -m +option. +.PP +The +.B -p +option plots only the vertices of the polygons. +.PP +Clicking on a polyline with button 1 displays the coordinates and a +.I t +value that tells how far along the polyline. +.IR (t =0 +at the first vertex, +.IR t =1 +at the first vertex, +.IR t =1.5 +halfway between the second and third vertices, etc.) The +.B -l +option generates a log file that lists all points selected in this manner. +.PP +The most important interactive operations are to +.I zoom in +by sweeping out a rectangle, or to +.I zoom out +so that everything currently being displayed shrinks to fit in the swept-out +rectangle. Other options on the button 3 menu are +.I unzoom +which restores the coordinate system to the default state where everything +fits on the screen, +.I recenter +which takes a point and makes it the center of the window, and +.I square up +which makes the horizontal and vertical scale factors equal. +.PP +To take a graph of a function where some part is almost linear and +see how it deviates from a straight line, select two points on this +part of the graph (i.e., select one with button 1 and then select the +other) and then use the +.I slant +command on the button 3 menu. +This slants the coordinate system so that the line between the two +selected points appears horizontal (but vertical still means positive +.IR y ). +Then the +.I zoom in +command can be used to accentuate deviations from horizontal. +There is also an +.I unslant +command that undoes all of this and goes back to an unslanted coordinate +system. +.PP +There is a +.I recolor +command on button 3 that lets you select a color and change everything +to have that color, and a similar command on button 2 that only affects +the selected polyline. If the input file uses the +.B Multi(...) +feature explained below, either flavor of +.I recolor +allows you to type a digit in lieu of selecting a color. +.PP +The +.I thick +or +.I thin +command on button 2 changes the thickness of the selected polyline +and there is also an undo command for such edits. +Finally, button 3 has commands to +.I read +a new input file and display it on top of everything else, +.I restack +the drawing order (in case lines of different color are drawn on top of +each other), +.I write +everything into an output file, or +.I exit +the program. +.PP +Each polyline in an input or output file is a space-delimited +.I x +.I y +coordinate pair on a line by itself, and the polyline is a sequence +of such vertices followed by a label. The label could be just a +blank line or it could be a string in double +quotes, or virtually any text that does not contain spaces and is +on a line by itself. The label at the end of the last polyline is +optional. It is not legal to have two consecutive labels, since that +would denote a zero-vertex polyline and each polyline must have at least +one vertex. (One-vertex polylines are useful for scatter plots.) +Under the +.B -l +option, a newline causes the selected polyline's label to appear in +the log file (where it could be seen by invoking +.B tail -f +in another window). + +If the label after a polyline contains the word +.B "Thick" +or a color name +.BR (Red , +.BR Pink , +.BR Dkred , +.BR Orange , +.BR Yellow , +.BR Dkyellow , +.BR Green , +.BR Dkgreen , +.BR Cyan , +.BR Blue , +.BR Ltblue , +.BR Magenta , +.BR Violet , +.BR Gray , +.BR Black , +.BR White ), +whichever color name comes first will be used to color the polyline. +Alternatively, labels can contain +.B Multi +followed by single-letter versions of these names: +.BR (R , +.BR P , +.BR r , +.BR O , +.BR Y , +.BR y , +.BR G , +.BR g , +.BR C , +.BR B , +.BR b , +.BR M , +.BR V , +.BR A , +.BR K , +.BR W , +each optionally preceded by +.BR T ). +Then +.I recolor +followed by a nonzero digit +.I n +selects the +.IR n th +alternative for each polyline. + +.SH EXAMPLE +To see a graph of the function +.IR y = sin( x )/ x , +generate input with an awk script and pipe it into +.IR gview : +.IP +.EX +awk 'BEGIN{for(x=.1;x<500;x+=.1)print x,sin(x)/x}' | gview +.EE +.SH SOURCE +.B /sys/src/cmd/gview.c +.SH SEE ALSO +.IR awk (1), +.IR tail (1) +.SH BUGS +The user interface for the +.I slant +command is counter-intuitive. Perhaps it would be better to have a scheme +for sweeping out a parallelogram. +.PP +The +.B -p +option makes the interactive point selection feature behave strangely, and +is unnecessary since extra blank lines in the input achieve essentially the +same effect. diff --git a/sys/man/1/gzip b/sys/man/1/gzip new file mode 100755 index 000000000..f56a6a246 --- /dev/null +++ b/sys/man/1/gzip @@ -0,0 +1,210 @@ +.TH GZIP 1 +.SH NAME +gzip, gunzip, bzip2, bunzip2, compress, uncompress, zip, unzip \- compress and expand data +.SH SYNOPSIS +.B gzip +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B gunzip +.RB [ -ctTvD ] +.RI [ file +.BR ... ] +.PP +.B bzip2 +.RB [ -cvD [ 1-9 ]] +.RI [ file +.BR ... ] +.PP +.B bunzip2 +.RB [ -cvD ] +.RI [ file +.BR ... ] +.PP +.B compress +[ +.B -cv +] [ +.I file +.B ... +] +.PP +.B uncompress +[ +.B -cv +] [ +.I file +.B ... +] +.PP +.B zip +.RB [ -avD [ 1-9 ]] +.RB [ -f +.IR zipfile ] +.I file +.RB [ ... ] +.PP +.B unzip +.RB [ -cistTvD ] +.RB [ -f +.IR zipfile ] +.RI [ file +.BR ... ] +.SH DESCRIPTION +.PP +.I Gzip +encodes files with a hybrid Lempel-Ziv 1977 and Huffman compression algorithm +known as +.BR deflate . +Most of the time, the resulting file is smaller, +and will never be much bigger. +Output files are named by taking the last path element of each file argument +and appending +.BR .gz ; +if the resulting name ends with +.BR .tar.gz , +it is converted to +.B .tgz +instead. +.I Gunzip +reverses the process. +Its output files are named by taking the last path element of each file argument, +converting +.B .tgz +to +.BR .tar.gz , +and stripping any +.BR .gz ; +the resulting name must be different from the original name. +.PP +.I Bzip2 +and +.I bunzip2 +are similar in interface to +.I gzip +and +.IR gunzip , +but use a modified Burrows-Wheeler block sorting +compression algorithm. +The default suffix for output files is +.BR .bz2 , +with +.B .tar.bz2 +becoming +.BR .tbz . +.I Bunzip2 +recognizes the extension +.B .tbz2 +as a synonym for +.BR .tbz . +.PP +.I Compress +and +.I uncompress +are similar in interface to +.I gzip +and +.IR gunzip , +but use the Lempel-Ziv-Welch compression algorithm. +The default suffix for output files is +.BR .Z . +.I Compress +is one of the oldest widespread Unix compression programs. +.PP +.I Zip +encodes the named files and places the results into the archive +.IR zipfile , +or the standard output if no file is given. +.I Unzip +extracts files from an archive created by +.IR zip . +If no files are named as arguments, all of files in the archive are extracted. +A directory's name implies all recursively contained files and subdirectories. +.I Zip +is the +.I "de facto" +standard for compression on Microsoft operating systems. +.PP +None of these programs removes the original files. +If the process fails, the faulty output files are removed. +.PP +The options are: +.TP 0.6i +.B -a +Automaticialy creates directories as needed, needed for zip files +created by broken implementations which omit directories. +.TP +.B -c +Write to standard output rather than creating an output file. +.TP +.B -i +Convert all archive file names to lower case. +.TP +.B -s +Streaming mode. Looks at the file data adjacent to each compressed file +rather than seeking in the central file directory. +This is the mode used by +.I unzip +if no +.I zipfile +is specified. +If +.B -s +is given, +.B -T +is ignored. +.TP +.B -t +List matching files in the archive rather than extracting them. +.TP +.B -T +Set the output time to that specified in the archive. +.TP +.BR -1 " .. " -9 +Sets the compression level. +.B -1 +is tuned for speed, +.B -9 +for minimal output size. +The best compromise is +.BR -6 , +the default. +.TP +.B -v +Produce more descriptive output. +With +.BR -t , +adds the uncompressed size in bytes and the modification time to the output. +Without +.BR -t , +prints the names of files on standard error as they are compressed or decompressed. +.TP +.B -D +Produce debugging output. +.SH SOURCE +.B /sys/src/cmd/gzip +.br +.B /sys/src/cmd/bzip2 +.br +.B /sys/src/cmd/compress +.SH SEE ALSO +.IR tar (1) +.br +"A Technique for High Performance Data Compression", +Terry A. Welch, +.IR "IEEE Computer" , +vol. 17, no. 6 (June 1984), pp. 8-19. +.SH BUGS +.I Unzip +can only extract files which are uncompressed or compressed +with the +.B deflate +compression scheme. Recent zip files fall into this category. +Very recent zip files may have tables of contents that +.I unzip +cannot read. Such files are still readable by invoking +.I unzip +with the +.B -s +option. diff --git a/sys/man/1/hget b/sys/man/1/hget new file mode 100755 index 000000000..7cc8c97c5 --- /dev/null +++ b/sys/man/1/hget @@ -0,0 +1,86 @@ +.TH HGET 1 +.SH NAME +hget \- retrieve a web page corresponding to a url +.SH SYNOPSIS +.B hget +[ +.B -dhv +] [ +.B -o +.I ofile +] [ +.B -p +.I body +] [ +.B -x +.I netmntpt +] [ +.B -r +.I header +] +.I url +.SH DESCRIPTION +.I Hget +retrieves the web page specified by the URL +.I url +and writes it, absent the +.B -o +option, to standard output. +The known URL types are: http and ftp. +.PP +If +.I url +is of type HTTP and the +.B -p +option is specified, then an HTTP POST is performed +with +.I body +as the data to be posted. +.PP +The +.B -o +option is used to keep a local file in sync with a +web page. If the web page has been modified later than the +file, it is copied into the file. If the file is up to date +but incomplete, +.I hget +will fetch the missing bytes. +.PP +Option +.B -h +causes HTTP headers to be printed to standard output +in addition to the transferred web page. +.PP +Option +.B -r +sends an arbitrary HTTP +.IR header . +.PP +Option +.B -d +turns on debugging written to standard error. +.PP +Normally, +.I hget +uses the IP stack mounted under +.BR /net . +The +.B -x +option can be used to specify the mount point of +a different IP stack to use. +.PP +Option +.B -v +writes progress lines to standard error once a second. +Each line contains two numbers, the bytes transferred so +far and the total length to be transferred. +.PP +If the environment variable +.B httpproxy +is set, it is used as a URL denoting an HTTP proxy server. +All HTTP accesses use this server to get the page instead of +calling the destination server. +.SH SOURCE +.B /sys/src/cmd/hget.c +.SH "SEE ALSO" +.IR ftpfs (4) diff --git a/sys/man/1/history b/sys/man/1/history new file mode 100755 index 000000000..889da36a1 --- /dev/null +++ b/sys/man/1/history @@ -0,0 +1,102 @@ +.TH HISTORY 1 +.SH NAME +history \- print file names from the dump +.SH SYNOPSIS +.B history +[ +.B -Dabcemnw +] [ +.B -fuv +] [ +.B -d +.I dumpfilesystem +] [ +.B -s +.I yyyymmdd +] +.I files ... +.SH DESCRIPTION +.I History +prints the names, dates, and sizes, and modifier of all versions of the named +.IR files , +looking backwards in time, +stored in the dump file system. +If the file exists in the main tree, the first line of output will be its current state. +For example, +.IP +.EX +history /adm/users +.EE +.PP +produces +.IP +.EX +May 14 15:29:18 EDT 2001 /adm/users 10083 [adm] +May 14 15:29:18 EDT 2001 /n/dump/2001/0515/adm/users 10083 [adm] +May 11 17:26:24 EDT 2001 /n/dump/2001/0514/adm/users 10481 [adm] +May 10 16:40:51 EDT 2001 /n/dump/2001/0511/adm/users 10476 [adm] + ... +.EE +.PP +When presented with a path of the form +.BI /n/ fs / path \fR, +.I history +will use +.IB fs dump +as the name of the dump file system, and will print a history of +.IR path . +.PP +The +.B -v +option enables verbose debugging printout. +.PP +The +.B -D +option causes +.IR diff (1) +to be run for each adjacent pair of dump files. +The options +.B -abcemnw +are passed through to +.IR diff; +the little-used +.I diff option +.B -f +is replaced by the functionality described below, +and the +.B -r +option is disallowed. +.PP +The +.B -u +option causes times to be printed in GMT (UT) rather than local time. +.PP +The +.B -d +option selects some other dump file system such as +.IR /n/bootesdump . +.PP +The +.B -f +option forces the search to continue even when the +file in question does not exist (useful for files that only +exist intermittently). +.PP +Finally, the +.B -s +option +sets the starting (most recent) date for the output. +.SH EXAMPLES +Check how often a user has been logged in. +.IP +.EX +history /usr/ches/tmp +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /sys/src/cmd/history.c +.SH SEE ALSO +.IR fs (4) +.br +.IR yesterday (1) diff --git a/sys/man/1/hoc b/sys/man/1/hoc new file mode 100755 index 000000000..0d939afc0 --- /dev/null +++ b/sys/man/1/hoc @@ -0,0 +1,144 @@ +.TH HOC 1 +.SH NAME +hoc \- interactive floating point language +.SH SYNOPSIS +.B hoc +[ +.B -e +.I expression +] +[ +.I file ... +] +.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/sys/man/1/htmlroff b/sys/man/1/htmlroff new file mode 100755 index 000000000..470d1952d --- /dev/null +++ b/sys/man/1/htmlroff @@ -0,0 +1,119 @@ +.TH HTMLROFF 1 +.SH NAME +htmlroff \- HTML formatting and typesetting +.SH SYNOPSIS +.B htmlroff +[ +.B -iuv +] +[ +.B -m +.I name +] +[ +.B -r +.I aN +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Htmlroff +accepts +.IR troff (1) +input in the named +.I files +and formats it as HTML for viewing in a web browser. +.PP +If no +.I file +argument is given, +.I htmlroff +reads the standard input. +An argument consisting of a single minus +.RB ( - ) +is taken to be +a file name corresponding to the standard input. +The options are: +.TP +.B -i +Read standard input after the input files are exhausted. +.TP +.BI -m name +Process the macro file +.BI /sys/lib/tmac/tmac. name +before the input +.IR files . +.TP +.BI -r aN +Set register +.I a +(one character name) to +.IR N . +.TP +.B -u +Generate UTF output. +By default, +.I htmlroff +converts Unicode runes into the corresponding +HTML entity sequences +.RB ( α , +.BR   , +and so on). +.I Htmlroff +invokes +.IR tcs (1) +for the conversion. +.TP +.B -v +Generate debugging output and warnings about suspicious input. +.PD +.PP +Most +.I troff +input files, especially those using the +.IR ms (6) +macros, can be used unaltered. +In general, the macro file +.B tmac.html +should be processed after processing other standard macro files, +as in +.B htmlroff +.B -ms +.BR -mhtml . +.PP +.IR Htmlroff (6) +describes the changes to the input language. +.PP +.IR Mhtml (6) +describes the new macros. +.SH EXAMPLES +Format the Plan 9 web page: +.IP +.EX +cd /usr/web/plan9 +htmlroff -mhtml index.tr >index.html +.EE +.PP +Format a paper: +.IP +.EX +cd /sys/doc +pic auth.ms | tbl | eqn | htmlroff -ms -mhtml >auth.html +.EE +.SH FILES +.TP +.B /sys/lib/troff/font/devutf/utfmap +Mapping from +.I troff +two-character names like +.B \e(*a +to Unicode characters like α. +.SH SOURCE +.B /sys/src/cmd/htmlroff +.SH "SEE ALSO +.IR tcs (1), +.IR troff (1), +.IR htmlroff (6), +.IR mhtml (6) diff --git a/sys/man/1/idiff b/sys/man/1/idiff new file mode 100755 index 000000000..e16bada67 --- /dev/null +++ b/sys/man/1/idiff @@ -0,0 +1,73 @@ +.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 +.I file2 +onto standard output. +Wherever +.I file1 +and +.I file2 +differ, +.I idiff +displays the differences in the style of +.RB `` diff +.BR -n '' +on standard error +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, +if passed, +are +passed 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. diff --git a/sys/man/1/join b/sys/man/1/join new file mode 100755 index 000000000..9c3368163 --- /dev/null +++ b/sys/man/1/join @@ -0,0 +1,147 @@ +.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. +.PP +One of the files must be randomly accessible. diff --git a/sys/man/1/jpg b/sys/man/1/jpg new file mode 100755 index 000000000..f9b42adc5 --- /dev/null +++ b/sys/man/1/jpg @@ -0,0 +1,263 @@ +.TH JPG 1 +.SH NAME +jpg, gif, png, ppm, bmp, v210, yuv, ico, togif, toppm, topng, toico \- view and convert pictures +.SH SYNOPSIS +.B jpg +[ +.B -39cdefFkJrtv +] [ +.I file ... +] +.br +.B gif +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B png +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B ppm +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B bmp +[ +.I file +] +.br +.B v210 +[ +.B -39cdektv +] [ +.I file ... +] +.br +.B yuv +[ +.I file +] +.PP +.B togif +[ +.B -c +.I comment +] [ +.B -l +.I loopcount +] [ +.B -d +.I msec +] [ +.B -t +.I transindex +] [ +.I file ... +[ +.B -d +.I msec +] +.I file ... +] +.br +.B toppm +[ +.B -c +.I comment +] [ +.I file +] +.br +.B topng +[ +.B -c +.I comment +] [ +[ +.B -g +.I gamma +] [ +.I file +] +.PP +.B ico +[ +.I file +] +.br +.B toico +[ +.I file ... +] +.SH DESCRIPTION +These programs read, display, and write image files in public formats. +.IR Jpg , +.IR gif , +.IR png , +.IR ppm , +.IR bmp , +.IR v210 , +and +.IR yuv +read files in the corresponding formats and, by default, display +them in the current window; options cause them instead to convert the images +to Plan 9 image format and write them to standard output. +.IR Togif , +.IR Toppm , +and +.I topng +read Plan 9 images files, convert them to GIF, PPM, or PNG, and write them to standard output. +.PP +The default behavior of +.IR jpg , +.IR gif , +and +.IR ppm +is to display the +.IR file , +or standard input if no file is named. +Once a file is displayed, typing a character causes the program to display the next image. +Typing a +.BR q , +DEL, or control-D exits the program. +For a more user-friendly interface, use +.IR page (1), +which invokes these programs to convert the images to standard format, +displays them, and offers scrolling, panning, and menu-driven navigation among the files. +.PP +These programs share many options: +.TP +.B -e +Disable Floyd-Steinberg error diffusion, which is used to improve the appearance +of images on color-mapped displays, typically with 8 bits per pixel. +Primarily useful for debugging; if the display has true RGB color, the image +will be displayed in full glory. +.TP +.B -k +Convert and display the image as a black and white (really grey-scale) image. +.TP +.B -v +Convert the image to an RGBV color-mapped image, even if the +display has true RGB color. +.TP +.B -d +Suppress display of the image; this is set automatically by +any of the following options: +.TP +.B -c +Convert the image to a Plan 9 representation, as defined by +.IR image (6), +and write it to standard output. +.TP +.B -9 +Like +.BR -c , +but produce an uncompressed image. +This saves processing time, particularly when the output is +being piped to another program such as +.IR page (1), +since it avoids compression and decompression. +.TP +.B -t +Convert the image, if it is in color, to a true color RGB image. +.TP +.B -3 +Like +.BR -t , +but force the image to RGB even if it is originally grey-scale. +.PD +.PP +.I Jpg +has two extra options used to process the output of the LML +video card: +.TP +.B -f +Merge two adjacent images, which represent the two fields of a video picture, +into a single image. +.TP +.B -F +The input is a motion JPEG file, with multiple images representing frames of the movie. Sets +.BR -f . +.PD +.PP +The +.IR togif +and +.IR toppm +programs go the other way: they convert from Plan 9 images to GIF and PPM, +and have no display capability. +Both accept an option +.B -c +to set the comment field of the resulting file. +If there is only one input picture, +.I togif +converts the image to GIF format. +If there are many +.IR files , +though, it will assemble them into an animated GIF file. +The options control this process: +.TP +.BI -l loopcount +By default, the animation will loop forever; +.I loopcount +specifies how many times to loop. +A value of zero means loop forever and a negative value means +to stop after playing the sequence once. +.TP +.BI -d msec +By default, the images are displayed as fast as they can be rendered. +This option specifies the time, in milliseconds, to pause while +displaying the next named +.IR file . +.PP +.I Gif +translates files that contain a `transparency' index by attaching +an alpha channel to the converted image. +.PP +.I Ico +displays a Windows icon (.ico) file. If no file is +specified, +.I ico +reads from standard input. +Icon files +contain sets of icons represented by an image and a mask. +Clicking the right button pops up a menu that lets you +write any icon's image as a Plan 9 image (\fIwidth\fBx\fIheight\fB.image\fR), +write any icon's mask as a Plan 9 image (\fIwidth\fBx\fIheight\fB.mask\fR), +or exit. Selecting one of the write menu items yields a sight cursor. +Move the sight over the icon and right click again to write. +.PP +.I Toico +takes a list of Plan 9 image files (or standard input) and creates +a single icon file. The masks in the icon file will be the white +space in the image. The icon file is written to standard output. +.SH SOURCE +.B /sys/src/cmd/jpg +.SH "SEE ALSO" +.IR page (1), +.IR image (6). +.br +.B http://www.w3.org/Graphics/JPEG/itu-t81.pdf +.br +.B http://www.w3.org/Graphics/GIF/spec-gif89a.txt +.br +.B http://www.w3.org/TR/2003/REC-PNG-20031110 +.br +.B http://netpbm.sourceforge.net/doc/ppm.html +.br +.B http://en.wikipedia.org/wiki/Windows_bitmap +.br +.B http://en.wikipedia.org/wiki/Yuv +.SH BUGS +Writing an animated GIF using +.I togif +is a clumsy undertaking. diff --git a/sys/man/1/kbmap b/sys/man/1/kbmap new file mode 100755 index 000000000..5a8d8a4e3 --- /dev/null +++ b/sys/man/1/kbmap @@ -0,0 +1,35 @@ +.TH KBMAP 1 +.SH NAME +kbmap \- show a list of available keyboard maps and switch between them. +.SH SYNOPSIS +.B kbmap +[ +.IR file ... +] +.SH DESCRIPTION +.I Kbmap +shows a single column consisting of the names of keyboard maps for different +alphabets available on the system. With no arguments +.B kbmap +will look for files in +.BR /sys/lib/kbmap . +.PP +Clicking the right mouse button will highlight the entry and force the +keyboard mapping defined in the corresponding file to become current +for the system; typing 'q' quits. +.PP +.I Kbmap +requires that the file +.B /dev/kbmap +served by +.IR kbmap (3) +exists and is writable. +..SH FILES +.TF /lib/kbmap/* +.SH SOURCE +.B /sys/src/cmd/kbmap.c +.SH "SEE ALSO" +.IR kbmap (3) +.SH BUGS +Not all keyboards map the entire set of characters, so one has to +switch back to the default map before changing to another. diff --git a/sys/man/1/kill b/sys/man/1/kill new file mode 100755 index 000000000..a4abe8a2f --- /dev/null +++ b/sys/man/1/kill @@ -0,0 +1,70 @@ +.TH KILL 1 +.SH NAME +kill, slay, broke \- print commands to kill processes +.SH SYNOPSIS +.B kill +.I name ... +.PP +.B slay +.I name ... +.PP +.B broke +[ +.I user +] +.SH DESCRIPTION +.I Kill +prints commands that will cause all processes called +.I name +and owned by the current user to be terminated. +Use the +.B send +command of +.IR rio (1), +or pipe the output of +.I kill +into +.IR rc (1) +to execute the commands. +.PP +.I Kill +suggests sending a +.B "kill" +note to the process; the same +message delivered to the process's +.B ctl +file (see +.IR proc (3)) +is a surer, if heavy handed, kill, +but is necessary if the offending process is +ignoring notes. +The +.I slay +command prints commands to do this. +.PP +.I Broke +prints commands that will cause all processes +in the +.I Broken +state +and owned by +.I user +(by default, the current user) +to go away. +When a process dies because of an error caught by +the system, it may linger in the +.I Broken +state to allow examination with a debugger. +Executing the commands printed by +.I broke +lets the system reclaim the resources used by +the broken processes. +.SH SOURCE +.B /rc/bin/kill +.br +.B /rc/bin/broke +.SH "SEE ALSO" +.IR ps (1), +.IR stop (1), +.IR notify (2), +.IR proc (3) diff --git a/sys/man/1/ktrace b/sys/man/1/ktrace new file mode 100755 index 000000000..ef1086f11 --- /dev/null +++ b/sys/man/1/ktrace @@ -0,0 +1,62 @@ +.TH KTRACE 1 +.SH NAME +ktrace \- interpret kernel stack dumps +.SH SYNOPSIS +.B ktrace +[ +.B -i +] +.I kernel +.I pc +.I sp +[ +.I link +] +.SH DESCRIPTION +.I Ktrace +translates a hexadecimal kernel stack dump +into a sequence of +.IR acid (1) +commands to show the points in the call trace. +The +.I kernel +argument should be the path of the kernel being debugged, +and +.I pc +and +.I sp +are the PC and SP values given in the stack dump. +For MIPS kernels, the contents of the +.I link +register must also be supplied. +.PP +A stack trace consists of a +.I ktrace +command followed by a series of lines containing +fields of the form +.IB location = contents \fR: +.EX +ktrace /kernel/path 80105bc1 8048e174 +8048e114=80105ac6 8048e120=80140bb4 8048e134=8010031c +8048e16c=80137e45 8048e170=80105bc1 8048e178=80137e62 +\&... +.EE +.PP +The trace can be edited to provide the correct kernel path +and then pasted into a shell window. +If the +.B -i +option is present, +.I ktrace +instead prompts for the contents of the memory locations in which it is interested; +this is useful when the stack trace is on a screen rather than +in a machine readable form. +.SH SOURCE +.B /sys/src/cmd/ktrace.c +.SH SEE ALSO +.IR acid (1), +.IR rdbfs (4) +.SH BUGS +When examining a kernel trace resulting from +an interrupt on top of other interrupts, +only the topmost call trace is printed. diff --git a/sys/man/1/leak b/sys/man/1/leak new file mode 100755 index 000000000..6890b0553 --- /dev/null +++ b/sys/man/1/leak @@ -0,0 +1,235 @@ +.TH LEAK 1 +.SH NAME +leak, kmem, umem \- help find memory leaks +.SH SYNOPSIS +.B leak +[ +.B -abcds +] +[ +.B -f +.I binary +] +[ +.B -r +.I res +] +[ +.B -x +.I width +] +.I pid ... +.PP +.B kmem +[ +.I kernel +] +.PP +.B umem +.I pid +[ +.I textfile +] +.SH DESCRIPTION +.I Leak +examines the named processes, which +should be sharing their data and bss segments, +for memory leaks. +It uses a mark and sweep-style algorithm to +determine which allocated blocks are no longer +reachable from the set of root pointers. +The set of root pointers is created by looking through +the shared bss segment as well as each process's registers. +.PP +Unless directed otherwise, +.I leak +prints, for each block, a line with seven space-separated fields: +the string +.BR block , +the address of the block, +the size of the block, +the first two words of the block, +and the function names represented by the first two words of the block. +Usually, the first two words of the block +contain the malloc and realloc tags +(see +.IR malloc (2)), +useful for finding who allocated the leaked blocks. +.PP +If the +.B -s +or the +.B -c +option is given, +.I leak +will instead present a sequence of +.IR acid (1) +commands that show each leaky allocation site. +With +.B -s +a comment appears next to each command to +indicate how many lost blocks were allocated +at that point in the program. +With +.B -c +the comments are extended to indicate also the total +number of bytes lost at that point in the program, +and an additional comment line gives the +overall total number of bytes. +.PP +If the +.B -a +option is given, +.I leak +will print information as decribed above, +but for all allocated blocks, +not only leaked ones. +If the +.B -d +option is given, +.I leak +will print information as decribed above, +but for all free blocks, +i.e. those freed, +or those that are not yet +in use (fragmentation?). +The +.B -a +and +.B -d +options can be combined. +.PP +If the +.B -b +option is given, +.I leak +will print a Plan 9 image file +graphically summarizing the memory arenas. +In the image, each pixel represents +.I res +(default 8) +bytes. +The color code is: +.TP "\w'\fIbright blue\fR 'u +.I "dark blue +Completely allocated. +.TP +.I "bright blue +Contains malloc headers. +.TP +.I "bright red +Contains malloc headers for leaked memory. +.TP +.I "dark red +Contains leaked memory. +.TP +.I "yellow +Completely free +.TP +.I "white +Padding to fill out the image. +.PD +The bright pixels representing headers help in +counting the number of blocks. +Magnifying the images with +.IR lens (1) +is often useful. +.PP +If given a name rather than a list of process ids, +.I leak +echoes back a command-line with process ids of every process +with that name. +.PP +The +.B -f +option specifies a binary to go on the +.IR acid (1) +command-line used to inspect the +processes, and is only necessary +when inspecting processes started +from stripped binaries. +.PP +.I Umem +prints a summary of all allocated blocks in the process with id +.IR pid . +Each line of the summary gives the count and total size of +blocks allocated at an allocation point. +The list is sorted by count in decreasing order. +.I Umem +prints summarizes all allocations, not just +memory leaks, but it is faster and requires less memory than +.I leak . +.PP +.I Kmem +is like +.I umem +but prints a summary for the running kernel. +.SH EXAMPLES +List lost blocks in +.IR 8.out . +This depends on the fact that there is only +once instance of +.I 8.out +running; if there were more, the output of +.B "leak -s 8.out +would need editing before sending to the shell. +.IP +.EX +% leak -s 8.out +leak -s 229 230 +% leak -s 8.out | rc +src(0x0000bf1b); // 64 +src(0x000016f5); // 7 +src(0x0000a988); // 7 +% +.EE +.LP +View the memory usage graphic for the window system. +.IP +.EX +% leak -b rio | rc | page +.EE +.PP +List the top allocation points in the kernel, +first by count and then by total size: +.IP +.EX +% kmem | sed 10q +% kmem | sort -nr +1 | sed 10q +.EE +.SH SOURCE +.B /sys/lib/acid/leak +.br +.B /sys/src/cmd/aux/acidleak.c +.br +.B /rc/bin/leak +.br +.B /rc/bin/kmem +.br +.B /rc/bin/umem +.SH SEE ALSO +.IR getcallerpc (2), +.I setmalloctag +in +.IR malloc (2) +.SH BUGS +.I Leak +and +.I kmem +depend on the internal structure of the +libc pool memory allocator (see +.IR pool (2)). +Since the ANSI/POSIX environment uses a different +allocator, +.I leak +will not work on APE programs. +.PP +.I Leak +is not speedy, and +.I acidleak +can consume more memory than the process(es) being examined. +.PP +These commands require +.B /sys/src/libc/port/pool.acid +to be present and generated from +.BR pool.c . diff --git a/sys/man/1/lens b/sys/man/1/lens new file mode 100755 index 000000000..f944540c1 --- /dev/null +++ b/sys/man/1/lens @@ -0,0 +1,45 @@ +.TH LENS 1 +.SH NAME +lens \- interactive screen magnifier +.SH SYNOPSIS +.B lens +.SH DESCRIPTION +.I Lens +presents a magnified view in its window of an arbitrary area on the screen. +The default magnification is 4 (showing each pixel as a 4×4 pixel block in +.IR lens 's +window). This may be changed by typing a digit on the keyboard (with +.B 0 +standing for 10), or by using the +.B + +and +.B - +keys to increase or decrease the magnification by one unit. +The lower limit is ×1; the upper ×16. +.PP +The interface to indicate what area to magnify is dictated by the mouse multiplexing rules of +.IR rio (1). +Start by pressing mouse button 1 in the +.I lens +window and dragging, with the button pressed, to the center of the area to magnify. +.I Lens +will update the display as the mouse moves. +Releasing the button freezes the +.I lens +display. +The magnified view is static\(ema snapshot, not a movie\(embut typing a space or +.B . +key in the +.I lens +window will refresh the +display, as will changing the magnification. +.PP +To make counting pixels easier, typing a +.B g +toggles whether a checkerboard grid is imposed on the magnified area. +.PP +Button 3 brings up a menu of actions. +.SH SOURCE +.B /sys/src/cmd/lens.c +.SH BUGS +There should be an easier way to indicate what to magnify. diff --git a/sys/man/1/lex b/sys/man/1/lex new file mode 100755 index 000000000..f0f148335 --- /dev/null +++ b/sys/man/1/lex @@ -0,0 +1,81 @@ +.TH LEX 1 +.SH NAME +lex \- generator of lexical analysis programs +.SH SYNOPSIS +.B lex +[ +.B -tvn9 +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lex +generates programs to be used in simple lexical analysis of text. +The input +.I files +(standard input default) +contain regular expressions +to be searched for and actions written in C to be executed when +expressions are found. +.PP +A C source program, +.B lex.yy.c +is generated. +This program, when run, copies unrecognized portions of +the input to the output, +and executes the associated +C action for each regular expression that is recognized. +.PP +The options have the following meanings. +.TP +.B -t +Place the result on the standard output instead of in file +.BR lex.yy.c . +.TP +.B -v +Print a one-line summary of statistics of the generated analyzer. +.TP +.B -n +Opposite of +.BR -v ; +.B -n +is default. +.TP +.B -9 +Adds code to be able to compile through the native C compilers. +.SH EXAMPLES +This program converts upper case to lower, +removes blanks at the end of lines, +and replaces multiple blanks by single blanks. +.PP +.EX +%% +[A-Z] putchar(yytext[0]+\'a\'-\'A\'); +[ ]+$ +[ ]+ putchar(\' \'); +.EE +.SH FILES +.TF /sys/lib/lex/ncform +.TP +.B lex.yy.c +output +.TP +.B /sys/lib/lex/ncform +template +.SH "SEE ALSO" +.IR yacc (1), +.IR sed (1) +.br +M. E. Lesk and E. Schmidt, +`LEX\(emLexical Analyzer Generator', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH SOURCE +.B /sys/src/cmd/lex +.SH BUGS +Cannot handle +.SM UTF. +.PP +The asteroid to kill this dinosaur is still in orbit. diff --git a/sys/man/1/lock b/sys/man/1/lock new file mode 100755 index 000000000..bc6251e04 --- /dev/null +++ b/sys/man/1/lock @@ -0,0 +1,61 @@ +.TH LOCK 1 +.SH NAME +lock \- run a command under lock +.SH SYNOPSIS +.B lock +[ +.B -w +] +.I lockfile +[ +.I command +[ +.I argument +\&... +] ] +.SH DESCRIPTION +.I Lock +runs +.I command +(default +.LR rc ) +with +.I arguments +while holding +.I lockfile +open and (over)writing at least one byte each minute +to keep the exclusive-access lock alive. +If +.I lockfile +doesn't already have the exclusive-access bit set in +its mode, +the exclusive-access bits are set in its mode and +.BR qid.type . +.PP +Under +.BR -w , +.I lock +waits for exclusive access to +.I lockfile +instead of just trying once. +.PP +.I Lock +sets +.B /env/prompt +to contain the name of the lock file. +.SH EXAMPLES +Build a +.IR replica (1) +database while preventing collisions with other occurrences. +.IP +.EX +cd /sys/lib/dist +lock scan.lock replica/scan $dist/sources.replica +.EE +.SH SOURCE +.B /sys/src/cmd/lock.c +.SH SEE ALSO +.IR intro (5), +.IR stat (5) +.\" .SH DIAGNOSTICS +.\" .SH BUGS diff --git a/sys/man/1/look b/sys/man/1/look new file mode 100755 index 000000000..1bf634fd7 --- /dev/null +++ b/sys/man/1/look @@ -0,0 +1,85 @@ +.TH LOOK 1 +.SH NAME +look \- find lines in a sorted list +.SH SYNOPSIS +.B look +[ +.BI -dfnixt c +] +[ +.I string +] +[ +.I file +] +.SH DESCRIPTION +.I Look +consults a sorted +.I file +and prints all lines that begin with +.IR string . +It uses binary search. +.PP +The following options are recognized. +Options +.B dfnt +affect comparisons as in +.IR sort (1). +.TP +.B -i +Interactive. +There is no +.I string +argument; instead +.I look +takes lines from the standard input as strings to be looked up. +.TP +.B -x +Exact. +Print only lines of the file whose key matches +.I string +exactly. +.TP +.B -d +`Directory' order: +only letters, digits, +tabs and blanks participate in comparisons. +.TP +.B -f +Fold. +Upper case letters compare equal to lower case. +.TP +.B -n +Numeric comparison with initial string of digits, optional minus sign, +and optional decimal point. +.TP +.BR -t [ \f2c\f1 ] +Character +.I c +terminates the sort key in the +.IR file . +By default, tab terminates the key. If +.I c +is missing the entire line comprises the key. +.PP +If no +.I file +is specified, +.B /lib/words +is assumed, with collating sequence +.BR df . +.SH FILES +.B /lib/words +.SH SOURCE +.B /sys/src/cmd/look.c +.SH "SEE ALSO" +.IR sort (1), +.IR grep (1) +.SH DIAGNOSTICS +The exit status is +.RB `` "not found" '' +if no match is found, and +.RB `` "no dictionary" '' +if +.I file +or the default dictionary cannot be opened. diff --git a/sys/man/1/lp b/sys/man/1/lp new file mode 100755 index 000000000..35b30e7c6 --- /dev/null +++ b/sys/man/1/lp @@ -0,0 +1,189 @@ +.TH LP 1 +.SH NAME +lp \- printer output +.SH SYNOPSIS +.B lp +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lp +is a generalized output printing service. +It can be used to queue files for printing, +check a queue, or kill jobs in a queue. +The options are: +.TF -d\ \fIde\fP +.TP +.BI -d " dest" +Select the destination printer. +If +.I dest +is +.LR ? , +list the currently available printers. +In the absence of +.LR -d , +the destination is taken from the environment variable +.BR LPDEST . +Destination +.L stdout +is the standard output. +Destination +.L safari +is +.L /dev/lpt1data +line printer port on a 386 machine, assumed +to be connected to a PostScript printer. +Destinations +.L hpdeskjet +and +.L bjc240l +are also +.L /dev/lpt1data +but assumed to be connected to an HP Deskjet 670 or +Canon BJC-240. +.I Lp +can print to any printer supported by +Ghostscript using syntax +.BI gs!device +where +.I device +is a Ghostscript output device. +See +.IR gs (1) +and the +.L canonbjc240l +entry in +.LR /sys/lib/lp/devices . +.TP +.B -k +Kill the job(s) given as subsequent arguments, instead of file names, +for the given destination. +.TP +.BI -p " proc" +The given processor is invoked. +The default processor is +.LR generic , +which tries to do the right thing for regular text, +.IR troff (1) +output, or +.IR tex (1) +output. +If no processing is desired +.L noproc +may be specified. +.TP +.B -q +Print the queue for the given destination. +For some devices, include printer status. +.TP +.B -R +Stops and restarts the printer daemon. +If the printer is wedged, it is often useful to cycle the power on the printer +before running this command. +.PD +.PP +The remaining options may be used to affect the output at a given device. +These options may not be applicable to all devices. +.TF "-p\ \fIpr\fP" +.TP +.BI -c " n" +Print +.I n +copies. +.TP +.BI -f " font" +Set the font (default +.LR CW.11 ). +.TP +.BI -H +Suppress printing of header page. +.TP +.BI -i " n" +Select paper input tray. +.I n +may be a number 0-9, the word +.L man +for the manual feed slot, and/or +.L simplex +or +.L duplex +to get single or double sided output. +Multiple input tray options may be specified if they are +separated by commas. +.TP +.BI -l " n" +Set the number of lines per page to +.IR n . +.TP +.B -L +Print pages in landscape mode (i.e. turned 90 degrees). +.TP +.BI -m " v" +Set magnification to +.IR v . +.TP +.BI -n " n" +Print +.I n +logical pages per physical page. +.TP +.BI -o " list" +Print only pages whose page numbers appear in +the comma-separated +.I list +of numbers and ranges. +A range +.IB n - m +means pages +.I n +through +.IR m ; +a range +.BI - n +means from the beginning to page +.IR n ; +a range +.IB n - +means from page +.I n +to the end. +.TP +.B -r +Reverse the order of page printing. +.TP +.BI -x " v" +Set the horizontal +offset of the print image, measured in inches. +.TP +.BI -y " v" +Set the vertical +offset of the print image, measured in inches. +.SH EXAMPLES +.TP 0 +.L +eqn paper | troff -ms | lp -dsafari +Typeset and print a paper containing equations. +.TP +.L +pr -l100 file | lp -l100 -fCW.8 +Print a file in a small font at 100 lines per page. +.TP +.L +lp -dstdout /dev/windows/3/window > doc.ps +Convert an image to a postscript file. +.SH SOURCE +.nf +.B /rc/bin/lp +.B /sys/src/cmd/lp +.SH SEE ALSO +.IR lp (8) +.br +P. Glick, +``A Guide to the Lp Printer Spooler''. +.SH BUGS +Not all options work with all output devices. +Any user can kill any job. diff --git a/sys/man/1/ls b/sys/man/1/ls new file mode 100755 index 000000000..e89d75d6a --- /dev/null +++ b/sys/man/1/ls @@ -0,0 +1,160 @@ +.TH LS 1 +.SH NAME +ls, lc \- list contents of directory +.SH SYNOPSIS +.B ls +[ +.B -dlmnpqrstuFQT +] +.I name ... +.PP +.B lc +[ +.B -dlmnqrstuFQT +] +.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 -T +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; +.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/sys/man/1/mail b/sys/man/1/mail new file mode 100755 index 000000000..cfe042969 --- /dev/null +++ b/sys/man/1/mail @@ -0,0 +1,164 @@ +.TH MAIL 1 +.SH NAME +mail, go.fishing \- mail and mailboxes +.SH SYNOPSIS +.B mail +[ +.I arg ... +] +.PP +.B go.fishing +.SH DESCRIPTION +.PP +Mail is a shell script that invokes +.IR nedmail (1), +the mail reader, +when no recipients appear on the command line and +.IR marshal (1), +the mail preparer, +otherwise. +All command line options are passed through. +See the man pages for those two commands for +more details. +.PP +Incoming mail for a user +.I username +is put in the file +.BI /mail/box/ username /mbox +unless either the file +.BI /mail/box/ username /forward +or +.BI /mail/box/ username /pipeto +exists. +The mailbox must have append-only and exclusive-access mode +(see +.IR chmod (1)). +A user must create his or her own mailbox using the +.B -c +option of +.IR nedmail (1). +Mailboxes are created writable (append-only) but not readable by others. +.PP +If the file +.BI /mail/box/ username /forward +exists and is readable by everyone, incoming mail +will be forwarded to the addresses contained in the first line of the file. +The file may contain multiple addresses. +Forwarding loops are caught and resolved by local delivery. +.PP +If the file +.BI /mail/box/ username /pipeto +exists and is readable and executable by everyone, +it will be run for each incoming message for the user. +The message will be piped to it rather +than appended to his/her mail box. +The file is run as user +.BR none . +Its two arguments are the +with arguments of the destination address +(e.g., +.BR local!gremlin ) +and the user's mail box path +(e.g., +.BR /mail/box/gremlin/mbox ) +.SS Auto-answer +.PP +To use +.I mail +as an answering machine while you are away, +run +.IR go.fishing , +which will create +.B /mail/box/$user/gone.fishing +as a flag for +.B pipeto +processing, +and truncate +.BR /mail/box/$user/gone.addrs . +Any existing +.B pipeto +file that uses +.B /mail/lib/pipeto.lib +will invoke the +.I gone.fishing +machinery when it calls +.B spool +or +.BR spool-tagged-spam . +.PP +If +.B /mail/box/$user/gone.msg +exists, it +will be sent (just once) to everyone who +sends you mail that lists your address in a +.L To +or +.L Cc +header; +if not, +.B /mail/lib/gone.msg +will be sent. +Upon your return, remove +.B /mail/box/$user/gone.fishing +to stop automatic responses. +.SH FILES +.TF /mail/box/$user/gone.fishing +.TP +.B /sys/log/mail +mail log file +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.TP +.B /mail/box/*/forward +forwarding address(es) +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /mail/box/*/L.reading +mutual exclusion lock for multiple mbox readers +.TP +.B /mail/box/*/L.mbox +mutual exclusion lock for altering mbox +.TP +.B /lib/face/48x48x? +directories of icons for +.I seemail +.TP +.B /mail/lib/pipeto.lib +helper functions for pipeto files +.TP +.B /mail/lib/gone.msg +default vacation message +.TP +.B /mail/lib/gone.fishing +auto-responder as +.I pipeto +script +.TP +.B /mail/box/$user/gone.fishing +flag to active gone processing +.TP +.B /mail/box/$user/gone.addrs +list of senders answered by +.I gone.fishing +.SH SOURCE +.B /rc/bin/mail +.br +.B /rc/bin/go.fishing +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/man b/sys/man/1/man new file mode 100755 index 000000000..fd85456c9 --- /dev/null +++ b/sys/man/1/man @@ -0,0 +1,122 @@ +.TH MAN 1 +.SH NAME +man, lookman, sig \- print or find pages of this manual +.SH SYNOPSIS +.B man +[ +.B -bnpPStw +] +[ +.I section ... +] +.I title ... +.PP +.B lookman +.I key ... +.PP +.B sig +.I function ... +.SH DESCRIPTION +.I Man +locates and prints pages of this manual named +.I title +in the specified +.IR sections . +.I Title +is given in lower case. +Each +.I section +is a number; +pages marked (2S), for example, +belong to chapter 2. +If no +.I section +is specified, pages +in all sections are printed. +Any name from the +.SM NAME +section at the top of the page will serve as a +.IR title . +.PP +The options are: +.TP +.B -n +(Default) +Print the pages on the standard output using +.IR nroff . +.TP +.B -b +Print the pages using +.I nroff +and send them to +.IR plumber (4) +for display in the editor. +.TP +.B -p +Run +.IR proof (1) +on the specified man pages. +.TP +.B -P +Run +.IR page (1) +on the specified man pages. +.TP +.B -S +Do not search the manual indices for the names. +Only print pages whose file names match the names. +.TP +.B -t +Run +.IR troff (1) +and send its output +to standard output. +.TP +.B -w +Print the names of the man page source files. +.PD +.PP +.B Lookman +prints the names of all manual sections that contain +all of the +.I key +words given on the command line. +.PP +.B Sig +prints the signature (i.e. C definition) of the +.IR function s +given on the command line. +.SH FILES +.TP +.B /sys/man/?/* +.I troff +source for manual; this page is +.B /sys/man/1/man +.TP +.B /sys/man/?/INDEX +indices searched to find pages corresponding to titles +.TP +.B /sys/lib/man/secindex +command to make an index for a given section +.TP +.B /sys/lib/man/lookman/index +index for +.I lookman +.SH SOURCE +.B /rc/bin/man +.br +.B /rc/bin/lookman +.SH "SEE ALSO" +.IR page (1), +.IR proof (1) +.SH BUGS +The manual was intended to be typeset; some detail is sacrificed on text terminals. +.PP +There is no automatic mechanism to keep the indices up to date. +.PP +Except for special cases, +.I man +doesn't recognize things that should be run through +.I tbl +and/or +.IR eqn . diff --git a/sys/man/1/marshal b/sys/man/1/marshal new file mode 100755 index 000000000..b2fc90e27 --- /dev/null +++ b/sys/man/1/marshal @@ -0,0 +1,173 @@ +.TH MARSHAL 1 +.SH NAME +marshal \- formatting and sending mail +.SH SYNOPSIS +.B upas/marshal +[ +.B -[aA] +.I attachment +] [ +.B -C +.I copyaddr +] [ +.B -nrx# +] [ +.B -R +.I reply-msg +] [ +.B -s +.I subject +] [ +.B -t +.I mime-type +] [ +.I mailaddr ... +] +.SH DESCRIPTION +.I Marshal +builds a mail message from standard input and passes it, +if the body is non-empty, +for transmission or delivery to +.BI /mail/box/ username /pipefrom +if it exists, otherwise to +.BR /bin/upas/send . +The message format is both RFC 822 and +MIME conformant, so +.I marshal +adds any required headers not already in the message, prefixed by +the contents of +.BI /mail/box/ username /headers\f1. +This allows the addition of personal headers like +.B From: +lines with a full name or a different +return address. +Command line options direct marshal to add a subject line +and append attachments. The arguments to +.I marshal +are the addresses of the recipients. +.PP +When running in a +.IR rio (1) +window, +.I marshal +automatically puts the window into hold mode (see +.IR rio (1)); +this means that the message can be edited freely, +because nothing will be sent to +.I marshal +until the ESC key is hit to exit hold mode. +.PP +The options are: +.TF "-a file" +.TP +.BI -a file +directs +.I marshal +to append +.I file +as a mime attachment. +Unless explicitly specified by the +.B -t +option, the type of the attachment is determined +by running the +.IR file (1) +command. +.TP +.BI -A file +is like +.B -a +but the message disposition is marked as +.I inline +directing any mail reader to display the attachment +(if it can) when the mail message is read. +.TP +.BI -C copyaddr +adds a +.B Cc: +header with +.I copyaddr +and also adds +.I copyaddr +as a recipient. +.TP +.BI -n +intentionally no standard input +.TP +.B -#xr +are all passed as command line options to the +.I send +that +.I marshal +invokes. +.TP +.BI -R replymsg +tells marshal what message this one is in reply to. +.I Replymsg +is an +.IR upasfs (4) +directory containing the message. +.I Marshal +uses any message id in this message in its +.B In-Reply-To +field. It also passes the directory to +.BI /mail/box/ username /pipefrom +in the +.B replymsg +environment variable. Thus, +.B pipefrom +can alter the message to somehow match +the reply to the message it is replying to. +.TP +.BI -s subject +adds a +.B Subject: +header line to the message if one does not +already exist. +.TP +.BI -t type +sets the content type for the attachments from +all subsequent +.B -a +and +.B -A +options. +.PD +.PP +.I Marshal +also expands any user mail aliases contained in +.BI /mail/box/ username /names. +The format of the alias file is the same as that +for system aliases, see +.IR aliasmail (8). +.PP +.I Marshal +uses the login name as the reply address. This +can be overriden using the environment variable +.BR upasname . +Its value will become both the envelope +and +.B From: +mailbox name. +For example: +.IP +.EX +upasname=natasha@kremvax.com upas/mail boris@squirrel.com +.EE +.SH FILES +.TP +.B /mail/box/*/dead.letter +.SH SOURCE +.TP +.B /sys/src/cmd/upas/marshal +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) diff --git a/sys/man/1/mc b/sys/man/1/mc new file mode 100755 index 000000000..40fec44d4 --- /dev/null +++ b/sys/man/1/mc @@ -0,0 +1,44 @@ +.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) +or +.IR acme (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 acme (1), +.IR acme (4), +.IR pr (1), +.I lc +in +.IR ls (1) diff --git a/sys/man/1/mk b/sys/man/1/mk new file mode 100755 index 000000000..bd1a8ae8f --- /dev/null +++ b/sys/man/1/mk @@ -0,0 +1,655 @@ +.TH MK 1 +.SH NAME +mk, membername \- maintain (make) related files +.SH SYNOPSIS +.B mk +[ +.B -f +.I mkfile +] ... +[ +.I option ... +] +[ +.I target ... +] +.PP +.B membername +.I aggregate ... +.SH DESCRIPTION +.I Mk +uses the dependency rules specified in +.I mkfile +to control the update (usually by compilation) of +.I targets +(usually files) +from the source files upon which they depend. +The +.I mkfile +(default +.LR mkfile ) +contains a +.I rule +for each target that identifies the files and other +targets upon which it depends and an +.IR rc (1) +script, a +.IR recipe , +to update the target. +The script is run if the target does not exist +or if it is older than any of the files it depends on. +.I Mkfile +may also contain +.I meta-rules +that define actions for updating implicit targets. +If no +.I target +is specified, the target of the first rule (not meta-rule) in +.I mkfile +is updated. +.PP +The environment variable +.B $NPROC +determines how many targets may be updated simultaneously; +Plan 9 sets +.B $NPROC +automatically to the number of CPUs on the current machine. +.PP +Options are: +.TP \w'\fL-d[egp]\ 'u +.B -a +Assume all targets to be out of date. +Thus, everything is updated. +.PD 0 +.TP +.BR -d [ egp ] +Produce debugging output +.RB ( p +is for parsing, +.B g +for graph building, +.B e +for execution). +.TP +.B -e +Explain why each target is made. +.TP +.B -i +Force any missing intermediate targets to be made. +.TP +.B -k +Do as much work as possible in the face of errors. +.TP +.B -n +Print, but do not execute, the commands +needed to update the targets. +.TP +.B -s +Make the command line arguments sequentially rather than in parallel. +.TP +.B -t +Touch (update the modified date of) file targets, without +executing any recipes. +.TP +.BI -w target1 , target2,... +Pretend the modify time for each +.I target +is the current time; useful in conjunction with +.B -n +to learn what updates would be triggered by +modifying the +.IR targets . +.PD +.PP +The +.IR rc (1) +script +.I membername +extracts member names +(see `Aggregates' below) +from its arguments. +.SS The \fLmkfile\fP +A +.I mkfile +consists of +.I assignments +(described under `Environment') and +.IR rules . +A rule contains +.I targets +and a +.IR tail . +A target is a literal string +and is normally a file name. +The tail contains zero or more +.I prerequisites +and an optional +.IR recipe , +which is an +.B rc +script. +Each line of the recipe must begin with white space. +A rule takes the form +.IP +.EX +target: prereq1 prereq2 + rc \f2recipe using\fP prereq1, prereq2 \f2to build\fP target +.EE +.PP +When the recipe is executed, +the first character on every line is elided. +.PP +After the colon on the target line, a rule may specify +.IR attributes , +described below. +.PP +A +.I meta-rule +has a target of the form +.IB A % B +where +.I A +and +.I B +are (possibly empty) strings. +A meta-rule acts as a rule for any potential target whose +name matches +.IB A % B +with +.B % +replaced by an arbitrary string, called the +.IR stem . +In interpreting a meta-rule, +the stem is substituted for all occurrences of +.B % +in the prerequisite names. +In the recipe of a meta-rule, the environment variable +.B $stem +contains the string matched by the +.BR % . +For example, a meta-rule to compile a C program using +.IR 2c (1) +might be: +.IP +.EX +%: %.c + 2c $stem.c + 2l -o $stem $stem.2 +.EE +.PP +Meta-rules may contain an ampersand +.B & +rather than a percent sign +.BR % . +A +.B % +matches a maximal length string of any characters; +an +.B & +matches a maximal length string of any characters except period +or slash. +.PP +The text of the +.I mkfile +is processed as follows. +Lines beginning with +.B < +followed by a file name are replaced by the contents of the named +file. +Lines beginning with +.B "<|" +followed by a file name are replaced by the output +of the execution of the named +file. +Blank lines and comments, which run from unquoted +.B # +characters to the following newline, are deleted. +The character sequence backslash-newline is deleted, +so long lines in +.I mkfile +may be folded. +Non-recipe lines are processed by substituting for +.BI `{ command } +the output of the +.I command +when run by +.IR rc . +References to variables are replaced by the variables' values. +Special characters may be quoted using single quotes +.BR \&'' +as in +.IR rc (1). +.PP +Assignments and rules are distinguished by +the first unquoted occurrence of +.B : +(rule) +or +.B = +(assignment). +.PP +A later rule may modify or override an existing rule under the +following conditions: +.TP +\- +If the targets of the rules exactly match and one rule +contains only a prerequisite clause and no recipe, the +clause is added to the prerequisites of the other rule. +If either or both targets are virtual, the recipe is +always executed. +.TP +\- +If the targets of the rules match exactly and the +prerequisites do not match and both rules +contain recipes, +.I mk +reports an ``ambiguous recipe'' error. +.TP +\- +If the target and prerequisites of both rules match exactly, +the second rule overrides the first. +.SS Environment +Rules may make use of +.B rc +environment variables. +A legal reference of the form +.B $OBJ +is expanded as in +.IR rc (1). +A reference of the form +.BI ${name: A % B = C\fL%\fID\fL}\fR, +where +.I A, B, C, D +are (possibly empty) strings, +has the value formed by expanding +.B $name +and substituting +.I C +for +.I A +and +.I D +for +.I B +in each word in +.B $name +that matches pattern +.IB A % B\f1. +.PP +Variables can be set by +assignments of the form +.I + var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR +.br +Blanks in the +.I value +break it into words, as in +.I rc +but without the surrounding parentheses. +Such variables are exported +to the environment of +recipes as they are executed, unless +.BR U , +the only legal attribute +.IR attr , +is present. +The initial value of a variable is +taken from (in increasing order of precedence) +the default values below, +.I mk's +environment, the +.IR mkfiles , +and any command line assignment as an argument to +.IR mk . +A variable assignment argument overrides the first (but not any subsequent) +assignment to that variable. +.PP +The variable +.B MKFLAGS +contains all the option arguments (arguments starting with +.L - +or containing +.LR = ) +and +.B MKARGS +contains all the targets in the call to +.IR mk . +.PP +It is recommended that mkfiles start with +.IP +.EX +\fP/address-list +.TP +.B /mail/box/\fI\fP +list's mailbox directory +.TP +.B /mail/box/\fI\fP-owner +owner's mailbox directory +.TP +.B /mail/box/\fI\fP/address-list +log of mailing list deletions and additions +.SH SOURCE +.TP +.B /sys/src/cmd/upas/ml +.SH "SEE ALSO" +.IR aliasmail (8), +.IR faces (1), +.IR filter (1), +.IR mail (1), +.IR marshal (1), +.IR nedmail (1), +.IR qer (8), +.IR rewrite (6), +.IR send (8), +.IR smtp (8), +.IR upasfs (4) + diff --git a/sys/man/1/mp3dec b/sys/man/1/mp3dec new file mode 100755 index 000000000..b455f54a7 --- /dev/null +++ b/sys/man/1/mp3dec @@ -0,0 +1,47 @@ +.TH MP3DEC 1 +.SH NAME +mp3dec \- decode audio MPEG files (layers 1, 2 and 3) +.SH SYNOPSIS +.B mp3dec +[ +.B -o +.I outfile +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Mp3dec +decodes one or more MPEG audio files, writing +16-bit stereo linear PCM sample data to +.I outfile +(default +.BR /dev/audio ). +If no files are named, +.I mp3dec +reads standard input. +.PP +In the absence of the +.B -o +option, +.I mp3dec +also opens +.BR /dev/volume +and sets the sample rate for playback to +match the audio stream. +When writing to +.IR outfile , +.I mp3dec +prints a warning to standard error +if the stream rate is not 44100 Hz. +.SH SOURCE +.B /sys/src/games/mp3dec +.SH "SEE ALSO" +.IR mp3enc (1), +.IR juke (7), +.IR playlistfs (7) +.br +.B http://www.underbit.com/products/mad/ +.SH BUGS +It's another GNU behemoth, lightly tamed. diff --git a/sys/man/1/mp3enc b/sys/man/1/mp3enc new file mode 100755 index 000000000..53b533bb2 --- /dev/null +++ b/sys/man/1/mp3enc @@ -0,0 +1,209 @@ +.TH MP3ENC 1 +.SH NAME +mp3enc \- create mp3 audio files +.SH SYNOPSIS +.in +0.5i +.ti -0.5i +.B games/mp3enc +[ +.B -hprv +] [ +.B -b +.I bitrate +] [ +.B -B +.I bitrate +] [ +.B -m +.I mode +] [ +.B -q +q ] [ +.B -s +.I sfreq +] [ +.B -V +.I q +] [ +.I "long or silly options" +] +.in -0.5i +.SH DESCRIPTION +.I Mp3enc +compresses audio on standard input, +normally PCM-encoded, +and produces MP3-encoded audio on standard output. +By default, the MP3 file will use `constant bit-rate' (CBR) +encoding, but that can be changed via +.B --abr +(average bitrate desired, ABR) +or +.BR -v +(variable bitrate, VBR). +.SS Options +.TF "\fB-b \fP" +.TP +.B -b +set minimum allowed +.I bitrate +in Kb/s for VBR, default 32Kb/s. +For CBR, +set the exact bitrate in Kb/s, which defaults to 128Kb/s. +.TP +.B -B +set maximum allowed +.I bitrate +in Kb/s for VBR, default 256Kb/s. +.TP +.BI -h +same as +.LR "-q 2" . +.TP +.B -m +.I mode +may be +(s)tereo, +(j)oint, +(f)orce +or +(m)ono +(default j). +.B force +forces mid/side stereo on all frames. +.TP +.B -p +add CRC error protection (adds an additional 16 bits per frame to the stream). +This seems to break playback. +.TP +.B -q +sets output quality to +.I q +(see +.BR -V ). +.TP +.B -r +input is raw pcm +.TP +.B -s +set sampling frequency of input file (in KHz) to +.IR sfreq , +default is 44.1. +.TP +.B -v +use variable bitrate (VBR) encoding +.TP +.B -V +set quality setting for VBR to +.IR q . +Default +.I q +is 4; +0 produces highest-quality and largest files, and +9 produces lowest-quality and smallest files. +.SS Long options +.TF "\fB--resample sfreq \fP" +.TP +.BI --abr " bitrate" +sets average +.I bitrate +desired in Kb/s, instead of setting quality, +and generates ABR encoding. +.TP +.BI --resample " sfreq" +set sampling frequency of output file (in KHz) to +.IR sfreq , +default is input sfreq. +.TP +.BI --mp3input +.I input +is an MP3 file +. +.SS Silly options +.TF --nohist +.TP +.BI -f +same as +.LR "-q 7" . +Such a deal. +.TP +.BI -o +mark as non-original (i.e. do not set the original bit) +.TP +.BI -c +mark as copyright +.TP +.BI -k +disable sfb=21 cutoff +.TP +.BI -e " emp" +de-emphasis n/5/c +(default n) +.TP +.BI -d +allow channels to have different blocktypes +.TP +.BI -t +disable Xing VBR informational tag +.TP +.BI -a +autoconvert from stereo to mono file for mono encoding +.TP +.BI -x +force byte-swapping of input (see +.IR dd (1) +instead) +.TP +.BI -S +don't print progress report, VBR histograms +.TP +.BI --athonly +only use the ATH for masking +.TP +.BI --nohist +disable VBR histogram display +.TP +.BI --voice +experimental voice mode +. +.SH EXAMPLES +Encode a +.L .wav +file as highest-quality MP3. +.IP +.EX +games/mp3enc -q 0 -b 320 +.EE +.LP +Create a fixed 128Kb/s MP3 file from a +.L .wav +file. +.IP +.EX +games/mp3enc -h foo.mp3 +.EE +.LP +Streaming from stereo 44.1KHz raw PCM data, encoding mono at 16KHz +(you may not need +.IR dd ): +.IP +.EX +dd -conv swab | games/mp3enc -a -r -m m --resample 16 -b 24 +.EE +.SH SOURCE +.B /sys/src/games/mp3enc +.SH SEE ALSO +.IR dd (1), +.IR mp3dec (1), +.IR audio (3), +.IR cdfs (4), +.IR audio (7), +.IR juke (7), +.IR playlistfs (7) +.br +.B http://www.sulaco.org/mp3 +.SH BUGS +Quality is much better than encoders based on the ISO routines, +but still not as good as the FhG encoder. +.PP +It's a GNU behemoth, lightly rehabilitated. +There are zillions of undocumented options. diff --git a/sys/man/1/ms2html b/sys/man/1/ms2html new file mode 100755 index 000000000..6f4b45dd4 --- /dev/null +++ b/sys/man/1/ms2html @@ -0,0 +1,78 @@ +.TH MS2HTML 1 +.SH NAME +ms2html, html2ms \- convert between troff's ms macros and html +.SH SYNOPSIS +.B ms2html +[ +.B -q +] [ +.B -b +.I basename +] [ +.B -d +.I delims +] [ +.B -t +.I title +] +.br +.B html2ms +.SH DESCRIPTION +.I Ms2html +converts the +.IR ms (6) +source on standard input into HTML and prints it to +standard output. +If the source contains +.IR tbl (1) +or +.IR eqn +input, you must first pipe the text through those +preprocessors. +Postscript images, equations, and tables will be +converted to gif files. +If the document has a +.B .TL +entry, its contents will be used as the title; otherwise +.I ms2html +will look for a +.B ._T +macro, unknown to +.IR ms (6), +and take its value. +Options are: +.TF q +.IP q +suppresses warnings about malformed input; +.IP b +sets the HTML base name to +.IR basename ; +.IP d +sets the +.IR eqn (1) +delimiters to +.IR delim ; +.IP t +sets the HTML title to +.IR title . +.PD +.PP +.I Html2ms +reads HTML from standard input and converts it +to +.IR ms (6) +source on standard output. +.SH SOURCE +.B /sys/src/cmd/ms2html.c +.br +.B /sys/src/cmd/html2ms.c +.SH SEE ALSO +.IR htmlroff (1), +.IR ms (6) +.SH BUGS +.PP +Ms2html doesn't understand a number of troff +commands. It does handle macros and defined +strings. +.PP +Html2ms doesn't understand html tables. diff --git a/sys/man/1/mtime b/sys/man/1/mtime new file mode 100755 index 000000000..5bfe4da32 --- /dev/null +++ b/sys/man/1/mtime @@ -0,0 +1,13 @@ +.TH MTIME 1 +.SH NAME +mtime \- print file modification time +.SH SYNOPSIS +.B mtime +.I file ... +.SH DESCRIPTION +.I Mtime +prints the modification time (in seconds since the epoch) and name +of each +.IR file . +.SH SOURCE +.B /sys/src/cmd/mtime.c diff --git a/sys/man/1/mug b/sys/man/1/mug new file mode 100755 index 000000000..93815fc0b --- /dev/null +++ b/sys/man/1/mug @@ -0,0 +1,56 @@ +.TH MUG 1 +.SH NAME +mug - convert an image to a face icon +.SH SYNOPSIS +.B mug +[ +.I file +] +.SH DESCRIPTION +.I Mug +reads a Plan 9 +.IR image (6) +from +.I file +(or standard input if there is no +.IR file ) +and +displays a working version of the icon +a gray ramp, +and a larger image (the `crop box'), +all derived from +.IR file . +Selecting +.L Write +from the button-3 menu will write the icon in +.IR face (6) +format to standard output. +.LP +Imagine a 3x3 grid on the crop box. You can move an +edge or corner of the box by putting the mouse in the +corresponding section of the grid and dragging. +Dragging in the middle box in the grid translates the +crop box. The mouse cursor changes to tell you where you are. +.LP +The bar in the gray ramp controls the map from picture +gray levels to the output levels. The values along the +bar are mapped to 0 through 255 in the output. You can +move the bar vertically by grabbing the midsection or +adjust the width by grabbing an endpoint. +.LP +The current icon is shown in the bottom left corner, +surrounded by eight small empty boxes. You can save the +settings as they are by dragging the current icon into +one of the other boxes. You can restore the settings by +dragging an icon from one of the periphery boxes into the middle. +.SH EXAMPLES +Convert a JPEG image into a face icon. +.IP +.EX +jpg -c plus.jpg | mug >plus.1 +.EE +.SH SEE ALSO +.IR faces (1), +.IR jpg (1), +.IR face (6), +.IR image (6) diff --git a/sys/man/1/nedmail b/sys/man/1/nedmail new file mode 100755 index 000000000..6cf29cc39 --- /dev/null +++ b/sys/man/1/nedmail @@ -0,0 +1,340 @@ +.TH NEDMAIL 1 +.SH NAME +nedmail \- reading mail +.SH SYNOPSIS +.B upas/nedmail +[ +.B -nr +] +[ +.B -f +.I mailfile +] +[ +.B -s +.I mailfile +] +.PP +.B upas/nedmail +.B -c +.I dir +.SH DESCRIPTION +.I Nedmail +edits a mailbox. +The default mailbox is +.BI /mail/box/ username /mbox\f1. +The +.B -f +command line option specifies an alternate mailbox. +Unrooted path names are interpreted relative to +.BI /mail/box/ username. +If the +.I mailfile +argument is omitted, the name defaults to +.BR stored . +.PP +The options are: +.TF "-f mailfile" +.TP +.BI -c " dir +Create a mailbox. If +.I dir +is specified, the new mailbox is created in +.BI /mail/box/ username / dir /mbox\f1. +Otherwise, the default mailbox is created. +.TP +.B -r +Reverse: show messages in first-in, first-out order; the default is last-in, first-out. +.TP +.B -n +Make the message numbers the same as the file names in the mail +box directory. This implies the +.B -r +option. +.TP +.BI -f " mailfile" +Read messages from the specified file (see above) instead of the default mailbox. +.TP +.BI -s " mailfile" +Read a single message file +.IR mailfile , +as produced by +.IR fs , +and treat it as an entire mailbox. +This is provided for +use in plumbing rules; see +.IR faces (1). +.PD +.PP +.I Nedmail +starts by reading the mail box, printing out the number +of messages, and then prompting for commands from standard input. +Commands, as in +.IR ed (1), +are of the form +.RI `[ range ] +.I command +.RI [ arguments ]'. +The command is applied to each message in the (optional) range. +.PP +The address range can be: +.TP 1.4i +.I address +to indicate a single message header +.PD 0 +.TP +.IB address , address +to indicate a range of contiguous message headers +.TP +.BI g/ expression / +to indicate all messages whose headers match the regular +.IR expression . +.TP +.BI g% expression % +to indicate all messages whose contents match the regular +.IR expression . +.PD +.PP +The addresses can be: +.TP 1.4i +.I number +to indicate a particular message +.PD 0 +.TP +.IB address . number +to indicate a subpart of a particular message +.TP +.BI / expression / +to indicate the next message whose header matches +.I expression +.TP +.BI % expression % +to indicate the next message whose contents match +expression +.TP +.I "empty or . +to indicate the current message +.TP +.BI - address +to indicate backwards search or movement +.PD +.PP +Since messages in MIME are hierarchical +structures, in +.I nedmail +all the subparts are individually addressable. +For example if message 2 contains 3 attachments, +the attachments are numbered 2.1, 2.2, and 2.3. +.PP +The commands are: +.TP 1.1i +.BI a " args +Reply to all addresses in the +.BR To: , +.BR From: , +and +.BR Cc: +header lines. +.I Marshal +is used to format the reply and any arguments the +user specifies are added to the command line to +.I marshal +before the recipient. +The possibility of making a fool of yourself is very +high with this command. +.PD 0 +.TP +.BI A " args +Like +.B a +but with the message +appended to the reply. +.TP +.B b +Print the headers for the next ten messages. +.TP +.B d +Mark message to be deleted upon exiting +.IR nedmail . +.TP +.B f +Append the message to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B h +Print the disposition, size in characters, reception time, sender, +and subject of the message. +.TP +.B H +Print the MIME structure of the message. +.TP +.B help +Print a summary of the commands. +.TP +.BI m " person ... +Forward the message as a mime attachment to the named +.IR persons . +.TP +.BI M " person ... +Like +.B m +but allow the user to type in text to be included +with the forwarded message. +.TP +.B p +Print message. An interrupt stops the printing. +.TP +.BI r " args +Reply to the sender of the message. +.I Marshal +is used to format the reply. +If and optional +.I Args +are specified, they are added to the command line to +.I marshal +before the recipient's address. +.TP +.B R " args +Like +.B r +but with the original message included as an attachment. +.TP +.B rf +Like +.B r +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B Rf +Like +.B R +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.BI s " mfile" +Append the message to the specified mailbox. +If +.I mfile +doesn't start with a `/', it is interpreted relative to the directory in which the mailbox resides. +If +.I mfile +is a directory then the destination is a file in that directry. +If the MIME header specifies a file name, that one is used. +Otherwise, one is generated using +.IR mktemp (2) +and the string +.BR att.XXXXXXXXXXX . +.TP +.B q +Put undeleted mail back in the mailbox and stop. +.TP +EOT (control-D) +Same as +.BR q . +.TP +.BI w " file +Same as +.B s +with the mail header line(s) stripped. This can be used to +save binary mail bodies. +.TP +.B u +Remove mark for deletion. +.TP +.B x +Exit, without changing the mailbox file. +.TP +.B y +Synchronize with the mail box. Any deleted +messages are purged and any new messages read. +This is equivalent to quiting nedmail and restarting. +.TP +.BI | command +Run the +.I command +with the message body as standard input. +.TP +.BI || command +Run the +.I command +with the whole message as standard input. +.TP +.BI ! command +Escape to the shell to do +.IR command . +.TP +.B \&= +Print the number of the current message. +.PD +.PP +Here's an example of a mail session that looks at a summary +of the mail messages, saves away an html file added as an +attachment to a message and then deletes the message: +.LP +.EX +% mail +7 messages +: ,h +1 H 2129 07/22 12:30 noone@madeup.net "Add Up To 2000 free miles" +2 504 07/22 11:43 jmk +3 H 784 07/20 09:05 presotto +4 822 07/11 09:23 xxx@yyy.net "You don't call, you don't write..." +5 193 07/06 16:55 presotto +6 529 06/01 19:42 jmk +7 798 09/02 2000 howard +: 1H +1 multipart/mixed 2129 from=noone@madeup.net + 1.1 text/plain 115 + 1.2 text/html 1705 filename=northwest.htm +: 1.2w /tmp/northwest.html +!saved in /tmp/northwest.html +1.2: d +1: q +!1 message deleted +% +.EE +.PP +Notice that the delete of message 1.2 deleted the entire message and +not just the attachment. +.SH FILES +.TF /mail/box/*/dead.letter +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.TP +.B /mail/box/*/forward +forwarding address(es) +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /mail/box/*/L.reading +mutual exclusion lock for multiple mbox readers +.TP +.B /mail/box/*/L.mbox +mutual exclusion lock for altering mbox +.SH SOURCE +.B /sys/src/cmd/upas/ned +.SH "SEE ALSO" +.IR mail (1), +.IR aliasmail (8), +.IR filter (1), +.IR marshal (1), +.IR mlmgr (1), +.IR nedmail (1), +.IR upasfs (4), +.IR smtp (8), +.IR faces (1), +.IR rewrite (6) diff --git a/sys/man/1/netstat b/sys/man/1/netstat new file mode 100755 index 000000000..817e763f1 --- /dev/null +++ b/sys/man/1/netstat @@ -0,0 +1,51 @@ +.TH NETSTAT 1 +.SH NAME +netstat \- summarize network connections +.SH SYNOPSIS +.B netstat +[ +.B -in +] [ +.B -p +.I proto +] [ +.I netmtpt +] +.SH DESCRIPTION +.I Netstat +prints information about network mounted at +.IR netmtpt , +default +.BR /net . +For +.I IP +connections, +.I netstat +reports the protocol, connection number, user, +connection state, local port, remote port and +remote address. +.PP +The options are: +.TP +.B -i +Instead of the usual listing, print one line per network interface. +Each line gives the +device, MTU, local address, mask, remote address, packets in, +packets out, errors in, and errors out for this interface. +.TP +.B -n +By default, +.I netstat +looks up port numbers and addresses in the network databases +to print symbolic names if possible. +This option disables such translation. +.TP +.B -p +Show only connections with the given protocol. +.PD +.SH FILES +.B /net/*/* +.SH SOURCE +.B /sys/src/cmd/netstat.c +.SH "SEE ALSO" +.IR ipconfig (8) diff --git a/sys/man/1/news b/sys/man/1/news new file mode 100755 index 000000000..f95b987f3 --- /dev/null +++ b/sys/man/1/news @@ -0,0 +1,63 @@ +.TH NEWS 1 +.SH NAME +news \- print news items +.SH SYNOPSIS +.B news +[ +.B -a +] +[ +.B -n +] +[ +.I item ... +] +.SH DESCRIPTION +When invoked without options, +this simple local news service +prints files that have appeared in +.BR /lib/news +since last reading, most recent first, +with each preceded by an appropriate header. +The time of reading is recorded. +The options are +.TP +.B -a +Print all items, regardless of currency. +The recorded time is not changed. +.TP +.B -n +Report the names of the current items without +printing their contents, and without changing +the recorded time. +.PP +Other arguments +select particular news items. +.PP +To post a news item, create a file in +.BR /lib/news . +.PP +You may arrange to receive news automatically by +registering your mail address in +.BR /sys/lib/subscribers . +A daemon mails recent news +to all addresses on the list. +.PP +Empty news items, and news items named +.B core +or +.B dead.letter +are ignored. +.SH FILES +.TF \fL/sys/lib/subscribers +.TP +.B /lib/news/* +articles +.TP +.B $HOME/lib/newstime +modify time is time news was last read +.TP +.B /sys/lib/subscribers +who gets news mailed to them +.SH SOURCE +.B /sys/src/cmd/news.c diff --git a/sys/man/1/nm b/sys/man/1/nm new file mode 100755 index 000000000..a77480180 --- /dev/null +++ b/sys/man/1/nm @@ -0,0 +1,107 @@ +.TH NM 1 +.SH NAME +nm \- name list (symbol table) +.SH SYNOPSIS +.B nm +[ +.B -aghnsTu +] +.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 -T +Prefix each line with the symbol's type signature. +.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/sys/man/1/ns b/sys/man/1/ns new file mode 100755 index 000000000..b62398abc --- /dev/null +++ b/sys/man/1/ns @@ -0,0 +1,44 @@ +.TH NS 1 +.SH NAME +ns \- display name space +.SH SYNOPSIS +.B ns +[ +.B -r +] [ +.I pid +] +.SH DESCRIPTION +.I Ns +prints a representation of the file name space of the process with the named +.IR pid , +or by default itself. +The output is in the form of an +.IR rc (1) +script that could, in principle, recreate the name space. +The output is produced by reading and reformatting the contents of +.BI /proc/ pid /ns . +.PP +By default, +.I ns +rewrites the names of network data files to represent the network +address that data file is connected to, for example replacing +.B /net/tcp/82/data +with +.BR tcp!123.122.121.9 . +The +.B -r +flag suppresses this rewriting. +.SH FILES +.B /proc/*/ns +.SH SOURCE +.B /sys/src/cmd/ns.c +.SH "SEE ALSO" +.IR ps (1), +.IR proc (3), +.IR namespace (4), +.IR namespace (6) +.SH BUGS +The names of files printed by +.I ns +will be inaccurate if a file or directory it includes has been renamed. diff --git a/sys/man/1/p b/sys/man/1/p new file mode 100755 index 000000000..d3287599b --- /dev/null +++ b/sys/man/1/p @@ -0,0 +1,33 @@ +.TH P 1 +.SH NAME +p \- paginate +.SH SYNOPSIS +.B p +[ +.BI - number +] +[ +.I file ... +] +.SH DESCRIPTION +.I P +copies its standard input, or the named files if given, +to its standard output, +stopping at the end of every 22nd line, and between files, +to wait for a newline from the user. +The option sets the +.I number +of lines on a page. +.PP +While waiting for a newline, +.I p +interprets the commands: +.TP +.B ! +Pass the rest of the line to the shell as a command. +.TP +.B q +Quit. +.PP +.SH SOURCE +.B /sys/src/cmd/p.c diff --git a/sys/man/1/page b/sys/man/1/page new file mode 100755 index 000000000..4246080c0 --- /dev/null +++ b/sys/man/1/page @@ -0,0 +1,271 @@ +.TH PAGE 1 +.SH NAME +page \- view +FAX, +image, graphic, PostScript, PDF, and +typesetter output +files +.SH SYNOPSIS +.B page +[ +.B -abirPRvVw +] +[ +.B -p +.I ppi +] +[ +.IR file ... +] +.SH DESCRIPTION +.I Page +is a general purpose document viewer. +It can be used to display the individual pages +of a +PostScript, +PDF, +or +.IR tex (1) +or +.IR troff (1) +device independent output +file. +.I Tex +or +.I troff +output is simply converted to PostScript in order to be viewed. +It can also be used to view any number of +graphics files +(such as a +FAX +page, +a Plan 9 +.IR image (6) +file, an Inferno bitmap file, or other common format). +.I Page +displays these +in sequence. +In the absence of named files, +.I page +reads one from standard input. +.PP +By default, +.I page +runs in the window in which it is started +and leaves the window unchanged. +The +.B -R +option causes +.I page +to grow the window if necessary +to display the page being viewed. +The +.B -w +option causes +.I page +to create a new window for itself. +The newly created window will grow as under the +.B -R +option. +If being used to display +multipage documents, +only one file may be specified on the command line. +.PP +The +.B -p +option sets the resolution for PostScript and PDF +files, in pixels per inch. +The default is 100 ppi. +The +.B -r +option reverses the order in which pages are displayed. +.PP +When viewing a document, +.I page +will try to guess the true bounding box, usually rounding up from +the file's bounding box to +8½×11 or A4 size. +The +.B -b +option causes it to respect the bounding box given in the file. +As a more general problem, +some PostScript files claim to conform to Adobe's +Document Structuring Conventions but do not. +The +.B -P +option enables a slightly slower and slightly more +skeptical version of the PostScript processing code. +Unfortunately, there are PostScript documents +that can only be viewed with the +.B -P +option, and there are PostScript documents that +can only be viewed without it. +.PP +When viewing images with +.IR page , +it listens to the +.B image +plumbing channel +(see +.IR plumber (4)) +for more images to display. +The +.B -i +option causes +.I page +to not load any graphics files nor to read +from standard input but rather to listen +for ones to load from the plumbing channel. +.PP +The +.B -v +option turns on extra debugging output, and +the +.B -V +option turns on even more debugging output. +The +.B -a +option causes +.I page +to call +.IR abort (2) +rather than exit cleanly on errors, +to facilitate debugging. +.PP +Pressing and holding button 1 permits panning about the page. +.PP +Button 2 raises a menu of operations on the current image or the +entire set. The image transformations are non-destructive and are +valid only for the currently displayed image. They are lost as soon +as another image is displayed. +The button 2 menu operations are: +.TF Resize +.TP +.B Orig size +Restores the image to the original. All modifications are lost. +.TP +.B Zoom +Prompts the user to sweep a rectangle on the image which is +expanded proportionally to the rectangle. +.TP +.B Fit window +Resizes the image so that it fits in the current window. +.TP +.B Rotate 90 +Rotates the image 90 degrees clockwise +.TP +.B Upside down +Toggles whether images are displayed upside-down. +.TP +.B Next +Displays the next page. +.TP +.B Prev +Displays the previous page. +.TP +.B Zerox +Displays the current image in a new page window. +Useful for selecting important pages from large documents. +.TP +.B Reverse +Reverses the order in which pages are displayed. +.TP +.B Write +Writes the image to file. +.PD +.PP +Button 3 raises a menu of the +pages +to be selected for viewing in any order. +.PP +Typing a +.B q +or +control-D exits the program. +Typing a +.B u +toggles whether images are displayed upside-down. +(This is useful in the common case of mistransmitted upside-down faxes). +Typing a +.B r +reverses the order in which pages are displayed. +Typing a +.B w +will write the currently viewed page to a new file as a compressed +.IR image (6) +file. +When possible, the filename is of the form +.IR basename . pagenum . bit . +Typing a +.B d +removes an image from the working set. +.PP +To go to a specific page, one can type its number followed by enter. +Typing left arrow, backspace, or minus displays the previous page. +Typing right arrow, space, or enter displays the next page. +The up and down arrow pan up and down one half screen height, +changing pages when panning off the top or bottom of the page. +.PP +.I Page +calls +.IR gs (1) +to draw each page of PostScript +and +PDF +.IR files . +It also calls a variety of conversion programs, such as those described in +.IR jpg (1), +to convert the various raster graphics formats +into Inferno bitmap files. +Pages are converted ``on the fly,'' as needed. +.SH EXAMPLES +.TP +.L +page /sys/src/cmd/gs/examples/tiger.eps +Display a color PostScript file. +.TP +.L +page /usr/inferno/icons/*.bit +Browse the Inferno bitmap library. +.TP +.L +man -t page | page -w +Preview this manual in a new window. +.SH "SEE ALSO +.IR gs (1), +.IR jpg (1), +.IR tex (1), +.IR troff (1) +.SH SOURCE +.B /sys/src/cmd/page +.SH DIAGNOSTICS +The mouse cursor changes to an arrow and ellipsis +when +.I page +is reading or writing a file. +.SH BUGS +.I Page +supports reading of only one document +file at a time, and +the user interface is clumsy when viewing very large documents. +.PP +When viewing multipage PostScript files that do not contain +.RB `` %%Page '' +comments, the button 3 menu only contains +``this page'' and ``next page'': +correctly determining +page boundaries in Postscript code is not computable +in the general case. +.PP +If +.I page +has trouble viewing a Postscript file, +it might not be exactly conforming: try viewing it with the +.B -P +option. +.PP +The interface to the plumber is unsatisfactory. In particular, +document references cannot be sent +via plumbing messages. +.PP +There are too many keyboard commands. diff --git a/sys/man/1/passwd b/sys/man/1/passwd new file mode 100755 index 000000000..d15461e3b --- /dev/null +++ b/sys/man/1/passwd @@ -0,0 +1,59 @@ +.TH PASSWD 1 +.SH NAME +passwd, netkey \- change or verify user password +.SH SYNOPSIS +.B passwd +[ +.IR username [@ domain ] +] +.PP +.B netkey +.SH DESCRIPTION +.I Passwd +changes the invoker's Plan 9 password and/or APOP secret. +The Plan 9 password is used to login to a terminal while +the APOP secret is used for a number of external services: +POP3, IMAP, and VPN access. The optional argument specifies +the user name and authentication domain to use if different +than the one associated with the machine +.I passwd +is run on. +.PP +The program first prompts for the old Plan 9 password in the specified +domain to establish +identity. +It then prompts for changes to the password and the +secret. +New passwords and secrets must be typed twice, to forestall mistakes. +New passwords must be sufficiently hard to guess. +They may be of any length greater than seven characters. +.PP +.I Netkey +prompts for a password to encrypt network challenges. +It is a substitute for a SecureNet box. +.PP +These commands may be run only on a terminal, to avoid +transmitting clear text passwords over the network. +.SH SOURCE +.B /sys/src/cmd/auth/passwd.c +.br +.B /sys/src/cmd/auth/netkey.c +.SH "SEE ALSO" +.I readnvram +in +.IR authsrv (2), +.IR encrypt (2), +.IR cons (3), +.IR auth (8), +.IR securenet (8) +.PP +Robert Morris and Ken Thompson, +``UNIX Password Security,'' +.I AT&T Bell Laboratories Technical Journal +Vol 63 (1984), pp. 1649-1672 +.SH BUGS +Now that +.I cpu +connections are always encrypted, the only good reason +to require that these commands be run only on terminals +is concern that the CPU server might be subverted. diff --git a/sys/man/1/patch b/sys/man/1/patch new file mode 100755 index 000000000..3fb4a490c --- /dev/null +++ b/sys/man/1/patch @@ -0,0 +1,158 @@ +.TH PATCH 1 +.SH NAME +patch \- simple patch creation and tracking system +.SH SYNOPSIS +.B patch/create +.I name +.I email +.I files ... +[ +.B < +.I description +] +.PP +.B patch/list +[ +.I name ... +] +.PP +.B patch/diff +.I name +.PP +.B patch/apply +.I name +.PP +.B patch/undo +.I name +.PP +.B patch/note +.I name +[ +.B < +.I note +] +.SH DESCRIPTION +These scripts are a simple patch submission and tracking system +used to propose additions or changes to Plan 9. +There is no guarantee that any patch will be accepted, nor +that it will be accepted verbatim. +Each patch has a +.I name +(lowercase letters, numbers, dash, dot, and underscore only) +and is stored in +.BI /n/sources/patch/ name. +.PP +.I Patch/create +creates a new patch consisting of the changes to +the listed files from the distribution, reading +a description of the patch from standard input: +please provide an explanation of what the change is supposed to do, +some context, and a rationale for the change. +Test data or pointers to same to verify that the fix works are also welcome. +When sending a patch, follow these guidelines: +.IP • 3 +Before preparing the patch, run +.I replica/pull +and base your patch on current distribution source code. +.IP • +If this is a bug fix, explain the bug clearly. +Don't assume the bug is obvious from the fix. +.IP • +If this is a new feature, explain it clearly. +Don't assume it is obvious from the change. +.IP • +Make the new code look as much like the old code as possible: +don't make gratuitous changes, and do follow the style of the old code. +See +.IR style (6) +for the canonical Plan 9 coding style. +.IP • +If your patch changes externally-visible behaviour, +update the manual page. +.PP +The +.I email +address, if not +.LR - , +will be sent notification messages when the patch is applied, rejected, +or commented on. +If rejected, the e-mail will contain a note explaining why and +probably listing suggested changes and encouraging you to resubmit. +.PP +.I Patch/list +displays information about the named patches, +or all currently pending patches if none are specified. +.PP +.I Patch/diff +shows a patch as diffs between the original +source files and the patched source files. +.PP +.I Patch/apply +applies the patch to the current source tree. +It is intended to be run by the Plan 9 developers with +.B pie +as their root file system. +If the source has changed since the patch was +created, +.I apply +will report the conflict and not change any files. +Before changing any files, +.I patch/apply +makes backup copies of the current source tree's +files. The backups are stored in the patch directory. +.PP +.I Patch/undo +will copy the backups saved by +.I patch/apply +back into the source tree. +It will not restore a backup if the file +being replaced is not byte-identical to the one +created by +.I patch/apply. +.SH EXAMPLES +Propose a change to +.IR pwd , +which you have modified locally: +.IP +.EX +% patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c +Fix pwd to print errors to fd 2 rather than 1. +^D +% +.EE +.PP +Then the developers at Bell Labs run +.IP +.EX +patch/diff pwd-errors +.EE +.PP +to inspect the change (possibly viewing +.B /n/sources/patch/pwd-errors/pwd.c +to see the larger context). +To make the change, they run +.IP +.EX +patch/apply pwd-errors +.EE +.LP +Otherwise they run +.IP +.EX +% patch/note pwd-errors +Pwd should definitely print errors to fd 1 because ... +^D +% +.EE +.PP +to add a note to the +.B /n/sources/pwd-errors/notes +file. +.SH FILES +.B /n/sources/patch +.SH SOURCE +.B /rc/bin/patch +.SH SEE ALSO +.IR diff (1) +.br +.B http://plan9.bell-labs.com/wiki/plan9/How_to_contribute diff --git a/sys/man/1/pcc b/sys/man/1/pcc new file mode 100755 index 000000000..fd7acd916 --- /dev/null +++ b/sys/man/1/pcc @@ -0,0 +1,185 @@ +.TH PCC 1 +.SH NAME +pcc \- APE C compiler driver +.SH SYNOPSIS +.B pcc +[ +.I option ... +] +[ +.I name ... +] +.SH DESCRIPTION +.I Pcc +compiles and loads C programs, +using APE (ANSI C/POSIX) include files and libraries. +Named files ending with +.B .c +are preprocessed with +.IR cpp (1), +then compiled with one of the compilers described in +.IR 2c (1), +as specified by the environment variable +.BR $objtype . +The object files are then loaded using one of the loaders described in +.IR 2l (1). +The options are: +.TP \w'\fL-D\ \fIname=def\ 'u +.B "-+ +Accept C++ +.B // +comments. +.TP +.BI -o " out" +Place loader output in file +.I out +instead of the default +.BR 2.out , +.BR v.out , +etc. +.TP +.B -P +Omit the compilation and loading phases; +leave the result of preprocessing +.IB name .c +in +.IB name .i\f1. +.TP +.B -E +Like +.BR -P , +but send the result to standard output. +.TP +.B -c +Omit the loading phase. +.TP +.B -p +Insert profiling code into the executable output. +.TP +.B -w +Print compiler warning messages. +.TP +.BI -l lib +Include +.BI / $objtype /lib/ape/lib lib .a +as a library during the linking phase. +.TP +.B -B +Don't complain about functions used without +ANSI function prototypes. +.TP +.B -V +Enable +.B void* +conversion warnings, as in +.IR 2c (1). +.TP +.B -v +Echo the preprocessing, compiling, and loading commands +before they are executed. +.TP +.BI -D name=def +.br +.ns +.TP +.BI -D name +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -U name +Undefine the +.I name +to the preprocessor, +as if by +.LR #undef . +.TP +.BI -I dir +.L #include +files whose names do not begin with +.L / +are always +sought first in the directory +of the +.I file +argument, +then in directories named in +.B -I +options, +then in +.BR /$objtype/include/ape . +.TP +.B -N +Don't optimize compiled code. +.TP +.B -S +Print an assembly language version of the object code +on standard output. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except that functions for structures declared in included header files +are omitted. +.TP +.B -F +Enable vararg type checking as described in +.IR 2c (1). +This is of limited use without the appropriate +.B #pragma +definitions. +.PP +The APE environment contains all of the include +files and library routines specified in the ANSI C standard +(X3.159-1989), as well as those specified in the IEEE Portable +Operating System Interface standard (POSIX, 1003.1-1990, ISO 9945-1). +In order to access the POSIX routines, source programs should +define the preprocessor constant +.BR _POSIX_SOURCE . +.SH FILES +.TF /$objtype/lib/ape/libap.a +.TP +.B /sys/include/ape +directory for machine-independent +.B #include +files. +.TP +.B /$objtype/include/ape +directory for machine-dependent +.B #include +files. +.TP +.B /$objtype/lib/ape/libap.a +ANSI C/POSIX library. +.SH "SEE ALSO" +.IR cpp (1), +.IR 2c (1), +.IR 2a (1), +.IR 2l (1), +.IR mk (1), +.IR nm (1), +.IR acid (1), +.IR db (1), +.IR prof (1) +.PP +Howard Trickey, +``APE \(em The ANSI/POSIX Environment'' +.SH SOURCE +.B /sys/src/cmd/pcc.c +.SH BUGS +The locale manipulation functions are minimal. +Signal functions and terminal characteristic +handlers are only minimally implemented. +.IR Link +always fails, because Plan 9 doesn't support multiple links to a file. +The functions related to setting effective user and group ids +cannot be implemented because the concept doesn't exist in Plan 9. diff --git a/sys/man/1/pic b/sys/man/1/pic new file mode 100755 index 000000000..685de68fc --- /dev/null +++ b/sys/man/1/pic @@ -0,0 +1,344 @@ +.TH PIC 1 +.de PS \" start picture +. \" $1 is height, $2 is width, both in inches +.if \\$1>0 .sp .35 +.ie \\$1>0 .nr $1 \\$1 +.el .nr $1 0 +.in (\\n(.lu-\\$2)/2u +.ne \\$1 +.. +.de PE \" end of picture +.in +.if \\n($1>0 .sp .65 +.. +.SH NAME +pic, tpic \- troff and tex preprocessors for drawing pictures +.SH SYNOPSIS +.B pic +[ +.I files +] +.PP +.B tpic +[ +.I files +] +.SH DESCRIPTION +.I Pic +is a +.IR troff (1) +preprocessor for drawing figures on a typesetter. +.I Pic +code is contained between +.B .PS +and +.B .PE +lines: +.IP +.EX +\&.PS \f2optional-width\fP \f2optional-height\fP +\f2element-list\fP +\&.PE +.EE +.LP +or in a file mentioned in a +.B .PS +line: +.IP +.BI .PS " " < file +.LP +If +.IR optional-width +is present, the picture is made that many inches wide, +regardless of any dimensions used internally. +The height is scaled in the same proportion unless +.IR optional-height +is present. +If +.B .PF +is used instead of +.BR .PE , +the typesetting position after printing is restored to what it was +upon entry. +.PP +An +.IR element-list +is a list of elements: +.EX + \f2primitive attribute-list\fP + \f2placename\fP : \f2element\fP + \f2placename\fP : \f2position\fP + \f2var\fP = \f2expr\fP + \f2direction\fP + { \f2element-list\fP } + [ \f2element-list\fP ] + for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP } + if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP } + copy \f2file,\fP copy thru \f2macro,\fP copy \f2file\fP thru \fPmacro\fP + sh { \f2commandline\fP } + print \f2expr\fP + reset \f2optional var-list\fP + \f2troff-command\fP +.EE +.PP +Elements are separated by newlines or semicolons; +a long element may be continued by ending the line with a backslash. +Comments are introduced by a +.BI # +and terminated by a newline. +Variable names begin with a lower case letter; +place names begin with upper case. +Place and variable names retain their values +from one picture to the next. +.PP +After each primitive +the current position moves in the current direction +.RB ( up , down , +.BR left , right +(default)) by the size of the primitive. +The current position and direction are saved upon entry +to a +.BR { ... } +block and restored upon exit. +Elements within a block enclosed in +.BR [ ... ] +are treated as a unit; +the dimensions are determined by the extreme points +of the contained objects. +Names, variables, and direction of motion within a block are local to that block. +.PP +.IR Troff-command +is any line that begins with a period. +Such a line is assumed to make sense in the context where it appears; +generally, this means only size and font changes. +.PP +The +.I primitive +objects are: +.br +.EX + box circle ellipse arc line arrow spline move \f2text-list\fP +.EE +.L arrow +is a synonym for +.LR "line ->" . +.PP +An +.IR attribute-list +is a sequence of zero or more attributes; +each attribute consists of a keyword, perhaps followed by a value. +.EX +.ta .5i 2.5i + h(eigh)t \f2expr\fP wid(th) \f2expr\fP + rad(ius) \f2expr\fP diam(eter) \f2expr\fP + up \f2opt-expr\fP down \f2opt-expr\fP + right \f2opt-expr\fP left \f2opt-expr\fP + from \f2position\fP to \f2position\fP + at \f2position\fP with \f2corner\fP + by \f2expr, expr\fP then + dotted \f2opt-expr\fP dashed \f2opt-expr\fP + chop \f2opt-expr\fP -> <- <-> + invis same + fill \f2opt-expr\fP + \f2text-list\fP \f2expr\fP +.EE +Missing attributes and values are filled in from defaults. +Not all attributes make sense for all primitives; +irrelevant ones are silently ignored. +The attribute +.L at +causes the geometrical center to be put at the specified place; +.L with +causes the position on the object to be put at the specified place. +For lines, splines and arcs, +.L height +and +.L width +refer to arrowhead size. +A bare +.I expr +implies motion in the current direction. +.PP +Text is normally an attribute of some primitive; +by default it is placed at the geometrical center of the object. +Stand-alone text is also permitted. +A text list +is a list of text items: +.EX +\f2 text-item\fP: + "..." \f2positioning ...\fP + sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP +\f2 positioning\fP: + center ljust rjust above below +.EE +If there are multiple text items for some primitive, +they are arranged vertically and centered except as qualified. +Positioning requests apply to each item independently. +Text items may contain +.I troff +commands for size and font changes, local motions, etc., +but make sure that these are balanced +so that the entering state is restored before exiting. +.PP +A position is ultimately an +.I x,y +coordinate pair, but it may be specified in other ways. +.EX +\f2 position\fP: + \f2expr, expr\fP + \f2place\fP ± \f2expr, expr\fP + \f2place\fP ± ( \f2expr, expr\fP ) + ( \f2position\fP,\f2 position\fP ) \f2x\fP\fR from one, \f2y\fP\fR the other\fP + \f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP + \f2expr\fP < \f2position\fP , \f2position\fP > + ( \f2position\fP ) +.EE +.PP +.EX +\f2 place\fP: + \f2placename\fP \f2optional-corner\fP + \f2corner\fP of \f2placename\fP + \f2nth\fP \f2primitive\fP \f2optional-corner\fP + \f2corner\fP of \f2nth\fP \f2primitive\fP + Here +.EE +An +.IR optional-corner +is one of the eight compass points +or the center or the start or end of a primitive. +.EX +\f2 optional-corner\fP: + .n .e .w .s .ne .se .nw .sw .c .start .end +\f2 corner\fP: + top bot left right start end +.EE +Each object in a picture has an ordinal number; +.IR nth +refers to this. +.EX +\f2 nth\fP: + \f2n\fPth\f2, n\fPth last +.EE +.PP +The built-in variables and their default values are: +.EX +.ta .5i 2.5i + boxwid 0.75 boxht 0.5 + circlerad 0.25 arcrad 0.25 + ellipsewid 0.75 ellipseht 0.5 + linewid 0.5 lineht 0.5 + movewid 0.5 moveht 0.5 + textwid 0 textht 0 + arrowwid 0.05 arrowht 0.1 + dashwid 0.1 arrowhead 2 + scale 1 +.EE +These may be changed at any time, +and the new values remain in force from picture to picture until changed again +or reset by a +.L reset +statement. +Variables changed within +.B [ +and +.B ] +revert to their previous value upon exit from the block. +Dimensions are divided by +.B scale +during output. +.PP +Expressions in +.I pic +are evaluated in floating point. +All numbers representing dimensions are taken to be in inches. +.EX +\f2 expr\fP: + \f2expr\fP \f2op\fP \f2expr\fP + - \f2expr\fP + ! \f2expr\fP + ( \f2expr\fP ) + variable + number + \f2place\fP .x \f2place\fP .y \f2place\fP .ht \f2place\fP .wid \f2place\fP .rad + sin(\f2expr\fP) cos(\f2expr\fP) atan2(\f2expr,expr\fP) log(\f2expr\fP) exp(\f2expr\fP) + sqrt(\f2expr\fP) max(\f2expr,expr\fP) min(\f2expr,expr\fP) int(\f2expr\fP) rand() +\f2 op\fP: + + - * / % < <= > >= == != && || +.EE +.PP +The +.B define +and +.B undef +statements are not part of the grammar. +.EX + define \f2name\fP { \f2replacement text\fP } + undef \f2name\fP +.EE +Occurrences of +.BR $1 , +.BR $2 , +etc., +in the replacement text +will be replaced by the corresponding arguments if +.I name +is invoked as +.EX + \f2name\fP(\f2arg1\fP, \f2arg2\fP, ...) +.EE +Non-existent arguments are replaced by null strings. +Replacement text +may contain newlines. +The +.B undef +statement removes the definition of a macro. +.PP +.I Tpic +is a +.IR tex (1) +preprocessor that accepts +.IR pic +language. +It produces Tex commands that define a box called +.BR \egraph , +which contains the picture. +The box may be output this way: +.IP +.L +\ecenterline{\ebox\egraph} +.SH EXAMPLES +.EX +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.EE +.PP +.PS +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.PE +.SH SOURCE +.B /sys/src/cmd/pic +.SH "SEE ALSO" +.IR grap (1), +.IR doctype (1), +.IR troff (1) +.br +B. W. Kernighan, +``PIC\(ema Graphics Language for Typesetting'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 diff --git a/sys/man/1/pipefile b/sys/man/1/pipefile new file mode 100755 index 000000000..19f207f31 --- /dev/null +++ b/sys/man/1/pipefile @@ -0,0 +1,101 @@ +.TH PIPEFILE 1 +.SH NAME +pipefile \- attach filter to file in name space +.SH SYNOPSIS +.B pipefile +[ +.B -d +] [ +.B -r +.I command +] [ +.B -w +.I command +] +.I file +.SH DESCRIPTION +.I Pipefile +uses +.IR bind (2) +to attach a pair of pipes to +.IR file , +using them to +interpose filter +.I commands +between the true file and the simulated file that subsequently +appears in the name space. +Option +.B -r +interposes a filter that will affect the data delivered to programs that read from +.IR file ; +.B -w +interposes a filter that will affect the data written by programs to +.IR file . +At least one +.I command +must be specified; +.I pipefile +will insert a +.IR cat (1) +process in the other direction. +.PP +After +.I pipefile +has been run, the filters are established for programs that subsequently +open the +.IR file ; +programs already using the +.I file +are unaffected. +.PP +.I Pipefile +opens the +.I file +twice, once for each direction. If the +.I file +is a single-use device, such as +.BR /dev/mouse , +use the +.B -d +flag to specify that the file is to be opened once, in +.B ORDWR +mode. +.SH EXAMPLES +Simulate an old terminal: +.EX +.IP +% pipefile -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% echo hello +HELLO +% +.EE +.PP +Really simulate an old terminal: +.EX +.IP +% pipefile -r 'tr A-Z a-z' -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% DATE +THU OCT 12 10:13:45 EDT 2000 +% +.EE +.SH SOURCE +.B /sys/src/cmd/pipefile.c +.SH SEE ALSO +.IR mouse (8) +.SH BUGS +The I/O model of +.I pipefile +is peculiar; it doesn't work well on plain files. +It is really intended for use with continuous devices such as +.I /dev/cons +and +.IR /dev/mouse . +.I Pipefile +should be rewritten to be a user-level file system. +.PP +If the program using the file managed by +.I pipefile +exits, the filter will see EOF and exit, and the file will be unusable +until the name space is repaired. diff --git a/sys/man/1/plot b/sys/man/1/plot new file mode 100755 index 000000000..cd1a1b816 --- /dev/null +++ b/sys/man/1/plot @@ -0,0 +1,61 @@ +.TH PLOT 1 +.SH NAME +plot \- graphics filter +.SH SYNOPSIS +.B plot +[ +.I file ... +] +.SH DESCRIPTION +.I Plot +interprets plotting instructions (see +.IR plot (6)) +from the +.I files +or standard input, +drawing the results in a newly created +.IR rio (1) +window. +Plot persists until a newline is typed in the window. +Various options may be interspersed with the +.I file +arguments; they take effect at the given point in processing. +Options are: +.TP "\w'\fL-g \fIgrade\fLXX'u" +.B -d +Double buffer: accumulate the plot off-screen and write to the screen all at once +when an erase command is encountered or at end of file. +.TP +.B -e +Erase the screen. +.TP +.BI -c " col" +Set the foreground color (see +.IR plot (6) +for color names). +.TP +.BI -f " fill" +Set the background color. +.TP +.BI -g " grade" +Set the quality factor for arcs. +Higher grades give better quality. +.TP +.BI -p " col" +Set the pen color. +.TP +.BI -w +Pause until a newline is typed on standard input. +.TP +.B -C +Close the current plot. +.TP +.B -W " x0,y0,x1,y1" +Specify the bounding rectangle of plot's window. +By default it uses a 512×512 window in the +middle of the screen. +.SH SOURCE +.B /sys/src/cmd/plot +.SH "SEE ALSO" +.IR rio (1), +.IR plot (6) diff --git a/sys/man/1/plumb b/sys/man/1/plumb new file mode 100755 index 000000000..6c51d68bd --- /dev/null +++ b/sys/man/1/plumb @@ -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/sys/man/1/pr b/sys/man/1/pr new file mode 100755 index 000000000..14da53770 --- /dev/null +++ b/sys/man/1/pr @@ -0,0 +1,110 @@ +.TH PR 1 +.SH NAME +pr \- print file +.SH SYNOPSIS +.B pr +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Pr +produces a printed listing of one or more +.I files +on its standard output. +The output is separated into pages headed by a date, +the name of the file or a specified header, and the page number. +With no file arguments, +.I pr +prints its standard input. +.PP +Options apply to all following files but may be reset +between files: +.TP +.BI - n +Produce +.IR n -column +output. +.TP +.BI + n +Begin printing with page +.IR n . +.TP +.B -b +Balance columns on last page, in case of multi-column output. +.TP +.B -d +Double space. +.TP +.BI -e n +Set the tab stops for input text every +.I n +spaces. +.TP +.B -h +Take the next argument as a page header +.RI ( file +by default). +.TP +.BI -i n +Replace sequences of blanks in the output +by tabs, using tab stops set every +.I n +spaces. +.TP +.BI -f +Use form feeds to separate pages. +.TP +.BI -l n +Take the length of the page to be +.I n +lines instead of the default 66. +.TP +.B -m +Print all +.I files +simultaneously, +each in one column. +.TP +.BI -n m +Number the lines of each +.IR file . +The numeric argument +.IR m , +default 5, +sets the width of the line-number field. +.TP +.BI -o n +Offset the left margin +.I n +character positions. +.TP +.BI -p +Pad each file printed to an even number of pages, if necessary. +For two-sided printers, +this will ensure each file will start a new page. +.TP +.BI -s c +Separate columns by the single character +.I c +instead of aligning them with white space. +A missing +.I c +is taken to be a tab. +.TP +.B -t +Do not print the 5-line header or the +5-line trailer normally supplied for each page. +.TP +.BI -w n +For multi-column output, +take the width of the page to be +.I n +characters instead of the default 72. +.SH SOURCE +.B /sys/src/cmd/pr.c +.SH "SEE ALSO" +.IR cat (1), +.IR lp (1) diff --git a/sys/man/1/prof b/sys/man/1/prof new file mode 100755 index 000000000..40e4a9901 --- /dev/null +++ b/sys/man/1/prof @@ -0,0 +1,167 @@ +.TH PROF 1 +.SH NAME +prof, tprof, kprof \- display profiling data +.SH SYNOPSIS +.B prof +[ +.B -dr +] +[ +.I program +] +[ +.I profile +] +.PP +.B tprof +.I pid +.PP +.B kprof +.I kernel +.I kpdata +.SH DESCRIPTION +.I Prof +interprets files produced automatically by programs loaded using the +.B -p +option of +.IR 2l (1) +or other loader. +The symbol table in the +named program file +.RL ( 2.out +etc., according to +.BR $objtype , +by default) +is read and correlated with the +profile file +.RL ( prof.out +by default). +For each symbol, the percentage +of time (in seconds) spent executing between that symbol +and the next +is printed (in decreasing order), +together with the time spent there and +the number of times that routine was called. +.PP +Under option +.BR -d , +.I prof +prints the dynamic call graph of the target program, +annotating the calls with the time spent in each routine +and those it calls, recursively. The output is indented +two spaces for each call, and is formatted as +.IP +.EX +symbol:time/ncall +.EE +.LP +where +.I symbol +is the entry point of the call, +.I time +is in milliseconds, +and +.I ncall +is the number of times that entry point was called at that +point in the call graph. If +.I ncall +is one, the +.B /ncall +is elided. +Normally recursive calls are compressed to keep the output brief; +option +.B -r +prints the full call graph. +.PP +The size of the buffer +in +.I program +used to hold the profiling +data, by default 2000 entries, +may be controlled by setting the environment variable +.B profsize +before running +.IR program . +If the buffer fills, subsequent function calls may not be recorded. +.PP +The profiling code provided by the linker initializes itself to profile the current pid, +producing a file called +.B prof.\f2pid\fP. +If a process forks, only the parent will continue to be profiled. Forked children +can cause themselves to be profile by calling +.IP +.EX +prof(fn, arg, entries, what) +.EE +.LP +which causes the function \f2fn\fP(\f2arg\fP) to be profiled. When \f2fn\fP +returns +.B prof.\f2pid\fP +is produced for the current process pid. +.PP +The environment variable +.B proftype +can be set to one of +.BR user , +.BR kernel , +.BR elapsed , +or +.BR sample , +to profile time measured spent in user mode, time spent in user+kernel mode, or elapsed time, +using the cycle counter, or the time in user mode using the kernel's HZ clock. The cycle counter +is currently only available on modern PCs and on the PowerPC. Default profiling measures user +time, using the cycle counter if it is available. +.PP +.I Tprof +is similar to +.IR prof , +but is intended for profiling multiprocess programs. +It uses the +.BI /proc/ pid /profile +file to collect instruction frequency counts for the text image associated with the process, +for all processes that share that text. +It must be run while the program is still active, since the data is stored with the running program. +To enable +.I tprof +profiling for a given process, +.IP +.EX +echo profile > /proc/\f2pid\f1/ctl +.EE +.LP +and then, after the program has run for a while, execute +.IP +.EX +tprof \f2pid\f1 +.EE +.LP +Since the data collected for +.I tprof +is based on interrupt-time sampling of the program counter, +.I tprof +has no +.B -d +or +.B -r +options. +.PP +.I Kprof +is similar to +.IR prof , +but presents the data accumulated by the kernel +profiling device, +.IR kprof (3) . +The symbol table file, that of the operating system kernel, +and the data file, typically +.BR /dev/kpdata , +must be provided. +.I Kprof +has no options and cannot present dynamic data. +.SH SOURCE +.B /sys/src/cmd/prof.c +.br +.B /sys/src/cmd/kprof.c +.SH SEE ALSO +.IR 2l (1), +.IR exec (2), +.IR kprof (3) diff --git a/sys/man/1/proof b/sys/man/1/proof new file mode 100755 index 000000000..f0c6c7f5e --- /dev/null +++ b/sys/man/1/proof @@ -0,0 +1,134 @@ +.TH PROOF 1 +.SH NAME +proof \- troff output interpreter +.SH SYNOPSIS +.B proof +[ +.BI -m mag +] +[ +.BI -/ nview +] +[ +.B -F +.I dir +] +[ +.B -d +] +[ +.I file +] +.SH DESCRIPTION +.I Proof +reads +.IR troff (1) +intermediate language from +.I file +or standard input +and simulates the resulting pages on the screen. +.PP +After a page of text is displayed, +.I proof +pauses for a command from the keyboard. +The typed commands are: +.TP \w'newline\ \ \ 'u +newline +Go on to next page of text. +.TP +.B - +Go back to the previous page. +.TP +.B q +Quit. +.TP +.BI p n +Print page +.IR n . +An out-of-bounds page number means the end nearer to that number; +a missing number means the current page; +a signed number means an offset to the current page. +.TP +.I n +Same as +.BI p n\f1. +.TP +.B c +Clear the screen, then wait for another command. +.TP +.BI m mag +Change the magnification at which the output is printed. +Normally it is printed with magnification .9; +.IR mag "=.5" +shrinks it to half size; +.IR mag "=2" +doubles the size. +.TP +.BI x val +Move everything +.I val +screen pixels to the right (left, if +.I val +is negative). +.TP +.BI y val +Move everything +.I val +screen pixels down (up, if +.I val +is negative). +.TP +.BI / nview +Split the window into +.I nview +pieces. The current page goes into the rightmost, bottommost piece, +and previous pages are shown in the other pieces. +.TP +.BI "-F " dir +Use +.I dir +for fonts instead of +.BR /lib/font/bit . +.TP +.B d +Toggle the debug flag. +.PD +.PP +These commands are also available, under slightly different form, +from a menu on button 3. The +.B pan +menu item allows arbitrary positioning of the page: +after selecting +.BR pan , +press the mouse button again and hold it down while moving +the page to the desired location. The page will be redisplayed +in its entirety when the button is released. +Mouse button 1 also pans, without the need for selecting from a menu. +.PP +The +.BR m , +.BR x , +.BR y , +.BR F , +.BR / , +and +.B d +commands are also available as command line options. +.SH FILES +.TF \fL/lib/font/bit/MAP +.TP +.B /lib/font/bit/* +fonts +.TP +.B /lib/font/bit/MAP +how to convert troff output fonts and character names +into screen fonts and character numbers +.SH SOURCE +.B /sys/src/cmd/proof +.SH SEE ALSO +.IR lp (1), +.IR gs (1), +.IR page (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' diff --git a/sys/man/1/ps b/sys/man/1/ps new file mode 100755 index 000000000..3f3c9629d --- /dev/null +++ b/sys/man/1/ps @@ -0,0 +1,113 @@ +.TH PS 1 +.SH NAME +ps, psu \- process status +.SH SYNOPSIS +.B ps +[ +.B -apr +] +.PP +.B psu +[ +.B -apr +] +[ +.I user +] +.SH DESCRIPTION +.I Ps +prints information about processes. +.I Psu +prints only information about processes started by +.I user +(default +.BR $user ). +.PP +For each process reported, +the user, +process id, +user time, +system time, +size, +state, +and command name are printed. +State is one of the following: +.TP \w'\fLno\ \fIresource\ \ \ 'u +.B Moribund +Process has exited and is about to have its +resources reclaimed. +.TP +.B Ready +on the queue of processes ready to be run. +.TP +.B Scheding +about to be run. +.TP +.B Running +running. +.TP +.B Queueing +waiting on a queue for a resource. +.TP +.B Wakeme +waiting for I/O or some other kernel event to wake it up. +.TP +.B Broken +dead of unnatural causes; lingering +so that it can be examined. +.TP +.B Stopped +stopped. +.TP +.B Stopwait +waiting for another process to stop. +.TP +.B Fault +servicing a page fault. +.TP +.B Idle +waiting for something to do (kernel processes only). +.TP +.B New +being created. +.TP +.B Pageout +paging out some other process. +.TP +.I Syscall +performing the named system call. +.TP +.BI no " resource +waiting for more of a critical +.IR resource . +.PD +.PP +The +.B -r +flag causes +.I ps +to print, before the user time, the elapsed real time for the process. +.PP +The +.B -p +flag causes +.I ps +to print, after the system time, the baseline and current priorities of each process. +.PP +The +.B -a +flag causes +.I ps +to print the arguments for the process. Newlines in arguments will be translated to spaces for display. +.SH FILES +.B /proc/*/status +.SH SOURCE +.B /sys/src/cmd/ps.c +.br +.B /rc/bin/psu +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR kill (1), +.IR ns (1), +.IR proc (3) diff --git a/sys/man/1/ps2pdf b/sys/man/1/ps2pdf new file mode 100755 index 000000000..a4b9a5dd1 --- /dev/null +++ b/sys/man/1/ps2pdf @@ -0,0 +1,90 @@ +.TH PS2PDF 1 +.SH NAME +ps2pdf, pdf2ps \- convert between PostScript and PDF +.SH SYNOPSIS +.B ps2pdf +[ +.I gs-options +] +[ +.I input-file +[ +.I output-file +] +] +.PP +.B pdf2ps +[ +.I gs-options +] +[ +.I input-file +[ +.I output-file +] +] +.SH DESCRIPTION +.I Ps2pdf +and +.I pdf2ps +convert from PostScript to PDF and back by invoking +.IR gs (1). +If +.I output-file +is not specified, they write to standard output. +If neither +.I input-file +nor +.I output-file +is not specified, they read from standard input and write to standard output. +.PP +The +.I gs-options +are passed to Ghostscript unaltered. +The most useful option to +.I ps2pdf +is +.BR -dCompatibilityLevel=\fIlevel , +which sets the version of PDF to be written. +The default is +.BR 1.2 ; +.B 1.3 +and +.B 1.4 +are also possible. +Similarly, the most useful option to +.I pdf2ps +is +.BR -dLanguageLevel=\fIlevel , +which sets the version of PostScript to be written. +The default is +.BR 2 ; +.B 1 +and +.B 3 +are also possible. +.PP +.I Ps2pdf +produces output competitive with +Adobe Distiller in most cases, and it +accepts all the embedded PDF-generation hints that Adobe Distiller does. +.PP +.I Pdf2ps +produces a PostScript file containing one large bitmap +per page. For a more direct and smaller translation, +use Adobe Acrobat's +.B -toPostScript +command-line option. +.SH SOURCE +.B /rc/bin/ps2pdf +.br +.B /rc/bin/pdf2ps +.SH SEE ALSO +.IR gs (1) +.SH BUGS +.IR Gs 's +.I pdfwrite +sometimes emits bad PDF at the default level 1.2. +Adding +.BR '-dCompatibilityLevel=1.4' +should cure it. diff --git a/sys/man/1/pump b/sys/man/1/pump new file mode 100755 index 000000000..d1868d023 --- /dev/null +++ b/sys/man/1/pump @@ -0,0 +1,119 @@ +.TH PUMP 1 +.SH NAME +pump \- copy asynchronously via a large circular buffer +.SH SYNOPSIS +.B pump +[ +.B -b +.I iando +] [ +.B -d +.I sleepms +] [ +.B -f +.I ofile +] [ +.B -i +.I ireadsize +] [ +.B -k +.I KB-buf +] [ +.B -o +.I owritesize +] [ +.B -s +.I start-KB +] [ +.I file +\&... ] +.SH DESCRIPTION +.I Pump +copies +.IR files +(or standard input if none) +to standard output +by using two processes, +one reading and one writing, +sharing a large circular buffer, +thus permitting the reading process to +get ahead of the writing process if the +output device is slow (e.g., an optical disc). +This in turn can keep the output device busy. +The pipeline +.L "dd | dd" +can approximate this, but pipe buffering is limited to 64K +bytes, which is fairly modest. +.PP +Options are: +.TF \fL-m +.TP +.B -b +sets the size of +.I read +and +.I write +operations to +.I iando +bytes. +The default size is 8 kilobytes. +.TP +.B -d +causes the output process to sleep for +.I sleepms +milliseconds initially, giving the reading +process time to accumulate data in the buffer. +.TP +.B -f +writes +.I ofile +rather than standard output +.TP +.B -i +sets the size of +.I read +operations to +.I ireadsize +bytes. +.TP +.B -k +allocates a circular buffer of +.I KB-buf +kilobytes rather than the default +5000 kilobytes. +.TP +.B -o +sets the size of +.I write +operations to +.I owritesize +bytes. +.TP +.B -s +prevents output until +.I start-KB +kilobytes have been read. +.SH EXAMPLES +Append a +.IR venti (8) +arena to a DVD or BD quickly. +.PD 0 +.IP +.EX +cdfs +venti/rdarena arena0 arena.3 | + pump -b 65536 -k 51200 >/mnt/cd/wd/arena.3 +.EE +.PD +.\" .SH FILES +.SH SOURCE +.B /sys/src/cmd/pump.c +.SH SEE ALSO +.IR cp (1), +.IR dd (1), +.IR ecp (1), +.IR cdfs (4) +.SH BUGS +.I Pump +processes spin while waiting for the circular buffer +to fill or drain. diff --git a/sys/man/1/pwd b/sys/man/1/pwd new file mode 100755 index 000000000..f36e4fbf5 --- /dev/null +++ b/sys/man/1/pwd @@ -0,0 +1,38 @@ +.TH PWD 1 +.SH NAME +pwd, pbd \- working directory +.SH SYNOPSIS +.B pwd +.br +.B pbd +.SH DESCRIPTION +.I Pwd +prints the path name of the working (current) directory. +.I Pwd +is guaranteed to return the same path that was used to +enter the directory. +If, however, the name space has changed, or directory names +have been changed, this path name may no longer be valid. +(See +.IR fd2path (2) +for a description of +.BR pwd 's +mechanism.) +.PP +.I Pbd +prints the base name of the working (current) directory. +It prints no final newline and is intended for applications +such as constructing shell prompts. +.SH SOURCE +.B /sys/src/cmd/pwd.c +.br +.B /sys/src/cmd/pbd.c +.SH SEE ALSO +.I cd +in +.IR rc (1), +.IR bind (1), +.IR intro (2), +.IR getwd (2), +.IR fd2path (2) + diff --git a/sys/man/1/ratrace b/sys/man/1/ratrace new file mode 100755 index 000000000..515b5214f --- /dev/null +++ b/sys/man/1/ratrace @@ -0,0 +1,57 @@ +.TH RATRACE 1 +.SH NAME +ratrace \- trace process system calls +.SH SYNOPSIS +.B ratrace +[ +.I pid +] | [ +.I -c command +] +.SH DESCRIPTION +.I Ratrace +shows the system calls executed by a process, +either the one with +.I pid +or a fresh invocation of +.IR command . +.PP +Trace output is determined by the kernel, not +.IR ratrace . +Certain fixed rules apply. +The first four fields of the output are +pid, text name, system call name, and the PC of the user program. +Data is always printed as +.IB pointer /\c +"\fIstring\fP", +where the +.I string +is the first 32 bytes of the data, with +.L \&. +replacing non-printing ASCII characters +(printing characters are those between ASCII space (SP) and delete (DEL), exclusive). +Return values follow an +.LR = , +and include the integer return value, +the +.I errstr +(with "" if there is no +.IR errstr ), +and +the start and stop times for the system call in nanoseconds. +The times are exclusive of the overhead for tracing. +.SH FILES +.BI /proc/ pid /syscalltrace +.br +.BI /proc/ pid /ctl +.SH SOURCE +.B /sys/src/cmd/ratrace.c +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR proc (3) +.SH BUGS +The printing of the data is too limited in length; +printing +.L \&. +instead of something more sensible is limiting. diff --git a/sys/man/1/rc b/sys/man/1/rc new file mode 100755 index 000000000..2dd2a1dd3 --- /dev/null +++ b/sys/man/1/rc @@ -0,0 +1,993 @@ +.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 +.I command +] +[ +.B -m +.I initial +] +[ +.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. +Subscripts can also take the form +.IB m - n +or +.IB m - +to indicate a sequence of elements. +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. +The standard input file +may also be redirected from a file by the sequence +.BI <> file \f1, +which opens +.I file +exactly once, for reading and writing. +.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 ], +.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 . +.PP +.B newconn <>/net/tcp/clone >[1=0] +opens +.B /net/tcp/clone +exactly once for reading and writing and puts it on standard input and output. +.B lpd <>[3]/net/tcp/42/data +opens +.B /net/tcp/42/data +exactly once for reading and writing and puts it on file descriptor 3. +.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 -m +Read commands to initialize +.I rc +from +.I initial +instead of from +.BR /rc/lib/rcmain . +.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. +.PP +Using +.B ~ +to check the value of +.B $status +changes +.BR $status . +.PP +Functions containing here documents don't work. +.PP +Free carets don't get inserted next to keywords. diff --git a/sys/man/1/replica b/sys/man/1/replica new file mode 100755 index 000000000..2201c017a --- /dev/null +++ b/sys/man/1/replica @@ -0,0 +1,341 @@ +.TH REPLICA 1 +.SH NAME +changes, pull, push, scan \- client-server replica management +.SH SYNOPSIS +.B replica/pull +[ +.B -nv +] +[ +.B -c +.I name +]... +[ +.B -s +.I name +]... +.I name +[ +.I path +... +] +.br +.B replica/push +[ +.B -nv +] +.I name +[ +.I path +... +] +.br +.B replica/changes +.I name +[ +.I path +... +] +.br +.B replica/scan +.I name +[ +.I path +... +] +.SH DESCRIPTION +These shell scripts provide a simple log-based client-server replica management. +The server keeps a log of changes made to its file system, +and clients synchronize by reading the log and applying these changes locally. +.PP +These scripts are a polished interface to the low-level tools described in +.IR replica (8). +See +.IR replica (8) +for details on the inner workings of replica management. +These tools were written primarily as the fourth +edition Plan 9 distribution mechanism, but they +have wider applicability. +For example, they could be used to synchronize one's +home directory between a laptop and a central file server. +.PP +Replicas are described by configuration files. +The +.I name +in all the replica commands is a configuration +file. Paths that do not begin with +.BR / , +.BR ./ , +or +.B ../ +are assumed to be relative to +.BR $home/lib/replica . +Configuration files are described below. +.PP +.I Replica/scan +is the only one of these programs that does not +need to be run on the client. +It scans the server file system for changes +and appends entries for those changes into the server log. +Typically it is run on a machine with a fast network +connection to the server file system. +.PP +.I Replica/pull +copies changes from the server to the client, +while +.I replica/push +copies changes from the client to the server. +(Both run on the client.) +If a list of +.I paths +is given, only changes to those paths or their children are copied. +The +.B -v +flag causes +.I pull +or +.I push +to print a summary of what it is doing. +Each status line is of the form +.ift .sp 0.5 +.ifn .sp +\h'0.25i' +.I verb +.I path +.I serverpath +.I mode +.I uid +.I gid +.I mtime +.I length +.ift .sp 0.5 +.ifn .sp +.I Verb +describes the event: +addition of a file +.RB ( a ), +deletion of a file +.RB ( d ), +a change to a file's contents +.RB ( c ), +or a change to a file's metadata +.RB ( m ). +.I Path +is the file path on the client; +.I serverpath +is the file path on the server. +.IR Mode , +.IR uid , +.IR gid , +and +.I mtime +are the file's metadata as in the +.B Dir +structure (see +.IR stat (5)). +For deletion events, the metadata is that of the deleted file. +For other events, the metadata is that after the event. +The +.B -n +flag causes +.I pull +or +.I push +to print the summary but not actually carry out the actions. +.PP +.I Push +and +.I pull +are careful to notice simultaneous changes to a file or +its metadata on both client and server. +Such simultaneous changes are called +.IR conflicts . +Here, simultaneous does not mean at the same instant +but merely that both changes were carried out without knowledge +of the other. +For example, if a client and server both make changes to a file +without an intervening +.I push +or +.IR pull , +the next +.I push +or +.I pull +will report an update/update conflict. +If a conflict is detected, both files are left the same. +The +.B -c +flag to +.I pull +specifies that conflicts for paths beginning with +.I name +should be resolved using the client's copy, +while +.B -s +specifies the server's copy. +The +.B -c +and +.B -s +options may be repeated. +.PP +.I Replica/changes +prints a list of local changes made on the client +that have not yet been pushed to the server. +It is like +.I push +with the +.B -n +flag, except that it does not check for conflicts +and thus does not require the server to be available. +.PP +The replica configuration file is an +.IR rc (1) +script that must define the following functions and variables: +.TP +.B servermount +A function that mounts the server; run on both client and server. +.TP +.B serverupdate +A function that rescans the server for changes. +Typically this command dials a CPU server known +to be close to the file server and runs +.I replica/scan +on that well-connected machine. +.TP +.B serverroot +The path to the root of the replicated file +system on the server, as it will be in the name space +after running +.BR servermount . +.TP +.B serverlog +The path to the server's change log, after running +.BR servermount . +.TP +.B serverproto +The path to the proto file describing the server's files, +after running +.BR servermount . +Only used by +.IR scan . +.TP +.B serverdb +The path to the server's file database, after running +.BR servermount . +Only used by +.IR scan . +.TP +.B clientmount +A function to mount the client file system; run only on the client. +.TP +.B clientroot +The path to the root of the replicated file system on the client, +after running +.BR clientmount . +.TP +.B clientlog +The path to the client's copy of the server log file. +The client log is maintained by +.IR pull . +.TP +.B clientproto +The path to the proto file describing the client's files. +Only used by +.IR changes . +Often just a copy of +.BR $serverproto . +.TP +.B clientdb +The path to the client's file database, after running +.BR clientmount . +.TP +.B clientexclude +A (potentially empty) list of paths to exclude from +synchronization. A typical use of this is to exclude +the client database and log files. +These paths are relative to the root of the replicated file system. +.PD +.PP +As an example, the Plan 9 distribution replica configuration looks like: +.EX + fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist } + fn serverupdate { status='' } + serverroot=/n/dist + s=/n/dist/dist/replica + serverlog=$s/plan9.log + serverproto=$s/plan9.proto + + fn clientmount { 9fs kfs } + clientroot=/n/kfs + c=/n/kfs/dist/replica + clientlog=$c/client/plan9.log + clientproto=$c/plan9.proto + clientdb=$c/client/plan9.db + clientexclude=(dist/replica/client) +.EE +.PP +(Since the Plan 9 developers run +.I scan +manually to update the log, the clients need not do anything +to rescan the file system. +Thus +.B serverupdate +simply returns successfully.) +.PP +The fourth edition Plan 9 distribution uses these +tools to synchronize installations with the central +server at Bell Labs. +The replica configuration files and metadata are kept +in +.BR /dist/replica . +To update your system, make sure you are connected +to the internet and run +.EX + replica/pull /dist/replica/network +.EE +If conflicts are reported (say you have made local changes to +.B /rc/bin/cpurc +and +.BR /rc/bin/termrc , +but only want to keep the +.B cpurc +changes), +use +.EX + replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network +.EE +to instruct +.I pull +to ignore the server's change to +.BR cpurc . +.PP +The script +.B /usr/glenda/bin/rc/pull +runs +.I pull +with the +.B -v +flag and with +.B /dist/replica/network +inserted at the right point on the command line. +Logged in as glenda, one can repeat the above example with: +.EX + pull -c rc/bin/cpurc -s rc/bin/termrc +.EE +.PP +To see a list of changes made to the local file system +since installation, run +.EX + replica/changes /dist/replica/network +.EE +(Although the script is called +.IR network , +since +.I changes +is a local-only operation, the network need not be configured.) +.SH SOURCE +.B /rc/bin/replica +.SH SEE ALSO +.IR replica (8) diff --git a/sys/man/1/resample b/sys/man/1/resample new file mode 100755 index 000000000..35968d054 --- /dev/null +++ b/sys/man/1/resample @@ -0,0 +1,58 @@ +.TH RESAMPLE 1 +.SH NAME +resample \- resample a picture +.SH SYNOPSIS +.B resample +[ +.B -x +.I size +] [ +.B -y +.I size +] [ +.I file +] +.SH DESCRIPTION +.I Resample +resamples its input image (default standard input) to a new size. +The image is decimated or interpolated using +a Kaiser window. +.PP +The size of the resampled image can be specified +with the +.B -x +and +.B -y +options. +An unadorned value sets the number of pixels of that dimension; a suffixed percent sign specifies a percentage. +If only one of +.B -x +or +.B -y +is given, the other dimension is scaled to preserve +the aspect ratio of the original image. +Thus, +.B -x50% +will reduce the image to half its original dimension in both +.B x +and +.BR y . +.PP +The input should be a Plan 9 image +as described in +.IR image (6), +and the output will be a compressed 24-bit +.B r8g8b8 +image. +To uncompress the image or change the pixel format, use +.I iconv +(see +.IR crop (1)). +.PP +.SH SOURCE +.B /sys/src/cmd/resample.c +.SH "SEE ALSO +.IR crop (1), +.IR image (6) +.SH BUGS +Faster algorithms exist, but this implementation produces correct pictures. diff --git a/sys/man/1/rio b/sys/man/1/rio new file mode 100755 index 000000000..e0b297dcb --- /dev/null +++ b/sys/man/1/rio @@ -0,0 +1,537 @@ +.TH RIO 1 +.SH NAME +rio, label, window, wloc \- window system +.SH SYNOPSIS +.B rio +[ +.BI "-i '"cmd ' +] +[ +.BI "-k '"kbdcmd ' +] +[ +.B -s +] +[ +.B -f +.I font +] +.PP +.B label +.I name +.PP +.B window +[ +.B -m +] [ +.B -r +.I minx miny maxx maxy +] [ +.B -dx +.I n +] [ +.B -dy +.I n +] [ +.B -minx +.I n +] [ +.B -miny +.I n +] [ +.B -maxx +.I n +] [ +.B -maxy +.I n +] [ +.B -cd +.I dir +] [ +.B -hide +] [ +.B -scroll +] [ +.B -noscroll +] [ +.I cmd +.I arg ... +] +.PP +.B wloc +.SH DESCRIPTION +.I Rio +manages asynchronous layers of text, or windows, on a raster display. +It also serves a variety of files for communicating with +and controlling windows; these are discussed in section +.IR rio (4). +.SS Commands +The +.I rio +command starts a new instance of the window system. +Its +.B -i +option names a startup script, which typically contains several +.I window +commands generated by +.IR wloc . +The +.B -k +option causes +.I rio +to run the command +.I kbdcmd +at startup and allow it to provide characters as keyboard input; the +.B keyboard +program described in +.IR bitsyload (1) +is the usual choice. +.PP +The +.B -s +option initializes windows so that text scrolls; +the default is not to scroll. +The +.I font +argument names a font used to display text, both in +.IR rio 's +menus +and as a default for any programs running in its windows; it also +establishes the +environment variable +.BR $font . +If +.B -f +is not given, +.I rio +uses the imported value of +.BR $font +if set; otherwise it imports the default font from the underlying graphics +server, usually the terminal's operating system. +.PP +The +.I label +command changes a window's identifying name. +.PP +The +.I window +command creates a window. +By default, it creates a shell window and sizes and places it automatically. +The geometry arguments control the size +.IB ( dx , +.BR dy ) +and placement +.RB ( minx , +.BR miny , +.BR maxx , +.BR maxy ); +the units are pixels with the +upper left corner of the screen at (0, 0). +The +.B hide +option causes the window to be created off-screen. +The +.B scroll +and +.B noscroll +options set the scroll mode. +The +.B cd +option sets the working directory. +The optional command and arguments +define which program to run in the window. +.PP +By default, +.I window +uses +.B /dev/wctl +(see +.IR rio (4)) +to create the window and run the command. Therefore, the window and command +will be created by +.I rio +and run in a new file name space, just as if the window had been created using the interactive menu. +However, the +.B -m +option uses the file server properties of +.I rio +to +.B mount +(see +.IR bind (1)) +the new window's name space within the name space of the program calling +.IR window . +This means, for example, that running +.B window +in a CPU window will create another window whose command runs on the terminal, where +.I rio +is running; while +.B window +.B -m +will create another window whose command runs on the CPU server. +.PP +The +.I wloc +command prints the coordinates and label of each window in its instance of +.I rio +and is used to construct arguments for +.IR window . +.SS Window control +Each window behaves as a separate terminal with at least one process +associated with it. +When a window is created, a new process (usually a shell; see +.IR rc (1)) +is established and bound to the window as a new process group. +Initially, each window acts as a simple terminal that displays character text; +the standard input and output of its processes +are attached to +.BR /dev/cons . +Other special files, accessible to the processes running in a window, +may be used to make the window a more general display. +Some of these are mentioned here; the complete set is +discussed in +.IR rio (4). +.PP +One window is +.IR current , +and is indicated with a dark border and text; +characters typed on the keyboard are available in the +.B /dev/cons +file of the process in the current window. +Characters written on +.B /dev/cons +appear asynchronously in the associated window whether or not the window +is current. +.PP +Windows are created, deleted and rearranged using the mouse. +Clicking (pressing and releasing) mouse button 1 in a non-current +window makes that window current and brings it in front of +any windows that happen to be overlapping it. +When the mouse cursor points to the background area or is in +a window that has not claimed the mouse for its own use, +pressing mouse button 3 activates a +menu of window operations provided by +.IR rio . +Releasing button 3 then selects an operation. +At this point, a gunsight or cross cursor indicates that +an operation is pending. +The button 3 menu operations are: +.TF Resize +.TP +.B New +Create a window. +Press button 3 where one corner of the new rectangle should +appear (cross cursor), and move the mouse, while holding down button 3, to the +diagonally opposite corner. +Releasing button 3 creates the window, and makes it current. +Very small windows may not be created. +.TP +.B Resize +Change the size and location of a window. +First click button 3 in the window to be changed +(gunsight cursor). +Then sweep out a window as for the +.B New +operation. +The window is made current. +.TP +.B Move +Move a window to another location. +After pressing and holding button 3 over the window to be moved (gunsight cursor), +indicate the new position by dragging the rectangle to the new location. +The window is made current. +Windows may be moved partially off-screen. +.TP +.B Delete +Delete a window. Click in the window to be deleted (gunsight cursor). +Deleting a window causes a +.L hangup +note to be sent to all processes in the window's process group +(see +.IR notify (2)). +.TP +.B Hide +Hide a window. Click in the window to be hidden (gunsight cursor); +it will be moved off-screen. +Each hidden window is given a menu entry in the button 3 menu according to the +value of the file +.BR /dev/label , +which +.I rio +maintains +(see +.IR rio (4)). +.TP +.I label +Restore a hidden window. +.PD +.PP +Windows may also be arranged by dragging their borders. +Pressing button 1 or 2 over a window's border allows one to +move the corresponding edge or corner, while button 3 +moves the whole window. +.PD +.SS Text windows +Characters typed on the keyboard or written to +.B /dev/cons +collect in the window to form +a long, continuous document. +.PP +There is always some +.I selected +.IR text , +a contiguous string marked on the screen by reversing its color. +If the selected text is a null string, it is indicated by a hairline cursor +between two characters. +The selected text +may be edited by mousing and typing. +Text is selected by pointing and clicking button 1 +to make a null-string selection, or by pointing, +then sweeping with button 1 pressed. +Text may also be selected by double-clicking: +just inside a matched delimiter-pair +with one of +.B {[(<«`'" +on the left and +.B }])>»`'" +on the right, it selects all text within +the pair; at the beginning +or end of a line, it selects the line; within or at the edge of an alphanumeric word, +it selects the word. +.PP +Characters typed on the keyboard replace the selected text; +if this text is not empty, it is placed in a +.I snarf buffer +common to all windows but distinct from that of +.IR sam (1). +.PP +Programs access the text in the window at a single point +maintained automatically by +.IR rio . +The +.I output point +is the location in the text where the next character written by +a program to +.B /dev/cons +will appear; afterwards, the output point is the null string +beyond the new character. +The output point is also the location in the text of the next character +that will be read (directly from the text in the window, +not from an intervening buffer) +by a program from +.BR /dev/cons . +When such a read will occur is, however, under control of +.I rio +and the user. +.PP +In general there is text in the window after the output point, +usually placed there by typing but occasionally by the editing +operations described below. +A pending read of +.B /dev/cons +will block until the text after the output point contains +a newline, whereupon the read may +acquire the text, up to and including the newline. +After the read, as described above, the output point will be at +the beginning of the next line of text. +In normal circumstances, therefore, typed text is delivered +to programs a line at a time. +Changes made by typing or editing before the text is read will not +be seen by the program reading it. +If the program in the window does not read the terminal, +for example if it is a long-running computation, there may +accumulate multiple lines of text after the output point; +changes made to all this text will be seen when the text +is eventually read. +This means, for example, that one may edit out newlines in +unread text to forestall the associated text being read when +the program finishes computing. +This behavior is very different from most systems. +.PP +Even when there are newlines in the output text, +.I rio +will not honor reads if the window is in +.I hold +.IR mode , +which is indicated by a white cursor and blue text and border. +The ESC character toggles hold mode. +Some programs, such as +.IR mail (1), +automatically turn on hold mode to simplify the editing of multi-line text; +type ESC when done to allow +.I mail +to read the text. +.PP +An EOT character (control-D) behaves exactly like newline except +that it is not delivered to a program when read. +Thus on an empty line an EOT serves to deliver an end-of-file indication: +the read will return zero characters. +Like newlines, unread EOTs may be successfully edited out of the text. +The BS character (control-H) erases the character before the selected text. +The ETB character (control-W) erases any nonalphanumeric characters, then +the alphanumeric word just before the selected text. +`Alphanumeric' here means non-blanks and non-punctuation. +The NAK character (control-U) erases the text after the output point, +and not yet read by a program, but not more than one line. +All these characters are typed on the keyboard and hence replace +the selected text; for example, typing a BS with a word selected +places the word in the snarf buffer, removes it from the screen, +and erases the character before the word. +.PP +An ACK character (control-F) or Insert character triggers file name completion +for the preceding string (see +.IR complete (2)). +.PP +Typing a left or right arrow moves the cursor one character in that direction. +Typing an SOH character (control-A) moves the cursor to the beginning of the +current line; an ENQ character (control-E) moves to the end. +.PP +Text may be moved vertically within the window. +A scroll bar on the left of the window shows in its clear portion what fragment of the +total output text is visible on the screen, and in its gray part what +is above or below view; +it measures characters, not lines. +Mousing inside the scroll bar moves text: +clicking button 1 with the mouse pointing inside the scroll bar +brings the line at the top of the +window to the cursor's vertical location; +button 3 takes the line at the cursor to the top of the window; +button 2, treating the scroll bar as a ruler, jumps to the indicated portion +of the stored text. +Holding a button pressed in the scroll bar will cause the text +to scroll continuously until the button is released. +Also, a page down +or down-arrow +scrolls forward +half a window, and page up or up-arrow scrolls back. +Typing the home key scrolls to the top of the window; typing the end key scrolls +to the bottom. +.PP +The DEL character sends an +.L interrupt +note to all processes in the window's process group. +Unlike the other characters, the DEL, VIEW, and up- and down-arrow +keys do not affect the selected text. +The left (right) arrow key moves the selection to one character +before (after) the current selection. +.PP +Normally, written output to a window blocks when +the text reaches the end of the screen; +a button 2 menu item toggles scrolling. +.PP +Other editing operations are selected from a menu on button 2. +The +.B cut +operation deletes the selected text +from the screen and puts it in the snarf buffer; +.B snarf +copies the selected text to the buffer without deleting it; +.B paste +replaces the selected text with the contents of the buffer; +and +.B send +copies the snarf buffer to just after the output point, adding a final newline +if missing. +.B Paste +will sometimes and +.B send +will always place text after the output point; the text so placed +will behave exactly as described above. Therefore when pasting +text containing newlines after the output point, it may be prudent +to turn on hold mode first. +.PP +The +.B plumb +menu item sends the contents of the selection (not the snarf buffer) to the +.IR plumber (4). +If the selection is empty, it sends the white-space-delimited text +containing the selection (typing cursor). +A typical use of this feature is to tell the editor to find the source of an error +by plumbing the file and line information in a compiler's diagnostic. +.SS Raw text windows +Opening or manipulating certain files served by +.IR rio +suppresses some of the services supplied to ordinary text windows. +While the file +.B /dev/mouse +is open, any mouse operations are the responsibility of another program +running in the window. Thus, +.I rio +refrains from maintaining +the scroll bar, +supplying text editing or menus, interpreting the +VIEW key as a request to scroll, and also turns scrolling on. +.PP +The file +.B /dev/consctl +controls interpretation of keyboard input. +In particular, a raw mode may be set: +in a raw-input window, no typed keyboard characters are special, +they are not echoed to the screen, and all are passed +to a program immediately upon reading, instead of being gathered into +lines. +.SS Graphics windows +A program that holds +.B /dev/mouse +and +.B /dev/consctl +open after putting the console in raw mode +has complete control of the window: +it interprets all mouse events, gets all keyboard characters, +and determines what appears on the screen. +.SH FILES +.TF /srv/riowctl.\fIuser\fP.\fIpid\fP +.TP +.B /lib/font/bit/* +font directories +.TP +.B /mnt/wsys +Files served by +.I rio +(also unioned in +.B /dev +in a window's name space, before the terminal's real +.B /dev +files) +.TP +.B /srv/rio.\fIuser\fP.\fIpid\fP +Server end of +.IR rio . +.TP +.B /srv/riowctl.\fIuser\fP.\fIpid\fP +Named pipe for +.I wctl +messages. +.SH SOURCE +.TF /sys/src/cmd/rio +.TP +.B /sys/src/cmd/rio +.TP +.B /rc/bin/label +.TP +.B /rc/bin/window +.TP +.B /rc/bin/wloc +.SH "SEE ALSO" +.IR rio (4), +.IR rc (1), +.IR cpu (1), +.IR sam (1), +.IR mail (1), +.IR proof (1), +.IR graphics (2), +.IR frame (2), +.IR window (2), +.IR notify (2), +.IR cons (3), +.IR draw (3), +.IR mouse (3), +.IR keyboard (6) +.SH BUGS +The standard input of +.I window +is redirected to the newly created window, so there is no way to pipe the output +of a program to the standard input of the new window. +In some cases, +.IR plumb (1) +can be used to work around this limitation. diff --git a/sys/man/1/rm b/sys/man/1/rm new file mode 100755 index 000000000..c5786f92e --- /dev/null +++ b/sys/man/1/rm @@ -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/sys/man/1/rwd b/sys/man/1/rwd new file mode 100755 index 000000000..14e1a57ce --- /dev/null +++ b/sys/man/1/rwd @@ -0,0 +1,161 @@ +.TH RWD 1 +.SH NAME +rwd, conswdir \- maintain remote working directory +.SH SYNOPSIS +.B rwd +.I path +.PP +.B conswdir +[ +.I prog +] +.SH DESCRIPTION +.I Rwd +and +.I conswdir +conspire to keep +.IR rio (4) +and +.IR acme (4) +informed about the current directory on +remote systems during login sessions. +.I Rio +and +.I acme +include this information in plumb messages sent to +.IR plumber (4). +If the remote system's name space is mounted in the +plumber's name space, +the end result is that file paths printed during the session +are plumbable. +.PP +.I Rwd +informs +.IR rio +and +.IR acme +of directory changes. +The name of the remote machine is taken from +the environment variable +.BR $remotesys . +.I Rwd +writes the full path to +.BR /dev/wdir ; +writes the last element of the path, +suffixed by +.BI @ remotesys \fR, +to +.BR /dev/label ; +and when run inside a +.I win +(see +.IR acme (1)) +window, changes the window title to +.IB path /- remotesys +using +.BR /dev/acme/ctl . +.PP +.I Conswdir +copies standard input to standard output, looking for in-band messages +about directory changes. +The messages are of the form: +.IP +.EX +\e033];\fIpath\fP\e007 +.EE +.LP +where +.B \e033 +and +.B \e007 +are ASCII escape and bell characters. +Such messages are removed from the stream and not printed to standard output; +for each such message +.I conswdir +runs +.I prog +(default +.BR /bin/rwd ) +with +.I path +as its only argument. +.SH EXAMPLES +Add this plumbing rule (see +.IR plumb (6)) +in order to run commands in the plumber's name space: +.IP +.EX +# have plumber run command +kind is text +data matches 'Local (.*)' +plumb to none +plumb start rc -c $1 +.EE +.PP +Mount a Unix system in your name space and the plumber's: +.IP +.EX +% 9fs unix +% plumb 'Local 9fs unix' +.EE +.LP +(If you're using acme, execute +.B "Local 9fs unix +with the middle button to mount the Unix system in acme's name space.) +.PP +Connect to the Unix system, processing in-band directory change messages: +.IP +.EX +% ssh unix | aux/conswdir +.EE +.PP +Add this shell function to your +.B .profile +on the Unix system +to generate directory change messages every time a +.B cd +command is executed: +.IP +.EX +H=`hostname | sed 's/\e..*//'` +_cd () { + \ecd $* && + case $- in + *i*) + _dir=`pwd` + echo /n/$H$_dir | awk '{printf("\e033];%s\e007", $1);}' + esac +} +alias cd=_cd +.EE +.PP +The examples described so far only help for relative +path names. Add this plumbing rule to handle rooted names +like +.BR /usr/include/stdio.h : +.IP +.EX +# remote rooted path names +type is text +wdir matches '/n/unix(/.*)?' +data matches '/([.a-zA-Z¡-￿0-9_/\e-]*[a-zA-Z¡-￿0-9_/\e-])('$addr')?' +arg isfile /n/unix/$1 +data set $file +attr add addr=$3 +plumb to edit +plumb client window $editor +.EE +.SH SOURCE +.B /rc/bin/rwd +.br +.B /sys/src/cmd/aux/conswdir.c +.SH SEE ALSO +.IR plumber (4), +.IR plumb (6), +.IR srv (4) +.SH BUGS +This mechanism is clunky, but Unix and SSH +make it hard to build a better one. +.PP +The escape sequence was chosen because +it changes the title on xterm windows. diff --git a/sys/man/1/sam b/sys/man/1/sam new file mode 100755 index 000000000..282448d24 --- /dev/null +++ b/sys/man/1/sam @@ -0,0 +1,891 @@ +.TH SAM 1 +.ds a \fR*\ \fP +.SH NAME +sam, B, sam.save, samterm \- 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 -a +Autoindent. In this mode, when a newline character is typed +in the terminal interface, +.I samterm +copies leading white space on the current line to the new line. +.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/sys/man/1/secstore b/sys/man/1/secstore new file mode 100755 index 000000000..113db5a92 --- /dev/null +++ b/sys/man/1/secstore @@ -0,0 +1,225 @@ +.TH SECSTORE 1 +.SH NAME +aescbc, ipso, secstore \- secstore commands +.SH SYNOPSIS +.B auth/secstore +[ +.B -cinv +] [ +.B -(g|G) +.I getfile +] [ +.B -p +.I putfile +] [ +.B -r +.I rmfile +] [ +.B -s +.I server +] [ +.B -u +.I user +] +.PP +.B auth/aescbc +-e +[ -in ] +.I ciphertext +.br +.B auth/aescbc +-d +[ -in ] +.I cleartext +.PP +.B ipso +[ +.B -a -e -l -f -s +] [ +.I file +\&... +] +.SH DESCRIPTION +.I Secstore +authenticates to a secure-store server +using a password and optionally a hardware token, +then saves or retrieves a file. +This is intended to be a credentials store (public/private keypairs, +passwords, and other secrets) for a factotum. +.PP +Option +.B -c +prompts for a password change. +.PP +Option +.B -g +retrieves a file to the local directory; +option +.B -G +writes it to standard output instead. +Specifying +.I getfile +of +.L \&. +will send to standard output +a list of remote files with dates, lengths and SHA1 hashes. +.PP +Option +.B -i +says that the password should be read from standard input +instead of from +.BR /dev/cons . +.PP +Option +.B -n +says that the password should be read from NVRAM +(see +.IR authsrv (2)) +instead of from +.BR /dev/cons . +.PP +Option +.B -p +stores a file on the secstore. +.PP +Option +.B -r +removes a file from the secstore. +.PP +The server is +.BR tcp!$auth!secstore , +or the server specified by option +.BR -s . +.PP +Option +.B -u +access the secure-store files belonging to +.IR user . +.PP +Option +.B -v +produces more verbose output, in particular providing a few +bits of feedback to help the user detect mistyping. +.PP +For example, to add a secret to the file read by +.IR factotum (4) +at startup, open a new window, type +.LP +.EX + % ramfs -p; cd /tmp + % auth/secstore -g factotum + secstore password: + % echo 'key proto=apop dom=x.com user=ehg !password=hi' >> factotum + % auth/secstore -p factotum + secstore password: + % read -m factotum > /mnt/factotum/ctl +.EE +.LP +and delete the window. +The first line creates an ephemeral memory-resident workspace, +invisible to others and automatically removed when the window is deleted. +The next three commands fetch the persistent copy of the secrets, +append a new secret, +and save the updated file back to secstore. +The final command loads the new secret into the running factotum. +.PP +The +.I ipso +command packages this sequence into a convenient script to simplify editing of +.I files +stored on a secure store. +It copies the named +.I files +into a local +.IR ramfs (4) +and invokes +.IR acme (1) +on them. When the editor exits, +.I ipso +prompts the user to confirm copying modifed or newly created files back to +.I secstore. +If no +.I file +is mentioned, +.I ipso +grabs all the user's files from +.I secstore +for editing. +.PP +By default, +.I ipso +will edit the +.I secstore +files and, if +one of them is named +.BR factotum , +flush current keys from factotum and load +the new ones from the file. +If the +.BR -e , +.BR -f , +or +.BR -l +options are given, +.I ipso +will just perform only the requested operations, i.e., +edit, flush, and/or load. +.PP +The +.B -s +option of +.I ipso +invokes +.IR sam (1) +as the editor insted of +.BR acme ; +the +.B -a +option provides a similar service for files encrypted by +.I aescbc +.RI ( q.v. ). +With the +.B -a +option, the full rooted pathname of the +.I file +must be specified and all +.I files +must be encrypted with the same key. +Also with +.BR -a , +newly created files are ignored. +.PP +.I Aescbc +encrypts (under +.LR -e ) +and decrypts (under +.LR -d ) +using AES (Rijndael) in cipher block chaining (CBC) mode. +Options +.L i +and +.L n +are as per +.IR secstore , +except that +.L i +reads from file descriptor 3. +.SH SOURCE +.B /rc/bin/ipso +.br +.B /sys/src/cmd/auth/secstore +.SH SEE ALSO +.IR factotum (4), +.IR secstore (8) +.SH BUGS +There is deliberately no backup of files on the secstore, so +.B -r +(or a disk crash) is irrevocable. You are advised to store +important secrets in a second location. +.PP +When using +.IR ipso , +secrets will appear as plain text in the editor window, +so use the command in private. diff --git a/sys/man/1/sed b/sys/man/1/sed new file mode 100755 index 000000000..6bb2e6123 --- /dev/null +++ b/sys/man/1/sed @@ -0,0 +1,389 @@ +.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 option +.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 ...] [\fL;\fP] +.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 +.B # +Comment. +Ignore the rest of the line. +.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/sys/man/1/seq b/sys/man/1/seq new file mode 100755 index 000000000..60d1f12a9 --- /dev/null +++ b/sys/man/1/seq @@ -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/sys/man/1/size b/sys/man/1/size new file mode 100755 index 000000000..cd7ba9b84 --- /dev/null +++ b/sys/man/1/size @@ -0,0 +1,28 @@ +.TH SIZE 1 +.SH NAME +size \- print size of executable files +.SH SYNOPSIS +.B size +[ +.I file ... +] +.SH DESCRIPTION +.I Size +prints the size of the segments for each of the argument executable files +(default +.BR v.out ). +The format is +.IP +.IB textsize t ++ +.IB datasize d ++ +.IB bsssize b += +.I total +.PP +where the numbers are in bytes. +.SH SOURCE +.B /sys/src/cmd/size.c +.SH "SEE ALSO +.IR a.out (6) diff --git a/sys/man/1/sleep b/sys/man/1/sleep new file mode 100755 index 000000000..cc7d49218 --- /dev/null +++ b/sys/man/1/sleep @@ -0,0 +1,33 @@ +.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. +.I Time +may be floating-point. +.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/sys/man/1/sort b/sys/man/1/sort new file mode 100755 index 000000000..168e4dd19 --- /dev/null +++ b/sys/man/1/sort @@ -0,0 +1,262 @@ +.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 +] +] ... +.br +\h'0.5in +[ +.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/sys/man/1/spell b/sys/man/1/spell new file mode 100755 index 000000000..62f621a8b --- /dev/null +++ b/sys/man/1/spell @@ -0,0 +1,96 @@ +.TH SPELL 1 +.SH NAME +spell, sprog \- find spelling errors +.SH SYNOPSIS +.B spell +[ +.I options +] +\&... +[ +.I file +] +\&... +.PP +.B aux/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 on standard error, 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 \fL/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. +.PP +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/sys/man/1/spin b/sys/man/1/spin new file mode 100755 index 000000000..fd30b024b --- /dev/null +++ b/sys/man/1/spin @@ -0,0 +1,331 @@ +.TH SPIN 1 +.SH NAME +spin - verification tool for models of concurrent systems +.SH SYNOPSIS +.B spin +.B -a +[ +.B -m +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +[ +.B -bglmprsv +] +[ +.BI -n N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -c +[ +.B -t +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -d +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -f +.I ltl +.PP +.B spin +.B -F +.I file +.PP +.B spin +.B -i +[ +.B -bglmprsv +] +[ +.BI -n N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -M +[ +.B -t +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.BR -t [ \fIN ] +[ +.B -bglmprsv +] +[ +.BI -j N +] +[ +.BI -P cpp +] +.I file +.PP +.B spin +.B -V +.SH DESCRIPTION +.I Spin +is a tool for analyzing the logical consistency of +asynchronous systems, specifically distributed software +amd communication protocols. +A verification model of the system is first specified +in a guarded command language called +.IR Promela . +This specification language, described in the reference, +allows for the modeling of dynamic creation of +asynchronous processes, +nondeterministic case selection, loops, gotos, local and +global variables. +It also allows for a concise specification of logical +correctness requirements, including, but not restricted +to requirements expressed in linear temporal logic. +.PP +Given a Promela model stored in +.IR file , +.I spin +can perform interactive, guided, or random simulations +of the system's execution. +It can also generate a C program that performs an exhaustive +or approximate verification of the correctness requirements +for the system. +. +.TP +.B -a +Generate a verifier (model checker) for the specification. +The output is written into a set of C files, named +.BR pan.[cbhmt] , +that can be compiled +.RB ( "pcc pan.c" ) +to produce an executable verifier. +The online +.I spin +manuals (see below) contain +the details on compilation and use of the verifiers. +. +.TP +.B -c +Produce an ASCII approximation of a message sequence +chart for a random or guided (when combined with +.BR -t ) +simulation run. See also option +.BR -M . +. +.TP +.B -d +Produce symbol table information for the model specified in +.IR file . +For each Promela object this information includes the type, name and +number of elements (if declared as an array), the initial +value (if a data object) or size (if a message channel), the +scope (global or local), and whether the object is declared as +a variable or as a parameter. For message channels, the data types +of the message fields are listed. +For structure variables, the third field defines the +name of the structure declaration that contains the variable. +. +.TP +.BI -f " ltl" +Translate the LTL formula +.I ltl +into a +.I never +claim. +.br +This option reads a formula in LTL syntax from the second argument +and translates it into Promela syntax (a +.I never +claim, which is Promela's +equivalent of a Büchi Automaton). +The LTL operators are written: +.B [] +(always), +.B <> +(eventually), +and +.B U +(strong until). There is no +.B X +(next) operator, to secure +compatibility with the partial order reduction rules that are +applied during the verification process. +If the formula contains spaces, it should be quoted to form a +single argument to the +.I spin +command. +. +.TP +.BI -F " file" +Translate the LTL formula stored in +.I file +into a +.I never +claim. +.br +This behaves identically to option +.B -f +but will read the formula from the +.I file +instead of from the command line. +The file should contain the formula as the first line. Any text +that follows this first line is ignored, so it can be used to +store comments or annotation on the formula. +(On some systems the quoting conventions of the shell complicate +the use of option +.BR -f . +Option +.B -F +is meant to solve those problems.) +. +.TP +.B -i +Perform an interactive simulation, prompting the user at +every execution step that requires a nondeterministic choice +to be made. The simulation proceeds without user intervention +when execution is deterministic. +. +.TP +.B -M +Produce a message sequence chart in Postscript form for a +random simulation or a guided simulation +(when combined with +.BR -t ), +for the model in +.IR file , +and write the result into +.IR file.ps . +See also option +.BR -c . +. +.TP +.B -m +Changes the semantics of send events. +Ordinarily, a send action will be (blocked) if the +target message buffer is full. +With this option a message sent to a full buffer is lost. +. +.TP +.BI -n N +Set the seed for a random simulation to the integer value +.IR N . +There is no space between the +.B -n +and the integer +.IR N . +. +.TP +.B -t +Perform a guided simulation, following the error trail that +was produces by an earlier verification run, see the online manuals +for the details on verification. +. +.TP +.B -V +Prints the +.I spin +version number and exits. +. +.PP +With only a filename as an argument and no options, +.I spin +performs a random simulation of the model specified in +the file (standard input is the default if the filename is omitted). +If option +.B -i +is added, the simulation is +.IR interactive , +or if option +.B -t +is added, the simulation is +.IR guided . +.PP +The simulation normally does not generate output, except what is generated +explicitly by the user within the model with +.I printf +statements, and some details about the final state that is +reached after the simulation completes. +The group of options +.B -bglmprsv +sets the desired level of information that the user wants +about a random, guided, or interactive simulation run. +Every line of output normally contains a reference to the source +line in the specification that generated it. +. +.TP +.B -b +Suppress the execution of +.I printf +statements within the model. +.TP +.B -g +Show at each time step the current value of global variables. +.TP +.B -l +In combination with option +.BR -p , +show the current value of local variables of the process. +.TP +.B -p +Show at each simulation step which process changed state, +and what source statement was executed. +.TP +.B -r +Show all message-receive events, giving +the name and number of the receiving process +and the corresponding the source line number. +For each message parameter, show +the message type and the message channel number and name. +.TP +.B -s +Show all message-send events. +.TP +.B -v +Verbose mode, add some more detail, and generate more +hints and warnings about the model. +.SH SOURCE +.B /sys/src/cmd/spin +.SH SEE ALSO +.in +4 +.ti -4 +.BR http://spinroot.com : +.BR GettingStarted.pdf , +.BR Roadmap.pdf , +.BR Manual.pdf , +.BR WhatsNew.pdf , +.B Exercises.pdf +.br +.in -4 +G.J. Holzmann, +.IR "Design and Validation of Computer Protocols" , +Prentice Hall, 1991. +.br +—, `Design and validation of protocols: a tutorial,' +.IR "Computer Networks and ISDN Systems" , +Vol. 25, No. 9, 1993, pp. 981-1017. +.br +—, `The model checker Spin,' +.IR "IEEE Trans. on SE" , +Vol, 23, No. 5, May 1997. diff --git a/sys/man/1/split b/sys/man/1/split new file mode 100755 index 000000000..ffb012d79 --- /dev/null +++ b/sys/man/1/split @@ -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/sys/man/1/src b/sys/man/1/src new file mode 100755 index 000000000..f6e22ce91 --- /dev/null +++ b/sys/man/1/src @@ -0,0 +1,83 @@ +.TH SRC 1 +.SH NAME +src \- find source code for executable +.SH SYNOPSIS +.B src +[ +.B -n +] +[ +.B -s +.I symbol +] +.I file +.B ... +.SH DESCRIPTION +.I Src +examines the named +.I files +to find the corresponding source code, which is then sent to the editor using +.B B +(see +.IR sam (1)). +If +.I file +is an +.IR rc (1) +script, the source is the file itself. +If +.I file +is an executable, the source is defined to be the single file containing the +definition of +.B main +and +.I src +will point the editor at the line that begins the definition. +.I Src +uses +.IR db (1) +to extract the symbol table information that identifies the source. +.PP +.I Src +looks for each +.I file +in the current directory, in +.BR /bin , +and in the subdirectories of +.BR /bin , +in that order. +.PP +The +.B -n +flag causes +.B src +to print the file name but not send it to the editor. +The +.B -s +flag identifies a +.I symbol +other than +.B main +to locate. +.SH EXAMPLES +Find the source to the +.B main +routine in +.BR /bin/ed : +.IP +.EX +src ed +.EE +.PP +Find the source for +.BR strcmp : +.IP +.EX +src -s strcmp rc +.EE +.SH SOURCE +.B /rc/bin/src +.SH "SEE ALSO" +.IR db (1), +.IR plumb (1), +.IR sam (1). diff --git a/sys/man/1/ssh b/sys/man/1/ssh new file mode 100755 index 000000000..b43f3152a --- /dev/null +++ b/sys/man/1/ssh @@ -0,0 +1,346 @@ +.TH SSH 1 +.SH NAME +ssh, sshnet, scp, sshserve \- secure login and file copy from/to Unix or Plan 9 +.SH SYNOPSIS +.B ssh +[ +.B -CfiImPpRrw +] +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -[lu] +.I user +] +.RI [ user\fB@ ] host +[ +.I cmd +[ +.I args +\&... ]] +.PP +.B sshnet +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I service +] +.RI [ user\fB@ ] host +.PP +.B scp +[host:]file [host:]file +.br +.B scp +[host:]file ... [host:]dir +.PP +.B aux/sshserve +[ +.B -p +] +.I address +.SH DESCRIPTION +.I Ssh +allows authenticated login over an encrypted channel to hosts that +support the ssh protocol (see the RFCs listed below for encryption and +authentication details). +.LP +.I Ssh +takes the host name of the machine to connect to as its mandatory argument. +It may be specified as a domain name or an IP address. +Normally, login is attempted using the user name from /dev/user. +.PP +Command-line options are: +.TP +.B -C +force input to be read in cooked mode: +``line at a time'' with local echo. +.TP +.B -f +enable agent forwarding. +With this flag, +.I ssh +uses SSH's agent forwarding protocol to allow +programs running on the remote server to +interact with +.IR factotum (4) +to perform RSA authentication. +.TP +.B -i +force interactive mode. +In interactive mode, +.I ssh +prompts for passwords and confirmations of +new host keys when necessary. +(In non-interactive mode, password requests +are rejected and unrecognized host keys are +cause for disconnecting.) +By default, +.I ssh +runs in interactive mode only when its +input file descriptor is +.BR /dev/cons . +.TP +.B -I +force non-interactive mode. +.TP +.B -m +disable the +.RB control- \e +menu, described below. +.TP +.B -p +force pseudoterminal request. +The +.I ssh +protocol, grounded in Unix tradition, +differentiates between connections +that request controlling pseudoterminals +and those that do not. +By default, +.I ssh +requests a pseudoterminal only when no +.I command +is given. +.TP +.B -P +force no pseudoterminal request. +.TP +.B -r +strip carriage returns. +.TP +.B -R +put the allocated pseudoterminal, if any, in raw mode. +.TP +.B -w +notify the remote side whenever the window changes size. +.TP +.BR - [ lu ] "\fI user +specify user name. +This option is deprecated in favor of the +.IB user @ hostname +syntax. +.TP +.B "-A\fI authlist +specify an ordered space-separated list of authentication protocols to try. +The full set of authentication protocols is +.B rsa +(RSA using +.IR factotum (4) +to moderate key usage), +.B password +(use a password gathered from factotum), +and +.B tis +(challenge-response). +The default list is all three in that order. +.TP +.B "-c\fI cipherlist +specify an ordered space-separated list of allowed ciphers to use when encrypting the channel. +The full set of ciphers is +.B des +(standard DES), +.B 3des +(a somewhat doubtful variation on triple DES), +.B blowfish +(Bruce Schneier's Blowfish), +.B rc4 +(RC4), +and +.B none +(no encryption). +The default cipher list is +.B blowfish +.B rc4 +.BR 3des . +.PD +.PP +The +.RB control\- \e +character is a local escape, as in +.IR con (1). +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B q +Exit. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +.TP +.B r +Toggle printing of carriage returns. +.PD +.LP +If no command is specified, +a login session is started on the remote +host. +Otherwise, the command is executed with its arguments. +.LP +.I Ssh +establishes a connection with an ssh daemon on the remote host. +The daemon sends to +.I ssh +its RSA public host key and session key. +Using these, +.I ssh +sends a session key which, presumably, only the +daemon can decipher. After this, both sides start encrypting their +data with this session key. +.LP +When the daemon's host key has been received, +.I ssh +looks it up in +.B $home/lib/keyring +and in +.BR /sys/lib/ssh/keyring . +If +the key is found there, and it matches the received key, +.I ssh +is satisfied. If not, +.I ssh +reports this and offers to add the key to +.BR $home/lib/keyring . +.LP +Over the encrypted channel, +.I ssh +attempts to convince the daemon to accept the call +using the listed authentication protocols +(see the +.B -A +option above). +.LP +The preferred way to authenticate is a +.IR netkey -style +challenge/response or via a SecurID token. +.I Ssh +users on other systems than Plan 9 should enable \s-2TIS_A\s0uthentication. +.LP +When the connection is authenticated, the given command line, +(by default, a login shell) is executed on the remote host. +.sp 1 +The SSH protocol allows clients to make outgoing TCP calls via the server. +.I Sshnet +establishes an SSH connection and, rather than execute a remote command, +presents the remote server's TCP stack as a network stack +(see the discussion of TCP in +.IR ip (3)) +mounted at +.I mtpt +(default +.BR /net ), +optionally posting a 9P service +descriptor for the new file system as +.IB /srv/ service \fR. +The +.B -A +and +.B -c +arguments are as in +.IR ssh . +.sp 1 +.I Scp +uses +.I ssh +to copy files from one host to another. A remote file is identified by +a host name, a colon and a file name (no spaces). +.I Scp +can copy files from remote hosts and to remote hosts. +.sp 1 +.I Sshserve +is the server that services +.I ssh +calls from remote hosts. +The +.B -A +and +.B -c +options set valid authentication methods and ciphers +as in +.IR ssh , +except that there is no +.B rsa +authentication method. +Unlike in +.IR ssh , +the list is not ordered: the server presents a set and the client makes the choice. +The default sets are +.B tis +and +.B blowfish +.B rc4 +.BR 3des . +By default, users start with the namespace defined in +.BR /lib/namespace . +Users in group +.B noworld +in +.B /adm/users +start with the namespace defined in +.BR /lib/namespace.noworld . +.I Sshserve +does not provide the TCP forwarding functionality used +by +.IR sshnet , +because many Unix clients present +this capability in an insecure manner. +.PP +.I Sshserve +requires that +.IR factotum (4) +hold the host key, +identified by having attributes +.B proto=rsa +.BR service=sshserve . +To generate a host key: +.IP +.EX +auth/rsagen -t 'service=sshserve' >/mnt/factotum/ctl +.EE +.LP +To extract the public part of the host key in the form +used by SSH key rings: +.IP +.EX +grep 'service=sshserve' /mnt/factotum/ctl | auth/rsa2ssh +.EE +.SH FILES +.TP +.B /sys/lib/ssh/keyring +System key ring file containing public keys for remote ssh clients and servers. +.TP +.B /usr/\fIuser\fP/lib/keyring +Personal key ring file containing public keys for remote ssh clients and +servers. +.SH SOURCE +.B /sys/src/cmd/ssh +.SH "SEE ALSO" +.B /lib/rfc/rfc425[0-6] +.br +.IR factotum (4), +.IR authsrv (6), +.IR rsa (8) +.SH BUGS +Only version 1 of the SSH protocol is implemented. diff --git a/sys/man/1/stop b/sys/man/1/stop new file mode 100755 index 000000000..46e88772c --- /dev/null +++ b/sys/man/1/stop @@ -0,0 +1,36 @@ +.TH STOP 1 +.SH NAME +stop, start \- print commands to stop and start processes +.SH SYNOPSIS +.B stop +.I name +.PP +.B start +.I name +.SH DESCRIPTION +.I Stop +prints commands that will cause all processes called +.I name +and owned by the current user to be stopped. +The processes can then be debugged when they are in a consistent state. +.PP +.I Start +prints commands that will cause all stopped processes called +.I name +and owned by the current user to be started again. +.PP +Use the +.B send +command of +.IR rio (1), +or pipe into +.IR rc (1) +to execute the commands. +.SH SOURCE +.B /rc/bin/stop +.br +.B /rc/bin/start +.SH "SEE ALSO" +.IR ps (1), +.IR kill (1), +.IR proc (3) diff --git a/sys/man/1/strings b/sys/man/1/strings new file mode 100755 index 000000000..9164194bd --- /dev/null +++ b/sys/man/1/strings @@ -0,0 +1,36 @@ +.TH STRINGS 1 +.SH NAME +strings \- extract printable strings +.SH SYNOPSIS +.B strings +[ +.B -m +.I min +] [ +.I file ... +] +.SH DESCRIPTION +.I Strings +finds and prints strings containing +.I min +(default 6) +or more +consecutive printable +.SM UTF\c +-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/sys/man/1/strip b/sys/man/1/strip new file mode 100755 index 000000000..20de5f2da --- /dev/null +++ b/sys/man/1/strip @@ -0,0 +1,31 @@ +.TH STRIP 1 +.SH NAME +strip \- remove symbols from binary files +.SH SYNOPSIS +.B strip +.I file ... +.PP +.B strip +.B -o +.I ofile +.I file +.SH DESCRIPTION +.I Strip +removes symbol table segments from executable files, +rewriting the files in place. +Stripping a file requires write permission of the file +and the directory it is in. +.PP +If the +.B -o +flag is given, +the single input file +.I file +is stripped and the result written to +.IR ofile . +.I File +is unchanged. +.SH SOURCE +.B /sys/src/cmd/strip.c +.SH "SEE ALSO" +.IR a.out (6) diff --git a/sys/man/1/sum b/sys/man/1/sum new file mode 100755 index 000000000..0a6084fba --- /dev/null +++ b/sys/man/1/sum @@ -0,0 +1,94 @@ +.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 +[ +.B -2 +.I bits +] [ +.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 +.IR file s +are given, +the standard input is +summed. +Other summing algorithms are available. +The options are +.TF -r +.PD +.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 +.I Md5sum +computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm +described in RFC1321. +.PP +.I Sha1sum +computes the 40 hex digit National Institute of Standards and Technology +(NIST) +SHA1 secure hash algorithm +described in FIPS PUB 180-1, +by default. +Given the +.L 2 +option, +it instead computes the +.IR bits -bit +NIST SHA2 secure hash algorithm +described in FIPS PUB 180-2 +and prints the hash in hex. +Currently supported values of +.I bits +are +224, +256, +384, +and +512. +.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), +.IR sechash (2) diff --git a/sys/man/1/syscall b/sys/man/1/syscall new file mode 100755 index 000000000..54cf5516d --- /dev/null +++ b/sys/man/1/syscall @@ -0,0 +1,77 @@ +.TH SYSCALL 1 +.SH NAME +syscall \- test a system call +.SH SYNOPSIS +.B syscall +[ +.B -osx +] +.I entry +[ +.I arg ... +] +.SH DESCRIPTION +.I Syscall +invokes the system call +.I entry +with the given arguments. +(Some functions, such as +.I write +and +.IR read (2), +although not strictly system calls, are valid +.IR entries .) +It prints the return value and the error string, if there was an error. +An argument is either an integer constant as in C (its value is passed), +a string (its address is passed), +or the literal +.B buf +(a pointer to a 1MB buffer is passed). +.PP +If +.B -o +is given, the contents of the 1MB buffer are printed as a zero-terminated string +after the system call is done. +The +.B -x +and +.B -s +options are similar, but +.B -x +formats the data as hexadecimal bytes, while +.B -s +interprets the data as a +.IR stat (5) +message and formats it similar to the style of +.B ls +.B -lqm +(see +.IR ls (1)), +with extra detail about the modify and access times. +.SH EXAMPLES +Write a string to standard output: +.IP +.EX +syscall write 1 hello 5 +.EE +.PP +Print information about the file connected to standard input: +.IP +.EX +syscall -s fstat 0 buf 1024 +.EE +.SH SOURCE +.B /sys/src/cmd/syscall +.SH "SEE ALSO" +Section 2 of this manual. +.SH DIAGNOSTICS +If +.I entry +is not known to +.IR syscall , +the exit status is +.LR unknown . +If the system call succeeds, the exit status is null; +otherwise the exit status is the string that +.IR errstr (2) +returns. diff --git a/sys/man/1/tail b/sys/man/1/tail new file mode 100755 index 000000000..3a4f3c692 --- /dev/null +++ b/sys/man/1/tail @@ -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. +.PP +According to custom, option +.BI + number +counts lines from 1, and counts +blocks and bytes from 0. +.PP +.I Tail +is ignorant of UTF. diff --git a/sys/man/1/tar b/sys/man/1/tar new file mode 100755 index 000000000..da79167dd --- /dev/null +++ b/sys/man/1/tar @@ -0,0 +1,202 @@ +.TH TAR 1 +.SH NAME +tar, dircp \- archiver +.SH SYNOPSIS +.B tar +.I key +[ +.I file ... +] +.PP +.B dircp +.I fromdir +.I todir +.SH DESCRIPTION +.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 r +The named files +are appended to the archive. +.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 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. +.PP +The modifiers are: +.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 g +Use the next (numeric) argument as the group id for files in +the output archive. +.TP +.B i +Ignore errors encountered when reading. +Errors writing either produce a corrupt archive +or indicate deeper file system problems. +.TP +.B k +(keep) +Modifies the behavior of +.B x +not to extract files which already exist. +.TP +.B m +Do not set the modification time on extracted files. +This is the default behavior; the flag exists only for compatibility with other tars. +.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. +This is the default behavior; the flag exists only for backwards compatibility +with older versions of tar. +.TP +.B P +Do not generate the POSIX ustar format. +.TP +.B R +When extracting, respect leading slash on file names. +By default, files are always extracted relative to the current directory. +.TP +.B s +When extracting, attempt to resynchronise after not finding a tape header +block where expected. +.TP +.B T +Modifies the behavior of +.B x +to set the modified time, +mode and, for POSIX archives and filesystem permitting, +the user and group +of each file to that specified in the archive. +.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 v +(verbose) +Print the name of each file as it is processed. +With +.BR t , +give more details about the +archive entries. +.TP +.B z +Operate on compressed +.I tar +archives. +The type of compression is inferred from the file name extension: +.IR gzip (1) +for +.B .tar.gz +and +.BR .tgz ; +.I bzip2 +(see +.IR gzip (1)) +for +.BR .tar.bz , +.BR .tbz , +.BR .tar.bz2 , +and +.BR .tbz2 ; +.I compress +for +.B .tar.Z +and +.BR .tz . +If no extension matches, +.I gzip +is used. +The +.B z +flag is unnecessary (but allowed) when using the +.B t +and +.B x +verbs on archives with recognized extensions. +.br +.ne 6 +.SH EXAMPLES +.I Tar +can be used to copy hierarchies thus: +.IP +.EX +@{cd fromdir && tar c .} | @{cd todir && tar xT} +.EE +.PP +.I Dircp +does this. +.SH SOURCE +.B /sys/src/cmd/tar.c +.br +.B /rc/bin/dircp +.SH SEE ALSO +.IR ar (1), +.IR bundle (1), +.IR tapefs (4), +.IR mkfs (8) +.SH BUGS +There is no way to ask for any but the last +occurrence of a file. +.PP +File path names are limited to +100 characters +(256 when using ustar format). +.PP +The +.I tar +format allows specification of links and symbolic links, +concepts foreign to Plan 9: they are ignored. +.PP +The +.B r +key (append) +cannot be used on compressed archives. +.PP +.IR Tar , +thus +.IR dircp , +doesn't record Plan-9-specific metadata +such as append-only and exclusive-open permission bits, so they aren't copied. diff --git a/sys/man/1/tbl b/sys/man/1/tbl new file mode 100755 index 000000000..921e9e85e --- /dev/null +++ b/sys/man/1/tbl @@ -0,0 +1,285 @@ +.TH TBL 1 +.SH NAME +tbl \- format tables for nroff or troff +.SH SYNOPSIS +.B tbl +[ +.I file ... +] +.SH DESCRIPTION +.I Tbl +is a preprocessor for formatting tables for +.I nroff +or +.IR troff (1). +The input +.I files +are copied to the standard output, +except for segments of the form +.IP +.nf +.B .TS +.IB options " ; +.IB format " . +.I data +.B .T& +.IB format " . +.I data +\&. . . +.B .TE +.fi +.LP +which describe tables +and are replaced by +.I troff +requests to lay out the tables. +If no arguments are given, +.I tbl +reads the standard input. +.PP +The (optional) +.I options +line is terminated by a semicolon and contains one or more +of +.RS +.TF linesize(n) +.TP +.B center +center the table; default is left-adjust +.TP +.B expand +make table as wide as current line length +.TP +.B box +.TP +.B doublebox +enclose the table in a box or double box +.TP +.B allbox +enclose every item in a box +.TP +.BI tab( x ) +use +.I x +to separate input items; default is tab +.TP +.BI linesize( n ) +set rules in +.IR n -point +type +.TP +.BI delim( xy ) +recognize +.I x +and +.I y +as +.IR eqn (1) +delimiters +.PD +.RE +.PP +Each line, except the last, of the obligatory +.I format +describes one row of the table. +The last line describes all rows until the next +.BR .T& , +where the format changes, +or the end of the table at +.BR .TE . +A format is specified by key letters, one per column, either upper or lower case: +.RS +.TP 0 +.B L +Left justify: the default for +columns without format keys. +.PD0 +.TP +.B R +Right justify. +.TP +.B C +Center. +.TP +.B N +Numeric: align at decimal point (inferred for integers) or at +.LR \e& . +.TP +.B S +Span: extend previous column across this one. +.TP +.B A +Alphabetic: left-aligned within column, widest item centered, indented relative to +.B L +rows. +.TP +.B ^ +Vertical span: continue item from previous row into this row. +.TP +.B - +Draw a horizontal rule in this column. +.TP +.B = +Draw a double horizontal rule in this column. +.PD +.RE +.PP +Key letters may be followed by modifiers, also either case: +.RS +.TP \w'\fLF\fIfont\fLXX'u +.B | +Draw vertical rule between columns. +.PD0 +.TP +.B || +Draw a double vertical rule between columns. +.TP +.I n +Gap between column is +.I n +ens wide. +Default is 3. +.TP +.BI F font +Use specified +.IR font . +.B B +and +.B I +mean +.B FB +and +.BR FI . +.TP +.B T +Begin vertically-spanned item at top row of range; default is +vertical centering (with +.LR ^ ). +.TP +.BI P n +Use point size +.IR n . +.TP +.BI V n +Use +.IR n -point +vertical spacing in text block; signed +.I n +means relative change. +.TP +.BI W( n ) +Column width as a +.I troff +width specification. +Parens are optional if +.I n +is a simple integer. +.TP +.B E +Equalize the widths of all columns marked +.BR E . +.PD +.RE +.PP +Each line of +.I data +becomes one row of the table; tabs separate items. +Lines beginning with +.L . +are +.I troff +requests. +Certain special data items are recognized: +.RS +.TP 0 +.B _ +Draw a horizontal rule in this column. +.PD0 +.TP +.B = +Draw a double horizontal rule in this column. +A data line consisting of a single +.L _ +or +.L = +draws the rule across the whole table. +.TP +.B \e_ +Draw a rule only as wide as the contents of the column. +.TP +.BI \eR x +Repeat character +.I x +across the column. +.TP +.B \e^ +Span the previous item in this column down into this row. +.TP +.B T{ +The item is a text block to be separately formatted +by +.I troff +and placed in the table. +The block continues to the next line beginning with +.BR T} . +The remainder of the data line follows at that point. +.PD +.RE +.PP +When it is used in a pipeline with +.IR eqn , +the +.I tbl +command should be first, to minimize the volume +of data passed through +pipes. +.SH EXAMPLES +.ds tb \fR\fP +Let \*(tb +represent a tab (which should +be typed as a genuine tab). +.if t .2C +.EX +\&.TS +c s s +c c s +c c c +l n n. +Household Population +Town\*(tbHouseholds +\*(tbNumber\*(tbSize +Bedminster\*(tb789\*(tb3.26 +Bernards Twp.\*(tb3087\*(tb3.74 +Bernardsville\*(tb2018\*(tb3.30 +\&.TE +.if t \{\0 +\0 +\0\} +.if n .PP +.TS +c s s +c c s +c c c +l n n. +Household Population +Town Households + Number Size +Bedminster 789 3.26 +Bernards Twp. 3087 3.74 +Bernardsville 2018 3.30 +.TE +.EE +.if t \{.sp3 +.1C\} +.SH SOURCE +.B /sys/src/cmd/tbl +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR doctype (1) +.br +M. E. Lesk and L. L. Cherry, +``TBL\(ema Program to Format Tables'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/tcs b/sys/man/1/tcs new file mode 100755 index 000000000..664073d36 --- /dev/null +++ b/sys/man/1/tcs @@ -0,0 +1,172 @@ +.TH TCS 1 +.SH NAME +tcs \- translate character sets +.SH SYNOPSIS +.B tcs +[ +.B -slcv +] +[ +.B -f +.I ics +] +[ +.B -t +.I ocs +] +[ +.I file ... +] +.SH DESCRIPTION +.I Tcs +interprets the named +.I file(s) +(standard input default) as a stream of characters from the +.I ics +character set or format, converts them to runes, +and then converts them into a stream of characters from the +.I ocs +character set or format on the standard output. +The default value for +.I ics +and +.I ocs +is +.BR utf , +the +.SM UTF +encoding described in +.IR utf (6). +The +.B -l +option lists the character sets known to +.IR tcs . +Processing continues in the face of conversion errors (the +.B -s +option prevents reporting of these errors). +The +.B -c +option forces the output to contain only correctly converted characters; +otherwise, +.B Runeerror +(0xFFFD) +characters will be substituted for +.SM UTF +encoding errors and unknown characters. +.PP +The +.B -v +option generates various diagnostic and summary information on standard error, +or makes the +.B -l +output more verbose. +.PP +.I Tcs +recognizes an ever changing list of character sets. +In particular, it supports a variety of Russian and Japanese encodings. +Some of the supported encodings are +.TF jis-kanji +.TP +.B utf +The Plan 9 +.SM UTF +encoding, known by ISO as UTF-8 +.TP +.B utf1 +The deprecated original +.SM UTF +encoding from ISO 10646 +.TP +.B ascii +7-bit ASCII +.TP +.B 8859-1 +Latin-1 (Central European) +.TP +.B 8859-2 +Latin-2 (Czech .. Slovak) +.TP +.B 8859-3 +Latin-3 (Dutch .. Turkish) +.TP +.B 8859-4 +Latin-4 (Scandinavian) +.TP +.B 8859-5 +Part 5 (Cyrillic) +.TP +.B 8859-6 +Part 6 (Arabic) +.TP +.B 8859-7 +Part 7 (Greek) +.TP +.B 8859-8 +Part 8 (Hebrew) +.TP +.B 8859-9 +Latin-5 (Finnish .. Portuguese) +.TP +.B html +Unicode as encoded by HTML +.TP +.B koi8 +KOI-8 (GOST 19769-74) +.TP +.B jis-kanji +ISO 2022-JP +.TP +.B ujis +EUC-JX: JIS 0208 +.TP +.B ms-kanji +Microsoft, or Shift-JIS +.TP +.B jis +(from only) guesses between ISO 2022-JP, EUC or Shift-Jis +.TP +.B gb +Chinese national standard (GB2312-80) +.TP +.B big5 +Big 5 (HKU version) +.TP +.B unicode +Unicode Standard 1.0 +.TP +.B tis +Thai character set plus +.SM ASCII +(TIS 620-1986) +.TP +.B msdos +IBM PC: CP 437 +.TP +.B atari +Atari-ST character set +.SH EXAMPLES +.TP +.B tcs -f 8859-1 +Convert 8859-1 (Latin-1) characters into +.SM UTF +format. +.TP +.B tcs -s -f jis +Convert characters encoded in one of several shift JIS encodings into +.SM UTF +format. +Unknown Kanji will be converted into +.B 0xFFFD +characters. +.TP +.B tcs -t html +Convert UTF into character set-independent HTML. +.TP +.B tcs -lv +Print an up to date list of the supported character sets. +.SH SOURCE +.B /sys/src/cmd/tcs +.SH SEE ALSO +.IR ascii (1), +.IR rune (2), +.IR utf (6). diff --git a/sys/man/1/tee b/sys/man/1/tee new file mode 100755 index 000000000..d237fb7fa --- /dev/null +++ b/sys/man/1/tee @@ -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/sys/man/1/tel b/sys/man/1/tel new file mode 100755 index 000000000..69bc37331 --- /dev/null +++ b/sys/man/1/tel @@ -0,0 +1,49 @@ +.TH TEL 1 +.SH NAME +tel, iwhois \- look in phone book +.SH SYNOPSIS +.B tel +.I key ... +.PP +.B iwhois +.IR name [ \fL@\f2domain ] +.SH DESCRIPTION +.I Tel +looks up +.I key +in a private telephone book, +.BR $home/lib/tel , +and in the public telephone book, +.BR /lib/tel . +It uses +.IR grep +(with the +.B -i +option to ignore case differences), so the key may be any part of a +name or number. Customarily, the telephone book contains names, +userids, home numbers, and office numbers of users. It also contains +a directory of area codes and miscellaneous people of general +interest. +.PP +.I Iwhois +looks up names in the Internet NIC's personnel database. +.I Name +should be a surname optionally followed by a comma and given name. +A different server can be chosen by appending to the name an +.B @ +followed by the server's domain name. +.SH FILES +.TF /lib/areacodes +.TP +.B /lib/areacodes +Telephone area codes database. +.TP +.B /lib/tel +Public telephone number database. +.TP +.B $home/lib/tel +Personal telephone number database. +.SH SOURCE +.B /rc/bin/tel +.br +.B /rc/bin/iwhois diff --git a/sys/man/1/test b/sys/man/1/test new file mode 100755 index 000000000..8feabf19a --- /dev/null +++ b/sys/man/1/test @@ -0,0 +1,218 @@ +.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) +.SH BUGS +Won't complain about extraneous arguments +since there may be arguments left unprocessed by +short-circuit evaluation of +.B -a +or +.BR -o . diff --git a/sys/man/1/thesaurus b/sys/man/1/thesaurus new file mode 100755 index 000000000..c605e635c --- /dev/null +++ b/sys/man/1/thesaurus @@ -0,0 +1,11 @@ +.TH THESAURUS 1 +.SH NAME +thesaurus \- search online thesaurus +.SH SYNOPSIS +.B thesaurus +.BI word +.SH DESCRIPTION +.I thesaurus +searches the online thesaurus at http://thesaurus.reference.com +.SH SOURCE +.B /rc/bin/thesaurus diff --git a/sys/man/1/time b/sys/man/1/time new file mode 100755 index 000000000..2c6b834b2 --- /dev/null +++ b/sys/man/1/time @@ -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/sys/man/1/touch b/sys/man/1/touch new file mode 100755 index 000000000..ac5937ec1 --- /dev/null +++ b/sys/man/1/touch @@ -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/sys/man/1/tr b/sys/man/1/tr new file mode 100755 index 000000000..0e11f5b96 --- /dev/null +++ b/sys/man/1/tr @@ -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/sys/man/1/trace b/sys/man/1/trace new file mode 100755 index 000000000..6acabe11d --- /dev/null +++ b/sys/man/1/trace @@ -0,0 +1,84 @@ +.TH TRACE 1 +.SH NAME +trace \- show (real-time) process behavior +.SH SYNOPSIS +.B trace +[ +.B -d +.I file +] +[ +.B -v +] +[ +.B -w +] +[ +.I pid +\&... +] +.SH DESCRIPTION +.I Trace +displays the behavior of processes running on the machine. In its +window it shows a time line for each traced process. Running +processes appear as colored blocks, with arrows marking important +events in real-time processes +(see +.IR proc (3)). +Black up arrows mark process releases, +black down arrows mark process deadlines, +green down arrows mark times when a process yielded the processor +before its deadline, +red down arrows mark times when the process overran its allotted time. +.PP +.I Trace +reads +.B /proc/trace +to retrieve trace events from the kernel +scheduler. Trace events are binary data structures generated by +the kernel scheduler. +It is assumed that the reader of +.B /proc/trace +and the kernel providing it have the same byte order. +.PP +The options are: +.TP +.B -d +specify an alternate trace event file +.TP +.B -v +print events as they are read from the trace event file +.TP +.B -w +run in a new window rather than using the current one +.PD +.PP +.I Trace +recognizes these keystroke commands while it is running: +.TP +.B + +zoom in by a factor of two +.TP +.B - +zoom out by a factor of two +.TP +.B p +pause or resume +.TP +.B q +quit +.PD +.PP +.SH SEE ALSO +.IR proc (3) +.SH FILES +.TF /sys/include/trace.h +.TP +.B /proc/trace +trace event file +.TP +.B /sys/include/trace.h +trace event data structures +.PD +.SH SOURCE +.B /sys/src/cmd/trace.c diff --git a/sys/man/1/troff b/sys/man/1/troff new file mode 100755 index 000000000..2838fcd26 --- /dev/null +++ b/sys/man/1/troff @@ -0,0 +1,237 @@ +.TH TROFF 1 +.SH NAME +troff, nroff, dpost \- text formatting and typesetting +.SH SYNOPSIS +.B troff +[ +.I option ... +] +[ +.I file ... +] +.PP +.B dpost +[ +.B -f +] [ +.I file ... +] +.PP +.B nroff +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Troff +formats text in the named +.I files +for +printing on a typesetter, +emitting a textual intermediate format called +`typesetter-independent +.I troff +output', +understood by programs such as +.IR proof (1) +and +.IR lp (1), +but also by a +.I troff +post-processor named +.IR dpost , +which emits corresponding Postscript. +Under +.BR -f , +.I dpost +also emits Postscript font definitions as needed. +.I Nroff +does the same as +.IR troff , +but produces output suitable +for typewriter-like devices, +usually without further post-processing, +but see +.IR col (1). +.PP +If no +.I file +argument is present, the standard input is read. +An argument consisting of a single minus +.RB ( - ) +is taken to be +a file name corresponding to the standard input. +The options are: +.nr xx \w'\fL-m\f2name\ \ ' +.TP \n(xxu +.BI -o list +Print pages in the comma-separated +.I list +of numbers and ranges. +A range +.IB N - M +means +.I N +through +.IR M ; +initial +.BI - M +means up to +.IR M ; +final +.IB N - +means from +.I N +to the end. +.TP +.BI -n N +Number first generated page +.IR N . +.TP +.BI -m name +Process the macro file +.BI /sys/lib/tmac/tmac. name +before the input +.IR files . +.TP +.BI -r aN +Set register +.I a +(one character name) to +.IR N . +.TP +.B -i +Read standard input after the input files are exhausted. +.TP +.B -q +Invoke the simultaneous input-output mode of the +.B rd +request. +.TP +.B -N +Produce output suitable for typewriter-like devices. +.SS Typesetter devices (not \fL-N\fP) only +.TP \n(xxu +.B -a +Send a printable +textual +approximation +of the results to the standard output. +.TP +.BI -T dest +Prepare output for typesetter +.IR dest : +.br +.ns +.RS +.TP \w'\fL-TLatin1\ 'u +.B -Tutf +(The default.) PostScript printers with +preprocessing to handle Unicode +characters encoded in +.SM UTF +.PD0 +.TP +.B -Tpost +Regular PostScript printers +.PD0 +.TP +.B -T202 +Mergenthaler Linotron 202 +.RE +.PD +.TP "\w'\fL-m\f2name 'u" +.BI -F dir +Take font information from directory +.IR dir . +.SS Typewriter (\fL-N\fP) output only +.TP \n(xxu +.BI -s N +Halt prior to every +.I N +pages (default +.IR N =1) +to allow paper loading or changing. +.TP +.BI -T name +Prepare output for specified terminal. +Known +.I names +include +.B utf +for the normal Plan 9 +.SM UTF +encoding of the Unicode Standard character set (default), +.B 37 +for the +Teletype model 37, +.B lp +(`line-printer') +for any terminal without half-line capability, +.B 450 +for the \s-1DASI\s+1-450 +(Diablo Hyterm), +and +.B think +(HP ThinkJet). +.TP +.B -e +Produce equally-spaced words in adjusted +lines, using full terminal resolution. +.TP +.B -h +Use output tabs during horizontal spacing +to speed output and reduce output character count. +Tab settings are assumed to be every +8 nominal character widths. +.SH FILES +.TF /sys/lib/troff/term/* +.TP +.B /tmp/trtmp* +temporary file +.TP +.B /sys/lib/tmac/tmac.* +standard macro files +.TP +.B /sys/lib/troff/term/* +terminal driving tables for +.I nroff +.TP +.B /sys/lib/troff/font/* +font width tables for +.I troff +.SH SOURCE +.B /sys/src/cmd/troff +.br +.B /rc/bin/dpost +.br +.ne 3 +.SH "SEE ALSO" +.IR lp (1), +.IR proof (1), +.IR page (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR doctype (1), +.IR ms (6), +.IR image (6), +.IR tex (1), +.IR deroff (1), +.IR col (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' +.br +B. W. Kernighan, +``A Typesetter-Independent TROFF'', +CSTR #97 +.br +B. W. Kernighan, +``A TROFF Tutorial'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/sys/man/1/troff2html b/sys/man/1/troff2html new file mode 100755 index 000000000..7f777a766 --- /dev/null +++ b/sys/man/1/troff2html @@ -0,0 +1,99 @@ +.TH TROFF2HTML 1 +.SH NAME +troff2html \- convert troff output into HTML +.SH SYNOPSIS +.B troff2html +[ +.B -t +.I title +] [ +.I file +\ ... +] +.SH DESCRIPTION +.I Troff2html +reads the +.IR troff (1) +output in the named +.IR files , +default standard input, +and converts them into HTML. +.PP +.I Troff2html +does a tolerable job with straight +.B troff +output, but it is helped by annotations, described below. +Its main use is for +.B man2html +(see +.IR httpd (8)), +which converts +.IR man (1) +pages into HTML +and depends on a specially annotated set of +.IR man (6) +macros, invoked by +.B troff +.BR -manhtml . +.PP +.B Troff +output lines beginning +.IP +.EX +x X html \f1... +.EE +.LP +which are introduced by placing +.B \eX'html\ \f1...\fP' +in the +.IR input , +cause the rest of the line to be interpolated into the HTML produced. +Several such lines are recognized specially by +.IR troff2html . +The most important are the pair +.IP +.EX +x X html manref start cp 1 +x X html manref end cp 1 +.EE +.PP +which are used to create HTML hyperlinks around text of the form +.IR cp (1) +pointing to +.BR /magic/man2html/1/cp . +.PP +.I Troff2html +is new and experimental; in time, it may improve and subsume +.IR ms2html (1). +On the one hand, because it uses the input, +.B ms2html +can handle +.IR pic (1), +.IR eqn (1), +etc., which +.I troff2html +does not handle at all; on the other hand, +.B ms2html +understands only +.IR ms (6) +documents and is easily confused by complex +.B troff +constructions. +.I Troff2html +has the reverse properties: it does not handle the preprocessors but its output +is reliable and (modulo helper annotations) is independent of macro package. +.SH SOURCE +.B /sys/src/cmd/troff2html +.SH SEE ALSO +.IR troff (1), +.IR ms2html (1), +.B man2html +in +.IR httpd (8). +.SH BUGS +.B Troff +and HTML have different models, and they don't mesh well in all cases. +.BR Troff 's +indented paragraphs are not well served in HTML, and the output of +.I troff2html +shows this. diff --git a/sys/man/1/tweak b/sys/man/1/tweak new file mode 100755 index 000000000..e3f195038 --- /dev/null +++ b/sys/man/1/tweak @@ -0,0 +1,167 @@ +.TH TWEAK 1 +.CT 1 graphics +.SH NAME +tweak \- edit image files, subfont files, face files, etc. +.SH SYNOPSIS +.B tweak +[ +.I file ... +] +.SH DESCRIPTION +.I Tweak +edits existing files holding various forms of images. +To create original images, start from an existing image, subfont, etc. +.PP +.I Tweak +reads its argument +.I files +and displays the resulting images in a vertical column. +If the image is too wide to fit across the display, it +is folded much like a long line of text in an +.IR rio +window. +Under each image is displayed one or two lines of text +presenting its parameters. +The first line shows the image's +.BR depth , +the number +of bits per pixel; +.BR r , +the rectangle covered by the image; +and the name of the +.B file +from which it was read. +If the file is a subfont, a second line presents a hexadecimal 16-bit +.B offset +to be applied to character values from the subfont +(typically as stored in a font file; see +.IR font (6)); +and the subfont's +.BR n , +.BR height , +and +.B ascent +as defined in +.IR cachechars (2). +.PP +By means described below, magnified views of portions of the images +may be displayed. +The text associated with such a view includes +.BR mag , +the magnification. +If the view is of a single character from a subfont, the second +line of text shows the character's value (including the subfont's offset) +in hexadecimal and as a character in +.I tweak's +default font; the character's +.BR x , +.BR top , +.BR bottom , +.BR left , +and +.BR width +as defined in +.IR cachechars (2); +and +.BR iwidth , +the physical width of the image in the subfont's image. +.PP +There are two methods to obtain a magnified view of a character from a +subfont. +The first is to click mouse button 1 over the image of the character in +the subfont. The second is to select the +.B char +entry on the button 3 menu, +point the resulting gunsight cursor at the desired subfont and click button 3, +and then type at the text prompt at the bottom of the screen the +character value, either as a multi-digit hexadecimal number or as a single +rune representing the character. +.PP +To magnify a portion of other types of image files, +click button 1 over the unmagnified file. +The cursor will switch to a cross. +Still with button 1, sweep a rectangle, as in +.BR rio , +that encloses the portion of the image to be magnified. +(If the file is 16×16 or smaller, +.I tweak +will just magnify the entire file; no sweeping is necessary.) +.PP +Pressing buttons 1 and 2 within magnified images changes pixel values. +By default, button 1 sets the pixel to all zeros and button 2 sets the pixel +to all ones. +.PP +Across the top of the screen is a textual display of global parameters. +These values, as well as many of the textual values associated with +the images, may be edited by clicking button 1 on the displayed +value and typing a new value. +The values along the top of the screen are: +.TP +.B mag +Default magnification. +.TP +.B val(hex) +The value used to modify pixels within magnified images. +The value must be in hexadecimal, optionally preceded by a +tilde for bitwise negation. +.TP +.B but1 +.TP +.B but2 +The pixel value written when the corresponding button is pressed over a pixel. +.TP +.B invert-on-copy +Whether the pixel values are inverted when a +.B copy +operation is performed. +.PP +Under button 3 is a menu holding a variety of functions. +Many of these functions prompt for the image upon which to act +by switching to a gunsight cursor; click button 3 over the +selection, or click a different button to cancel the action. +.TP +.B open +Read and display a file. The name of the file is typed to the prompt +on the bottom line. +.TP +.B read +Reread a file. +.TP +.B write +Write a file. +.TP +.B copy +Use the copy function, default +.BR S , +to transfer a rectangle of pixels from one image to another. +The program prompts with a cross cursor; sweep out a rectangle in +one image or just click button 3 to select the whole image. +The program will leave that rectangle in place and +attach another one to the cursor. Move that rectangle to the desired +place in any image and click button 3, or another button to cancel the action. +.TP +.B char +As described above, open a magnified view of a character image in a subfont. +.TP +.B pixels +Report the coordinate and value of individual pixels indicated by pressing button 3. +This is a mode of operation canceled by pressing button 1 or 2. +.TP +.B close +Close the specified image. +If the image is the unmagnified file, also close any magnified views of that file. +.TP +.B exit +Quit +.IR tweak . +The program will complain once about modified but unwritten files. +.SH SOURCE +.B /sys/src/cmd/tweak.c +.SH "SEE ALSO" +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH BUGS +For a program written to adjust width tables in fonts, +.I tweak +has been pushed unreasonably far. diff --git a/sys/man/1/uniq b/sys/man/1/uniq new file mode 100755 index 000000000..65fcd49fa --- /dev/null +++ b/sys/man/1/uniq @@ -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/sys/man/1/units b/sys/man/1/units new file mode 100755 index 000000000..504c26f2e --- /dev/null +++ b/sys/man/1/units @@ -0,0 +1,107 @@ +.TH UNITS 1 +.if n .ds / / +.SH NAME +units \- conversion program +.SH SYNOPSIS +.B units +[ +.B -v +] +[ +.I file +] +.SH DESCRIPTION +.I Units +converts quantities expressed +in various standard scales to +their equivalents in other scales. +It works interactively in this fashion: +.IP +.EX +you have: inch +you want: cm + * 2.54 + / 0.393701 +.EE +.PP +A quantity is specified as a multiplicative combination +of units and floating point numbers. +Operators have the following precedence: +.IP +.EX +.ta \w'\fLXXXXXXXXXXXXXXX'u +\fL+\fP \fL-\fP \f1add and subtract +\fL*\fP \fL/\fP \fL×\fP \fL÷\fP \f1multiply and divide +catenation multiply +\fL²\fP \fL³\fP \fL^\fP \f1exponentiation +\fL|\fP \f1divide +\fL(\fP ... \fL)\fP \f1grouping +.EE +.PP +Most familiar units, +abbreviations, and metric prefixes are recognized, +together with a generous leavening of exotica +and a few constants of nature including: +.IP +.de fq +\fL\\$1\\fP \\$2 \\$3 \\$4 \\$5 \\$6 +.. +.ta \w'\fLwaterXXX'u +.nf +.fq pi,\f1π\fP ratio of circumference to diameter +.fq c speed of light +.fq e charge on an electron +.fq g acceleration of gravity +.fq force same as \fLg\fP +.fq mole Avogadro's number +.fq water "pressure head per unit height of water" +.fq au astronomical unit +.fi +.PP +The +.L pound +is a unit of +mass. +Compound names are run together, e.g. +.LR lightyear . +British units that differ from their US counterparts +are prefixed thus: +.LR brgallon . +Currency is denoted +.LR belgiumfranc , +.LR britainpound , +etc. +.PP +The complete list of units can be found in +.BR /lib/units . +A +.I file +argument to +.I units +specifies a file to be used instead of +.BR /lib/units. +The +.B -v +flag causes +.I units +to print its entire database. +.SH EXAMPLE +.EX +you have: 15 pounds force/in² +you want: atm + * 1.02069 + / .97973 +.EE +.SH FILES +.B /lib/units +.SH SOURCE +.B /sys/src/cmd/units.y +.SH BUGS +Since +.I units +does only multiplicative scale changes, +it can convert Kelvin to Rankine but not Centigrade to +Fahrenheit. +.PP +Currency conversions are only as accurate as the last time someone +updated the database. diff --git a/sys/man/1/uptime b/sys/man/1/uptime new file mode 100755 index 000000000..75470077b --- /dev/null +++ b/sys/man/1/uptime @@ -0,0 +1,21 @@ +.TH UPTIME 1 +.SH NAME +uptime \- show how long the system has been running +.SH SYNOPSIS +.B uptime +.SH DESCRIPTION +.I Uptime +shows how long the system has been running. It uses the following format: +.PP +.B + sysname up 33 days, 17:56:42 +.PP +The time given accounts for the timezone. + +..SH FILES +.TF /dev/time +.TF /dev/sysname +.SH SOURCE +.B /rc/bin/uptime +.SH "SEE ALSO" +.IR date (1) diff --git a/sys/man/1/vac b/sys/man/1/vac new file mode 100755 index 000000000..0cf30b01d --- /dev/null +++ b/sys/man/1/vac @@ -0,0 +1,176 @@ +.TH VAC 1 +.SH NAME +vac, unvac \- create, extract a vac archive on Venti +.SH SYNOPSIS +.B vac +[ +.B -mqsv +] [ +.B -b +.I blocksize +] [ +.B -d +.I oldvacfile +] [ +.B -e +.I exclude +] [ +.B -f +.I vacfile +] [ +.B -i +.I name +] [ +.B -h +.I host +] +.I file ... +.PP +.B unvac +[ +.B -Tctv +] [ +.B -h +.I host +] +.I vacfile +[ +.I file ... +] +.SH DESCRIPTION +.I Vac +creates an archival copy of Plan 9 file trees on Venti. It can be used +to build a simple backup system. One of the unusual properties of Venti is +that duplicate blocks are detected and coalesced. When +.I vac +is used on a file tree that shares data with an existing archive, the consumption of +storage will be approximately equal to an incremental backup. +This reduction in storage consumption occurs transparently to the user. +.PP +As an optimization, the +.B -d +and +.B -q +options, described below, can be used to explicitly create an archive relative to an existing archive. +These options do not change the resulting archive generated by +.IR vac , +but simply reduce the number of write operations to Venti. +.PP +The output of +.I vac +is the hexadecimal representation of the SHA1 fingerprint of the root of the archive, in this format: +.IP +.EX +vac:64daefaecc4df4b5cb48a368b361ef56012a4f46 +.EE +.PP +The options to +.I vac +are: +.TF "-d\fI oldvacfile" +.PD +.TP +.BI -b " blocksize +Specifies the block size that data will be broken into. +The units for the size can be specified by appending +.L k +to indicate kilobytes. +The default is 8k. +The size must be in the range +of 512 bytes to 52k. +.TP +.BI -d " oldvacfile +Reduce the number of blocks written to Venti by comparing the files to be stored with +the contents of an existing +.I vac +file tree whose score is stored in +.IR oldvacfile . +.TP +.BI -e " exclude +Do not include the file or directory specified by +.IR exclude . +This option may be repeated multiple times. +.TP +.BI -f " vacfile +The results of +.I vac +are placed in +.IR vacfile , +or the standard output if no file is given. +.TP +.BI -i " name +Include standard input as one of the input files, storing it in the archive +with the specified +.IR name . +.TP +.BI -h " host +The network address of the Venti server. +The default is taken from the environment variable +.BR venti . +If this variable does not exist, then the default is the +metaname +.BR $venti , +which can be configured via +.IR ndb (6). +.TP +.B -m +Expand and merge any +.I vac +archives that are found while reading the input files. This option is +useful for building an archive from a collection of existing archives. Each archive is inserted +into the new archive as if it had been unpacked in the directory in which it was found. Multiple +archives can be unpacked in a single directory and the contents will be merged. To be detected, the +archives must end in +.LR .vac . +Note, an archive is inserted by simply copying the root fingerprint and does not require +the archive to be unpacked. +.TP +.B -q +Increase the performance of the +.B -d +option by detecting unchanged files based on a match of the files name and other meta data, +rather than examining the contents of the files. +.TP +.B -s +Print out various statistics on standard error. +.TP +.B -v +Produce more verbose output on standard error, including the name of the files added to the archive +and the vac archives that are expanded and merged. +.PP +.I Unvac +lists or extracts files stored in the vac archive +.IR vacfile , +which can be either a vac archive string in the format +given above or the name of a file containing one. +If +.I file +arguments are given, only those files or directories +will be extracted. +The options are: +.TP +.B -T +Set the modification time on extracted files +to the time listed in the archive. +.TP +.B -c +Write extracted files to standard output instead of creating a file. +.TP +.B -h +as per +.IR vac . +.TP +.B -t +Print a list of the files to standard output rather than extracting them. +.TP +.B -v +If extracting files, print the name of each file and directory +to standard error. +If listing files, print metadata in addition to the names. +.SH SOURCE +.B /sys/src/cmd/vac +.br +.B /sys/src/cmd/unvac +.SH "SEE ALSO" +.IR vacfs (4), +.IR venti (8) diff --git a/sys/man/1/venti b/sys/man/1/venti new file mode 100755 index 000000000..4b9510338 --- /dev/null +++ b/sys/man/1/venti @@ -0,0 +1,153 @@ +.TH VENTI 1 +.SH NAME +read, write, copy \- simple Venti clients +.SH SYNOPSIS +.B venti/read +[ +.B -h +.I host +] +[ +.B -t +.I type +] +.I score +.br +.B venti/write +[ +.B -z +] +[ +.B -h +.I host +] +[ +.B -t +.I type +] +.br +.B venti/copy +[ +.B -fir +] +[ +.B -t +.I type +] +.I srchost +.I dsthost +.I score +[ +.I type +] +.SH DESCRIPTION +Venti is a SHA1-addressed block storage server. +See +.IR venti (6) +for a full introduction. +.PP +.I Read +reads a block with the given +.I score +and numeric +.I type +from the server +.I host +and prints the block to standard output. +If the +.B -h +option is omitted, +.I read +consults the environment variable +.B $venti +for the name of the Venti server. +If the +.B -t +option is omitted, +.I read +will try each type, one at a time, until it finds +one that works. +It prints the corresponding +.B read +.B -t +command to standard error +to indicate the type of the block. +.PP +.I Write +writes at most 56 kilobytes of data from standard input +to the server +.I host +and prints the resulting score to standard output. +If the +.B -t +option is omitted, +.I write +uses type 0, +denoting a data block. +If the +.B -z +option is given, +.I write +zero truncates the block before writing it to the server. +.PP +.I Copy +expects +.I score +to be the score of a +.B VtRoot +block. +It copies the entire tree of blocks reachable from +the root block from the server +.I srchost +to the server +.IR dsthost . +.PP +The +.B -f +option causes +.I copy +to run in `fast' mode, +assuming that if a block already exists on the +destination Venti server, all its children also +exist and need not be checked. +.PP +The +.B -i +and +.B -r +options control +.IR copy 's +reaction to errors reading +from +.IR srchost . +.I Copy +always prints information to standard error +about each read error. +By default, +.I copy +exits after printing the first error. +If the +.B -i +option is given, read errors are ignored. +This is dangerous behavior because it breaks the +assumption made by `fast' mode. +If the +.B -r +option is given, +.I copy +replaces pointers to unreadable blocks with +pointers to the zero block. +It writes the new root score to standard output. +.SH SOURCE +.B /sys/src/cmd/venti +.SH SEE ALSO +.IR vac (1), +.IR venti (2), +.IR vacfs (4), +.IR venti (6), +.IR venti (8), +.IR venti-backup (8), +.IR venti-fmt (8) +.SH BUGS +There should be programs to read and write +venti files and directories. diff --git a/sys/man/1/vi b/sys/man/1/vi new file mode 100755 index 000000000..1adf8d209 --- /dev/null +++ b/sys/man/1/vi @@ -0,0 +1,170 @@ +.TH VI 1 +.SH NAME +5i, ki, vi, qi \- instruction simulators +.SH SYNOPSIS +.B vi +[ +.I textfile +] +.br +.B vi +.I pid +.br +.B 5i +[ +.I textfile +] +.br +.B 5i +.I pid +.br +.B ki +[ +.I textfile +] +.br +.B ki +.I pid +.br +.B qi +[ +.I textfile +] +.br +.B qi +.I pid +.SH DESCRIPTION +.I Vi +simulates the execution of a MIPS binary in +a Plan 9 environment. +It has two main uses: as +a debugger and as a statistics gatherer. +Programs running under +.I vi +execute about two hundred times +slower than normal\(embut faster than +single stepping under +.IR db . +.IR 5i , +.IR ki , +and +.IR qi +are similar to +.I vi +but interpret ARM, SPARC, and PowerPC binaries. +The following discussion refers to +.I vi +but applies to the others +as well. +.PP +.I Vi +will simulate the execution of a named +.IR textfile . +It will also make a copy of an existing process with process id +.I pid +and simulate its continuation. +.PP +As a debugger +.I vi +offers more complete information +than +.IR db (1). +Tracing can be performed at the level of instructions, +system calls, or function calls. +.I Vi +allows breakpoints to be triggered when specified addresses +in memory are accessed. +A report of instruction counts, +load delay fills and distribution is produced for +each run. +.I Vi +simulates the CPU's caches and MMU +to assist the optimization of compilers and programs. +.PP +The command interface mirrors the interface to +.IR db ; +see +.IR db (1) +for a detailed description. +Data formats and addressing are compatible with +.I db +except +for disassembly: +.I vi +offers only MIPS +.RB ( db +.BR -mmipsco ) +mnemonics for +machine instructions. +.I Ki +offers both Plan 9 and Sun SPARC formats. +.PP +Several extra commands allow +extended tracing and printing of statistics: +.TP +.BR $t [ 0ics ] +The +.I t +command controls tracing. Zero cancels all tracing +options. +.RS +.TP +.B i +Enable instruction tracing +.TP +.B c +Enable call tracing +.TP +.B s +Enable system call tracing +.RE +.TP +.BR $i [ itsp ] +The +.B i +command prints statistics accumulated by +all code run in this session. +.RS +.TP +.B i +Print instruction counts and frequency. +.TP +.B p +Print cycle profile. +.TP +.B t +.RI ( Vi +only) Print TLB and cache statistics. +.TP +.B s +Print memory reference, working set and size statistics. +.RE +.TP +.BR :b [ arwe ] +.I Vi +allows breakpoints to be set on any memory location. +These breakpoints monitor when a location is +accessed, read, written, or equals a certain value. +For equality the compared value is the +.I count +(see +.IR db (1)) +supplied to the command. +.SH SOURCE +.B /sys/src/cmd/vi +etc. +.SH "SEE ALSO" +.IR nm (1), +.IR db (1) +.SH BUGS +The code generated by +the compilers +is well supported, but some unusual instructions are unimplemented. +Some Plan 9 system calls such as +.I rfork +cause simulated traps. +The floating point simulation makes assumptions about the interpreting +machine's floating point support. The floating point conversions performed +by +.I vi +may cause a loss of precision. diff --git a/sys/man/1/vnc b/sys/man/1/vnc new file mode 100755 index 000000000..41f7ffd2f --- /dev/null +++ b/sys/man/1/vnc @@ -0,0 +1,237 @@ +.TH VNC 1 +.SH NAME +vncs, vncv \- remote frame buffer server and viewer for Virtual Network Computing (VNC) +.SH SYNOPSIS +.B vncs +[ +.B -v +] +[ +.B -c +.I cert +] +[ +.B -d +.BI : display +] +[ +.B -g +.IB width x height +] +[ +.B -p +.I pixfmt +] +[ +.B -x +.I net +] +[ +.I cmd +[ +.I args +... +] +] +.PP +.B vncs +.B -k +.BI : display +[ +.B -x +.I net +] +.PP +.B vncv +[ +.B -cstv +] +[ +.B -e +.I encodings +] +[ +.B -k +.I keypattern +] +.IR host [\fL: n ] +.SH DESCRIPTION +VNC is a lightweight protocol +for accessing graphical applications +remotely. The protocol allows one or more +clients to connect to a server. +While connected, clients display the frame buffer +presented by the server and can send mouse events, +keyboard events, and exchange snarf buffers. +The server persists across viewer sessions, so that +the virtual application can be accessed from various locations +as its owner moves around. +.PP +VNC displays have names of the form +.IB host : n \fR, +where +.I host +is the machine's network name and +.I n +is a small integer identifier; display +.I n +is served on TCP port +.RI 5900+ n . +.PP +.I Vncs +starts a new virtual frame buffer in memory, simulating +a Plan 9 terminal running +.I cmd +.IR args , +by default an interactive shell. +As viewers connect, each is authenticated using a +(rather breakable) challenge-response protocol using +the user's Inferno/POP password. +.PP +The options are: +.TF "\fL-p \fIpixfmt" +.PD +.TP +.B -c \fIcert +start TLS on each viewer connection using the certificate +in the file +.IR cert . +The corresponding private key must be loaded into +the server's +.IR factotum (4). +When serving TLS connections, the base port is +35729 rather than 5900. +.TP +.B -d :\fIn +run on display +.I n ; +without this option, the server searches +for an unused display. +.TP +.B -g \fIwidth\fBx\fIheight\fR +set the virtual frame buffer to be +.IB width x height +(default +1024x768) +pixels. +.TP +.B -p \fIpixfmt +set the virtual frame buffer's internal pixel format to +.I pixfmt +(default +.BR r5g6b5 ). +.TP +.B -v +print verbose output to standard error. +.TP +.B -x \fInet +announce on an alternate network interface. +Because of the weak authentication protocol and +default lack of encryption, this option must +be accompanied by +.BR -c . +.PD +.PP +The command +.B vncs +.B -k +.BI : n +kills the VNC server running on display +.IR n . +.PP +.I Vncv +provides access to remote display +.IB host : n \fR. +It resizes its window to be the smaller of the +remote frame buffer size and the local screen. +.PP +The options are: +.TP +.B -c +when connecting to 8-bit displays, request +.B r4g4b4 +pixels rather than +.B r3g3b2 +pixels. +This takes up more bandwidth but usually gives +significantly better matching to the Plan 9 color map. +.TP +.B -e \fIencodings +set the ordered list of allowed frame buffer update encodings. +The default (and full) set is +.B copyrect +.B corre +.B hextile +.B rre +.BR raw . +The encodings should be given as a single space-separated argument +(quoted when using the shell). +.TP +.B -k \fIkeypattern +add +.I keypattern +to the pattern used to select a key from +.IR factotum (4). +.TP +.B -s +share the display with extant viewers; +by default extant viewers are closed +when a new viewer connects. +.TP +.B -t +start TLS on the connection. +.TP +.B -v +print verbose output to standard error. +.PD +.PP +The VNC protocol represents keyboard input as +key up/down events. +Plan 9 does not expose the state of the +Ctl and Shift keys except as it can be inferred +from receipt of control or shifted characters. +It does not expose the state of the Alt key at all, +since the Alt key is used to compose Unicode characters +(see +.IR keyboard (6)). +.I Vncv +correctly handles the sending of control and shifted +characters. +To support systems that use key sequences like Alt-X +(or worse, Alt-mouse-click), typing the Plan 9 compose +sequences +.B Alt +.B Z +.B A +(for Alt), +.B Alt +.B Z +.B C +(for Ctrl), +and +.B Alt +.B Z +.B S +(for Shift) +will send a ``key down'' message for +the given key. +A corresponding ``key up'' message +will be sent after the next key is pressed, +or when the sequence is retyped, +whichever happens first. +.SH SOURCE +.B /sys/src/cmd/vnc +.SH "SEE ALSO +.IR drawterm (8) +.br +.B http://www.uk.research.att.com/vnc +.SH BUGS +If the remote frame buffer is larger than the local screen, +only the upper left corner can be accessed. +.PP +.I Vncv +does no verification of the TLS certificate presented +by the server. +.PP +.I Vncv +supports only version 3.3 of the RFB protocol. diff --git a/sys/man/1/vt b/sys/man/1/vt new file mode 100755 index 000000000..fefd7b8c2 --- /dev/null +++ b/sys/man/1/vt @@ -0,0 +1,135 @@ +.TH VT 1 +.SH NAME +vt \- emulate a VT-100 or VT-220 terminal +.SH SYNOPSIS +.B vt +[ +.B -2abcx +] +[ +.B -f +.I font +] [ +.B -l +.I log +] +.SH DESCRIPTION +.I Vt +replaces a +.I rio +window with a fresh instance of the shell, +.IR rc (1), +running within an emulation of a DEC VT-100 terminal. +To exit +.IR vt , +exit the +.B rc +it starts. +.SS Options +.TF m +.TP +.B 2 +.TP +.B a +.TP +.B x +change +.I vt +to emulate a VT-220, ANSI, or XTerm terminal respectively. +.TP +.B b +changes the color scheme to white text on a black background, +but potentially with colors from escape sequences. +.TP +.B c +changes the color scheme to monochrome (no colors). +.TP +.B f +sets the +.IR font . +.TP +.B l +names a +.I log +file for the session. +.SS Menus +The right button has a menu with the following entries to provide +the sort of character processing expected by non-Plan 9 systems: +.TF cooked +.TP +.B 24x80 +Resize the +.I vt +window to hold 24 rows of 80 columns. +.TP +.B crnl +Print a newline (linefeed) character after receiving a carriage return from the host. +.TP +.B cr +Do not print a newline after carriage return. +.TP +.B nlcr +Print a carriage return after receiving a newline from the host. +.TP +.B nl +Do not print a carriage return after newline. +.TP +.B raw +Enter raw (no echo, no interpretation) character mode for input. +.TP +.B cooked +Leave raw mode. +.TP +.B exit +Exit +.IR vt . +.PD +.PP +The middle button has a menu with the following entries: +.TF right_key +.TP +.B backup +Move the display back one screenful. +.TP +.B forward +Move the display forward one screenful. +(These are a poor substitute for a scroll bar.) +.TP +.B reset +Display the last screenful; the same as going +.B forward +to the end. +.TP +.B clear +Clear the screen. Previous contents can be recovered using +.BR backup . +.TP +.B send +Send the contents of the +.B rio +snarf buffer, just as +.B send +in the +.B rio +menu. +.TP +.B scroll +Make new lines visible as they appear at the bottom. +.TP +.B page +When the page fills, pause and wait for a character to be typed before proceeding. +The down arrow key advances a page without sending the character to the host. +.PD +.SH SOURCE +.B /sys/src/cmd/vt +.SH BUGS +This program is used only for communicating with foreign systems, +so it is not +as rich an emulation as its equivalent in other environments. +.PP +Use care in setting raw and newline modes when connecting to Unix systems +via +.IR con (1) +or +.IR ssh (1). +It may also be necessary to set the emulator into raw mode. diff --git a/sys/man/1/wc b/sys/man/1/wc new file mode 100755 index 000000000..fe2b80340 --- /dev/null +++ b/sys/man/1/wc @@ -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. +.PP +.I Wc +should have options to count suboptimal +.SM UTF +codes +and bytes that cannot occur in any +.SM UTF +code. diff --git a/sys/man/1/weather b/sys/man/1/weather new file mode 100755 index 000000000..a4ccbd88c --- /dev/null +++ b/sys/man/1/weather @@ -0,0 +1,35 @@ +.TH WEATHER 1 +.SH NAME +weather \- print weather report +.SH SYNOPSIS +.B weather +[ +.I air +] [ +.I st +] +.SH DESCRIPTION +.I Weather +prints the local conditions and seven-day forecast most recently reported at the +.SM US +airport with the three-letter location identifier +.IR air . +Given a two-letter +.SM US +state abbreviation +.I st +instead, +.I weather +prints a table of +.I air +location identifiers known for +.IR st . +.PP +The arguments are mutually exclusive and case-insensitive. +If neither is given, +.I air +defaults to location identifier +.BR ewr , +designating the Newark, NJ, airport near Bell Labs, Murray Hill. +.SH SOURCE +.B /rc/bin/weather diff --git a/sys/man/1/who b/sys/man/1/who new file mode 100755 index 000000000..1a13c3af0 --- /dev/null +++ b/sys/man/1/who @@ -0,0 +1,22 @@ +.TH WHO 1 +.SH NAME +who, whois \- who is using the machine +.SH SYNOPSIS +.B who +.PP +.B whois +.I person +.SH DESCRIPTION +.I Who +prints the name of everyone with a non-Exiting process +on the current machine. +.PP +.I Whois +looks in +.B /adm/whois +and +.B /adm/users +to find out more information about +.IR person . +.SH SOURCE +.B /rc/bin/who diff --git a/sys/man/1/winwatch b/sys/man/1/winwatch new file mode 100755 index 000000000..46183dcc3 --- /dev/null +++ b/sys/man/1/winwatch @@ -0,0 +1,46 @@ +.TH WINWATCH 1 +.SH NAME +winwatch \- monitor rio windows +.SH SYNOPSIS +.B winwatch +[ +.B -e +.I exclude +] [ +.B -f +.I font +] +.SH DESCRIPTION +.I Winwatch +displays the labels of all current +.IR rio (4) +windows, refreshing the display every five seconds. +Right clicking a window's label unhides, raises and gives focus to that window. +Typing +.B q +or +DEL +quits +.IR winwatch . +.PP +If the +.B -e +flag +is given, +windows matching the regular expression +.I exclude +are not shown. +.SH EXAMPLE +Excluding winwatch, stats and faces from being showed. +.IP +.EX +% winwatch -e '^(winwatch|stats|faces)' +.EE +.SH FILES +.B /dev/wsys/*/label +.SH SOURCE +.B /sys/src/cmd/winwatch.c +.SH SEE ALSO +.IR rio (1), +.IR rio (4), +.IR regexp (6). diff --git a/sys/man/1/xd b/sys/man/1/xd new file mode 100755 index 000000000..cc2d394f4 --- /dev/null +++ b/sys/man/1/xd @@ -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/sys/man/1/yacc b/sys/man/1/yacc new file mode 100755 index 000000000..a965f9537 --- /dev/null +++ b/sys/man/1/yacc @@ -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. diff --git a/sys/man/1/yesterday b/sys/man/1/yesterday new file mode 100755 index 000000000..7d924ce47 --- /dev/null +++ b/sys/man/1/yesterday @@ -0,0 +1,156 @@ +.TH YESTERDAY 1 +.SH NAME +yesterday, diffy \- print file names from the dump +.SH SYNOPSIS +.B yesterday +[ +.B -abcCdDs +] [ +.B -n +.I daysago +] [ +.I \-date +] +.I files ... +.PP +.B diffy +[ +.B -abcefmnrw +] +.I files ... +.SH DESCRIPTION +.I Yesterday +prints the names of the +.I files +from the most recent dump. +Since dumps are done early in the morning, +yesterday's files are really in today's dump. +For example, if today is March 17, 1992, +.IP +.EX +yesterday /adm/users +.EE +.PP +prints +.IP +.EX +/n/dump/1992/0317/adm/users +.EE +.PP +In fact, the implementation is to select the most recent dump in +the current year, so the dump selected may not be from today. +.PP +When presented with a path of the form +.BI /n/ fs / path \fR, +.I yesterday +will look for +dump files of the form +\fL/n/\fIfs\fLdump/\fIyyyy\fL/\fIhhmm\fL/\fIpath\fR. +.PP +By default, +.I yesterday +prints the names of the dump files corresponding to the named files. +The first set of options changes this behavior. +.TP +.B -a +Run +.IR acme (1)'s +.I adiff +to compare the dump files with the named files. +.TP +.B -b +Bind the dump files over the named files. +.TP +.B -c +Copy the dump files over the named files. +.TP +.B -C +Copy the dump files over the named files only when +they differ. +.TP +.B -d +Run +.B diff +to compare the dump files with the named files. +.TP +.B -D +Run +.B diff +.B -n +to compare the dump files with the named files. +.PP +The +.I date +option selects other day's dumps, with a format of +1, 2, 4, 6, or 8 digits of the form +.IR d, +.IR dd , +.IR mmdd , +.IR yymmdd , +or +.IR yyyymmdd . +.PP +The +.B -n +option selects the dump +.I daysago +prior to the current day. +.PP +The +.B -s +option selects the most recent snapshot instead of the most +recent archived dump. Snapshots may occur more frequently +than dumps. +.PP +.I Yesterday +does not guarantee that the string it prints represents an existing file. +.PP +.I Diffy +runs +.IR diff (1) +with the given options +to compare yesterday's version of each of the named files +with today's. +.SH EXAMPLES +.PP +Back up to yesterday's MIPS binary of +.BR vc : +.IP +.EX +yesterday -c /mips/bin/vc +.EE +.PP +Temporarily back up to March 1's MIPS C library to see if a program +runs correctly when loaded with it: +.IP +.EX +yesterday -b -0301 /mips/lib/libc.a +rm v.out +mk +v.out +.EE +.PP +Find what has changed in the C library since March 1: +.IP +.EX +yesterday -d -0301 /sys/src/libc/port/*.c +.EE +.PP +Find what has changed in the source tree today: +.IP +.EX +diffy -r /sys/src +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /rc/bin/yesterday +.br +.B /rc/bin/diffy +.SH SEE ALSO +.IR history (1), +.IR bind (1), +.IR diff (1), +.IR fs (4). +.SH BUGS +It's hard to use this command without singing. -- cgit v1.2.3