From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man1/9c.1 | 175 +++++++ man/man1/9p.1 | 125 +++++ man/man1/9term.1 | 6 +- man/man1/INDEX | 170 +++++++ man/man1/acid.1 | 30 +- man/man1/acme.1 | 44 +- man/man1/ascii.1 | 6 +- man/man1/astro.1 | 122 +++++ man/man1/bc.1 | 292 +++++++++++ man/man1/bundle.1 | 57 +++ man/man1/cat.1 | 26 +- man/man1/cleanname.1 | 2 +- man/man1/colors.1 | 73 +++ man/man1/core.1 | 46 ++ man/man1/crop.1 | 147 ++++++ man/man1/date.1 | 46 +- man/man1/db.1 | 5 +- man/man1/deroff.1 | 4 +- man/man1/dict.1 | 18 +- man/man1/doctype.1 | 56 +++ man/man1/ed.1 | 4 +- man/man1/eqn.1 | 2 +- man/man1/freq.1 | 2 +- man/man1/fsize.1 | 22 + man/man1/grap.1 | 2 +- man/man1/graph.1 | 2 +- man/man1/grep.1 | 26 +- man/man1/gzip.1 | 160 ++++++ man/man1/join.1 | 9 +- man/man1/jpg.1 | 243 +++++++++ man/man1/kill.1 | 69 +++ man/man1/label.1 | 71 +++ man/man1/lex.1 | 81 +++ man/man1/look.1 | 86 ++++ man/man1/ls.1 | 6 +- man/man1/man.1 | 105 ++++ man/man1/map.1 | 675 +++++++++++++++++++++++++ man/man1/mc.1 | 12 +- man/man1/mk.1 | 682 ++++++++++++++++++++++++++ man/man1/namespace.1 | 14 + man/man1/news.1 | 63 +++ man/man1/p.1 | 33 ++ man/man1/page.1 | 56 +++ man/man1/pic.1 | 2 +- man/man1/plot.1 | 8 +- man/man1/plumb.1 | 4 +- man/man1/pr.1 | 110 +++++ man/man1/proof.1 | 134 +++++ man/man1/ps.1 | 107 ++++ man/man1/psfonts.1 | 125 +++++ man/man1/pwd.1 | 26 + man/man1/rc.1 | 36 +- man/man1/rio.1 | 96 +++- man/man1/rm.1 | 2 +- man/man1/sam.1 | 28 +- man/man1/scat.1 | 12 +- man/man1/secstore.1 | 212 ++++++++ man/man1/sed.1 | 385 +++++++++++++++ man/man1/seq.1 | 2 +- man/man1/sleep.1 | 2 +- man/man1/split.1 | 4 +- man/man1/src.1 | 83 ++++ man/man1/tbl.1 | 2 +- man/man1/tcs.1 | 167 +++++++ man/man1/touch.1 | 2 +- man/man1/tr2post.1 | 111 +++++ man/man1/troff.1 | 9 +- man/man1/tweak.1 | 167 +++++++ man/man1/units.1 | 108 ++++ man/man1/vac.1 | 130 +++++ man/man1/web.1 | 75 +++ man/man1/wintext.1 | 98 ++++ man/man1/yacc.1 | 4 +- man/man3/9p.3 | 41 +- man/man3/9pclient.3 | 342 +++++++++++++ man/man3/9pcmdbuf.3 | 4 +- man/man3/9pfile.3 | 4 +- man/man3/INDEX | 1163 ++++++++++++++++++++++++++++++++++++++++++++ man/man3/abs.3 | 33 -- man/man3/allocimage.3 | 10 +- man/man3/arg.3 | 2 +- man/man3/arith3.3 | 269 ++++++++++ man/man3/atof.3 | 2 +- man/man3/auth.3 | 395 --------------- man/man3/authsrv.3 | 223 --------- man/man3/bio.3 | 20 +- man/man3/cachechars.3 | 8 +- man/man3/cleanname.3 | 2 +- man/man3/color.3 | 6 +- man/man3/complete.3 | 2 +- man/man3/cputime.3 | 8 +- man/man3/ctime.3 | 98 ++++ man/man3/dial.3 | 271 +++++------ man/man3/dirread.3 | 4 +- man/man3/disk.3 | 177 +++++++ man/man3/draw.3 | 20 +- man/man3/dsa.3 | 4 +- man/man3/dup.3 | 18 +- man/man3/encode.3 | 4 +- man/man3/encrypt.3 | 76 --- man/man3/errstr.3 | 28 +- man/man3/event.3 | 8 +- man/man3/exec.3 | 63 +-- man/man3/exits.3 | 20 +- man/man3/fcall.3 | 6 +- man/man3/fmtinstall.3 | 16 +- man/man3/fork.3 | 166 ------- man/man3/genrandom.3 | 1 - man/man3/get9root.3 | 75 +++ man/man3/getcallerpc.3 | 2 +- man/man3/getenv.3 | 28 +- man/man3/getfields.3 | 2 +- man/man3/getns.3 | 22 + man/man3/getpid.3 | 41 -- man/man3/getsnarf.3 | 37 ++ man/man3/getuser.3 | 37 +- man/man3/getwd.3 | 9 +- man/man3/graphics.3 | 64 +-- man/man3/ioproc.3 | 39 +- man/man3/ip.3 | 22 +- man/man3/isalpharune.3 | 6 +- man/man3/keyboard.3 | 18 +- man/man3/lock.3 | 57 ++- man/man3/mach-cmd.3 | 141 ++++++ man/man3/mach-file.3 | 28 +- man/man3/mach-map.3 | 51 +- man/man3/mach-stack.3 | 60 ++- man/man3/mach-symbol.3 | 55 ++- man/man3/mach.3 | 23 +- man/man3/malloc.3 | 55 +-- man/man3/matrix.3 | 350 +++++++++++++ man/man3/memdraw.3 | 17 +- man/man3/memlayer.3 | 8 +- man/man3/memory.3 | 126 +++++ man/man3/mousescrollsize.3 | 62 +++ man/man3/mp.3 | 10 +- man/man3/mux.3 | 154 ++++++ man/man3/nan.3 | 2 +- man/man3/needstack.3 | 69 +++ man/man3/notify.3 | 213 ++++---- man/man3/open.3 | 19 +- man/man3/opentemp.3 | 48 ++ man/man3/pipe.3 | 80 ++- man/man3/plumb.3 | 54 +- man/man3/post9pservice.3 | 29 ++ man/man3/postnote.3 | 16 +- man/man3/print.3 | 2 +- man/man3/proto.3 | 131 +++++ man/man3/pushtls.3 | 196 ++++++++ man/man3/qball.3 | 76 +++ man/man3/quaternion.3 | 152 ++++++ man/man3/quote.3 | 4 +- man/man3/rand.3 | 14 +- man/man3/read.3 | 9 +- man/man3/readcolmap.3 | 76 +++ man/man3/regexp.3 | 2 +- man/man3/regexp9.3 | 212 ++++++++ man/man3/rendezvous.3 | 57 --- man/man3/rfork.3 | 163 +++++++ man/man3/rsa.3 | 58 ++- man/man3/rune.3 | 6 +- man/man3/runestrcat.3 | 2 +- man/man3/scsi.3 | 188 +++++++ man/man3/seek.3 | 2 +- man/man3/sendfd.3 | 57 +++ man/man3/setjmp.3 | 4 +- man/man3/sleep.3 | 2 +- man/man3/stat.3 | 29 +- man/man3/strcat.3 | 6 +- man/man3/string.3 | 45 +- man/man3/stringsize.3 | 4 +- man/man3/subfont.3 | 6 +- man/man3/sysfatal.3 | 39 ++ man/man3/thread.3 | 239 ++++++--- man/man3/time.3 | 16 +- man/man3/udpread.3 | 68 +++ man/man3/wait.3 | 53 +- man/man3/wctl.3 | 39 ++ man/man3/window.3 | 244 ++++++++++ man/man4/0intro.4 | 82 ++++ man/man4/9pserve.4 | 46 ++ man/man4/INDEX | 6 + man/man4/acme.4 | 406 ++++++++++++++++ man/man4/plumber.4 | 121 +++++ man/man4/ramfs.4 | 50 ++ man/man5/INDEX | 1 + man/man7/INDEX | 18 + man/man7/color.7 | 150 ++++++ man/man7/face.7 | 115 +++++ man/man7/font.7 | 87 ++++ man/man7/image.7 | 205 ++++++++ man/man7/man.7 | 249 ++++++++++ man/man7/map.7 | 87 ++++ man/man7/ms.7 | 308 ++++++++++++ man/man7/plot.7 | 336 +++++++++++++ man/man7/plumb.7 | 417 ++++++++++++++++ man/man7/regexp.7 | 8 +- man/man7/regexp9.7 | 150 ++++++ man/man7/thumbprint.7 | 41 ++ man/man7/utf.7 | 2 +- man/man8/INDEX | 2 + man/man8/mk9660.8 | 233 +++++++++ man/man9/0intro.9p | 630 ++++++++++++++++++++++++ man/man9/INDEX | 16 + man/man9/attach.9p | 168 +++++++ man/man9/clunk.9p | 55 +++ man/man9/error.9p | 28 ++ man/man9/flush.9p | 109 +++++ man/man9/open.9p | 249 ++++++++++ man/man9/read.9p | 126 +++++ man/man9/remove.9p | 51 ++ man/man9/stat.9p | 297 +++++++++++ man/man9/version.9p | 99 ++++ man/man9/walk.9p | 189 +++++++ 214 files changed, 17110 insertions(+), 1997 deletions(-) create mode 100644 man/man1/9c.1 create mode 100644 man/man1/9p.1 create mode 100644 man/man1/INDEX create mode 100644 man/man1/astro.1 create mode 100644 man/man1/bc.1 create mode 100644 man/man1/bundle.1 create mode 100644 man/man1/colors.1 create mode 100644 man/man1/core.1 create mode 100644 man/man1/crop.1 create mode 100644 man/man1/doctype.1 create mode 100644 man/man1/fsize.1 create mode 100644 man/man1/gzip.1 create mode 100644 man/man1/jpg.1 create mode 100644 man/man1/kill.1 create mode 100644 man/man1/label.1 create mode 100644 man/man1/lex.1 create mode 100644 man/man1/look.1 create mode 100644 man/man1/man.1 create mode 100644 man/man1/map.1 create mode 100644 man/man1/mk.1 create mode 100644 man/man1/namespace.1 create mode 100644 man/man1/news.1 create mode 100644 man/man1/p.1 create mode 100644 man/man1/page.1 create mode 100644 man/man1/pr.1 create mode 100644 man/man1/proof.1 create mode 100644 man/man1/ps.1 create mode 100644 man/man1/psfonts.1 create mode 100644 man/man1/pwd.1 create mode 100644 man/man1/secstore.1 create mode 100644 man/man1/sed.1 create mode 100644 man/man1/src.1 create mode 100644 man/man1/tcs.1 create mode 100644 man/man1/tr2post.1 create mode 100644 man/man1/tweak.1 create mode 100644 man/man1/units.1 create mode 100644 man/man1/vac.1 create mode 100644 man/man1/web.1 create mode 100644 man/man1/wintext.1 create mode 100644 man/man3/9pclient.3 create mode 100644 man/man3/INDEX delete mode 100644 man/man3/abs.3 create mode 100644 man/man3/arith3.3 delete mode 100644 man/man3/auth.3 delete mode 100644 man/man3/authsrv.3 create mode 100644 man/man3/ctime.3 create mode 100644 man/man3/disk.3 delete mode 100644 man/man3/encrypt.3 delete mode 100644 man/man3/fork.3 create mode 100644 man/man3/get9root.3 create mode 100644 man/man3/getns.3 delete mode 100644 man/man3/getpid.3 create mode 100644 man/man3/getsnarf.3 create mode 100644 man/man3/mach-cmd.3 create mode 100644 man/man3/matrix.3 create mode 100644 man/man3/memory.3 create mode 100644 man/man3/mousescrollsize.3 create mode 100644 man/man3/mux.3 create mode 100644 man/man3/needstack.3 create mode 100644 man/man3/opentemp.3 create mode 100644 man/man3/post9pservice.3 create mode 100644 man/man3/proto.3 create mode 100644 man/man3/pushtls.3 create mode 100644 man/man3/qball.3 create mode 100644 man/man3/quaternion.3 create mode 100644 man/man3/readcolmap.3 create mode 100644 man/man3/regexp9.3 delete mode 100644 man/man3/rendezvous.3 create mode 100644 man/man3/rfork.3 create mode 100644 man/man3/scsi.3 create mode 100644 man/man3/sendfd.3 create mode 100644 man/man3/sysfatal.3 create mode 100644 man/man3/udpread.3 create mode 100644 man/man3/wctl.3 create mode 100644 man/man3/window.3 create mode 100644 man/man4/0intro.4 create mode 100644 man/man4/9pserve.4 create mode 100644 man/man4/INDEX create mode 100644 man/man4/acme.4 create mode 100644 man/man4/plumber.4 create mode 100644 man/man4/ramfs.4 create mode 100644 man/man5/INDEX create mode 100644 man/man7/INDEX create mode 100644 man/man7/color.7 create mode 100644 man/man7/face.7 create mode 100644 man/man7/font.7 create mode 100644 man/man7/image.7 create mode 100644 man/man7/man.7 create mode 100644 man/man7/map.7 create mode 100644 man/man7/ms.7 create mode 100644 man/man7/plot.7 create mode 100644 man/man7/plumb.7 create mode 100644 man/man7/regexp9.7 create mode 100644 man/man7/thumbprint.7 create mode 100644 man/man8/INDEX create mode 100644 man/man8/mk9660.8 create mode 100644 man/man9/0intro.9p create mode 100644 man/man9/INDEX create mode 100644 man/man9/attach.9p create mode 100644 man/man9/clunk.9p create mode 100644 man/man9/error.9p create mode 100644 man/man9/flush.9p create mode 100644 man/man9/open.9p create mode 100644 man/man9/read.9p create mode 100644 man/man9/remove.9p create mode 100644 man/man9/stat.9p create mode 100644 man/man9/version.9p create mode 100644 man/man9/walk.9p diff --git a/man/man1/9c.1 b/man/man1/9c.1 new file mode 100644 index 00000000..6745ae35 --- /dev/null +++ b/man/man1/9c.1 @@ -0,0 +1,175 @@ +.TH 9C 1 +.SH NAME +9c, 9a, 9l, 9ar \- C compiler, assembler, linker, archiver +.SH SYNOPSIS +.B 9c +.I file +\&... +.PP +.B 9a +.I file +\&... +.PP +.B 9l +[ +.I -o +.I target +] +.I object +\&... +[ +.I library +\&... +] +[ +.BI -L path +\&... +] +[ +.BI -l library +\&... +] +.PP +.B 9ar +.I key +[ +.I posname +] +.I afile +[ +.I file +\&... +] +.SH DESCRIPTION +These programs are shell scripts that invoke the appropriate standard tools +for the current operating system and architecture. +One can use them to write portable recipes for mkfiles. +.PP +.I 9c +compiles the named C +.I files +into object files for the current system. +The system C compiler is invoked with warnings enabled, +with the symbol +.B PLAN9PORT +is defined in the C preprocessor, and with +.B $PLAN9/include +on the include path. +.PP +.I 9c +also defines +.B __sun__ +on SunOS systems and +.B __Linux26__ +on Linux systems with 2.6-series kernels. +.PP +.I 9a +assembles the named files into object files for the current system. +Unlike some system assemblers, it does +.I not +promise to run the C preprocessor on the source files. +.PP +.I 9l +links the named object files and libraries to create the target executable. +Each +.B -l +option specifies that a library named +.BI lib library .a +be found and linked. +The +.B -L +option adds directories to the library search path. +.I 9l +invokes the system linker with +.B $PLAN9/lib +already on the library search path. +.PP +.I 9ar +maintains object file archives called libraries. +The exact set of valid command keys varies from system to system, +but +.I 9ar +always provides the following key characters: +.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. +.TP +.B t +List a table of contents of the archive. +If names are given, only those files are listed. +.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 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 9ar +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. +.PD +.PP +When a +.BR d , +.BR r , +or +.BR m +.I key +is specified, +.I 9ar +inserts a table of contents, required by the linker, at +the front of the library. +The table of contents is +rebuilt whenever the archive is modified. +.SH EXAMPLE +.TP +.L +9c file1.c file2.c file3.c +Compile three C source files. +.TP +.L +9a file4.s +Assemble one assembler source file. +.TP +.L +9ar rvc lib.a file[12].o +Archive the first two object files into a library. +.L +9l -o prog file3.o file4.o lib.a +Link the final two object files and any necessary objects from the library +into an executable. +.SH SOURCE +.B /usr/local/plan9/bin diff --git a/man/man1/9p.1 b/man/man1/9p.1 new file mode 100644 index 00000000..199c26b8 --- /dev/null +++ b/man/man1/9p.1 @@ -0,0 +1,125 @@ +.TH 9P 1 +.SH NAME +9p \- read and write files on a 9P server +.SH SYNOPSIS +.B 9p +[ +.B -a +.I addr +] +.B read +.I path +.br +.B 9p +[ +.B -a +.I addr +] +.B readfd +.I path +.PP +.B 9p +[ +.B -a +.I addr +] +.B write +.I path +.br +.B 9p +[ +.B -a +.I addr +] +.B writefd +.I path +.PP +.B 9p +[ +.B -a +.I addr +] +.B stat +.I path +.SH DESCRIPTION +.I 9p +is a trivial 9P client that can access a single file on a 9P server. +It can be useful for manual interaction with a 9P server or for +accessing simple 9P services from within shell scripts. +.PP +The first argument is a command, one of: +.TP +.B read +print the contents of +.I path +to standard output +.TP +.B write +write data on standard input to +.I path +.TP +.BR readfd ", " writefd +like +.B read +and +.B write +but use +.IR openfd (9p) +instead of +.IR open ; +this masks errors and is mainly useful for debugging +the implementation of +.I openfd +.TP +.B stat +execute +.I stat (9p) +on +.I path +and print the result +.PD +.PP +.I 9p +dials +.I address +to connect to the 9P server. +If the +.B -a +option is not given, +.I 9p +requires the +.I path +to be of the form +.IB service / subpath \fR; +it connects to the Unix domain socket +.I service +in the name space directory +(see +.IR intro (4)) +and then accesses +.IR subpath . +.SH EXAMPLE +To update +.IR plumber (4)'s +copy of your plumbing rules after editing +.BR $HOME/lib/plumbing : +.IP +.EX +cat $HOME/lib/plumbing | 9p write plumb/rules +.EE +.PP +To display the contents of the current +.IR acme (4) +window (specified by the environment variable +.BR $winid ) +on standard output: +.IP +.EX +9p read acme/$winid/body +.EE +.SH SOURCE +.B /usr/local/plan9/src/cmd/9p.c +.SH SEE ALSO +.IR intro (4), +.IR intro (9p), +.IR 9pclient (3) diff --git a/man/man1/9term.1 b/man/man1/9term.1 index 932a067e..ebb9bd70 100644 --- a/man/man1/9term.1 +++ b/man/man1/9term.1 @@ -12,7 +12,7 @@ ] [ .I cmd -... +\&... ] .PP .B label @@ -272,7 +272,9 @@ to turn on hold mode first. The .B plumb menu item sends the contents of the selection (not the snarf buffer) to the -.IR plumber (1). +.I plumber +(see +.IR plumb (1)). 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 diff --git a/man/man1/INDEX b/man/man1/INDEX new file mode 100644 index 00000000..de03a627 --- /dev/null +++ b/man/man1/INDEX @@ -0,0 +1,170 @@ +9a 9c.1 +9ar 9c.1 +9c 9c.1 +9l 9c.1 +9p 9p.1 +9term 9term.1 +label 9term.1 +acid acid.1 +acidtypes acid.1 +acme acme.1 +awd acme.1 +win acme.1 +ascii ascii.1 +unicode ascii.1 +astro astro.1 +basename basename.1 +bc bc.1 +bundle bundle.1 +cal cal.1 +calendar calendar.1 +cat cat.1 +read cat.1 +cleanname cleanname.1 +cmp cmp.1 +colors colors.1 +getmap colors.1 +comm comm.1 +core core.1 +crop crop.1 +iconv crop.1 +clock date.1 +date date.1 +db db.1 +dc dc.1 +delatex deroff.1 +deroff deroff.1 +dict dict.1 +diff diff.1 +doctype doctype.1 +echo echo.1 +ed ed.1 +eqn eqn.1 +factor factor.1 +primes factor.1 +fmt fmt.1 +htmlfmt fmt.1 +fortune fortune.1 +freq freq.1 +fsize fsize.1 +mtime fsize.1 +grap grap.1 +graph graph.1 +g grep.1 +grep grep.1 +gview gview.1 + +bunzip2 gzip.1 +bzip2 gzip.1 +gunzip gzip.1 +gzip gzip.1 +unzip gzip.1 +zip gzip.1 +hoc hoc.1 +idiff idiff.1 +join join.1 +bmp jpg.1 +gif jpg.1 +ico jpg.1 +jpg jpg.1 +png jpg.1 +ppm jpg.1 +togif jpg.1 +toico jpg.1 +topng jpg.1 +toppm jpg.1 +yuv jpg.1 +kill kill.1 +slay kill.1 +start kill.1 +stop kill.1 +awd label.1 +label label.1 +lex lex.1 +look look.1 +lc ls.1 +ls ls.1 +lookman man.1 +man man.1 +map map.1 +mapdemo map.1 +mc mc.1 +membername mk.1 +mk mk.1 +mkdir mkdir.1 +namespace namespace.1 +news news.1 +p p.1 +img page.1 +page page.1 +psv page.1 +pic pic.1 +tpic pic.1 +plot plot.1 +plumb plumb.1 +pr pr.1 +proof proof.1 +ps ps.1 +psu ps.1 +pbd pwd.1 +pwd pwd.1 +. rc.1 +cd rc.1 +eval rc.1 +exec rc.1 +exit rc.1 +flag rc.1 +rc rc.1 +rfork rc.1 +shift rc.1 +wait rc.1 +whatis rc.1 +~ rc.1 +rio rio.1 +rm rm.1 +B sam.1 +E sam.1 +sam sam.1 +sam.save sam.1 +samsave sam.1 +samterm sam.1 +scat scat.1 +aescbc secstore.1 +ipso secstore.1 +secstore secstore.1 +9sed sed.1 +sed sed.1 +seq seq.1 +sleep sleep.1 +sort sort.1 +spell spell.1 +sprog spell.1 +split split.1 +src src.1 +stats stats.1 +strings strings.1 +md5sum sum.1 +sha1sum sum.1 +sum sum.1 +tail tail.1 +tbl tbl.1 +tcs tcs.1 +tee tee.1 +test test.1 +time time.1 +touch touch.1 +tr tr.1 +nroff troff.1 +troff troff.1 +tweak tweak.1 +uniq uniq.1 +units units.1 +vac vac.1 +wc wc.1 +web web.1 +wmail web.1 +" wintext.1 +"" wintext.1 +wintext wintext.1 +xd xd.1 +yacc yacc.1 diff --git a/man/man1/acid.1 b/man/man1/acid.1 index 2d1523af..1f7c2649 100644 --- a/man/man1/acid.1 +++ b/man/man1/acid.1 @@ -26,7 +26,7 @@ acid, acidtypes \- debugger .I prefix ] .I file -... +\&... .\" .PP .\" .B acid .\" .B -l @@ -69,17 +69,9 @@ at startup; see below. .TP .BI -m " machine Assume instructions are for the given CPU type -(one of -.BR 3210 , -.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 +(see +.IR mach (3)) +instead of using the executable header to select the CPU type. .TP .BI -k @@ -100,9 +92,17 @@ Definitions in any file may override previously defined functions. If the function .IR acidinit () is defined, it will be invoked after all modules have been loaded. -See -.IR 2c (1) -for information about creating +Then the function +.IR acidmap () +will be invoked if defined. +.B /usr/local/plan9/acid/port +provides a definition of +.I acidmap +that attaches all the shared libraries being used by the target process +and then runs +.I acidtypes +.RI ( q.v. ) +to create .I acid functions for examining data structures. .SS Language diff --git a/man/man1/acme.1 b/man/man1/acme.1 index 359799bb..6f162731 100644 --- a/man/man1/acme.1 +++ b/man/man1/acme.1 @@ -345,7 +345,7 @@ With no arguments, prints the supplementary list. This command is largely superseded by plumbing (see -.IR plumb (6)). +.IR plumb (7)). .TP .B Kill Send a @@ -355,20 +355,30 @@ note to commands named as arguments. .TP .B Local -When prefixed to a command -run the -command in the same file name space and environment variable group as -.IR acme . -The environment of the command -is restricted but is sufficient to run -.IR bind (1), -.IR 9fs -(see -.IR srv (4)), -.IR import (4), -etc., -and to set environment variables such as -.BR $objtype . +In the Plan 9 +.IR acme , +this prefix causes a command to be run in +.IR acme 's own +file name space and environment variable group. +On Unix this is impossible. +.B Local +is recognized as a prefix, but has no effect on the command being executed. +.\" .TP +.\" .B Local +.\" When prefixed to a command +.\" run the +.\" command in the same file name space and environment variable group as +.\" .IR acme . +.\" The environment of the command +.\" is restricted but is sufficient to run +.\" .IR bind (1), +.\" .IR 9fs +.\" (see +.\" .IR srv (4)), +.\" .IR import (4), +.\" etc., +.\" and to set environment variables such as +.\" .BR $objtype . .TP .B Load Restore the state of @@ -662,9 +672,9 @@ MIPS-specific binaries for applications .SH SOURCE .B /usr/local/plan9/src/cmd/acme .br -.B /acme/bin/source/win +.B /usr/local/plan9/src/cmd/9term/win.c .br -.B /usr/local/plan9/src/cmd/awd.c +.B /usr/local/plan9/bin/awd .SH SEE ALSO .IR acme (4) .br diff --git a/man/man1/ascii.1 b/man/man1/ascii.1 index 05cec0f8..20a4302f 100644 --- a/man/man1/ascii.1 +++ b/man/man1/ascii.1 @@ -91,7 +91,7 @@ control characters or insert newlines. is similar; it converts between .SM UTF and character values from the Unicode Standard (see -.IR utf (6)). +.IR utf (7)). If given a range of hexadecimal numbers, .I unicode prints a table of the specified Unicode characters \(em their values and @@ -157,5 +157,5 @@ table of characters and descriptions. .SH "SEE ALSO" .IR look (1) .IR tcs (1), -.IR utf (6), -.IR font (6) +.IR utf (7), +.IR font (7) diff --git a/man/man1/astro.1 b/man/man1/astro.1 new file mode 100644 index 00000000..e2502f95 --- /dev/null +++ b/man/man1/astro.1 @@ -0,0 +1,122 @@ +.TH ASTRO 1 +.SH NAME +astro \- print astronomical information +.SH SYNOPSIS +.B astro +[ +.B -dlpsatokm +] +[ +.B -c +n +] +[ +.B -C +d +] +[ +.B -e +.I obj1 +.I obj2 +] +.SH DESCRIPTION +.I Astro +reports upcoming celestial events, by default for 24 hours starting now. +The options are: +.TP +.B d +Read the starting date. +A prompt gives the input +format. +.TP +.B l +Read the north latitude, west longitude, and elevation of the observation point. +A prompt gives the input format. +If +.B l +is missing, the initial position is read from the file +.BR /lib/sky/here . +.TP +.B c +Report for +.I n +(default 1) successive days. +.TP +.B C +Used with +.BR -c , +set the interval to +.B d +days (or fractions of days). +.TP +.B e +Report distance between the centers of +objects, in arc seconds, during eclipses or occultations involving +.I obj1 +and +.IR obj2 . +.TP +.B p +Print the positions of objects at the +given time rather than searching for interesting +conjunctions. +For each, the name is followed by +the right ascension (hours, minutes, seconds), +declination (degrees, minutes, seconds), +azimuth (degrees), +elevation (degrees), +and semidiameter (arc seconds). +For the sun and moon, the magnitude is also printed. +The first line of output presents the date and time, +sidereal time, and the latitude, longitude, and elevation. +.TP +.B s +Print output in English words suitable for speech synthesizers. +.TP +.B a +Include a list of artificial earth satellites for interesting events. +(There are no orbital elements for the satellites, so this option +is not usable.) +.TP +.B t +Read +ΔT +from standard input. +ΔT +is the difference between ephemeris and +universal time (seconds) due to the slowing of the earth's rotation. +ΔT +is normally calculated from an empirical formula. +This option is needed only for very accurate timing of +occultations, eclipses, etc. +.TP +.B o +Search for stellar occultations. +.TP +.B k +Print times in local time (`kitchen clock') +as described in the +.B timezone +environment variable. +.TP +.B m +Includes a single comet in the list of objects. +This is modified (in the source) to refer to an approaching comet +but in steady state +usually refers to the last interesting comet (currently Hale-Bopp, C/1995 O1). +.SH FILES +.TF /lib/sky/estartab +.TP +.B /lib/sky/estartab +ecliptic star data +.TP +.B /lib/sky/here +default latitude (N), longitude (W), and elevation (meters) +.SH SOURCE +.B /usr/local/plan9/src/cmd/astro +.SH SEE ALSO +.IR scat (1) +.SH BUGS +The +.B k +option reverts to GMT outside of 1970-2036. diff --git a/man/man1/bc.1 b/man/man1/bc.1 new file mode 100644 index 00000000..9bb0f08e --- /dev/null +++ b/man/man1/bc.1 @@ -0,0 +1,292 @@ +.TH BC 1 +.SH NAME +bc \- arbitrary-precision arithmetic language +.SH SYNOPSIS +.B bc +[ +.B -c +] +[ +.B -l +] +[ +.B -s +] +[ +.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. +The +.B -l +argument stands for the name +of an arbitrary precision math library. +The +.B -s +argument 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 /usr/local/plan9/src/cmd/bc.y +.SH "SEE ALSO" +.IR dc (1), +.IR hoc (1) +.SH BUGS +No +.LR && , +.LR || , +or +.L ! +operators. +.br +A +.L for +statement must have all three +.LR E s. +.br +A +.L quit +is interpreted when read, not when executed. diff --git a/man/man1/bundle.1 b/man/man1/bundle.1 new file mode 100644 index 00000000..c56e9430 --- /dev/null +++ b/man/man1/bundle.1 @@ -0,0 +1,57 @@ +.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 +.I 9ar +(see +.IR 9c (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 /usr/local/plan9/bin/bundle +.SH SEE ALSO +.I 9ar +(in +.IR 9c (1)), +.IR tar (1), +.IR mail (1) +.SH BUGS +.I Bundle +will not create directories and is unsatisfactory for non-text files. +.br +Beware of gift horses. diff --git a/man/man1/cat.1 b/man/man1/cat.1 index 3b24bdde..d2b8d5c0 100644 --- a/man/man1/cat.1 +++ b/man/man1/cat.1 @@ -1,6 +1,6 @@ .TH CAT 1 .SH NAME -cat, read \- catenate files +cat, read, nobs \- catenate files .SH SYNOPSIS .B cat [ @@ -16,6 +16,11 @@ cat, read \- catenate files ] [ .I file ... ] +.br +nobs +[ +.I file ... +] .SH DESCRIPTION .I Cat reads each @@ -57,15 +62,32 @@ causes it to read no more than .I nline lines. .PP -Read always executes a single +.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. +.PP +.I Nobs +copies the named files to +standard output except that it removes all backspace +characters and the characters that precede them. +It is useful to use as +.B $PAGER +with the Unix version of +.IR man (1) +when run inside a +.I win +(see +.IR acme (1)) +window. .SH SOURCE .B /usr/local/plan9/src/cmd/cat.c .br .B /usr/local/plan9/src/cmd/read.c +.br +.B /usr/local/plan9/bin/nobs .SH SEE ALSO .IR cp (1) .SH DIAGNOSTICS diff --git a/man/man1/cleanname.1 b/man/man1/cleanname.1 index d017ce5b..d2191380 100644 --- a/man/man1/cleanname.1 +++ b/man/man1/cleanname.1 @@ -29,4 +29,4 @@ before processing. .SH SOURCE .B /usr/local/plan9/src/cmd/cleanname.c .SH SEE ALSO -.IR cleanname (2). +.IR cleanname (3). diff --git a/man/man1/colors.1 b/man/man1/colors.1 new file mode 100644 index 00000000..ea33e9a5 --- /dev/null +++ b/man/man1/colors.1 @@ -0,0 +1,73 @@ +.TH COLORS 1 +.SH NAME +getmap, colors \- display color map +.SH SYNOPSIS +.PP +.B colors +[ +.B -r +.B -x +] +.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 (7)). +.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 (3). +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 /usr/local/plan9/src/cmd/draw/colors.c +.SH SEE ALSO +.IR color (7) diff --git a/man/man1/core.1 b/man/man1/core.1 new file mode 100644 index 00000000..3c2c0d41 --- /dev/null +++ b/man/man1/core.1 @@ -0,0 +1,46 @@ +.TH CORE 1 +.SH NAME +core \- print information about dead processes +.SH SYNOPSIS +.B core +[ +.I dir +| +.I corefile +]... +.SH DESCRIPTION +.I Core +prints information about dead processes that have +been saved as core dumps. +.PP +Core reads its arguments in order. +If a directory is encountered, +.I core +reads every core file named +.B core.* +or +.B *.core +in that directory. +.PP +For each core file read, +.I core +prints the date and time the core was generated, +the command that generated it, and a short stack trace +at the time of the core dump. +.PP +If no arguments are given, +.I core +searches the directory +.B $COREDIR +for core files; +if +.B $COREDIR +is not set, +.I core +searches the current directory. +.SH SOURCE +.B /usr/local/plan9/src/cmd/core.c +.SH "SEE ALSO +.IR acid (1), +.IR db (1), +.IR core (5) diff --git a/man/man1/crop.1 b/man/man1/crop.1 new file mode 100644 index 00000000..2804ece0 --- /dev/null +++ b/man/man1/crop.1 @@ -0,0 +1,147 @@ +.TH CROP 1 +.SH NAME +crop, iconv \- frame, crop, and convert image +.SH SYNOPSIS +.B crop +[ +.BI -c +.I red +.I green +.I blue +] +[ +.B -i +.I n +| +.B -x +.I dx +| +.B -y +.I dy +| +.B -r +.I minx +.I miny +.I maxx +.I maxy +] +[ +.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 (7) +file (default standard input), crops it, and writes it as a compressed +.IR image (7) +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 (3). +(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 (7)). +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 /usr/local/plan9/src/cmd/draw/crop.c +.SH SEE ALSO +.IR image (7), +.IR color (3) +.SH BUGS +.I Iconv +should be able to do Floyd-Steinberg error diffusion or dithering +when converting to small image depths. diff --git a/man/man1/date.1 b/man/man1/date.1 index cdc02285..45440e63 100644 --- a/man/man1/date.1 +++ b/man/man1/date.1 @@ -8,8 +8,8 @@ date, clock \- date and time ] [ .I seconds ] -.br -.B clock +.\" .br +.\" .B clock .SH DESCRIPTION Print the date, in the format .PP @@ -28,31 +28,31 @@ epoch, 00:00:00 GMT, January 1, 1970. The conversion from Greenwich Mean Time to local time depends on the .B $timezone environment variable; see -.IR ctime (2). +.IR ctime (3). .PP If the optional argument .I seconds is present, it is used as the time to convert rather than the real time. -.SH FILES -.TF /adm/timezone/local -.TP -.B /env/timezone -Current timezone name and adjustments. -.TP -.B /adm/timezone -A directory containing timezone tables. -.TP -.B /adm/timezone/local -Default timezone file, copied by -.IR init (8) -into -.BR /env/timezone . -.PD -.PP -.I Clock -draws a simple analog clock in its window. +.\" .SH FILES +.\" .TF /adm/timezone/local +.\" .TP +.\" .B /env/timezone +.\" Current timezone name and adjustments. +.\" .TP +.\" .B /adm/timezone +.\" A directory containing timezone tables. +.\" .TP +.\" .B /adm/timezone/local +.\" Default timezone file, copied by +.\" .IR init (8) +.\" into +.\" .BR /env/timezone . +.\" .PD +.\" .PP +.\" .I Clock +.\" draws a simple analog clock in its window. .SH SOURCE .B /usr/local/plan9/src/cmd/date.c -.br -.B /usr/local/plan9/src/cmd/clock.c +.\" .br +.\" .B /usr/local/plan9/src/cmd/draw/clock.c diff --git a/man/man1/db.1 b/man/man1/db.1 index 10d38cb2..b8021001 100644 --- a/man/man1/db.1 +++ b/man/man1/db.1 @@ -33,9 +33,7 @@ specifies the memory image of a process. A .I pid gives the id of an executing process to be accessed via -.IR ptrace (2) -or -.IR proc (5). +.IR ptrace (2). A .I corefile specifies the name of a core dump (see @@ -949,7 +947,6 @@ is one the breakpoint will fire. Beware that local variables may be stored in registers; see the BUGS section. .SH "SEE ALSO" -.IR 9nm (1), .IR acid (1) .SH SOURCE .B /usr/local/plan9/src/cmd/db diff --git a/man/man1/deroff.1 b/man/man1/deroff.1 index 2097a80d..18d62280 100644 --- a/man/man1/deroff.1 +++ b/man/man1/deroff.1 @@ -67,7 +67,7 @@ requests. Remove titles, attachments, etc., as well as ordinary .IR troff constructs, from -.IR ms (6) +.IR ms (7) or .I mm documents. @@ -93,7 +93,7 @@ files. .SH SOURCE .B /usr/local/plan9/src/cmd/deroff.c .br -.B /usr/local/plan9/src/cmd/tex/local/delatex.c +.B /usr/local/plan9/src/cmd/delatex.lx .SH "SEE ALSO" .IR troff (1), .IR tex (1), diff --git a/man/man1/dict.1 b/man/man1/dict.1 index 1665ea7c..3c01c71b 100644 --- a/man/man1/dict.1 +++ b/man/man1/dict.1 @@ -1,4 +1,4 @@ -.TH DICT 7 +.TH DICT 1 .SH NAME dict \- dictionary browser .SH SYNOPSIS @@ -46,7 +46,7 @@ Print a pronunciation key. .PD .PP Patterns are regular expressions (see -.IR regexp (6)), +.IR regexp (7)), with an implicit leading .L ^ and trailing @@ -146,18 +146,22 @@ Otherwise, the default command is the previous command. Other files in .BR /lib . .SH "SEE ALSO" -.IR regexp (6) +.IR regexp (7) .SH SOURCE .B /usr/local/plan9/src/cmd/dict .SH BUGS A font with wide coverage of the Unicode Standard should be used for best results. (Try -.BR /lib/font/bit/pelm/unicode.9.font .) -.br +.BR /usr/local/plan9/font/pelm/unicode.9.font .) +.PP If the .I pattern doesn't begin with a few literal characters, matching takes a long time. -.br -The dictionaries are not distributed outside Bell Labs. +.PP +The dictionaries are not distributed outside Bell Labs, +though see +.B /usr/local/plan9/dict/README +for information on using free dictionaries prepared +by Project Gutenberg. diff --git a/man/man1/doctype.1 b/man/man1/doctype.1 new file mode 100644 index 00000000..cb339ae6 --- /dev/null +++ b/man/man1/doctype.1 @@ -0,0 +1,56 @@ +.TH DOCTYPE 1 +.SH NAME +doctype \- intuit command line for formatting a document +.SH SYNOPSIS +.B doctype +[ +.I option ... +] [ +.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 (7) +and +.I mm +macro packages. +.PP +Option +.B -n +invokes +.I nroff +instead of +.IR troff . +Other options are passed to +.IR troff . +.SH EXAMPLES +.TP +.L +eval `{doctype chapter.?} | lp +Typeset files named +.BR chapter.0 , +.BR chapter.1 , +\&... +.SH SOURCE +.B /usr/local/plan9/bin/doctype +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR ms (7), +.IR man (7) +.SH BUGS +In true A.I. style, its best guesses are inspired rather than accurate. diff --git a/man/man1/ed.1 b/man/man1/ed.1 index 7b88f11d..b61972b2 100644 --- a/man/man1/ed.1 +++ b/man/man1/ed.1 @@ -96,7 +96,7 @@ beginning of a line. supports the .I "regular expression" notation described in -.IR regexp (6). +.IR regexp (7). Regular expressions are used in addresses to specify lines and in one command (see @@ -673,7 +673,7 @@ and all characters after the last newline. .SH "SEE ALSO" .IR sam (1), .IR sed (1), -.IR regexp (6) +.IR regexp (7) .SH DIAGNOSTICS .BI ? name for inaccessible file; diff --git a/man/man1/eqn.1 b/man/man1/eqn.1 index 7c917cdb..2d914495 100644 --- a/man/man1/eqn.1 +++ b/man/man1/eqn.1 @@ -316,7 +316,7 @@ when all else fails. .B /sys/lib/troff/font/devutf font descriptions for PostScript .SH SOURCE -.B /sys/src/cmd/eqn +.B /usr/local/plan9/src/cmd/eqn .SH "SEE ALSO" .IR troff (1), .IR tbl (1) diff --git a/man/man1/freq.1 b/man/man1/freq.1 index fd326a25..853e479d 100644 --- a/man/man1/freq.1 +++ b/man/man1/freq.1 @@ -36,5 +36,5 @@ character, respectively. .SH SOURCE .B /usr/local/plan9/src/cmd/freq.c .SH SEE ALSO -.IR utf (6), +.IR utf (7), .IR wc (1) diff --git a/man/man1/fsize.1 b/man/man1/fsize.1 new file mode 100644 index 00000000..cabe7f3d --- /dev/null +++ b/man/man1/fsize.1 @@ -0,0 +1,22 @@ +.TH FSIZE 1 +.SH NAME +fsize, mtime \- print file information +.SH SYNOPSIS +.B fsize +.I file ... +.PP +.B mtime +.I file ... +.SH DESCRIPTION +.I Fsize +prints the name and size of each of the files. +.PP +.I Mtime +prints the name and modification time (in seconds since the epoch) +of each of the files. +.SH SOURCE +.B /usr/local/plan9/src/cmd/fsize.c +.br +.B /usr/local/plan9/src/cmd/mtime.c +.SH BUGS +The output formats of the two programs are different. diff --git a/man/man1/grap.1 b/man/man1/grap.1 index b098f822..8fbfaaaf 100644 --- a/man/man1/grap.1 +++ b/man/man1/grap.1 @@ -404,7 +404,7 @@ copy thru / circle at $1,$2 / .B /sys/lib/grap.defines definitions of standard plotting characters, e.g., bullet .SH SOURCE -.B /sys/src/cmd/grap +.B /usr/local/plan9/src/cmd/grap .SH "SEE ALSO" .IR pic (1), .IR troff (1) diff --git a/man/man1/graph.1 b/man/man1/graph.1 index 4cdc6b24..f105d87d 100644 --- a/man/man1/graph.1 +++ b/man/man1/graph.1 @@ -135,7 +135,7 @@ If a specified lower limit exceeds the upper limit, the axis is reversed. .SH SOURCE -.B /sys/src/cmd/graph +.B /usr/local/plan9/src/cmd/graph .SH "SEE ALSO" .IR plot (1), .IR grap (1) diff --git a/man/man1/grep.1 b/man/man1/grep.1 index e58d0d97..b8cb431c 100644 --- a/man/man1/grep.1 +++ b/man/man1/grep.1 @@ -1,6 +1,6 @@ .TH GREP 1 .SH NAME -grep \- search a file for a pattern +grep, g \- search a file for a pattern .SH SYNOPSIS .B grep [ @@ -10,6 +10,14 @@ grep \- search a file for a pattern [ .I file ... ] +.B g +[ +.I option ... +] +.I pattern +[ +.I file ... +] .SH DESCRIPTION .I Grep\^ searches the input @@ -18,7 +26,7 @@ searches the input for lines that match the .IR pattern , a regular expression as defined in -.IR regexp (6) +.IR regexp (7) with the addition of a newline character as an alternative (substitute for .BR | ) @@ -90,14 +98,26 @@ in single quotes An expression starting with '*' will treat the rest of the expression as literal characters. +.PP +.I G +invokes grep with +.B -n +and forces tagging of output lines by file name. +If no files are listed, it searches all files matching +.IP +.EX +*.C *.b *.c *.h *.m *.cc *.java *.py *.tex *.ms +.EE .SH SOURCE .B /usr/local/plan9/src/cmd/grep +.br +.B /usr/local/plan9/bin/g .SH SEE ALSO .IR ed (1), .IR awk (1), .IR sed (1), .IR sam (1), -.IR regexp (6) +.IR regexp (7) .SH DIAGNOSTICS Exit status is null if any lines are selected, or non-null when no lines are selected or an error occurs. diff --git a/man/man1/gzip.1 b/man/man1/gzip.1 new file mode 100644 index 00000000..58886891 --- /dev/null +++ b/man/man1/gzip.1 @@ -0,0 +1,160 @@ +.TH GZIP 1 +.SH NAME +gzip, gunzip, bzip2, bunzip2, 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 zip +.RB [ -vD [ 1-9 ]] +.RB [ -f +.IR zipfile ] +.I file +.RB [ ... ] +.PP +.B unzip +.RB [ -cistTvD ] +.RB [ -f +.IR zipfile ] +.IR [ 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 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. +.PP +None of these programs removes the original files. +If the process fails, the faulty output files are removed. +.PP +The options are: +.TP 1i +.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 /usr/local/plan9/src/cmd/gzip +.br +.B /usr/local/plan9/src/cmd/bzip2 +.SH SEE ALSO +.IR tar (1), +.IR compress (1) +.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. diff --git a/man/man1/join.1 b/man/man1/join.1 index 2cf079f2..841d077c 100644 --- a/man/man1/join.1 +++ b/man/man1/join.1 @@ -106,21 +106,21 @@ in a line is significant. .SH EXAMPLES .TP .L -sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +sort /etc/passwd | join -t: -1 1 -a 1 -e "" - bdays Add birthdays to the -.B /adm/users +.B /etc/passwd file, leaving unknown birthdays empty. The layout of .B /adm/users is given in -.IR users (6); +.IR passwd (5); .B bdays contains sorted lines like .LR "ken:Feb\ 4,\ 1953" . .TP .L -tr : ' ' temp +tr : ' ' temp .br .ns .TP @@ -145,4 +145,3 @@ the sequence is that of .BI -k y , y\f1. .br One of the files must be randomly accessible. - diff --git a/man/man1/jpg.1 b/man/man1/jpg.1 new file mode 100644 index 00000000..b81490b2 --- /dev/null +++ b/man/man1/jpg.1 @@ -0,0 +1,243 @@ +.TH JPG 1 +.SH NAME +jpg, gif, png, ppm, bmp, 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 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 , +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 (7), +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 represeted 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), +write any icon's mask as a Plan 9 image (\fIwidth\fBx\fIheight\fB.mask), +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 /usr/local/plan9/src/cmd/jpg +.SH "SEE ALSO" +.IR page (1), +.IR image (7). +.SH BUGS +Writing an animated GIF using +.I togif +is a clumsy undertaking. diff --git a/man/man1/kill.1 b/man/man1/kill.1 new file mode 100644 index 00000000..c7d5ff92 --- /dev/null +++ b/man/man1/kill.1 @@ -0,0 +1,69 @@ +.TH KILL 1 +.SH NAME +kill, slay, start, stop \- print commands to manipulate processes +.SH SYNOPSIS +.B kill +.I name ... +.PP +.B slay +.I name ... +.PP +.B start +.I name ... +.PP +.B stop +.I name ... +.PP +.B broke +[ +.I user +] +.SH DESCRIPTION +.I Kill +prints commands that will cause all processes with +.I name +and owned by the current user to be terminated. +Each command is commented with an output line from +.IR ps (1) +describing the process that would be killed. +Use the +.B send +command of +.IR 9term (1), +or pipe the output of +.I kill +into +.IR rc (1) +or +.IR sh (1) +to execute the commands. +.PP +.I Kill +suggests sending a Unix +.B TERM +signal to the process; +sending a +.B KILL +signal is a surer, if heavy handed, kill, +but is necessary if the offending process is +ignoring signals. +The +.I slay +command prints commands to do this. +.PP +.I Stop +prints commands to pause execution of processes +by sending them the +.B STOP +signal. +.PP +.I Start +prints commands to restart stopped processes by sending them +the +.B CONT +signal. +.SH SOURCE +.B /usr/local/plan9/bin +.SH "SEE ALSO" +.IR ps (1), +.IR notify (3) diff --git a/man/man1/label.1 b/man/man1/label.1 new file mode 100644 index 00000000..0caf8d5c --- /dev/null +++ b/man/man1/label.1 @@ -0,0 +1,71 @@ +.TH LABEL 1 +.SH NAME +label, awd \- set window label +.SH SYNOPSIS +.B label +.I string +.br +.B awd +.SH DESCRIPTION +.I Label +sets the label of the current +.I win +(see +.IR acme (1)) +or X terminal window +.RI ( e.g., +.IR 9term (1) +or +.IR xterm (1)) +by echoing a special control sequence to standard output. +.PP +.I Acme +and +.I 9term +windows assume the label is a directory name. +When unrooted file names are plumbed in the window, +they are evaluated relative to the directory named in the label. +.SH EXAMPLE +One can use the following +.IR sh (1) +function to keep the label up-to-date in response to +.I cd +commands: +.IP +.EX +_cd () { + \ecd "$@" && + case $- in + *i*) + awd + esac +} +alias cd=_cd +cd . +.EE +.PP +.IR Rc (1) +installs a similar +.B fn +.B cd +at startup if there is not already a function named +.BR cd : +.IP +.EX +fn cd { + builtin cd $1 && flag i && awd +} +.EE +.SH SOURCE +.B /usr/local/plan9/bin/label +.br +.B /usr/local/plan9/bin/awd +.SH BUGS +.I Awd +is also documented in +.IR acme (1). +.PP +.I Awd +does not append the +.BI - label +suffix that it does on Plan 9. diff --git a/man/man1/lex.1 b/man/man1/lex.1 new file mode 100644 index 00000000..7021e8d7 --- /dev/null +++ b/man/man1/lex.1 @@ -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 /usr/local/plan9/src/cmd/lex +.SH BUGS +Cannot handle +.SM UTF. +.br +The asteroid to kill this dinosaur is still in orbit. diff --git a/man/man1/look.1 b/man/man1/look.1 new file mode 100644 index 00000000..e06e8420 --- /dev/null +++ b/man/man1/look.1 @@ -0,0 +1,86 @@ +.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 /usr/local/plan9/src/cmd/look.c +.SH "SEE ALSO" +.IR sort (1), +.IR grep (1) +.SH DIAGNOSTICS +The exit status is +.B \&"not found" +if no match is found, and +.B \&"no dictionary" +if +.I file +or the default dictionary cannot be opened. + diff --git a/man/man1/ls.1 b/man/man1/ls.1 index 35981ab2..4cea25bc 100644 --- a/man/man1/ls.1 +++ b/man/man1/ls.1 @@ -10,7 +10,7 @@ ls, lc \- list contents of directory .PP .B lc [ -.B -dlmnqrstuFQ +.B -dlmnpqrstuFQ ] .I name ... .SH DESCRIPTION @@ -60,7 +60,7 @@ Print only the final path element of each file name. List the .I qid (see -.IR stat (2)) +.IR stat (3)) of each file; the printed fields are in the order path, version, and type. .TP @@ -157,6 +157,6 @@ if none of the above permissions is granted. .br .B /usr/local/plan9/bin/lc .SH SEE ALSO -.IR stat (2) +.IR stat (3) .IR mc (1) diff --git a/man/man1/man.1 b/man/man1/man.1 new file mode 100644 index 00000000..7b865842 --- /dev/null +++ b/man/man1/man.1 @@ -0,0 +1,105 @@ +.TH MAN 1 +.SH NAME +man, lookman \- print or find pages of this manual +.SH SYNOPSIS +.B man +[ +.I option ... +] +[ +.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 -p +Run +.IR proof (1) +on the specified man pages. +.TP +.B -P +Run +.IR page (1) +on the specified man pages. +.TP +.B -t +Run +.I troff +and send its output +to standard output. +.TP +.B -n +(Default) +Print the pages on the standard output using +.IR nroff . +.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 +.TF /sys/lib/man/lookman/index +.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 /usr/local/plan9/bin/9man +.br +.B /usr/local/plan9/bin/lookman +.SH "SEE ALSO" +.IR proof (1) +.SH BUGS +The manual was intended to be typeset; some detail is sacrificed on text terminals. +.br +There is no automatic mechanism to keep the indices up to date. +.br +Except for special cases, it doesn't recognize things that should be run through +.I tbl +and/or +.IR eqn . diff --git a/man/man1/map.1 b/man/man1/map.1 new file mode 100644 index 00000000..cc73075e --- /dev/null +++ b/man/man1/map.1 @@ -0,0 +1,675 @@ +.TH MAP 1 +.SH NAME +map, mapdemo \- draw maps on various projections +.SH SYNOPSIS +.B map +.I projection +[ +.I option ... +] +.PP +.B mapdemo +.PP +.SH DESCRIPTION +.I Map +prepares on the standard output a +map suitable for display by any +plotting filter described in +.IR plot (1). +A menu of projections is produced in response to an unknown +.IR projection . +.I Mapdemo +is a short course in mapping. +.PP +The default data for +.I map +are world shorelines. +Option +.B -f +accesses more detailed data +classified by feature. +.TP +.BR -f " [ \fIfeature\fR ... ]" +Features are ranked 1 (default) to 4 from major to minor. +Higher-numbered ranks include all lower-numbered ones. +Features are +.RS +.TF country[1-3] +.TP +.BR shore [ 1 - 4 ] +seacoasts, lakes, and islands; option +.B -f +always shows +.B shore1 +.TP +.BR ilake [ 1 - 2 ] +intermittent lakes +.TP +.BR river [ 1 - 4 ] +rivers +.TP +.BR iriver [ 1 - 3 ] +intermittent rivers +.TP +.BR canal [ 1 - 3 ] +.BR 3 =irrigation +canals +.TP +.BR glacier +.TP +.BR iceshelf [ 12 ] +.TP +.BR reef +.TP +.BR saltpan [ 12 ] +.TP +.BR country [ 1 - 3 ] +.BR 2 =disputed +boundaries, +.BR 3 =indefinite +boundaries +.TP +.BR state +states and provinces (US and Canada only) +.PD +.RE +.PP +In other options +coordinates are in degrees, with north latitude +and west longitude counted as positive. +.TP 0 +.BI -l " S N E W" +Set the southern and northern latitude +and the eastern and western longitude limits. +Missing arguments are filled out from the list +\-90, 90, \-180, 180, +or lesser limits suitable to the +projection at hand. +.TP +.BI -k " S N E W +Set the scale as if for a map with limits +.B -l +.I "S N E W"\f1. +Do not consider any +.B -l +or +.B -w +option in setting scale. +.TP +.BI -o " lat lon rot" +Orient the map in a nonstandard position. +Imagine a transparent gridded sphere around the globe. +Turn the overlay about the North Pole +so that the Prime Meridian (longitude 0) +of the overlay coincides with meridian +.I lon +on the globe. +Then tilt the North Pole of the +overlay along its Prime Meridian to latitude +.I lat +on the globe. +Finally again turn the +overlay about its `North Pole' so +that its Prime Meridian coincides with the previous position +of meridian +.IR rot . +Project the map in +the standard form appropriate to the overlay, but presenting +information from the underlying globe. +Missing arguments are filled out from the list +90, 0, 0. +In the absence of +.BR - o , +the orientation is 90, 0, +.IR m , +where +.I m +is the middle of the longitude range. +.TP +.BI -w " S N E W" +Window the map by the specified latitudes +and longitudes in the tilted, rotated coordinate system. +Missing arguments are filled out from the list \-90, 90, \-180, 180. +(It is wise to give an encompassing +.B -l +option with +.BR -w . +Otherwise for small windows computing time +varies inversely with area!) +.TP +.BI -d " n" +For speed, plot only every +.IR n th +point. +.TP +.B -r +Reverse left and right +(good for star charts and inside-out views). +.ns +.TP +.B -v +Verso. +Switch to a normally suppressed sheet of the map, such as the +back side of the earth in orthographic projection. +.TP +.B -s1 +.br +.ns +.TP +.B -s2 +Superpose; outputs for a +.B -s1 +map (no closing) and a +.B -s2 +map (no opening) may be concatenated. +.TP +.BI -g " dlat dlon res" +Grid spacings are +.IR dlat , +.IR dlon . +Zero spacing means no grid. +Missing +.I dlat +is taken to be zero. +Missing +.I dlon +is taken the same as +.IR dlat . +Grid lines are drawn to a resolution of +.I res +(2° or less by default). +In the absence of +.BR - g , +grid spacing is 10°. +.TP +.BI -p " lat lon extent" +Position the point +.I lat, lon +at the center of the plotting area. +Scale the map so that the height (and width) of the +nominal plotting area is +.I extent +times the size of one degree of latitude +at the center. +By default maps are scaled and positioned +to fit within the plotting area. +An +.I extent +overrides option +.BR -k . +.TP +.BI -c " x y rot" +After all other positioning and scaling operations +have been performed, rotate the image +.I rot +degrees counterclockwise about the center +and move the center to position +.IR x , +.IR y , +where the nominal plotting area is +.RI \-1≤ x ≤1, +.RI \-1≤ y ≤1. +Missing arguments are taken to be 0. +.BR -x +Allow the map to extend outside the nominal plotting area. +.TP +.BR -m " [ \fIfile\fP ... ]" +Use +map data from named files. +If no files are named, omit map data. +Names that do not exist as pathnames are looked up in +a standard directory, which contains, in addition to the +data for +.BR -f , +.RS +.LP +.TF counties +.TP +.B world +World Data Bank I (default) +.TP +.B states +US map from Census Bureau +.TP +.B counties +US map from Census Bureau +.PD +.RE +.IP +The environment variables +.B MAP +and +.B MAPDIR +change the default +map and default directory. +.TP +.BI -b " \fR[\fPlat0 lon0 lat1 lon1\fR... ]" +Suppress the drawing of the normal boundary +(defined by options +.BR -l +and +.BR -w ). +Coordinates, if present, define the vertices of a +polygon to which the map is clipped. +If only two vertices are given, they are taken to be the +diagonal of a rectangle. +To draw the polygon, give its vertices as a +.B -u +track. +.TP +.BI -t " file ..." +The +.I files +contain lists of points, +given as latitude-longitude pairs in degrees. +If the first file is named +.LR - , +the standard input is taken instead. +The points of each list are plotted as connected `tracks'. +.IP +Points in a track file may be followed by label strings. +A label breaks the track. +A label may be prefixed by +\fL"\fR, +.LR : , +or +.L ! +and is terminated by a newline. +An unprefixed string or a string prefixed with +.L +" +is displayed at the designated point. +The first word of a +.L : +or +.L ! +string names a special symbol (see option +.BR -y ). +An optional numerical second word is a scale factor +for the size of the symbol, 1 by default. +A +.L : +symbol is aligned with its top to the north; a +.L ! +symbol is aligned vertically on the page. +.TP +.BI -u " file ..." +Same as +.BR -t , +except the tracks are +unbroken lines. +.RB ( -t +tracks appear as dot-dashed lines if the plotting filter supports them.) +.TP +.BI -y " file +The +.I file +contains +.IR plot (7)-style +data for +.L : +or +.L ! +labels in +.B -t +or +.B -u +files. +Each symbol is defined by a comment +.BI : name +then a sequence of +.L m +and +.L v +commands. +Coordinates (0,0) fall on the plotting point. +Default scaling is as if the nominal plotting range were +.LR "ra -1 -1 1 1" ; +.L ra +commands in +.I file +change the scaling. +.SS Projections +Equatorial projections centered on the Prime Meridian +(longitude 0). +Parallels are straight horizontal lines. +.PP +.PD 0 +.TP 1.5i +.B mercator +equally spaced straight meridians, conformal, +straight compass courses +.TP +.B sinusoidal +equally spaced parallels, +equal-area, same as +.LR "bonne 0" . +.TP +.BI cylequalarea " lat0" +equally spaced straight meridians, equal-area, +true scale on +.I lat0 +.TP +.B cylindrical +central projection on tangent cylinder +.TP +.BI rectangular " lat0" +equally spaced parallels, equally spaced straight meridians, true scale on +.I lat0 +.TP +.BI gall " lat0" +parallels spaced stereographically on prime meridian, equally spaced straight +meridians, true scale on +.I lat0 +.TP +.B mollweide +(homalographic) equal-area, hemisphere is a circle +.br +.B gilbert() +sphere conformally mapped on hemisphere and viewed orthographically +.TP +.B gilbert +globe mapped conformally on hemisphere, viewed orthographically +.PD +.PP +Azimuthal projections centered on the North Pole. +Parallels are concentric circles. +Meridians are equally spaced radial lines. +.PP +.PD 0 +.TP 1.5i +.B azequidistant +equally spaced parallels, +true distances from pole +.TP +.B azequalarea +equal-area +.TP +.B gnomonic +central projection on tangent plane, +straight great circles +.TP +.BI perspective " dist" +viewed along earth's axis +.I dist +earth radii from center of earth +.TP +.B orthographic +viewed from infinity +.TP +.B stereographic +conformal, projected from opposite pole +.TP +.B laue +.IR radius " = tan(2\(mu" colatitude ), +used in X-ray crystallography +.TP +.BI fisheye " n" +stereographic seen from just inside medium with refractive index +.I n +.TP +.BI newyorker " r" +.IR radius " = log(" colatitude / r ): +.I New Yorker +map from viewing pedestal of radius +.I r +degrees +.PD +.PP +Polar conic projections symmetric about the Prime Meridian. +Parallels are segments of concentric circles. +Except in the Bonne projection, +meridians are equally spaced radial +lines orthogonal to the parallels. +.PP +.PD 0 +.TP 1.5i +.BI conic " lat0" +central projection on cone tangent at +.I lat0 +.TP +.BI simpleconic " lat0 lat1" +equally spaced parallels, true scale on +.I lat0 +and +.I lat1 +.TP +.BI lambert " lat0 lat1" +conformal, true scale on +.I lat0 +and +.I lat1 +.TP +.BI albers " lat0 lat1" +equal-area, true scale on +.I lat0 +and +.I lat1 +.TP +.BI bonne " lat0" +equally spaced parallels, equal-area, +parallel +.I lat0 +developed from tangent cone +.PD +.PP +Projections with bilateral symmetry about +the Prime Meridian +and the equator. +.PP +.PD 0 +.TP 1.5i +.B polyconic +parallels developed from tangent cones, +equally spaced along Prime Meridian +.TP +.B aitoff +equal-area projection of globe onto 2-to-1 +ellipse, based on +.I azequalarea +.TP +.B lagrange +conformal, maps whole sphere into a circle +.TP +.BI bicentric " lon0" +points plotted at true azimuth from two +centers on the equator at longitudes +.IR ±lon0 , +great circles are straight lines +(a stretched +.IR gnomonic +) +.TP +.BI elliptic " lon0" +points plotted at true distance from +two centers on the equator at longitudes +.I ±lon0 +.TP +.B globular +hemisphere is circle, +circular arc meridians equally spaced on equator, +circular arc parallels equally spaced on 0- and 90-degree meridians +.TP +.B vandergrinten +sphere is circle, +meridians as in +.IR globular , +circular arc parallels resemble +.I mercator +.PD +.PP +Doubly periodic conformal projections. +.PP +.TP 1.5i +.B guyou +W and E hemispheres are square +.PD 0 +.TP +.B square +world is square with Poles +at diagonally opposite corners +.TP +.B tetra +map on tetrahedron with edge +tangent to Prime Meridian at S Pole, +unfolded into equilateral triangle +.TP +.B hex +world is hexagon centered +on N Pole, N and S hemispheres are equilateral +triangles +.PD +.PP +Miscellaneous projections. +.PP +.PD 0 +.TP 1.5i +.BI harrison " dist angle" +oblique perspective from above the North Pole, +.I dist +earth radii from center of earth, looking +along the Date Line +.I angle +degrees off vertical +.TP +.BI trapezoidal " lat0 lat1" +equally spaced parallels, +straight meridians equally spaced along parallels, +true scale at +.I lat0 +and +.I lat1 +on Prime Meridian +.PD +.br +.B lune(lat,angle) +conformal, polar cap above latitude +.I lat +maps to convex lune with given +.I angle +at 90\(deE and 90\(deW +.PP +Retroazimuthal projections. +At every point the angle between vertical and a straight line to +`Mecca', latitude +.I lat0 +on the prime meridian, +is the true bearing of Mecca. +.PP +.PD 0 +.TP 1.5i +.BI mecca " lat0" +equally spaced vertical meridians +.TP +.BI homing " lat0" +distances to Mecca are true +.PD +.PP +Maps based on the spheroid. +Of geodetic quality, these projections do not make sense +for tilted orientations. +For descriptions, see corresponding maps above. +.PP +.PD 0 +.TP 1.5i +.B sp_mercator +.TP +.BI sp_albers " lat0 lat1" +.SH EXAMPLES +.TP +.L +map perspective 1.025 -o 40.75 74 +A view looking down on New York from 100 miles +(0.025 of the 4000-mile earth radius) up. +The job can be done faster by limiting the map so as not to `plot' +the invisible part of the world: +.LR "map perspective 1.025 -o 40.75 74 -l 20 60 30 100". +A circular border can be forced by adding option +.LR "-w 77.33" . +(Latitude 77.33° falls just inside a polar cap of +opening angle arccos(1/1.025) = 12.6804°.) +.TP +.L +map mercator -o 49.25 -106 180 +An `equatorial' map of the earth +centered on New York. +The pole of the map is placed 90\(de away (40.75+49.25=90) +on the +other side of the earth. +A 180° twist around the pole of the map arranges that the +`Prime Meridian' of the map runs from the pole of the +map over the North Pole to New York +instead of down the back side of the earth. +The same effect can be had from +.L +map mercator -o 130.75 74 +.TP +.L +map albers 28 45 -l 20 50 60 130 -m states +A customary curved-latitude map of the United States. +.TP +.L +map harrison 2 30 -l -90 90 120 240 -o 90 0 0 +A fan view covering 60° on either +side of the Date Line, as seen from one earth radius +above the North Pole gazing at the +earth's limb, which is 30° off vertical. +The +.B -o +option overrides the default +.BR "-o 90 0 180" , +which would rotate +the scene to behind the observer. +.SH FILES +.TF /lib/map/[1-4]?? +.TP +.B /lib/map/[1-4]?? +World Data Bank II, for +.B -f +.TP +.B /lib/map/* +maps for +.B -m +.TP +.B /lib/map/*.x +map indexes +.TP +.B /bin/aux/mapd +Map driver program +.SH SOURCE +.B /usr/local/plan9/src/cmd/map +.SH "SEE ALSO" +.IR map (7), +.IR plot (1) +.SH DIAGNOSTICS +`Map seems to be empty'\(ema coarse survey found +zero extent within the +.B -l +and +.BR -w +bounds; for maps of limited extent +the grid resolution, +.IR res , +or the limits may have to be refined. +.SH BUGS +Windows (option +.BR -w ) +cannot cross the Date Line. +No borders appear along edges arising from +visibility limits. +Segments that cross a border are dropped, not clipped. +Excessively large scale or +.B -d +setting may cause long line segments to be dropped. +.I Map +tries to draw grid lines dotted and +.B -t +tracks dot-dashed. +As very few plotting filters properly support +curved textured lines, these lines are likely to +appear solid. +The west-longitude-positive convention +betrays Yankee chauvinism. +.I Gilbert +should be a map from sphere to sphere, independent of +the mapping from sphere to plane. diff --git a/man/man1/mc.1 b/man/man1/mc.1 index 1618befc..ac535204 100644 --- a/man/man1/mc.1 +++ b/man/man1/mc.1 @@ -18,7 +18,10 @@ splits the input into as many columns as will fit in .I N print positions. If run in a -.IR rio (1) +.IR 9term (1), +.IR xterm (1), +or +.IR acme (1) window, the default .I N is the number of blanks that will fit across the window; @@ -31,9 +34,12 @@ each input line ending in a colon .L : is printed separately. .SH SOURCE -.B /usr/local/plan9/src/cmd/mc.c +.B /usr/local/plan9/src/cmd/draw/mc.c .SH "SEE ALSO" -.IR rio (1), +.IR 9term (1), +.IR acme (1), +.IR acme (4), +.IR xterm (1), .IR pr (1), .I lc in diff --git a/man/man1/mk.1 b/man/man1/mk.1 new file mode 100644 index 00000000..59b1d0ea --- /dev/null +++ b/man/man1/mk.1 @@ -0,0 +1,682 @@ +.TH MK 1 +.de EX +.nf +.ft B +.. +.de EE +.fi +.ft R +.. +.de LR +.if t .BR \\$1 \\$2 +.if n .RB ` \\$1 '\\$2 +.. +.de L +.nh +.if t .B \\$1 +.if n .RB ` \\$1 ' +.. +.SH NAME +mk, membername \- maintain (make) related files +.SH SYNOPSIS +.B mk +[ +.B -f +.I mkfile +] ... +[ +.I option ... +] +[ +.I target ... +] +.PP +.B membername +.IR lib ( object ) +\&... +.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 sh (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; +Some operating systems, e.g., Plan 9, set +.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 +.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 shell +script. +Each line of the recipe must begin with white space. +A rule takes the form +.IP +.EX +target: prereq1 prereq2 + \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 9c (1) +might be: +.IP +.EX +%: %.c + 9c -c $stem.c + 9l -o $stem $stem.o +.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 sh . +References to variables are replaced by the variables' values. +Special characters may be quoted using single quotes +.BR \&'' +as in +.IR sh (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 +shell +environment variables. +A legal reference of the form +.B $OBJ +or +.B ${name} +is expanded as in +.IR sh (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. +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. +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 +Dynamic information may be included in the mkfile by using a line of the form +.IP +\fR<|\fIcommand\fR \fIargs\fR +.LP +This runs the command +.I command +with the given arguments +.I args +and pipes its standard output to +.I mk +to be included as part of the mkfile. For instance, the Inferno kernels +use this technique +to run a shell command with an awk script and a configuration +file as arguments in order for +the +.I awk +script to process the file and output a set of variables and their values. +.SS Execution +.PP +During execution, +.I mk +determines which targets must be updated, and in what order, +to build the +.I names +specified on the command line. +It then runs the associated recipes. +.PP +A target is considered up to date if it has no prerequisites or +if all its prerequisites are up to date and it is newer +than all its prerequisites. +Once the recipe for a target has executed, the target is +considered up to date. +.PP +The date stamp +used to determine if a target is up to date is computed +differently for different types of targets. +If a target is +.I virtual +(the target of a rule with the +.B V +attribute), +its date stamp is initially zero; when the target is +updated the date stamp is set to +the most recent date stamp of its prerequisites. +Otherwise, if a target does not exist as a file, +its date stamp is set to the most recent date stamp of its prerequisites, +or zero if it has no prerequisites. +Otherwise, the target is the name of a file and +the target's date stamp is always that file's modification date. +The date stamp is computed when the target is needed in +the execution of a rule; it is not a static value. +.PP +Nonexistent targets that have prerequisites +and are themselves prerequisites are treated specially. +Such a target +.I t +is given the date stamp of its most recent prerequisite +and if this causes all the targets which have +.I t +as a prerequisite to be up to date, +.I t +is considered up to date. +Otherwise, +.I t +is made in the normal fashion. +The +.B -i +flag overrides this special treatment. +.PP +Files may be made in any order that respects +the preceding restrictions. +.PP +A recipe is executed by supplying the recipe as standard input to +the command +.BR /bin/sh . +(Note that unlike +.IR make , +.I mk +feeds the entire recipe to the shell rather than running each line +of the recipe separately.) +The environment is augmented by the following variables: +.TP 14 +.B $alltarget +all the targets of this rule. +.TP +.B $newprereq +the prerequisites that caused this rule to execute. +.TP +.B $newmember +the prerequisites that are members of an aggregate +that caused this rule to execute. +When the prerequisites of a rule are members of an +aggregate, +.B $newprereq +contains the name of the aggregate and out of date +members, while +.B $newmember +contains only the name of the members. +.TP +.B $nproc +the process slot for this recipe. +It satisfies +.RB 0≤ $nproc < $NPROC . +.TP +.B $pid +the process id for the +.I mk +executing the recipe. +.TP +.B $prereq +all the prerequisites for this rule. +.TP +.B $stem +if this is a meta-rule, +.B $stem +is the string that matched +.B % +or +.BR & . +Otherwise, it is empty. +For regular expression meta-rules (see below), the variables +.LR stem0 ", ...," +.L stem9 +are set to the corresponding subexpressions. +.TP +.B $target +the targets for this rule that need to be remade. +.PP +These variables are available only during the execution of a recipe, +not while evaluating the +.IR mkfile . +.PP +Unless the rule has the +.B Q +attribute, +the recipe is printed prior to execution +with recognizable environment variables expanded. +Commands returning error status +cause +.I mk +to terminate. +.PP +Recipes and backquoted +.B rc +commands in places such as assignments +execute in a copy of +.I mk's +environment; changes they make to +environment variables are not visible from +.IR mk . +.PP +Variable substitution in a rule is done when +the rule is read; variable substitution in the recipe is done +when the recipe is executed. For example: +.IP +.EX +bar=a.c +foo: $bar + $CC -o foo $bar +bar=b.c +.EE +.PP +will compile +.B b.c +into +.BR foo , +if +.B a.c +is newer than +.BR foo . +.SS Aggregates +Names of the form +.IR a ( b ) +refer to member +.I b +of the aggregate +.IR a . +Currently, the only aggregates supported are +.I 9ar +(see +.IR 9c (1)) +archives. +.PP +.I Membername +echoes just the member names of a list of aggregate names. +It is useful in recipes like: +.EX +OFILES=a.o b.o +libc.a(%):N: % +libc.a: ${OFILES:%=libc.a(%)} + 9ar rvc libc.a `membername $newprereq` +.EE +which re-archives only the new object files. +.SS Attributes +The colon separating the target from the prerequisites +may be +immediately followed by +.I attributes +and another colon. +The attributes are: +.TP +.B D +If the recipe exits with a non-null status, the target is deleted. +.TP +.B E +Continue execution if the recipe draws errors. +.TP +.B N +If there is no recipe, the target has its time updated. +.TP +.B n +The rule is a meta-rule that cannot be a target of a virtual rule. +Only files match the pattern in the target. +.TP +.B P +The characters after the +.B P +until the terminating +.B : +are taken as a program name. +It will be invoked as +.B "sh -c prog 'arg1' 'arg2'" +and should return a zero exit status +if and only if arg1 is up to date with respect to arg2. +Date stamps are still propagated in the normal way. +.TP +.B Q +The recipe is not printed prior to execution. +.TP +.B R +The rule is a meta-rule using regular expressions. +In the rule, +.B % +has no special meaning. +The target is interpreted as a regular expression as defined in +.IR regexp (7). +The prerequisites may contain references +to subexpressions in form +.BI \e n\f1, +as in the substitute command of +.IR sed (1). +.TP +.B U +The targets are considered to have been updated +even if the recipe did not do so. +.TP +.B V +The targets of this rule are marked as virtual. +They are distinct from files of the same name. +.PD +.SH EXAMPLES +A simple mkfile to compile a program: +.IP +.EX +.ta 8n +8n +8n +8n +8n +8n +8n +[ fd0 =] @@ -542,7 +542,7 @@ function definition. A function with a special name will be called when .I rc receives a corresponding note; see -.IR notify (2). +.IR notify (3). The valid note names (and corresponding notes) are .B sighup .RB ( hangup ), @@ -757,10 +757,7 @@ command is executed, so they need not be enclosed in quotation marks. The .I environment is a list of strings made available to executing binaries by the -.B env -device -(see -.IR env (3)). +kernel. .I Rc creates an environment entry for each variable whose value is non-empty, and for each function. @@ -768,7 +765,7 @@ 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 +are separated by SOH .RB ( '\e001' ) characters. The string for a function is just the @@ -824,12 +821,23 @@ for the .B . command. If not set in the environment, it is initialized by +parsing the +.B $PATH +variable +(as in +.IR sh (1)) +or by .BR "path=(.\ /bin)" . -Its use is discouraged; instead use -.IR bind (1) -to build a -.B /bin -containing what's needed. +The variables +.B $path +and +.B $PATH +are maintained together: changes to one will be reflected in the other. +.\" 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 diff --git a/man/man1/rio.1 b/man/man1/rio.1 index 9af90e81..4e30e587 100644 --- a/man/man1/rio.1 +++ b/man/man1/rio.1 @@ -1,54 +1,101 @@ -.if t .ds 85 8\(12 -.if n .ds 85 8-1/2 .TH RIO 1 .SH NAME rio \- rio-like Window Manager for X .SH SYNOPSIS .B rio [ -.B \-grey -] [ -.B \-version -] [ .B \-font -.I fname -] [ +.I fontname +] +[ +.B \-grey +] +[ +.B \-s +] +[ .B \-term .I termprog -] [ -.BR exit | restart +] +[ +.B \-version +] +[ +.B \-virtuals +.I num +] +[ +.B exit +| +.B restart ] .SH DESCRIPTION +.if t .ds 85 8\(12 +.if n .ds 85 8-1/2 .I Rio is a window manager for X which attempts to emulate the window management policies of Plan 9's .I rio window manager. +Rio is derived from David Hogan's \*(85. .PP The .B \-grey -option makes the background light grey, as does \*(85. -Use this option for maximum authenticity. +option makes the background stippled grey, the default X11 background, +instead of solid grey, the Plan 9 background. +.PP +The .B \-font -.I fname +option sets the font in .IR rio 's menu to .IR fname , overriding the default. +Unlike the other programs in the Plan 9 ports, rio expects this +font to be an X11 font rather than a Plan 9 font. +.PP +The .B \-term -.I termprog +option specifies an alternative program to run when the .I New menu item is selected. +The default is to try +.IR 9term (1) +and then to fall back to +.IR xterm (1). +The +.B \-s +option causes +.I rio +to add +.B -s +to +.IR 9term 's +command-line, starting the window in scrolling mode. +.PP +The .B \-version +option prints the current version on standard error, then exits. .PP -To make +The +.B \-virtuals +option sets the number of virtual screens (the default is 1, +and the maximum is 12). +.PP +If the argument +.B exit +or +.B restart +is given, +it is sent to an already-running +.IR rio , +causing the extant .I rio -exit, you have to run -.B "rio exit" -on the command line. There is no ``exit'' menu item. +to exit or restart. +.SS Using rio .PP One window is .IR current , @@ -130,7 +177,16 @@ 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 +.PP +When the mouse cursor points to the background area +and +.I rio +has been started with multiple virtual screens using the +.B \-virtuals +option, +clicking button 2 brings up a menu to select a virtual screen to view. +Scrolling the mouse wheel while the cursor points at the background +will cycle through the virtual screens. .SH BUGS In Plan 9's @@ -154,4 +210,4 @@ starts a particular program.) There is a currently a compiled-in limit of 128 hidden windows. .SH "SEE ALSO" .IR 9term (1), -.IR xterm (1). +.IR xterm (1) diff --git a/man/man1/rm.1 b/man/man1/rm.1 index 97893960..a2ab0d1c 100644 --- a/man/man1/rm.1 +++ b/man/man1/rm.1 @@ -25,4 +25,4 @@ and the directory itself. .SH SOURCE .B /usr/local/plan9/src/cmd/rm.c .SH "SEE ALSO" -.IR remove (2) +.IR remove (3) diff --git a/man/man1/sam.1 b/man/man1/sam.1 index b4194b4b..e2085ad7 100644 --- a/man/man1/sam.1 +++ b/man/man1/sam.1 @@ -1,7 +1,7 @@ .TH SAM 1 .ds a \fR*\ \fP .SH NAME -sam, B, sam.save \- screen editor with structural regular expressions +sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions .SH SYNOPSIS .B sam [ @@ -17,10 +17,8 @@ sam, B, sam.save \- screen editor with structural regular expressions .B sam.save .PP .B B -[ -.BI -nnnn -] -.I file ... +.IB file \fR[\fP: line \fR] +\&... .SH DESCRIPTION .I Sam is a multi-file editor. @@ -62,7 +60,7 @@ for debugging. .PD .SS Regular expressions Regular expressions are as in -.IR regexp (6) +.IR regexp (7) with the addition of .BR \en to represent newlines. @@ -791,7 +789,7 @@ 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)). +.IR plumb (7)). .TP .B look Search forward for the next occurrence of the literal text in dot. @@ -838,6 +836,20 @@ 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). +.PP +.I E +is a shell-level command that can be used as +.B $EDITOR +in a Unix environment. +It runs +.I B +on +.I file +and then waits to exit until +.I file +is changed, which is taken as a signal that +.I file +is done being edited. .SS Abnormal termination If .I sam @@ -879,7 +891,7 @@ source for the separate terminal part .IR sed (1), .IR grep (1), .IR rio (1), -.IR regexp (6). +.IR regexp (7). .PP Rob Pike, ``The text editor sam''. diff --git a/man/man1/scat.1 b/man/man1/scat.1 index d9bf8db8..8840c1dc 100644 --- a/man/man1/scat.1 +++ b/man/man1/scat.1 @@ -1,4 +1,4 @@ -.TH SCAT 7 +.TH SCAT 1 .SH NAME scat \- sky catalogue and Digitized Sky Survey .SH SYNOPSIS @@ -10,7 +10,7 @@ outside the solar system and implements database-like manipulations on sets of such objects. It also provides an interface to -.IR astro (7) +.IR astro (1) to plot the locations of solar system objects. Finally, it displays images from the Space Telescope Science Institute's @@ -119,7 +119,7 @@ The names and .B comet refer to the earth's penumbra at lunar distance and the comet installed in the current -.IR astro (7). +.IR astro (1). The output is the planet's name, right ascension and declination, azimuth and altitude, and phase for the moon and sun, as shown by .BR astro . @@ -182,7 +182,7 @@ collects all objects in the patches that cover the current set. .TP .BI astro " option" Run -.IR astro (7) +.IR astro (1) with the specified .I options (to which will be appended @@ -322,9 +322,9 @@ Show a pretty galaxy. .SH FILES .B /lib/sky/*.scat .SH SOURCE -.B /sys/src/cmd/scat +.B /usr/local/plan9/src/cmd/scat .SH SEE ALSO -.IR astro (7) +.IR astro (1) .br .B /lib/sky/constelnames\ \ the three-letter abbreviations of the constellation names. diff --git a/man/man1/secstore.1 b/man/man1/secstore.1 new file mode 100644 index 00000000..862857da --- /dev/null +++ b/man/man1/secstore.1 @@ -0,0 +1,212 @@ +.TH SECSTORE 1 +.SH NAME +aescbc, secstore, ipso \- secstore commands +.SH SYNOPSIS +.B secstore +[ +.B -s +.I server +] +[ +.B -(g|G) +.I getfile +] +[ +.B -p +.I putfile +] +[ +.B -r +.I rmfile +] +[ +.B -c +] +[ +.B -u +.I user +] +[ +.B -v +] +[ +.B -i +] +.PP +.B aescbc +-e +.I ciphertext +.br +.B aescbc +-d +.I cleartext +.PP +.B ipso +[ +.B -a -e -l -f -s +] [ +.I file +\&... +] +.PP +.SH DESCRIPTION +.PP +.I Secstore +authenticates to the 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 -p +stores a file on the secstore. +.PP +Option +.B -g +retrieves a file to the local directory; +option +.B -G +writes it to standard output instead. +Specifying +.I getfile +of . will send to standard output +a list of remote files with dates, lengths and SHA1 hashes. +.PP +Option +.B -r +removes a file from the secstore. +.PP +Option +.B -c +prompts for a password change. +.PP +Option +.B -v +produces more verbose output, in particular providing a few +bits of feedback to help the user detect mistyping. +.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 +instead of from +.BR /dev/cons . +This option is unsupported. +.PP +The server is +.BR tcp!$auth!5356 , +or the server specified by option +.BR -s . +.PP +For example, to add a secret to the file read by +.IR factotum (4) +at startup, open a new window, type +.sp +.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 +.PP +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, ipso will edit the +.I secstore +files and, if +one of them is named +.BR factotum , +flush your current keys from factotum and load +the new ones from the file. +If you supply any of the +.BR -e , +.BR -f , +or +.BR -l +options, +.I ipso +will just perform the operations you requested, 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 and decrypts using AES (Rijndael) in cipher +block chaining (CBC) mode. +.SH SOURCE +.B /usr/local/plan9/src/cmd/secstore +.SH SEE ALSO +.IR factotum (4), +Plan 9's \fIsecstore\fR(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/man/man1/sed.1 b/man/man1/sed.1 new file mode 100644 index 00000000..4e9ac33f --- /dev/null +++ b/man/man1/sed.1 @@ -0,0 +1,385 @@ +.TH SED 1 +.SH NAME +9sed \- stream editor +.SH SYNOPSIS +.B 9sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the flag +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (7), +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 (7). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /usr/local/plan9/src/cmd/9sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (7) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed. diff --git a/man/man1/seq.1 b/man/man1/seq.1 index 73796c26..5fda241e 100644 --- a/man/man1/seq.1 +++ b/man/man1/seq.1 @@ -38,7 +38,7 @@ The options are .TP "\w'\fL-f \fIformat\fLXX'u" .BI -f format Use the -.IR print (2)-style +.IR print (3)-style .I format .IR print for printing each (floating point) number. diff --git a/man/man1/sleep.1 b/man/man1/sleep.1 index 6416bc1d..68c94a92 100644 --- a/man/man1/sleep.1 +++ b/man/man1/sleep.1 @@ -28,4 +28,4 @@ while (){ .SH SOURCE .B /usr/local/plan9/src/cmd/sleep.c .SH "SEE ALSO" -.IR sleep (2) +.IR sleep (3) diff --git a/man/man1/split.1 b/man/man1/split.1 index 6e7f7ebf..e00e3d01 100644 --- a/man/man1/split.1 +++ b/man/man1/split.1 @@ -41,7 +41,7 @@ File divisions occur at each line that matches a regular .IR expression ; see -.IR regexp (6). +.IR regexp (7). Multiple .B -e options may appear. @@ -79,4 +79,4 @@ to lower case. .IR sed (1), .IR awk (1), .IR grep (1), -.IR regexp (6) +.IR regexp (7) diff --git a/man/man1/src.1 b/man/man1/src.1 new file mode 100644 index 00000000..4c03dd7c --- /dev/null +++ b/man/man1/src.1 @@ -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 /usr/local/plan9/bin/src +.SH "SEE ALSO" +.IR db (1), +.IR plumb (1), +.IR sam (1). diff --git a/man/man1/tbl.1 b/man/man1/tbl.1 index 921e9e85..0e986e9a 100644 --- a/man/man1/tbl.1 +++ b/man/man1/tbl.1 @@ -272,7 +272,7 @@ Bernardsville 2018 3.30 .if t \{.sp3 .1C\} .SH SOURCE -.B /sys/src/cmd/tbl +.B /usr/local/plan9/src/cmd/tbl .SH SEE ALSO .IR troff (1), .IR eqn (1), diff --git a/man/man1/tcs.1 b/man/man1/tcs.1 new file mode 100644 index 00000000..e1a410c3 --- /dev/null +++ b/man/man1/tcs.1 @@ -0,0 +1,167 @@ +.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 (7). +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 0x80 +characters will be substituted for +.SM UTF +encoding errors and +.B 0xFFFD +characters will substituted for 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 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 -lv +Print an up to date list of the supported character sets. +.SH SOURCE +.B /usr/local/plan9/src/cmd/tcs +.SH SEE ALSO +.IR ascii (1), +.IR rune (3), +.IR utf (7). diff --git a/man/man1/touch.1 b/man/man1/touch.1 index 3b074896..551ea2ca 100644 --- a/man/man1/touch.1 +++ b/man/man1/touch.1 @@ -28,7 +28,7 @@ is present. .B /usr/local/plan9/src/cmd/touch.c .SH SEE ALSO .IR ls (1), -.IR stat (2), +.IR stat (3), .IR chmod (1) .SH BUGS .I Touch diff --git a/man/man1/tr2post.1 b/man/man1/tr2post.1 new file mode 100644 index 00000000..3c4597f3 --- /dev/null +++ b/man/man1/tr2post.1 @@ -0,0 +1,111 @@ +.TH TR2POST 1 +.SH NAME +tr2post \- convert troff intermediate to PostScript +.SH SYNOPSIS +.B tr2post +[ +.B options +] +[ +.I files ... +] +.SH DESCRIPTION +.I Tr2post +converts +.I files +(or standard input), +which should be the device-independent output of +.IR troff (1), +into the PostScript printer language. +.PP +The options are: +.TP +.BI -a " aspectratio +Set an aspect ratio +.RI ( y / x ) +to stretch the PostScript output (default 1.0). +.TP +.BI -c " copies +Set a comment in the PostScript output +marking the number of copies that should be printed. +The comment is intended for ancient versions of the Unix +\fIlp\fR(1) and is not recognized by any current printer +or print spooler. +.TP +.BI -d +Emit volumes of debugging output on standard error. +.TP +.BI -m " magnification +Magnify the PostScript output (default 1.0). +.TP +.BI -n " formsperpage +Print the PostScript with +.I formsperpage +logical pages per physical page +(default 1). +Using this option emits PostScript with invalid document structuring +comments. +It will print fine but will not view correctly in +.IR gv (1) +or +.IR psv (1). +.TP +.BI -o " pagelist +Print only the pages in the +.IR pagelist , +which is a comma-separated list of ranges. +Each range is of the form +.I p +(just page +.IR p ), +.IB p - q +(pages +.I p +through +.IR q ), +.BI - p +(pages 1 through +.IR p ), +or +.IB p - +(pages +.I p +through the end of the document). +.TP +.BI -p " " l +Print the document in landscape mode. +An argument that does not begin with +.L l +will print the document in portrait mode. +.TP +.BI -x " xoffset +Translate the page output by +.I xoffset +inches to the right. +(Negative offsets translate to the left.) +.TP +.BI -y " yoffset +Translate the page output by +.I yoffset +inches down. +(Negative offsets translate up.) +.TP +.BI -P " pscode +Emit the text +.I pscode +at the end of the usual PostScript header. +.PD +.SH EXAMPLE +Preview this manual page: +.IP +.EX +troff -man /usr/local/plan9/man/man1/tr2post.1 | +tr2post | +psfonts >/tmp/a.ps +psv /tmp/a.ps +.EE +.SH SOURCE +.B /usr/local/plan9/src/cmd/postscript/tr2post +.SH SEE ALSO +.IR troff (1), +.IR psfonts (1) diff --git a/man/man1/troff.1 b/man/man1/troff.1 index db5b9e6f..3f990ab7 100644 --- a/man/man1/troff.1 +++ b/man/man1/troff.1 @@ -174,17 +174,18 @@ terminal driving tables for font width tables for .I troff .SH SOURCE -.B /sys/src/cmd/troff +.B /usr/local/plan9/src/cmd/troff .SH "SEE ALSO" -.IR lp (1), +.IR lpr (1), .IR proof (1), +.IR tr2post (1), .IR eqn (1), .IR tbl (1), .IR pic (1), .IR grap (1), .IR doctype (1), -.IR ms (6), -.IR image (6), +.IR ms (7), +.IR image (7), .IR tex (1), .IR deroff (1) .br diff --git a/man/man1/tweak.1 b/man/man1/tweak.1 new file mode 100644 index 00000000..511e1ce8 --- /dev/null +++ b/man/man1/tweak.1 @@ -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 (7)); +and the subfont's +.BR n , +.BR height , +and +.B ascent +as defined in +.IR cachechars (3). +.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 (3); +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 /usr/local/plan9/src/cmd/draw/tweak.c +.SH "SEE ALSO" +.IR cachechars (3), +.IR image (7), +.IR font (7) +.SH BUGS +For a program written to adjust width tables in fonts, +.I tweak +has been pushed unreasonably far. diff --git a/man/man1/units.1 b/man/man1/units.1 new file mode 100644 index 00000000..23863569 --- /dev/null +++ b/man/man1/units.1 @@ -0,0 +1,108 @@ +.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 /usr/local/plan9/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. +.br +Currency conversions are only as accurate as the last time someone +updated +.BR /lib/units . diff --git a/man/man1/vac.1 b/man/man1/vac.1 new file mode 100644 index 00000000..4d3208d7 --- /dev/null +++ b/man/man1/vac.1 @@ -0,0 +1,130 @@ +.TH VAC 1 +.SH NAME +vac \- create 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 ... +.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 +Option to +.I vac +are: +.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 given by +.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 place 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. +.SH SOURCE +.B /usr/local/plan9/src/cmd/vac +.SH "SEE ALSO" +Plan 9's \fIvacfs\fR(4) and \fIventi\fR(8) + diff --git a/man/man1/web.1 b/man/man1/web.1 new file mode 100644 index 00000000..0bcc9ca1 --- /dev/null +++ b/man/man1/web.1 @@ -0,0 +1,75 @@ +.TH WEB 1 +.SH NAME +web, wmail \- handle web page, mail message for plumber +.SH SYNOPSIS +.B web +.I url +\&... +.br +.B wmail +.I address +.SH DESCRIPTION +.I Web +opens each of the named +.I urls +in a new web browser window. +Any of the +.I urls +may be relative paths to files in the file system; +they will be translated into +.B file:// +URLs before being passed to the web browser. +.PP +.I Web +uses the +web browser's +.B -remote +option command-line option, +which requires an instance of the web browser +to be already running. +The choice of browser is determined by the +.B $BROWSER +environment variable, which should be the name of +the executable for your choice of web browser. +Since the various browsers all use different syntaxes +in their +.B -remote +options, the executable name is inspected to determine +the type of browser. +The supported browsers are Opera, Mozilla Firefox, Mozilla Firebird, and Mozilla. +When possible, +.I web +opens each URL in a new tab rather than a new window. +.PP +.I Wmail +starts the composition of a new mail message to +.IR address . +.PP +The choice of mailer is determined by the +.B $MAILER +environment variable. +The supported mailers are: +.TP browser +invoke the mailer via a +.B mailto:// +URL passed to +.I web +.PD +.PP +.I Web +and +.I wmail +are invoked as start commands in the +.IR plumber (4)'s +rules for opening web pages and writing mail messages. +.SH FILES +.TP +.B /usr/local/plan9/plumb/basic +plumbing rules using +.I web +and +.I wmail +.SH SOURCE +.B /usr/local/plan9/bin +.SH SEE ALSO +.IR plumber (4) diff --git a/man/man1/wintext.1 b/man/man1/wintext.1 new file mode 100644 index 00000000..7d3463d1 --- /dev/null +++ b/man/man1/wintext.1 @@ -0,0 +1,98 @@ +.TH WINTEXT 1 +.SH NAME +wintext, ", "" \- access text in current window +.SH SYNOPSIS +.B wintext +.br +.B \C'"'\ +[ +.I prefix +] +.br +.B \C'"'\C'"'\ +[ +.I prefix +] +.SH DESCRIPTION +.I Wintext +prints the text of the current +.I win +(see +.IR acme (1)) +or +.IR 9term (1) +window to standard output. +.PP +.I \C'"' +searches the window text for commands typed with a particular prefix +and prints them, indented, to standard output. +.I Prefix +is a regular expression that is matched against the beginning of the command-line. +If +.I prefix +is omitted, +.I \C'"' +prints the last command executed. +.I \C'"'\C'"' +prints the last command that +.I \C'"' +would print and then executes it by piping it into +.IR rc (1). +.PP +Both +.I \C'"' +and +.I \C'"'\C'"' +identify commands in the window text by looking for lines +beginning with a shell prompt. +Prompts are assumed to be an unindented sequence of +non-whitespace characters followed by one of the +characters +.BR % , +.BR ; , +.BR $ , +or +.BR # . +.SH EXAMPLES +Print the +.IR ls (1) +and +.I lc +commands executed in this window: +.IP +.EX +.ta +4n +% \C'"' 'l[sc]' + % ls -l /tmp/qq* + # ls -lrt /etc + % lc r* +% +.EE +.PP +Execute the most recent +.I lc +command again: +.IP +.EX +.ta +4n +% \C'"'\C'"' lc + % lc r* +ramfs rc read rio rm +% +.EE +.SH SEE ALSO +.IR 9term (1), +.IR acme (1) +.SH SOURCE +.B /usr/local/plan9/bin +.SH BUGS +.I \C'"' +and +.I \C'"'\C'"' +are hard to type in shells other than +.IR rc (1). +.\" and in troff! +.PP +Don't run +.I \C'"'\C'"' +twice in a row. diff --git a/man/man1/yacc.1 b/man/man1/yacc.1 index 08d51b79..91bc7d0d 100644 --- a/man/man1/yacc.1 +++ b/man/man1/yacc.1 @@ -106,7 +106,7 @@ option reverses this. The parser accepts .SM UTF input text (see -.IR utf (6)), +.IR utf (7)), which has a couple of effects. First, the return value of .B yylex() @@ -145,7 +145,7 @@ parser prototype .B /usr/local/plan9/lib/yaccpars parser prototype using stdio .SH SOURCE -.B /usr/local/plan9/src/cmd/yacc.c +.B /usr/local/plan9/src/cmd/9yacc.c .SH "SEE ALSO" .IR lex (1) .br diff --git a/man/man3/9p.3 b/man/man3/9p.3 index 9e755735..9d8967eb 100644 --- a/man/man3/9p.3 +++ b/man/man3/9p.3 @@ -10,8 +10,9 @@ postmountsrv, readbuf, readstr, respond, +srv, threadpostmountsrv, -srv \- 9P file service +walkandclone \- 9P file service .SH SYNOPSIS .ft L .nf @@ -176,9 +177,7 @@ as .BI /srv/ name . .IP Fork a child process via -.I rfork -(see -.IR fork (3)) +.IR rfork (3) or .I procrfork (see @@ -214,9 +213,7 @@ The parent returns to the caller. .LP If any error occurs during this process, the entire process is terminated by calling -.I sysfatal -(see -.IR perror (3)). +.IR sysfatal (3). .SS Service functions The functions in a .B Srv @@ -603,12 +600,12 @@ consults in changing the metadata for .IB r -> fid as described in -.IR stat (5). +.IR stat (9p). When using file trees, .I srv will take care to check that the request satisfies the permissions outlined in -.IR stat (5). +.IR stat (9p). Otherwise .I wstat should take care to enforce permissions @@ -720,19 +717,16 @@ accept the option to increment .BR chatty9p . .SH EXAMPLES -.IR Archfs (4), -.IR cdfs (4), -.IR nntpfs (4), -.IR snap (4), -and -.B /usr/local/plan9/src/lib9p/ramfs.c -are good examples of simple single-threaded file servers. -.IR Webfs (4) +/usr/local/plan9/src/lib9p/ramfs.c +is an example of simple single-threaded file servers. +On Plan 9, see +.IR archfs , +.IR cdfs , +.IR nntpfs , +.IR webfs , and .I sshnet -(see -.IR ssh (1)) -are good examples of multithreaded file servers. +for more examples. .PP In general, the .B File @@ -752,9 +746,4 @@ or is maintained elsewhere. .SH SEE ALSO .IR 9pfid (3), .IR 9pfile (3), -.IR srv (3), -.IR intro (5) -.SH BUGS -The switch to 9P2000 was taken as an opportunity to tidy -much of the interface; we promise to avoid such gratuitous change -in the future. +.IR intro (9p) diff --git a/man/man3/9pclient.3 b/man/man3/9pclient.3 new file mode 100644 index 00000000..1c7e76ad --- /dev/null +++ b/man/man3/9pclient.3 @@ -0,0 +1,342 @@ +.TH 9PCLIENT 3 +.SH NAME +CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite \- 9P client library +.SH SYNOPSIS +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include <9pclient.h> +.PP +.ta +'\fLCFsys* 'u +.B +CFsys* fsmount(int fd, char *aname) +.PP +.B +CFsys* nsmount(char *name, char *aname) +.PP +.B +CFid* fsroot(CFsys *fsys) +.PP +.B +void fsunmount(CFsys *fsys) +.PP +.B +CFsys* fsinit(int fd) +.PP +.B +int fsversion(CFsys *fsys, int msize, char *version, int nversion) +.PP +.B +CFid *fsauth(CFsys *fsys, char *uname, char *aname) +.PP +.B +CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) +.PP +.B +void fssetroot(CFsys *fsys, CFid *fid) +.PP +.B +void fsclose(CFid *fid) +.PP +.B +CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm) +.PP +.B +CFid* fsopen(CFsys *fs, char *path, int mode) +.PP +.B +long fspread(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fspwrite(CFid *fid, void *buf, long n, vlong offset) +.PP +.B +long fsread(CFid *fid, void *buf, long n) +.PP +.B +long fsreadn(CFid *fid, void *buf, long n) +.PP +.B +long fswrite(CFid *fid, void *buf, long n) +.PP +.B +long fsdirread(CFid *fid, Dir **d) +.PP +.B +long fsdirreadall(CFid *fid, Dir **d) +.PP +.B +Dir* fsdirstat(CFsys *fs, char *path) +.PP +.B +Dir* fsdirfstat(CFid *fid) +.PP +.B +int fsdirwstat(CFsys *fs, char *path, Dir *d) +.PP +.B +int fsdirfwstat(CFid *fid, Dir *d) +.PP +.B +int fsopenfd(CFsys *fs, char *path, int mode) +.SH DESCRIPTION +The +.I 9pclient +library helps client programs interact with 9P servers. +.PP +A +.B CFsys* +represents a connection to a 9P server. +A +.B CFid* +represents an active fid on some connection; +see +.IR intro (9p). +.PP +A new connection to a 9P server is typically established by +.I fsmount +or +.IR nsmount . +.I Fsmount +initializes a new 9P conversation on the open file descriptor +.IR fd ; +.I nsmount +connects to a service named +.I name +in the current name space directory +(see +.IR intro (4)). +Both attach to the root of the file system +using the attach name +.IR aname . +.I Fsroot +returns the +.B CFid* +corresponding to this root. +.PP +.IR Fsinit , +.IR fsversion , +.IR fsauth , +.IR fsattach , +and +.I fssetroot +provide more detailed control over the file system connection +than +.I fsmount +and +.IR nsmount . +.I Fsinit +allocates a new +.B CFsys* +corresponding to a 9P conversation on the file descriptor +.IR fd . +.I Fsversion +executes a +.IR version (9p) +transaction to establish +maximum message size and 9P version. +.I Fsauth +executes an +.IR auth (9p) +transaction, returning the new auth fid. +.RI ( Fsread +and +.I fswrite +can then be used to run the authentication protocol over the fid.) +.I Fsattach +executes an +.IR attach (9p) +transaction to connect to the root of a file tree served by the server. +It presents +.I afid +(which may be nil) +to establish identity. +.I Fssetroot +sets the root fid used by +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +and +.IR fsdirwstat , +which evaluate rooted path names. +.PP +When a fid +is no longer needed, it should be clunked by calling +.I fsclose +and then considered freed. +Similarly, when the connection to the server is no longer needed, +it should be closed by calling +.IR fsunmount , +which will take care of calling +.I fsclose +on the current root fid. +Once all fids have been clunked +.I and +the connection has been closed +(the order is not important), +the allocated structures will be freed and the +file descriptor corresponding to the connection +will be closed +(see +.IR close (2)). +Fids are not reference counted: when +.I fsclose +is called, the clunk transaction and freeing of storage +happen immediately. +.PP +.I Fscreate +and +.I fsopen +establish new fids using the +.IR walk , +.I create +and +.I open +transactions +(see +.IR walk (9p) +and +.IR open (9p)). +The +.I path +argument is evaluated relative to the +.B CFsys +root +(see +.I fsroot +and +.I fssetroot +above). +The path is parsed as a slash-separated sequence of path elements, +as on Unix and Plan 9. +Elements that are empty or +dot +.B ( . ) +are ignored. +.PP +Once opened, these fids can be read and written using +.I fspread +and +.IR fspwrite , +which execute +.I read +and +.I write +transactions +(see +.IR read (9p)). +The library maintains an offset for each fid, +analagous to the offset maintained by the kernel for each open file descriptor. +.I Fsread +and +.I fswrite +read and write from this offset, and update it after successful calls. +Calling +.I fspread +or +.I fspwrite +with an +.I offset +of \-1 +is identical to calling +.I fsread +or +.IR fswrite . +.I Fsreadn +calls +.I fsread +repeatedly to obtain exactly +.I n +bytes of data, unless it encounters end-of-file or an error. +.PP +Reading an open a directory returns directory entries encoded as described in +.IR stat (9p). +.I Fsdirread +calls +.I fsread +and then parses the encoded entries into an array of +.B Dir* +data structures, +storing a pointer to the array in +.BI *d +and returning the number of entries. +.I Fsdirreadall +is similar but reads the entire directory. +The returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirfstat +and +.I fsdirfwstat +execute +.I stat +and +.I wstat +(see +.IR stat (9p)) +transactions. +The +.B Dir +structure returned by +.I fsdirfstat +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Fsdirstat +and +.I fsdirwstat +are similar to +.I fsdirfstat +and +.I fsdirfwstat +but operate on paths relative to the file system root +(see +.I fsopen +and +.I fscreate +above). +.PP +.I Fsopenfd +opens a file on the 9P server +for reading or writing but returns a Unix file descriptor +instead of a fid structure. +The file descriptor is actually one end of a +.IR pipe (2). +A proxy process on the other end is ferrying data +between the pipe and the 9P fid. +Because of the implementation as a pipe, +the only signal of a read or write error is the closing of the pipe. +The file descriptor remains valid even after the +.B CFsys +is unmounted. +.SH SOURCE +.B /usr/local/plan9/src/lib9pclient +.SH SEE ALSO +.IR intro (4), +.IR intro (9p) +.SH BUGS +The implementation +should use a special version string to distinguish between +servers that support +.IR openfd (9p) +and servers that do not. +.PP +The interface does not provide access to the +.IR walk (9p) +transaction, or to +.I open +and +.I create +on already-established fids. +.PP +There is no +.IR fsseek . diff --git a/man/man3/9pcmdbuf.3 b/man/man3/9pcmdbuf.3 index d6a78b92..e961422f 100644 --- a/man/man3/9pcmdbuf.3 +++ b/man/man3/9pcmdbuf.3 @@ -42,7 +42,9 @@ bytes at .I p (which need not be NUL-terminated) as a UTF string and splits it using -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). It returns a .B Cmdbuf structure holding pointers to each field in the message. diff --git a/man/man3/9pfile.3 b/man/man3/9pfile.3 index 083b6550..1bb3038e 100644 --- a/man/man3/9pfile.3 +++ b/man/man3/9pfile.3 @@ -94,7 +94,7 @@ and the permissions of .I dir are used to calculate the permission bits for the file as described in -.IR open (5). +.IR open (9p). It is permissible for .I name to be a slash-separated path rather than a single element. @@ -162,7 +162,7 @@ consume the passed reference. .PP Directories may be read, yielding a directory entry structure (see -.IR stat (5)) +.IR stat (9p)) for each file in the directory. In order to allow concurrent reading of directories, clients must obtain a diff --git a/man/man3/INDEX b/man/man3/INDEX new file mode 100644 index 00000000..9c067d00 --- /dev/null +++ b/man/man3/INDEX @@ -0,0 +1,1163 @@ +9p 9p.3 +Srv 9p.3 +dirread9p 9p.3 +emalloc9p 9p.3 +erealloc9p 9p.3 +estrdup9p 9p.3 +postfd 9p.3 +postmountsrv 9p.3 +readbuf 9p.3 +readstr 9p.3 +respond 9p.3 +srv 9p.3 +threadpostmountsrv 9p.3 +walkandclone 9p.3 +9pclient 9pclient.3 +CFid 9pclient.3 +CFsys 9pclient.3 +fsattach 9pclient.3 +fsauth 9pclient.3 +fsclose 9pclient.3 +fscreate 9pclient.3 +fsdirfstat 9pclient.3 +fsdirfwstat 9pclient.3 +fsdirread 9pclient.3 +fsdirreadall 9pclient.3 +fsdirstat 9pclient.3 +fsdirwstat 9pclient.3 +fsinit 9pclient.3 +fsmount 9pclient.3 +fsopen 9pclient.3 +fsopenfd 9pclient.3 +fspread 9pclient.3 +fspwrite 9pclient.3 +fsread 9pclient.3 +fsreadn 9pclient.3 +fsroot 9pclient.3 +fssetroot 9pclient.3 +fsunmount 9pclient.3 +fsversion 9pclient.3 +fswrite 9pclient.3 +nsmount 9pclient.3 +9pcmdbuf 9pcmdbuf.3 +Cmdbuf 9pcmdbuf.3 +lookupcmd 9pcmdbuf.3 +parsecmd 9pcmdbuf.3 +respondcmderror 9pcmdbuf.3 +9pfid 9pfid.3 +Fid 9pfid.3 +Fidpool 9pfid.3 +Req 9pfid.3 +Reqpool 9pfid.3 +allocfid 9pfid.3 +allocfidpool 9pfid.3 +allocreq 9pfid.3 +allocreqpool 9pfid.3 +closefid 9pfid.3 +closereq 9pfid.3 +freefidpool 9pfid.3 +freereqpool 9pfid.3 +lookupfid 9pfid.3 +lookupreq 9pfid.3 +removefid 9pfid.3 +removereq 9pfid.3 +9pfile 9pfile.3 +File 9pfile.3 +Tree 9pfile.3 +alloctree 9pfile.3 +closedirfile 9pfile.3 +closefile 9pfile.3 +createfile 9pfile.3 +freetree 9pfile.3 +hasperm 9pfile.3 +opendirfile 9pfile.3 +readdirfile 9pfile.3 +removefile 9pfile.3 +walkfile 9pfile.3 +Dx addpt.3 +Dy addpt.3 +Pt addpt.3 +Rect addpt.3 +Rpt addpt.3 +addpt addpt.3 +canonrect addpt.3 +combinerect addpt.3 +divpt addpt.3 +eqpt addpt.3 +eqrect addpt.3 +insetrect addpt.3 +mulpt addpt.3 +ptinrect addpt.3 +rectXrect addpt.3 +rectaddpt addpt.3 +rectclip addpt.3 +rectinrect addpt.3 +rectsubpt addpt.3 +subpt addpt.3 +aes aes.3 +aesCBCdecrypt aes.3 +aesCBCencrypt aes.3 +setupAESstate aes.3 +allocimage allocimage.3 +allocimagemix allocimage.3 +bytesperline allocimage.3 +cloadimage allocimage.3 +freeimage allocimage.3 +loadimage allocimage.3 +namedimage allocimage.3 +nameimage allocimage.3 +readimage allocimage.3 +setalpha allocimage.3 +unloadimage allocimage.3 +wordsperline allocimage.3 +writeimage allocimage.3 +ARGBEGIN arg.3 +ARGC arg.3 +ARGEND arg.3 +ARGF arg.3 +EARGF arg.3 +arg arg.3 +arginit arg.3 +argopt arg.3 +add3 arith3.3 +add4 arith3.3 +arith3 arith3.3 +closept3 arith3.3 +cross3 arith3.3 +dist3 arith3.3 +div3 arith3.3 +dot3 arith3.3 +eqpt3 arith3.3 +fff2p3 arith3.3 +len3 arith3.3 +lerp3 arith3.3 +midpt3 arith3.3 +mul3 arith3.3 +nearseg3 arith3.3 +neg3 arith3.3 +pdiv4 arith3.3 +pldist3 arith3.3 +pn2f3 arith3.3 +ppp2f3 arith3.3 +reflect3 arith3.3 +sub3 arith3.3 +sub4 arith3.3 +unit3 arith3.3 +vdiv3 arith3.3 +vrem3 arith3.3 +atof atof.3 +atoi atof.3 +atol atof.3 +atoll atof.3 +charstod atof.3 +strtod atof.3 +strtol atof.3 +strtoll atof.3 +strtoul atof.3 +strtoull atof.3 +bin bin.3 +binalloc bin.3 +binfree bin.3 +bingrow bin.3 +Bbuffered bio.3 +Bfdopen bio.3 +Bfildes bio.3 +Bflush bio.3 +Bgetc bio.3 +Bgetd bio.3 +Bgetrune bio.3 +Binit bio.3 +Binits bio.3 +Blinelen bio.3 +Boffset bio.3 +Bopen bio.3 +Bprint bio.3 +Bputc bio.3 +Bputrune bio.3 +Brdline bio.3 +Brdstr bio.3 +Bread bio.3 +Bseek bio.3 +Bterm bio.3 +Bungetc bio.3 +Bungetrune bio.3 +Bvprint bio.3 +Bwrite bio.3 +bio bio.3 +bfCBCdecrypt blowfish.3 +bfCBCencrypt blowfish.3 +bfECBdecrypt blowfish.3 +bfECBencrypt blowfish.3 +blowfish blowfish.3 +setupBFstate blowfish.3 +Font cachechars.3 +Fontchar cachechars.3 +Subfont cachechars.3 +agefont cachechars.3 +cachechars cachechars.3 +loadchar cachechars.3 +cleanname cleanname.3 +cmap2rgb color.3 +cmap2rgba color.3 +color color.3 +rgb2cmap color.3 +complete complete.3 +freecompletion complete.3 +cputime cputime.3 +times cputime.3 +asctime ctime.3 +ctime ctime.3 +gmtime ctime.3 +localtime ctime.3 +timezone ctime.3 +tm2sec ctime.3 + +block_cipher des.3 +des des.3 +des3CBCdecrypt des.3 +des3CBCencrypt des.3 +des3ECBdecrypt des.3 +des3ECBencrypt des.3 +des56to64 des.3 +des64to56 des.3 +desCBCdecrypt des.3 +desCBCencrypt des.3 +desECBdecrypt des.3 +desECBencrypt des.3 +des_key_setup des.3 +key_setup des.3 +setupDES3state des.3 +setupDESstate des.3 +triple_block_cipher des.3 +accept dial.3 +announce dial.3 +dial dial.3 +dialparse dial.3 +hangup dial.3 +listen dial.3 +netmkaddr dial.3 +reject dial.3 +dirread dirread.3 +dirreadall dirread.3 +Disk disk.3 +disk disk.3 +opendisk disk.3 +ARROW draw.3 +Image draw.3 +_string draw.3 +arc draw.3 +arcop draw.3 +bezier draw.3 +bezierop draw.3 +bezspline draw.3 +bezsplineop draw.3 +bezsplinepts draw.3 +border draw.3 +draw draw.3 +drawop draw.3 +drawrepl draw.3 +drawreplxy draw.3 +drawsetdebug draw.3 +ellipse draw.3 +ellipseop draw.3 +fillarc draw.3 +fillarcop draw.3 +fillbezier draw.3 +fillbezierop draw.3 +fillbezspline draw.3 +fillbezsplineop draw.3 +fillellipse draw.3 +fillellipseop draw.3 +fillpoly draw.3 +fillpolyop draw.3 +gendraw draw.3 +gendrawop draw.3 +icossin draw.3 +icossin2 draw.3 +line draw.3 +lineop draw.3 +poly draw.3 +polyop draw.3 +replclipr draw.3 +runestring draw.3 +runestringbg draw.3 +runestringbgop draw.3 +runestringn draw.3 +runestringnbg draw.3 +runestringnbgop draw.3 +runestringnop draw.3 +runestringop draw.3 +string draw.3 +stringbg draw.3 +stringbgop draw.3 +stringn draw.3 +stringnbg draw.3 +stringnbgop draw.3 +stringnop draw.3 +stringop draw.3 +dsa dsa.3 +dsagen dsa.3 +dsaprivalloc dsa.3 +dsaprivfree dsa.3 +dsaprivtopub dsa.3 +dsapuballoc dsa.3 +dsapubfree dsa.3 +dsasigalloc dsa.3 +dsasigfree dsa.3 +dsasign dsa.3 +dsaverify dsa.3 +dup dup.3 +egdecrypt elgamal.3 +egencrypt elgamal.3 +eggen elgamal.3 +egprivalloc elgamal.3 +egprivfree elgamal.3 +egprivtopub elgamal.3 +egpuballoc elgamal.3 +egpubfree elgamal.3 +egsigalloc elgamal.3 +egsigfree elgamal.3 +egsign elgamal.3 +egverify elgamal.3 +elgamal elgamal.3 +dec16 encode.3 +dec32 encode.3 +dec64 encode.3 +enc16 encode.3 +enc32 encode.3 +enc64 encode.3 +encode encode.3 +encodefmt encode.3 +errstr errstr.3 +rerrstr errstr.3 +werrstr errstr.3 +Event event.3 +Menu event.3 +Mouse event.3 +eatomouse event.3 +ecankbd event.3 +ecanmouse event.3 +ecanread event.3 +edrawgetrect event.3 +egetrect event.3 +einit event.3 +ekbd event.3 +emenuhit event.3 +emouse event.3 +emoveto event.3 +eread event.3 +ereadmouse event.3 +eresized event.3 +esetcursor event.3 +estart event.3 +estartfn event.3 +etimer event.3 +event event.3 +exec exec.3 +execl exec.3 +_exits exits.3 +atexit exits.3 +atexitdont exits.3 +exits exits.3 +terminate exits.3 +Fcall fcall.3 +convD2M fcall.3 +convM2D fcall.3 +convM2S fcall.3 +convS2M fcall.3 +dirfmt fcall.3 +dirmodefmt fcall.3 +fcall fcall.3 +fcallfmt fcall.3 +read9pmsg fcall.3 +sizeD2M fcall.3 +sizeS2M fcall.3 +statcheck fcall.3 +adler32 flate.3 +blockcrc flate.3 +deflate flate.3 +deflateblock flate.3 +deflateinit flate.3 +deflatezlib flate.3 +deflatezlibblock flate.3 +flate flate.3 +flateerr flate.3 +inflate flate.3 +inflateblock flate.3 +inflateinit flate.3 +inflatezlib flate.3 +inflatezlibblock flate.3 +mkcrctab flate.3 +dofmt fmtinstall.3 +dorfmt fmtinstall.3 +errfmt fmtinstall.3 +fmtfdflush fmtinstall.3 +fmtfdinit fmtinstall.3 +fmtinstall fmtinstall.3 +fmtprint fmtinstall.3 +fmtrune fmtinstall.3 +fmtrunestrcpy fmtinstall.3 +fmtstrcpy fmtinstall.3 +fmtstrflush fmtinstall.3 +fmtstrinit fmtinstall.3 +fmtvprint fmtinstall.3 +runefmtstrflush fmtinstall.3 +runefmtstrinit fmtinstall.3 +frame frame.3 +frcharofpt frame.3 +frclear frame.3 +frdelete frame.3 +frdrawsel frame.3 +frdrawsel0 frame.3 +frgetmouse frame.3 +frinit frame.3 +frinittick frame.3 +frinsert frame.3 +frptofchar frame.3 +frselect frame.3 +frselectpaint frame.3 +frsetrects frame.3 +frtick frame.3 +genrandom genrandom.3 +prng genrandom.3 +get9root get9root.3 +unsharp get9root.3 +getcallerpc getcallerpc.3 +getenv getenv.3 +putenv getenv.3 +getfields getfields.3 +gettokens getfields.3 +tokenize getfields.3 +getns getns.3 +getsnarf getsnarf.3 +putsnarf getsnarf.3 +getuser getuser.3 +sysname getuser.3 +getwd getwd.3 +Cursor graphics.3 +Display graphics.3 +Pfmt graphics.3 +Point graphics.3 +Rectangle graphics.3 +Rfmt graphics.3 +bufimage graphics.3 +buildfont graphics.3 +chantodepth graphics.3 +chantostr graphics.3 +closedisplay graphics.3 +cursorset graphics.3 +cursorswitch graphics.3 +drawerror graphics.3 +flushimage graphics.3 +freefont graphics.3 +gengetwindow graphics.3 +geninitdraw graphics.3 +getdefont graphics.3 +getwindow graphics.3 +graphics graphics.3 +initdisplay graphics.3 +initdraw graphics.3 +lockdisplay graphics.3 +openfont graphics.3 +strtochan graphics.3 +unlockdisplay graphics.3 +dimenkind html.3 +dimenspec html.3 +freedocinfo html.3 +freeitems html.3 +fromStr html.3 +html html.3 +parsehtml html.3 +printitems html.3 +targetid html.3 +targetname html.3 +toStr html.3 +validitems html.3 +Intmap intmap.3 +allocmap intmap.3 +caninsertkey intmap.3 +deletekey intmap.3 +freemap intmap.3 +insertkey intmap.3 +intmap intmap.3 +lookupkey intmap.3 +closeioproc ioproc.3 +iocall ioproc.3 +ioclose ioproc.3 +iodial ioproc.3 +iointerrupt ioproc.3 +ioopen ioproc.3 +ioproc ioproc.3 +ioread ioproc.3 +ioread9pmsg ioproc.3 +ioreadn ioproc.3 +iorecvfd ioproc.3 +iosendfd ioproc.3 +iosleep ioproc.3 +iowrite ioproc.3 +defmask ip.3 +eipfmt ip.3 +equivip ip.3 +hnputl ip.3 +hnputs ip.3 +hnputv ip.3 +ip ip.3 +isv4 ip.3 +maskip ip.3 +myetheraddr ip.3 +myipaddr ip.3 +nhgetl ip.3 +nhgets ip.3 +nhgetv ip.3 +parseether ip.3 +parseip ip.3 +parseipmask ip.3 +ptclbsum ip.3 +readipifc ip.3 +v4parsecidr ip.3 +v4parseip ip.3 +v4tov6 ip.3 +v6tov4 ip.3 +isalpharune isalpharune.3 +islowerrune isalpharune.3 +isspacerune isalpharune.3 +istitlerune isalpharune.3 +isupperrune isalpharune.3 +tolowerrune isalpharune.3 +totitlerune isalpharune.3 +toupperrune isalpharune.3 +closekeyboard keyboard.3 +ctlkeyboard keyboard.3 +initkeyboard keyboard.3 +keyboard keyboard.3 +canlock lock.3 +canqlock lock.3 +canrlock lock.3 +canwlock lock.3 +decref lock.3 +incref lock.3 +lock lock.3 +qlock lock.3 +qunlock lock.3 +rlock lock.3 +rsleep lock.3 +runlock lock.3 +rwakeup lock.3 +rwakeupall lock.3 +unlock lock.3 +wlock lock.3 +wunlock lock.3 +attachargs mach-cmd.3 +attachcore mach-cmd.3 +attachdynamic mach-cmd.3 +attachproc mach-cmd.3 +mach-cmd mach-cmd.3 +proctextfile mach-cmd.3 +crackhdr mach-file.3 +ctlproc mach-file.3 +detachproc mach-file.3 +mach-file mach-file.3 +mapfile mach-file.3 +mapproc mach-file.3 +procnotes mach-file.3 +uncrackhdr mach-file.3 +unmapfile mach-file.3 +unmapproc mach-file.3 +addrtoseg mach-map.3 +addrtosegafter mach-map.3 +addseg mach-map.3 +allocmap mach-map.3 +findseg mach-map.3 +fpformat mach-map.3 +freemap mach-map.3 +get1 mach-map.3 +get2 mach-map.3 +get4 mach-map.3 +get8 mach-map.3 +lget1 mach-map.3 +lget2 mach-map.3 +lget4 mach-map.3 +lget8 mach-map.3 +locaddr mach-map.3 +loccmp mach-map.3 +locconst mach-map.3 +loceval mach-map.3 +locfmt mach-map.3 +locindir mach-map.3 +locnone mach-map.3 +locreg mach-map.3 +locsimplify mach-map.3 +lput1 mach-map.3 +lput2 mach-map.3 +lput4 mach-map.3 +lput8 mach-map.3 +mach-map mach-map.3 +put1 mach-map.3 +put2 mach-map.3 +put4 mach-map.3 +put8 mach-map.3 +removeseg mach-map.3 +rget mach-map.3 +rput mach-map.3 +localaddr mach-stack.3 +mach-stack mach-stack.3 +stacktrace mach-stack.3 +unwindframe mach-stack.3 +windindex mach-stack.3 +windreglocs mach-stack.3 +beieeeftoa32 mach-swap.3 +beieeeftoa64 mach-swap.3 +beieeeftoa80 mach-swap.3 +beload2 mach-swap.3 +beload4 mach-swap.3 +beload8 mach-swap.3 +beswap2 mach-swap.3 +beswap4 mach-swap.3 +beswap8 mach-swap.3 +ieeeftoa32 mach-swap.3 +ieeeftoa64 mach-swap.3 +leieeeftoa32 mach-swap.3 +leieeeftoa64 mach-swap.3 +leieeeftoa80 mach-swap.3 +leload2 mach-swap.3 +leload4 mach-swap.3 +leload8 mach-swap.3 +leswap2 mach-swap.3 +leswap4 mach-swap.3 +leswap8 mach-swap.3 +mach-swap mach-swap.3 +ffindsym mach-symbol.3 +file2pc mach-symbol.3 +fileline mach-symbol.3 +findexsym mach-symbol.3 +findhdr mach-symbol.3 +findlsym mach-symbol.3 +findsym mach-symbol.3 +flookupsym mach-symbol.3 +fnbound mach-symbol.3 +indexlsym mach-symbol.3 +indexsym mach-symbol.3 +line2pc mach-symbol.3 +lookuplsym mach-symbol.3 +lookupsym mach-symbol.3 +mach-symbol mach-symbol.3 +pc2file mach-symbol.3 +pc2line mach-symbol.3 +symclose mach-symbol.3 +symoff mach-symbol.3 +symopen mach-symbol.3 +mach mach.3 +machbyname mach.3 +machbytype mach.3 +calloc malloc.3 +free malloc.3 +getmalloctag malloc.3 +getrealloctag malloc.3 +malloc malloc.3 +mallocz malloc.3 +realloc malloc.3 +setmalloctag malloc.3 +setrealloctag malloc.3 +adjoint matrix.3 +determinant matrix.3 +ident matrix.3 +invertmat matrix.3 +ixform matrix.3 +look matrix.3 +matmul matrix.3 +matmulr matrix.3 +matrix matrix.3 +move matrix.3 +persp matrix.3 +popmat matrix.3 +pushmat matrix.3 +qrot matrix.3 +rot matrix.3 +scale matrix.3 +viewport matrix.3 +xform matrix.3 +xformplane matrix.3 +xformpoint matrix.3 +xformpointd matrix.3 +Memdata memdraw.3 +Memdrawparam memdraw.3 +Memimage memdraw.3 +allocmemimage memdraw.3 +allocmemimaged memdraw.3 +allocmemsubfont memdraw.3 +byteaddr memdraw.3 +cloadmemimage memdraw.3 +creadmemimage memdraw.3 +drawclip memdraw.3 +freememimage memdraw.3 +freememsubfont memdraw.3 +getmemdefont memdraw.3 +hwdraw memdraw.3 +iprint memdraw.3 +loadmemimage memdraw.3 +memarc memdraw.3 +memdraw memdraw.3 +memellipse memdraw.3 +memfillcolor memdraw.3 +memfillpoly memdraw.3 +memimagedraw memdraw.3 +memimageinit memdraw.3 +memimageline memdraw.3 +memimagemove memdraw.3 +memimagestring memdraw.3 +memlinebbox memdraw.3 +memlineendsize memdraw.3 +mempoly memdraw.3 +memsetchan memdraw.3 +memsubfontwidth memdraw.3 +openmemsubfont memdraw.3 +readmemimage memdraw.3 +unloadmemimage memdraw.3 +wordaddr memdraw.3 +writememimage memdraw.3 +memdraw memlayer.3 +memlalloc memlayer.3 +memlayer memlayer.3 +memldelete memlayer.3 +memlexpose memlayer.3 +memlfree memlayer.3 +memlhide memlayer.3 +memline memlayer.3 +memlnorefresh memlayer.3 +memload memlayer.3 +memlorigin memlayer.3 +memlsetrefresh memlayer.3 +memltofront memlayer.3 +memltofrontn memlayer.3 +memltorear memlayer.3 +memltorearn memlayer.3 +memunload memlayer.3 +memccpy memory.3 +memchr memory.3 +memcmp memory.3 +memcpy memory.3 +memmove memory.3 +memory memory.3 +memset memory.3 +closemouse mouse.3 +cursorswitch mouse.3 +drawgetrect mouse.3 +getrect mouse.3 +initmouse mouse.3 +menuhit mouse.3 +mouse mouse.3 +moveto mouse.3 +readmouse mouse.3 +setcursor mouse.3 +mousescrollsize mousescrollsize.3 +betomp mp.3 +crtin mp.3 +crtout mp.3 +crtpre mp.3 +crtprefree mp.3 +crtresfree mp.3 +itomp mp.3 +letomp mp.3 +mp mp.3 +mpadd mp.3 +mpassign mp.3 +mpbits mp.3 +mpcmp mp.3 +mpcopy mp.3 +mpdigdiv mp.3 +mpdiv mp.3 +mpexp mp.3 +mpextendedgcd mp.3 +mpfactorial mp.3 +mpfmt mp.3 +mpfree mp.3 +mpinvert mp.3 +mpleft mp.3 +mplowbits0 mp.3 +mpmagadd mp.3 +mpmagcmp mp.3 +mpmagsub mp.3 +mpmod mp.3 +mpmul mp.3 +mpnew mp.3 +mpnorm mp.3 +mprand mp.3 +mpright mp.3 +mpsetminbits mp.3 +mpsignif mp.3 +mpsub mp.3 +mptoa mp.3 +mptobe mp.3 +mptoi mp.3 +mptole mp.3 +mptoui mp.3 +mptouv mp.3 +mptov mp.3 +mpvecadd mp.3 +mpveccmp mp.3 +mpvecdigmuladd mp.3 +mpvecdigmulsub mp.3 +mpvecmul mp.3 +mpvecsub mp.3 +strtomp mp.3 +uitomp mp.3 +uvtomp mp.3 +vtomp mp.3 +muldiv muldiv.3 +umuldiv muldiv.3 +Mux mux.3 +mux mux.3 +muxinit mux.3 +muxrpc mux.3 +muxthreads mux.3 +Inf nan.3 +NaN nan.3 +isInf nan.3 +isNaN nan.3 +nan nan.3 +needstack needstack.3 +atnotify notify.3 +noted notify.3 +notedisable notify.3 +noteenable notify.3 +notify notify.3 +notifyoff notify.3 +notifyon notify.3 +close open.3 +create open.3 +open open.3 +opentemp opentemp.3 +pipe pipe.3 +Plumbmsg plumb.3 +eplumb plumb.3 +plumb plumb.3 +plumbaddattr plumb.3 +plumbdelattr plumb.3 +plumbfree plumb.3 +plumblookup plumb.3 +plumbopen plumb.3 +plumbopenfid plumb.3 +plumbpack plumb.3 +plumbpackattr plumb.3 +plumbrecv plumb.3 +plumbrecvfid plumb.3 +plumbsend plumb.3 +plumbsendtext plumb.3 +plumbsendtofid plumb.3 +plumbunpack plumb.3 +plumbunpackattr plumb.3 +plumbunpackpartial plumb.3 +post9pservice post9pservice.3 +postnote postnote.3 +DSAprimes prime.3 +genprime prime.3 +gensafeprime prime.3 +genstrongprime prime.3 +prime prime.3 +probably_prime prime.3 +smallprimetest prime.3 +fprint print.3 +print print.3 +runeseprint print.3 +runesmprint print.3 +runesnprint print.3 +runesprint print.3 +runevseprint print.3 +runevsmprint print.3 +runevsnprint print.3 +seprint print.3 +smprint print.3 +snprint print.3 +sprint print.3 +vfprint print.3 +vseprint print.3 +vsmprint print.3 +vsnprint print.3 +proto proto.3 +rdproto proto.3 +freeThumbprints pushtls.3 +initThumbprints pushtls.3 +okThumbprint pushtls.3 +pushtls pushtls.3 +readcert pushtls.3 +readcertchain pushtls.3 +tlsClient pushtls.3 +tlsServer pushtls.3 +qball qball.3 +mtoq quaternion.3 +qadd quaternion.3 +qdiv quaternion.3 +qinv quaternion.3 +qlen quaternion.3 +qmid quaternion.3 +qmul quaternion.3 +qneg quaternion.3 +qsqrt quaternion.3 +qsub quaternion.3 +qtom quaternion.3 +quaternion quaternion.3 +qunit quaternion.3 +slerp quaternion.3 +doquote quote.3 +needsrcquote quote.3 +quote quote.3 +quotefmtinstall quote.3 +quoterunestrdup quote.3 +quoterunestrfmt quote.3 +quotestrdup quote.3 +quotestrfmt quote.3 +unquoterunestrdup quote.3 +unquotestrdup quote.3 +fastrand rand.3 +frand rand.3 +lnrand rand.3 +lrand rand.3 +nfastrand rand.3 +nrand rand.3 +ntruerand rand.3 +rand rand.3 +srand rand.3 +truerand rand.3 +rc4 rc4.3 +rc4back rc4.3 +rc4skip rc4.3 +setupRC4state rc4.3 +pread read.3 +pwrite read.3 +read read.3 +readn read.3 +write read.3 +RGB readcolmap.3 +readcolmap readcolmap.3 +writecolmap readcolmap.3 +regcomp regexp.3 +regcomplit regexp.3 +regcompnl regexp.3 +regerror regexp.3 +regexec regexp.3 +regexp regexp.3 +regsub regexp.3 +rregexec regexp.3 +rregsub regexp.3 +regcomp regexp9.3 +regcomplit regexp9.3 +regcompnl regexp9.3 +regerror regexp9.3 +regexec regexp9.3 +regexp9 regexp9.3 +regsub regexp9.3 +rregexec regexp9.3 +rregsub regexp9.3 +rfork rfork.3 + +X509dump rsa.3 +X509gen rsa.3 +X509req rsa.3 +X509toRSApub rsa.3 +X509verify rsa.3 +asn1dump rsa.3 +asn1toRSApriv rsa.3 +decodepem rsa.3 +decodepemchain rsa.3 +rsa rsa.3 +rsadecrypt rsa.3 +rsaencrypt rsa.3 +rsafill rsa.3 +rsagen rsa.3 +rsaprivalloc rsa.3 +rsaprivfree rsa.3 +rsaprivtopub rsa.3 +rsapuballoc rsa.3 +rsapubfree rsa.3 +chartorune rune.3 +fullrune rune.3 +rune rune.3 +runelen rune.3 +runenlen rune.3 +runetochar rune.3 +utfecpy rune.3 +utflen rune.3 +utfnlen rune.3 +utfrrune rune.3 +utfrune rune.3 +utfutf rune.3 +runestrcat runestrcat.3 +runestrchr runestrcat.3 +runestrcmp runestrcat.3 +runestrcpy runestrcat.3 +runestrdup runestrcat.3 +runestrecpy runestrcat.3 +runestrlen runestrcat.3 +runestrncat runestrcat.3 +runestrncmp runestrcat.3 +runestrncpy runestrcat.3 +runestrrchr runestrcat.3 +runestrstr runestrcat.3 +openscsi scsi.3 +scsi scsi.3 +scsicmd scsi.3 +scsierror scsi.3 +scsiready scsi.3 +hmac_md5 sechash.3 +hmac_sha1 sechash.3 +md4 sechash.3 +md5 sechash.3 +md5pickle sechash.3 +md5unpickle sechash.3 +sechash sechash.3 +sha1 sechash.3 +sha1pickle sechash.3 +sha1unpickle sechash.3 +seek seek.3 +recvfd sendfd.3 +sendfd sendfd.3 +longjmp setjmp.3 +notejmp setjmp.3 +setjmp setjmp.3 +alarm sleep.3 +sleep sleep.3 +dirfstat stat.3 +dirfwstat stat.3 +dirstat stat.3 +dirwstat stat.3 +fstat stat.3 +fwstat stat.3 +nulldir stat.3 +stat stat.3 +wstat stat.3 +cistrcmp strcat.3 +cistrncmp strcat.3 +cistrstr strcat.3 +strcat strcat.3 +strchr strcat.3 +strcmp strcat.3 +strcpy strcat.3 +strcspn strcat.3 +strdup strcat.3 +strecpy strcat.3 +strlen strcat.3 +strncat strcat.3 +strncmp strcat.3 +strncpy strcat.3 +strpbrk strcat.3 +strrchr strcat.3 +strspn strcat.3 +strstr strcat.3 +strtok strcat.3 +s_alloc string.3 +s_allocinstack string.3 +s_append string.3 +s_array string.3 +s_copy string.3 +s_error string.3 +s_free string.3 +s_freeinstack string.3 +s_getline string.3 +s_grow string.3 +s_incref string.3 +s_memappend string.3 +s_nappend string.3 +s_new string.3 +s_newalloc string.3 +s_parse string.3 +s_putc string.3 +s_rdinstack string.3 +s_read string.3 +s_read_line string.3 +s_reset string.3 +s_restart string.3 +s_terminate string.3 +s_tolower string.3 +s_unique string.3 +string string.3 +runestringnwidth stringsize.3 +runestringsize stringsize.3 +runestringwidth stringsize.3 +stringnwidth stringsize.3 +stringsize stringsize.3 +stringwidth stringsize.3 +allocsubfont subfont.3 +freesubfont subfont.3 +installsubfont subfont.3 +lookupsubfont subfont.3 +mkfont subfont.3 +readsubfont subfont.3 +readsubfonti subfont.3 +stringsubfont subfont.3 +strsubfontwidth subfont.3 +subfont subfont.3 +subfontname subfont.3 +uninstallsubfont subfont.3 +writesubfont subfont.3 +sysfatal sysfatal.3 +alt thread.3 +chancreate thread.3 +chanfree thread.3 +chaninit thread.3 +chanprint thread.3 +chansetname thread.3 +mainstacksize thread.3 +nbrecv thread.3 +nbrecvp thread.3 +nbrecvul thread.3 +nbsend thread.3 +nbsendp thread.3 +nbsendul thread.3 +proccreate thread.3 +procdata thread.3 +recv thread.3 +recvp thread.3 +recvul thread.3 +send thread.3 +sendp thread.3 +sendul thread.3 +thread thread.3 +threadcreate thread.3 +threaddata thread.3 +threadexec thread.3 +threadexecl thread.3 +threadexits thread.3 +threadexitsall thread.3 +threadgetgrp thread.3 +threadgetname thread.3 +threadid thread.3 +threadint thread.3 +threadintgrp thread.3 +threadkill thread.3 +threadkillgrp thread.3 +threadlinklibrary thread.3 +threadmain thread.3 +threadnotify thread.3 +threadpid thread.3 +threadsetgrp thread.3 +threadsetname thread.3 +threadsetstate thread.3 +threadspawn thread.3 +threadwaitchan thread.3 +yield thread.3 +nsec time.3 +time time.3 +udpread udpread.3 +udpwrite udpread.3 +await wait.3 +awaitfor wait.3 +awaitnohang wait.3 +wait wait.3 +waitfor wait.3 +waitnohang wait.3 +waitpid wait.3 +drawresizewindow wctl.3 +drawsetlabel wctl.3 +drawtopwindow wctl.3 +wctl wctl.3 +Screen window.3 +allocscreen window.3 +allocwindow window.3 +bottomnwindows window.3 +bottomwindow window.3 +freescreen window.3 +originwindow window.3 +publicscreen window.3 +topnwindows window.3 +topwindow window.3 +window window.3 diff --git a/man/man3/abs.3 b/man/man3/abs.3 deleted file mode 100644 index 46dbd929..00000000 --- a/man/man3/abs.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH ABS 3 -.SH NAME -abs, labs \- integer absolute values -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.B -int abs(int a) -.PP -.B -long labs(long a) -.SH DESCRIPTION -.I Abs -returns -the absolute value of integer -.IR a , -and -.I labs -does the same for a long. -.SH SOURCE -.B /usr/local/plan9/src/libc/port/abs.c -.SH SEE ALSO -.IR floor (3) -for -.I fabs -.SH DIAGNOSTICS -.I Abs -and -.I labs -return -the most negative integer or long when the true result is unrepresentable. diff --git a/man/man3/allocimage.3 b/man/man3/allocimage.3 index 26365dce..e9da53a5 100644 --- a/man/man3/allocimage.3 +++ b/man/man3/allocimage.3 @@ -148,7 +148,7 @@ The field will be set to the number of bits per pixel specified by the channel descriptor (see -.IR image (6)). +.IR image (7)). .I Allocimage returns 0 if the server has run out of image memory. .PP @@ -214,7 +214,7 @@ values between image and user space or external files. There is a fixed format for the exchange and storage of image data (see -.IR image (6)). +.IR image (7)). .PP .I Unloadimage reads a rectangle of pixels from image @@ -271,7 +271,7 @@ but for bytes of compressed image .I data (see -.IR image (6)). +.IR image (7)). On each call to .IR cloadimage, the @@ -289,7 +289,7 @@ return the number of bytes copied. .PP .I Readimage creates an image from data contained in an external file (see -.IR image (6) +.IR image (7) for the file format); .I fd is a file descriptor obtained by opening such a file for reading. @@ -336,7 +336,7 @@ To allocate a single-pixel replicated image that may be used to paint a region r .IR graphics (3), .IR draw (3), .IR draw (3), -.IR image (6) +.IR image (7) .SH DIAGNOSTICS These functions return pointer 0 or integer \-1 on failure, usually due to insufficient memory. diff --git a/man/man3/arg.3 b/man/man3/arg.3 index 35e5914d..6f7bb929 100644 --- a/man/man3/arg.3 +++ b/man/man3/arg.3 @@ -121,4 +121,4 @@ prog -bffile1 -r -f file2 arg1 arg2 prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2' .PP .SH SOURCE -.B /sys/include/libc.h +.B /usr/local/plan9/include/libc.h diff --git a/man/man3/arith3.3 b/man/man3/arith3.3 new file mode 100644 index 00000000..faba4aa5 --- /dev/null +++ b/man/man3/arith3.3 @@ -0,0 +1,269 @@ +.TH ARITH3 3 +.SH NAME +add3, sub3, neg3, div3, mul3, eqpt3, closept3, dot3, cross3, len3, dist3, unit3, midpt3, lerp3, reflect3, nearseg3, pldist3, vdiv3, vrem3, pn2f3, ppp2f3, fff2p3, pdiv4, add4, sub4 \- operations on 3-d points and planes +.SH SYNOPSIS +.PP +.B +#include +.PP +.B +#include +.PP +.B +Point3 add3(Point3 a, Point3 b) +.PP +.B +Point3 sub3(Point3 a, Point3 b) +.PP +.B +Point3 neg3(Point3 a) +.PP +.B +Point3 div3(Point3 a, double b) +.PP +.B +Point3 mul3(Point3 a, double b) +.PP +.B +int eqpt3(Point3 p, Point3 q) +.PP +.B +int closept3(Point3 p, Point3 q, double eps) +.PP +.B +double dot3(Point3 p, Point3 q) +.PP +.B +Point3 cross3(Point3 p, Point3 q) +.PP +.B +double len3(Point3 p) +.PP +.B +double dist3(Point3 p, Point3 q) +.PP +.B +Point3 unit3(Point3 p) +.PP +.B +Point3 midpt3(Point3 p, Point3 q) +.PP +.B +Point3 lerp3(Point3 p, Point3 q, double alpha) +.PP +.B +Point3 reflect3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +Point3 nearseg3(Point3 p0, Point3 p1, Point3 testp) +.PP +.B +double pldist3(Point3 p, Point3 p0, Point3 p1) +.PP +.B +double vdiv3(Point3 a, Point3 b) +.PP +.B +Point3 vrem3(Point3 a, Point3 b) +.PP +.B +Point3 pn2f3(Point3 p, Point3 n) +.PP +.B +Point3 ppp2f3(Point3 p0, Point3 p1, Point3 p2) +.PP +.B +Point3 fff2p3(Point3 f0, Point3 f1, Point3 f2) +.PP +.B +Point3 pdiv4(Point3 a) +.PP +.B +Point3 add4(Point3 a, Point3 b) +.PP +.B +Point3 sub4(Point3 a, Point3 b) +.SH DESCRIPTION +These routines do arithmetic on points and planes in affine or projective 3-space. +Type +.B Point3 +is +.IP +.EX +.ta 6n +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +Routines whose names end in +.B 3 +operate on vectors or ordinary points in affine 3-space, represented by their Euclidean +.B (x,y,z) +coordinates. +(They assume +.B w=1 +in their arguments, and set +.B w=1 +in their results.) +.TF reflect3 +.TP +Name +Description +.TP +.B add3 +Add the coordinates of two points. +.TP +.B sub3 +Subtract coordinates of two points. +.TP +.B neg3 +Negate the coordinates of a point. +.TP +.B mul3 +Multiply coordinates by a scalar. +.TP +.B div3 +Divide coordinates by a scalar. +.TP +.B eqpt3 +Test two points for exact equality. +.TP +.B closept3 +Is the distance between two points smaller than +.IR eps ? +.TP +.B dot3 +Dot product. +.TP +.B cross3 +Cross product. +.TP +.B len3 +Distance to the origin. +.TP +.B dist3 +Distance between two points. +.TP +.B unit3 +A unit vector parallel to +.IR p . +.TP +.B midpt3 +The midpoint of line segment +.IR pq . +.TP +.B lerp3 +Linear interpolation between +.I p +and +.IR q . +.TP +.B reflect3 +The reflection of point +.I p +in the segment joining +.I p0 +and +.IR p1 . +.TP +.B nearseg3 +The closest point to +.I testp +on segment +.IR "p0 p1" . +.TP +.B pldist3 +The distance from +.I p +to segment +.IR "p0 p1" . +.TP +.B vdiv3 +Vector divide \(em the length of the component of +.I a +parallel to +.IR b , +in units of the length of +.IR b . +.TP +.B vrem3 +Vector remainder \(em the component of +.I a +perpendicular to +.IR b . +Ignoring roundoff, we have +.BR "eqpt3(add3(mul3(b, vdiv3(a, b)), vrem3(a, b)), a)" . +.PD +.PP +The following routines convert amongst various representations of points +and planes. Planes are represented identically to points, by duality; +a point +.B p +is on a plane +.B q +whenever +.BR p.x*q.x+p.y*q.y+p.z*q.z+p.w*q.w=0 . +Although when dealing with affine points we assume +.BR p.w=1 , +we can't make the same assumption for planes. +The names of these routines are extra-cryptic. They contain an +.B f +(for `face') to indicate a plane, +.B p +for a point and +.B n +for a normal vector. +The number +.B 2 +abbreviates the word `to.' +The number +.B 3 +reminds us, as before, that we're dealing with affine points. +Thus +.B pn2f3 +takes a point and a normal vector and returns the corresponding plane. +.TF reflect3 +.TP +Name +Description +.TP +.B pn2f3 +Compute the plane passing through +.I p +with normal +.IR n . +.TP +.B ppp2f3 +Compute the plane passing through three points. +.TP +.B fff2p3 +Compute the intersection point of three planes. +.PD +.PP +The names of the following routines end in +.B 4 +because they operate on points in projective 4-space, +represented by their homogeneous coordinates. +.TP +pdiv4 +Perspective division. Divide +.B p.w +into +.IR p 's +coordinates, converting to affine coordinates. +If +.B p.w +is zero, the result is the same as the argument. +.TP +add4 +Add the coordinates of two points. +.PD +.TP +sub4 +Subtract the coordinates of two points. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry +.SH "SEE ALSO +.IR matrix (3) diff --git a/man/man3/atof.3 b/man/man3/atof.3 index f242036e..f8d7c608 100644 --- a/man/man3/atof.3 +++ b/man/man3/atof.3 @@ -127,7 +127,7 @@ Therefore, it may be necessary to back up the input stream one character after calling .IR charstod . .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR fscanf (3) .SH DIAGNOSTICS diff --git a/man/man3/auth.3 b/man/man3/auth.3 deleted file mode 100644 index 1fe81f97..00000000 --- a/man/man3/auth.3 +++ /dev/null @@ -1,395 +0,0 @@ -.TH AUTH 3 -.SH NAME -amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users -.SH SYNOPSIS -.nf -.PP -.ft L -#include -#include -#include -.fi -.ta 11n +4n +4n +4n +4n +4n +4n -.PP -.B -int newns(char *user, char *nsfile); -.PP -.B -int addns(char *user, char *nsfile); -.PP -.B -int amount(int fd, char *old, int flag, char *aname); -.PP -.B -int login(char *user, char *password, char *namespace); -.PP -.B -int noworld(char *user); -.PP -.B -AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey, -.br -.B char *params); -.PP -.B -AuthRpc* auth_allocrpc(int afd); -.PP -.B -void auth_freerpc(AuthRpc *rpc); -.PP -.B -uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n); -.PP -.B -int auth_getkey(char *proto, char *dom); -.PP -.B -int (*amount_getkey)(char*, char*); -.PP -.B -void auth_freeAI(AuthInfo *ai); -.PP -.B -int auth_chuid(AuthInfo *ai, char *ns); -.PP -.B -Chalstate* auth_challenge(char *fmt, ...); -.PP -.B -AuthInfo* auth_response(Chalstate*); -.PP -.B -void auth_freechal(Chalstate*); -.PP -.B -int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...); -.PP -.B -AuthInfo* auth_userpasswd(char*user, char*password); -.PP -.B -UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...); -.PP -.B -AuthInfo* auth_getinfo(int fd); -.SH DESCRIPTION -.PP -This library, in concert with -.IR factotum (4), -is used to authenticate users. -It provides the primary interface to -.IR factotum . -.PP -.I Newns -builds a name space for -.IR user . -It opens the file -.I nsfile -.RB ( /lib/namespace -is used if -.I nsfile -is null), -copies the old environment, erases the current name space, -sets the environment variables -.B user -and -.BR home , -and interprets the commands in -.IR nsfile . -The format of -.I nsfile -is described in -.IR namespace (6). -.PP -.I Addns -also interprets and executes the commands in -.IR nsfile . -Unlike -.I newns -it applies the command to the current name space -rather than starting from scratch. -.PP -.I Amount -is like -.I mount -but performs any authentication required. -It should be used instead of -.I mount -whenever the file server being mounted requires authentication. -See -.IR bind (3) -for a definition of the arguments to -.I mount -and -.IR amount . -.PP -.I Login -changes the user id of the process -.I user -and recreates the namespace using the file -.I namespace -(default -.BR /lib/nnamespace ). -It uses -.I auth_userpassword -and -.IR auth_chuid . -.PP -.I Noworld -returns 1 if the user is in the group -.B noworld -in -.BR /adm/users . -Otherwise, it returns 0. -.I Noworld -is used by telnetd and ftpd to provide sandboxed -access for some users. -.PP -The following routines use the -.B AuthInfo -structure returned after a successful authentication by -.IR factotum (4). -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct -{ - char *cuid; /* caller id */ - char *suid; /* server id */ - char *cap; /* capability */ - int nsecret; /* length of secret */ - uchar *secret; /* secret */ -} AuthInfo; -.EE -.sp -The fields -.B cuid -and -.B suid -point to the authenticated ids of the client and server. -.B Cap -is a capability returned only to the server. -It can be passed to the -.IR cap (3) -device to change the user id of the process. -.B Secret -is an -.BR nsecret -byte -shared secret that can be used by the client and server to -create encryption and hashing keys for the rest of the -conversation. -.PP -.I Auth_proxy -proxies an authentication conversation between a remote -server reading and writing -.I fd -and a -.I factotum -file. The -.I factotum -file used is -.BR /mnt/factotum/rpc . -An -.B sprint -(see -.IR print (3)) -of -.I fmt -and the variable arg list yields a key template (see -.IR factotum (4)) -specifying the key to use. -The template must specify at least the protocol ( -.BI proto= xxx ) -and the role (either -.B role=client -or -.BR role=server ). -.I Auth_proxy -either returns an allocated -.B AuthInfo -structure, or sets the error string and -returns nil. -.PP -.I Fauth_proxy -can be used instead of -.I auth_proxy -if a single connection to -.I factotum -will be used for multiple authentications. -This is necessary, for example, for -.I newns -which must open the -.I factotum -file before wiping out the namespace. -.I Fauth_proxy -takes as an argument a pointer to an -.B AuthRPC -structure which contains an fd for an open connection to -.I factotum -in addition to storage and state information for -the protocol. -An -.B AuthRPC -structure is obtained by calling -.I auth_allocrpc -with the fd of an open -.I factotum -connection. -It is freed using -.IR auth_freerpc . -Individual commands can be sent to -.IR factotum (4) -by invoking -.IR auth_rpc . -.PP -Both -.I auth_proxy -and -.I fauth_proxy -take a pointer to a routine, -.IR getkey , -to invoke should -.I factotum -not posess a key for the authentication. If -.I getkey -is nil, the authentication fails. -.I Getkey -is called with a key template for the desired -key. -We have provided a generic routine, -.IR auth_getkey , -which queries the user for -the key information and passes it to -.IR factotum . -This is the default for the global variable, -.IR amount_getkey , -which holds a pointer to the key prompting routine used by -.IR amount . -.PP -.I Auth_chuid -uses the -.B cuid -and -.B cap -fields of an -.B AuthInfo -structure to change the user id of the current -process and uses -.IR ns , -default -.BR /lib/namespace , -to build it a new name space. -.PP -.I Auth_challenge -and -.I auth_response -perform challenge/response protocols with -.IR factotum . -State between the challenge and response phase are -kept in the -.B Chalstate -structure: -.sp -.EX -struct Chalstate -{ - char *user; - char chal[MAXCHLEN]; - int nchal; - void *resp; - int nresp; - -/* for implementation only */ - int afd; - AuthRpc *rpc; - char userbuf[MAXNAMELEN]; - int userinchal; -}; -.EE -.sp -.I Auth_challenge -requires a key template generated by an -.B sprint -of -.I fmt -and the variable arguments. It must contain the protocol -(\fBproto=\fIxxx\fR) -and depending on the protocol, the user name ( -.BI user= xxx \fR).\fP -.B P9cr -and -.B vnc -expect the user specified as an attribute in -the key template and -.BR apop , -.BR cram , -and -.BR chap -expect it in the -.B user -field of the arg to -.IR auth_response . -For all protocols, the response is returned -to -.I auth_response -in the -.I resp -field of the -.BR Chalstate . -.I Chalstate.nresp -must be the length of the response. -.PP -Supply to -.I auth_respond -a challenge string and the fmt and args specifying a key, -and it will use -.I factotum -to return the proper user and response. -.PP -.I Auth_userpasswd -verifies a simple user/password pair. -.I Auth_getuserpasswd -retrieves a user/password pair from -.I factotum -if permitted. -.PP -.I Auth_getinfo -reads an -.B AuthInfo -message from -.I fd -and converts it into a structure. It is only -used by the other routines in this library when -communicating with -.IR factotum . -.PP -.ne 8 -.EX -.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n -typedef struct UserPasswd { - char *user; - char *passwd; -} UserPasswd; -.EE -.sp -.PP -.I Auth_freeAI -is used to free an -.B AuthInfo -structure returned by one of these routines. -Similary -.I auth_freechal -frees a challenge/response state. -.SH SOURCE -.B /usr/local/plan9/src/libauth -.SH SEE ALSO -.IR factotum (4), -.IR authsrv (3), -.IR bind (3) -.SH DIAGNOSTICS -These routines set -.IR errstr . diff --git a/man/man3/authsrv.3 b/man/man3/authsrv.3 deleted file mode 100644 index c8f3330d..00000000 --- a/man/man3/authsrv.3 +++ /dev/null @@ -1,223 +0,0 @@ -.TH AUTHSRV 3 -.SH NAME -authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers -.SH SYNOPSIS -.nf -.PP -.ft L -#include -#include -#include -.fi -.ta 8n +4n +4n +4n +4n +4n +4n -.PP -.B -int authdial(char *netroot, char *ad); -.PP -.B -int passtokey(char key[DESKEYLEN], char *password) -.PP -.B -uchar nvcsum(void *mem, int len) -.PP -.B -int readnvram(Nvrsafe *nv, int flag); -.PPP -.B -int convT2M(Ticket *t, char *msg, char *key) -.PP -.B -void convM2T(char *msg, Ticket *t, char *key) -.PP -.B -int convA2M(Authenticator *a, char *msg, char *key) -.PP -.B -void convM2A(char *msg, Authenticator *a, char *key) -.PP -.B -int convTR2M(Ticketreq *tr, char *msg) -.PP -.B -void convM2TR(char *msg, Ticketreq *tr) -.PP -.B -int convPR2M(Passwordreq *pr, char *msg, char *key) -.PP -.B -void convM2PR(char *msg, Passwordreq *pr, char *key) -.PP -.B -int _asgetticket(int fd, char *trbuf, char *tbuf); -.PP -.B -int _asrdresp(int fd, char *buf, int len); -.SH DESCRIPTION -.PP -.I Authdial -dials an authentication server over the -network rooted at -.IR net , -default -.BR /net . -The authentication domain, -.IR ad , -specifies which server to call. -If -.I ad -is non-nil, -the connection server -.B cs -(see -.IR ndb (8)) -is queried for an entry which contains -.B authdom=\fIad\fP -or -.BR dom=\fIad\fP , -the former having precedence, -and which also contains an -.B auth -attribute. -The string dialed is then -.I netroot\fP!\fIserver\fP!ticket -where -.I server -is the value of the -.B auth -attribute. -If no entry is found, the error string is -set to ``no authentication server found'' -and -1 is returned. -If -.I authdom -is nil, the string -.IB netroot !$auth! ticket -is used to make the call. -.PP -.I Passtokey -converts -.I password -into a DES key and stores the result in -.IR key . -It returns 0 if -.I password -could not be converted, -and 1 otherwise. -.PP -.I Readnvram -reads authentication information into the structure: -.EX -.ta 4n +4n +8n +4n +4n +4n +4n - struct Nvrsafe - { - char machkey[DESKEYLEN]; - uchar machsum; - char authkey[DESKEYLEN]; - uchar authsum; - char config[CONFIGLEN]; - uchar configsum; - char authid[ANAMELEN]; - uchar authidsum; - char authdom[DOMLEN]; - uchar authdomsum; - }; -.EE -.PP -On Sparc, MIPS, and SGI machines this information is -in non-volatile ram, accessible in the file -.BR #r/nvram . -On x86s and Alphas -.I readnvram -successively opens the following areas stopping with the -first to succeed: -.PP -\- the partition named by the -.B $nvram -environment variable -(commonly set via -.IR plan9.ini (8)) -.br -\- the partition -.B #S/sdC0/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sdC0/9fat -.br -\- the partition -.B #S/sd00/nvram -.br -\- a file called -.B plan9.nvr -in the partition -.B #S/sd00/9fat -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 0 -.br -\- a file called -.B plan9.nvr -on a DOS floppy in drive 1 -.PP -The -.IR nvcsum s -of the fields -.BR machkey , -.BR authid , -and -.B authdom -must match their respective checksum or that field is zeroed. -If -.I flag -is -.B NVwrite -or at least one checksum fails and -.I flag -is -.BR NVwriteonerr , -.I readnvram -will prompt for new values on -.B #c/cons -and then write them back to the storage area. -.PP -.IR ConvT2M , -.IR convA2M , -.IR convTR2M , -and -.I convPR2M -convert tickets, authenticators, ticket requests, and password change request -structures into transmittable messages. -.IR ConvM2T , -.IR convM2A , -.IR convM2TR , -and -.I convM2PR -are used to convert them back. -.I Key -is used for encrypting the message before transmission and decrypting -after reception. -.PP -The routine -.I _asgetresp -receives either a character array or an error string. -On error, it sets errstr and returns -1. If successful, -it returns the number of bytes received. -.PP -The routine -.I _asgetticket -sends a ticket request message and then uses -.I _asgetresp -to recieve an answer. -.SH SOURCE -.B /usr/local/plan9/src/libauthsrv -.SH SEE ALSO -.IR passwd (1), -.IR cons (3), -.IR dial (3), -.IR authsrv (6), -.SH DIAGNOSTICS -These routines set -.IR errstr . -Integer-valued functions return -1 on error. diff --git a/man/man3/bio.3 b/man/man3/bio.3 index 7f6c05f3..8228dada 100644 --- a/man/man3/bio.3 +++ b/man/man3/bio.3 @@ -1,6 +1,6 @@ .TH BIO 3 .SH NAME -Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output +Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output .SH SYNOPSIS .ta \w'Biobuf* 'u .B #include @@ -10,7 +10,10 @@ Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetru .B #include .PP .B -Biobuf* Bopen(char *file, int mode) +Biobuf* Bopen(char *file, int mode) +.PP +.B +Biobuf* Bfdopen(int fd, int mode) .PP .B int Binit(Biobuf *bp, int fd, int mode) @@ -93,6 +96,17 @@ It calls .IR malloc (3) to allocate a buffer. .PP +.I Bfdopen +allocates a buffer for the already-open file descriptor +.I fd +for mode +.B OREAD +or +.BR OWRITE . +It calls +.IR malloc (3) +to allocate a buffer. +.PP .I Binit initializes a standard size buffer, type .IR Biobuf , @@ -312,7 +326,7 @@ written. .IR open (3), .IR print (3), .IR exits (3), -.IR utf (6), +.IR utf (7), .SH DIAGNOSTICS .I Bio routines that return integers yield diff --git a/man/man3/cachechars.3 b/man/man3/cachechars.3 index 46bff616..bb7a475d 100644 --- a/man/man3/cachechars.3 +++ b/man/man3/cachechars.3 @@ -4,7 +4,7 @@ cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities .SH SYNOPSIS .B #include .br -.B #include +.B #include .br .B #include .PP @@ -127,7 +127,7 @@ A .B Font consists of an overall height and ascent and a collection of subfonts together with the ranges of runes (see -.IR utf (6)) +.IR utf (7)) they represent. Fonts are described by the following structures. .IP @@ -306,8 +306,8 @@ for replacement when the cache is full. .IR allocimage (3), .IR draw (3), .IR subfont (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)). diff --git a/man/man3/cleanname.3 b/man/man3/cleanname.3 index 27818ef2..5568880e 100644 --- a/man/man3/cleanname.3 +++ b/man/man3/cleanname.3 @@ -29,6 +29,6 @@ Therefore .I filename must contain room for at least two bytes. .SH SOURCE -.B /usr/local/plan9/src/libc/port/cleanname.c +.B /usr/local/plan9/src/lib9/cleanname.c .SH SEE ALSO .IR cleanname (1) diff --git a/man/man3/color.3 b/man/man3/color.3 index 7d772b5e..aac61bd7 100644 --- a/man/man3/color.3 +++ b/man/man3/color.3 @@ -19,7 +19,7 @@ int cmap2rgba(int col) .SH DESCRIPTION These routines convert between `true color' red/green/blue triples and the Plan 9 color map. See -.IR color (6) +.IR color (7) for a description of RGBV, the standard color map. .PP .I Rgb2cmap @@ -52,5 +52,5 @@ take colors as arguments. .IR graphics (3), .IR allocimage (3), .IR draw (3), -.IR image (6), -.IR color (6) +.IR image (7), +.IR color (7) diff --git a/man/man3/complete.3 b/man/man3/complete.3 index b1478ddc..dc74050d 100644 --- a/man/man3/complete.3 +++ b/man/man3/complete.3 @@ -1,6 +1,6 @@ .TH COMPLETE 3 .SH NAME -complete \- file name completion +complete, freecompletion \- file name completion .SH SYNOPSIS .B #include .br diff --git a/man/man3/cputime.3 b/man/man3/cputime.3 index 5acf671a..c88340d8 100644 --- a/man/man3/cputime.3 +++ b/man/man3/cputime.3 @@ -24,11 +24,5 @@ child processes in user code, and child processes in system calls. returns the sum of those same times, converted to seconds. .I Times returns the elapsed real time, in milliseconds, that the process has been running. -.PP -These functions read -.BR /dev/cputime , -opening that file when they are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 00000000..ef3ae111 --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,98 @@ +.TH CTIME 3 +.SH NAME +ctime, localtime, gmtime, asctime, tm2sec, timezone \- convert date and time +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* 'u +.B +char* ctime(long clock) +.PP +.B +Tm* localtime(long clock) +.PP +.B +Tm* gmtime(long clock) +.PP +.B +char* asctime(Tm *tm) +.PP +.B +long tm2sec(Tm *tm) +.SH DESCRIPTION +.I Ctime +converts a time +.I clock +such as returned by +.IR time (3) +into +.SM ASCII +(sic) +and returns a pointer to a +30-byte string +in the following form. +All the fields have constant width. +.PP +.B + Wed Aug 5 01:07:47 EST 1973\en\e0 +.PP +.I Localtime +and +.I gmtime +return pointers to structures containing +the broken-down time. +.I Localtime +corrects for the time zone and possible daylight savings time; +.I gmtime +converts directly to GMT. +.I Asctime +converts a broken-down time to +.SM ASCII +and returns a pointer +to a 30-byte string. +.IP +.EX +.ta 6n +\w'char 'u +\w'zone[4]; 'u +typedef +struct { + int sec; /* seconds (range 0..59) */ + int min; /* minutes (0..59) */ + int hour; /* hours (0..23) */ + int mday; /* day of the month (1..31) */ + int mon; /* month of the year (0..11) */ + int year; /* year A.D. \- 1900 */ + int wday; /* day of week (0..6, Sunday = 0) */ + int yday; /* day of year (0..365) */ + char zone[4]; /* time zone name */ + int tzoff; /* time zone delta from GMT */ +} Tm; +.EE +.PP +.I Tm2sec +converts a broken-down time to +seconds since the start of the epoch. +It ignores +.BR wday , +and assumes the local time zone +if +.B zone +is not +.BR GMT . +.SH SOURCE +.B /usr/local/plan9/src/lib9/date.c +.br +.B /usr/local/plan9/src/lib9/ctime.c +.SH "SEE ALSO" +.IR date (1), +.IR time (3) +.SH BUGS +The return values point to static data +whose content is overwritten by each call. +.br +Daylight Savings Time is ``normal'' in the Southern hemisphere. +.br +These routines are not equipped to handle non-\c +.SM ASCII +text, and are provincial anyway. diff --git a/man/man3/dial.3 b/man/man3/dial.3 index b26e65c6..51102273 100644 --- a/man/man3/dial.3 +++ b/man/man3/dial.3 @@ -1,6 +1,6 @@ .TH DIAL 3 .SH NAME -dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections +dial, hangup, announce, listen, accept, reject, netmkaddr, dialparse \- make and break network connections .SH SYNOPSIS .B #include .br @@ -10,9 +10,6 @@ dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetcon int dial(char *addr, char *local, char *dir, int *cfdp) .PP .B -int hangup(int ctl) -.PP -.B int announce(char *addr, char *dir) .PP .B @@ -26,15 +23,18 @@ int reject(int ctl, char *dir, char *cause) .PP .B char* netmkaddr(char *addr, char *defnet, char *defservice) +.\" .PP +.\" .B +.\" void setnetmtpt(char *to, int tolen, char *from) +.\" .PP +.\" .B +.\" NetConnInfo* getnetconninfo(char *conndir, int fd) +.\" .PP +.\" .B +.\" void freenetconninfo(NetConnINfo*) .PP .B -void setnetmtpt(char *to, int tolen, char *from) -.PP -.B -NetConnInfo* getnetconninfo(char *conndir, int fd) -.PP -.B -void freenetconninfo(NetConnINfo*) +int dialparse(char *addr, char **net, char **unix, u32int *host, int *port) .SH DESCRIPTION For these routines, .I addr @@ -44,8 +44,10 @@ is a network address of the form or simply .IR netaddr . .I Network -is any directory listed in -.B /net +is +.BR tcp , +.BR udp , +.BR unix , or the special token, .BR net . .B Net @@ -53,45 +55,28 @@ is a free variable that stands for any network in common between the source and the host .IR netaddr . .I Netaddr -can be a host name, a domain name, a network address, -or a meta-name of the form -.BI $ attribute\f1, -which -is replaced by -.I value -from the value-attribute pair -.IB attribute = value -most closely associated with the source host in the -network data base (see -.IR ndb (6)). +can be a host name, a domain name, or a network address. +.\" or a meta-name of the form +.\" .BI $ attribute\f1, +.\" which +.\" is replaced by +.\" .I value +.\" from the value-attribute pair +.\" .IB attribute = value +.\" most closely associated with the source host in the +.\" network data base (see +.\" .IR ndb (6)). .PP -If a connection attempt is successful and +On Plan 9, the .I dir -is non-zero, -the path name of a +argument is a path name to a .I line directory -that has files for accessing the connection -is copied into -.IR dir . -The path name is guaranteed to be less than 40 -bytes long. -One line directory exists for each possible connection. -The -.B data -file in the line directory should be used to communicate with the destination. -The -.B ctl -file in the line directory can be used to send commands to the line. -See -.IR ip (3) -for messages that can be written to the -.B ctl -file. -The last close of the -.B data -or -.B ctl -file will close the connection. +that has files for accessing the connection. +To keep the same function signatures, +the Unix port of these routines uses strings of the form +.BI /dev/fd/ n +instead of line directory paths. +These strings should be treated as opaque data and ignored. .PP .I Dial makes a call to destination @@ -111,26 +96,19 @@ file in the line directory. The .B addr file in the line directory contains the address called. -If the network allows the local address to be set, -as is the case with UDP and TCP port numbers, and -.IR local -is non-zero, the local address will be set to -.IR local . -If +.\" If the network allows the local address to be set, +.\" as is the case with UDP and TCP port numbers, and +.\" .IR local +.\" is non-zero, the local address will be set to +.\" .IR local . +.IR Dial 's +.IR local , +.IR dir , +and .I cfdp -is non-zero, -.BI * cfdp -is set to a file descriptor open for reading and -writing the control file. +arguments +are not supported and must be zero. .PP -.I Hangup -is a means of forcing a connection to hang up without -closing the -.B ctl -and -.B data -files. -.P .I Announce and .I listen @@ -181,73 +159,78 @@ It takes an address along with a default network and service to use if they are not specified in the address. It returns a pointer to static data holding the actual address to use. .PP -.I Getnetconninfo -returns a structure containing information about a -network connection. The structure is: -.EX - typedef struct NetConnInfo NetConnInfo; - struct NetConnInfo - { - char *dir; /* connection directory */ - char *root; /* network root */ - char *spec; /* binding spec */ - char *lsys; /* local system */ - char *lserv; /* local service */ - char *rsys; /* remote system */ - char *rserv; /* remote service */ - }; -.EE -.PP -The information is obtained from the connection directory, -.IR conndir . -If -.I conndir -is nil, the directory is obtained by performing -.IR fd2path (3) -on -.IR fd . -.I Getnetconninfo -returns either a completely specified structure, or -nil if either the structure can't be allocated or the -network directory can't be determined. -The structure -is freed using -.IR freenetconninfo . -.PP -.I Setnetmtpt -copies the name of the network mount point into -the buffer -.IR to , -whose length is -.IR tolen . -It exists to merge two pre-existing conventions for specifying -the mount point. -Commands that take a network mount point as a parameter -(such as -.BR dns , -.BR cs -(see -.IR ndb (8)), -and -.IR ipconfig (8)) -should now call -.IR setnetmtpt . -If -.I from -is -.BR nil , -the mount point is set to the default, -.BR /net . -If -.I from -points to a string starting with a slash, -the mount point is that path. -Otherwise, the mount point is the string pointed to by -.I from -appended to the string -.BR /net . -The last form is obsolete and is should be avoided. -It exists only to aid in conversion. +.I Dialparse +parses a network address as described above +into a network name, a Unix domain socket address, +an IPv4 host address, and an IPv4 port number. +.\" .PP +.\" .I Getnetconninfo +.\" returns a structure containing information about a +.\" network connection. The structure is: +.\" .EX +.\" typedef struct NetConnInfo NetConnInfo; +.\" struct NetConnInfo +.\" { +.\" char *dir; /* connection directory */ +.\" char *root; /* network root */ +.\" char *spec; /* binding spec */ +.\" char *lsys; /* local system */ +.\" char *lserv; /* local service */ +.\" char *rsys; /* remote system */ +.\" char *rserv; /* remote service */ +.\" }; +.\" .EE +.\" .PP +.\" The information is obtained from the connection directory, +.\" .IR conndir . +.\" If +.\" .I conndir +.\" is nil, the directory is obtained by performing +.\" .IR fd2path (3) +.\" on +.\" .IR fd . +.\" .I Getnetconninfo +.\" returns either a completely specified structure, or +.\" nil if either the structure can't be allocated or the +.\" network directory can't be determined. +.\" The structure +.\" is freed using +.\" .IR freenetconninfo . +.\" .PP +.\" .I Setnetmtpt +.\" copies the name of the network mount point into +.\" the buffer +.\" .IR to , +.\" whose length is +.\" .IR tolen . +.\" It exists to merge two pre-existing conventions for specifying +.\" the mount point. +.\" Commands that take a network mount point as a parameter +.\" (such as +.\" .BR dns , +.\" .BR cs +.\" (see +.\" .IR ndb (8)), +.\" and +.\" .IR ipconfig (8)) +.\" should now call +.\" .IR setnetmtpt . +.\" If +.\" .I from +.\" is +.\" .BR nil , +.\" the mount point is set to the default, +.\" .BR /net . +.\" If +.\" .I from +.\" points to a string starting with a slash, +.\" the mount point is that path. +.\" Otherwise, the mount point is the string pointed to by +.\" .I from +.\" appended to the string +.\" .BR /net . +.\" The last form is obsolete and is should be avoided. +.\" It exists only to aid in conversion. .SH EXAMPLES Make a call and return an open file descriptor to use for communications: @@ -259,12 +242,13 @@ int callkremvax(void) } .EE .PP -Call the local authentication server: +Connect to a Unix socket served by +.IR acme (4): .IP .EX -int dialauth(char *service) +int dialacme(void) { - return dial(netmkaddr("$auth", 0, service), 0, 0, 0); + return dial("unix!/tmp/ns.ken.:0/acme", 0, 0, 0); } .EE .PP @@ -315,17 +299,14 @@ bekremvax(void) } .EE .SH SOURCE -.BR /usr/local/plan9/src/libc/9sys , -.B /usr/local/plan9/src/libc/port -.SH "SEE ALSO" -.IR auth (3), -.IR ip (3), -.IR ndb (8) +.B /usr/local/plan9/src/lib9/dial.c +.br +.B /usr/local/plan9/src/lib9/announce.c +.br +.B /usr/local/plan9/src/lib9/_p9dialparse.c .SH DIAGNOSTICS .IR Dial , .IR announce , and .I listen return \-1 if they fail. -.I Hangup -returns nonzero if it fails. diff --git a/man/man3/dirread.3 b/man/man3/dirread.3 index 4258509a..ac83edf1 100644 --- a/man/man3/dirread.3 +++ b/man/man3/dirread.3 @@ -62,7 +62,7 @@ always returns complete .B Dir structures. See -.IR read (5) +.IR read (9p) for more information. .PP The constant @@ -83,7 +83,7 @@ structures filled in .BR buf . The file offset is advanced by the number of bytes actually read. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/dirread.c +.B /usr/local/plan9/src/lib9/dirread.c .SH SEE ALSO .IR intro (3), .IR open (3), diff --git a/man/man3/disk.3 b/man/man3/disk.3 new file mode 100644 index 00000000..30e4440a --- /dev/null +++ b/man/man3/disk.3 @@ -0,0 +1,177 @@ +.TH DISK 3 +.SH NAME +opendisk, Disk \- generic disk device interface +.SH SYNOPSIS +.nf +.ft L +#include +#include +#include +.ft +.PP +.ft L +typedef struct Disk { + char *prefix; + char part[NAMELEN]; + int fd, wfd, ctlfd, rdonly; + int type; + vlong secs, secsize, size, offset; + int c, h, s; +} Disk; +.ft +.PP +.B +Disk* opendisk(char *file, int rdonly, int noctl) +.SH DESCRIPTION +These routines provide a simple way to gather +and use information about +disks and disk partitions, +as well as plain files. +.PP +.I Opendisk +opens +.I file +for reading and stores the file descriptor in +the +.B fd +field of the +.B Disk +structure. +If +.I rdonly +is not set, +.I opendisk +also opens +.I file +for writing and stores that file descriptor in +.BR wfd . +The two file descriptors are kept separate to +help prevent accidents. +.PP +If +.I noctl +is not set, +.I opendisk +looks for a +.B ctl +file in the same directory as the +disk file; +if it finds one, it declares +the disk to be +an +.I sd +device, +setting the +.B type +field in the +.B Disk +structure +to +.BR Tsd . +If the passed +.I file +is named +.BI fd n disk \fR, +it looks for a file +.BI fd n ctl \fR, +and if it finds that, +declares the disk to be +a floppy disk, of type +.BR Tfloppy . +If either +control +file is found, it is opened for reading +and writing, and the resulting file descriptor +is saved as +.BR ctlfd . +Otherwise the returned disk +has type +.BR Tfile . +.PP +.I Opendisk +then stats the file and stores its length in +.BR size . +If the disk is an +.I sd +partition, +.I opendisk +reads the sector size from the +control +file and stores it in +.BR secsize ; +otherwise the sector size is assumed to be 512, +as is the case for floppy disks. +.I Opendisk +then stores the disk size measured in sectors in +.BR secs . +.PP +If the disk is an +.I sd +partition, +.I opendisk +parses the +control +file to find the partition's offset +within its disk; +otherwise it sets +.B offset +to zero. +If the disk is an ATA disk, +.I opendisk +reads +the disk geometry (number of cylinders, heads, and sectors) +from the +.B geometry +line in the +.I sd +control file; +otherwise it sets these to zero as well. +.B Name +is initialized with the base name of +the disk partition, and is useful for forming messages to the +.I sd +control file. +.B Prefix +is set to the passed filename without +the +.B name +suffix. +.PP +The IBM PC BIOS interface allocates +10 bits for the number of cylinders, 8 for +the number of heads, and 6 for the number of sectors per track. +Disk geometries are not quite so simple +anymore, but to keep the interface useful, +modern disks and BIOSes present geometries +that still fit within these constraints. +These numbers are still used when partitioning +and formatting disks. +.I Opendisk +employs a number of heuristics to discover this +supposed geometry and store it in the +.BR c , +.BR h , +and +.B s +fields. +Disk offsets in partition tables and +in FAT descriptors are stored in a form +dependent upon these numbers, so +.I opendisk +works hard to report numbers that +agree with those used by other operating +systems; the numbers bear little or no resemblance +to reality. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/disk.c +.SH SEE ALSO +Plan 9's +\fIfloppy\fR(3) and \fIsd\fR(3) +.SH BUGS +Disks on Unix systems do not present the interface +that +.I opendisk +expects, so +.I opendisk +will give them type +.BR Tfile . diff --git a/man/man3/draw.3 b/man/man3/draw.3 index 6ad6d375..be5e6c64 100644 --- a/man/man3/draw.3 +++ b/man/man3/draw.3 @@ -1,10 +1,14 @@ .TH DRAW 3 .SH NAME -Image, draw, gendraw, drawreplxy, drawrepl, -replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse, -fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn, -runestring, runestringn, stringbg, stringnbg, runestringbg, -runestringnbg, _string, ARROW, drawsetdebug \- graphics functions +Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl, +replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop, +bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop, +fillbezspline, fillbezsplineop, ellipse, ellipseop, +fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop, +icossin, icossin2, border, string, stringop, stringn, stringnop, +runestring, runestringop, runestringn, runestringnop, stringbg, +stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop, +runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug \- graphics functions .de PB .PP .ft L @@ -252,7 +256,7 @@ The clipping region may be modified dynamically using .TP .B chan The pixel channel format descriptor, as described in -.IR image (6). +.IR image (7). The value should not be modified after the image is created. .TP .B depth @@ -805,8 +809,8 @@ is non-zero. .SH SEE ALSO .IR graphics (3), .IR stringsize (3), -.IR color (6), -.IR utf (6), +.IR color (7), +.IR utf (7), .IR addpt (3) .PP T. Porter, T. Duff. diff --git a/man/man3/dsa.3 b/man/man3/dsa.3 index b1af55e0..f95ca771 100644 --- a/man/man3/dsa.3 +++ b/man/man3/dsa.3 @@ -79,7 +79,9 @@ a key is created using a new and .B q generated by -.IR DSAprimes (3). +.IR DSAprimes +(see +.IR prime (3)). Otherwise, .B p and diff --git a/man/man3/dup.3 b/man/man3/dup.3 index e3cee43b..3c7312d7 100644 --- a/man/man3/dup.3 +++ b/man/man3/dup.3 @@ -25,18 +25,14 @@ will use for the new file descriptor (closing any old file associated with .IR newfd ). -File descriptors are allocated dynamically, -so to prevent unwarranted growth of the file descriptor table, -.I dup -requires that -.I newfd -be no greater than 20 more than the highest file descriptor ever used by -the program. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR intro (3), -.IR dup (3) +.B /usr/local/plan9/src/lib9/dup.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +.I Dup +is a macro for +.I p9dup +to avoid name conflicts with the Unix function; see +.IR intro (3). diff --git a/man/man3/encode.3 b/man/man3/encode.3 index 1a93e37b..44c6afd5 100644 --- a/man/man3/encode.3 +++ b/man/man3/encode.3 @@ -80,6 +80,6 @@ For example, to display a 15 byte array as hex: .EE .SH SOURCE -.B /usr/local/plan9/src/libc/port/u32.c +.B /usr/local/plan9/src/lib9/u32.c .br -.B /usr/local/plan9/src/libc/port/u64.c +.B /usr/local/plan9/src/lib9/u64.c diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 deleted file mode 100644 index 50d00bfb..00000000 --- a/man/man3/encrypt.3 +++ /dev/null @@ -1,76 +0,0 @@ -.TH ENCRYPT 3 -.SH NAME -encrypt, decrypt, netcrypt \- DES encryption -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.B -int encrypt(void *key, void *data, int len) -.PP -.B -int decrypt(void *key, void *data, int len) -.PP -.B -int netcrypt(void *key, void *data) -.SH DESCRIPTION -.I Encrypt -and -.I decrypt -perform DES encryption and decryption. -.I Key -is an array of -.B DESKEYLEN -(defined as 7 in -.BR ) -bytes containing the encryption key. -.I Data -is an array of -.I len -bytes; -it must be at least 8 bytes long. -The bytes are encrypted or decrypted in place. -.PP -The DES algorithm encrypts an individual 8-byte block of data. -.I Encrypt -uses the following method to encrypt data longer than 8 bytes. -The first 8 bytes are encrypted as usual. -The last byte of the encrypted result -is prefixed to the next 7 unencrypted bytes to make the next 8 -bytes to encrypt. -This is repeated until fewer than 7 bytes remain unencrypted. -Any remaining unencrypted bytes are encrypted with enough of the preceding -encrypted bytes to make a full 8-byte block. -.I Decrypt -uses the inverse algorithm. -.PP -.I Netcrypt -performs the same encryption as a SecureNet Key. -.I Data -points to an -.SM ASCII -string of decimal digits with numeric value between 0 and 10000. -These digits are copied into an 8-byte buffer with trailing binary zero fill -and encrypted as one DES block. -The first four bytes are each formatted as two digit -.SM ASCII -hexadecimal numbers, -and the string is copied into -.IR data . -.SH SOURCE -.B /usr/local/plan9/src/libc/port -.SH DIAGNOSTICS -These routines return 1 if the data was encrypted, -and 0 if the encryption fails. -.I Encrypt -and -.I decrypt -fail if the data passed is less than 8 bytes long. -.I Netcrypt -can fail if it is passed invalid data. -.SH SEE ALSO -.IR securenet (8) -.SH BUGS -The implementation is broken in a way that makes -it unsuitable for anything but authentication. diff --git a/man/man3/errstr.3 b/man/man3/errstr.3 index 1a888978..a0e6d3f0 100644 --- a/man/man3/errstr.3 +++ b/man/man3/errstr.3 @@ -73,13 +73,35 @@ a string to pass to The string returned from .I errstr is discarded. +.PP +The error string is maintained in parallel with the Unix +error number +.IR errno . +Changing +.I errno +will reset the error string, +and changing the error string via +.I errstr +or +.I werrstr +will reset +.IR errno . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/werrstr.c +.B /usr/local/plan9/src/lib9/errstr.c .SH DIAGNOSTICS .I Errstr always returns 0. .SH SEE ALSO .IR intro (3), .IR perror (3) +.SH BUGS +The implementation sets +.I errno +to the (somewhat arbitrary) +constant 0x19283745 when +the error string is valid. +When +.I errno +is set to other values, the error string +is synthesized using +.IR strerror (3). diff --git a/man/man3/event.3 b/man/man3/event.3 index 7982b70a..e0299811 100644 --- a/man/man3/event.3 +++ b/man/man3/event.3 @@ -138,9 +138,9 @@ event mechanism and put in a queue. .I Ekbd returns the next rune from the queue, blocking until the queue is non-empty. -The characters are read in raw mode -(see -.IR cons (3)), +The characters are read in raw mode, +.\" (see +.\" .IR cons (3)), so they are available as soon as a complete rune is typed. .PP When the mouse moves or a mouse button is pressed or released, @@ -380,5 +380,5 @@ is nil, it restores the image to the default arrow. .IR rio (1), .IR graphics (3), .IR plumb (3), -.IR cons (3), +.\" .IR cons (3), .IR draw (3) diff --git a/man/man3/exec.3 b/man/man3/exec.3 index 48868616..285af111 100644 --- a/man/man3/exec.3 +++ b/man/man3/exec.3 @@ -1,6 +1,6 @@ .TH EXEC 3 .SH NAME -exec, execl, _clock, _privates, _nprivates \- execute a file +exec, execl \- execute a file .SH SYNOPSIS .B #include .br @@ -12,15 +12,6 @@ int exec(char *name, char* argv[]) .PP .B int execl(char *name, ...) -.PP -.B -long *_clock; -.PP -.B -void **_privates; -.PP -.B -int _nprivates; .fi .SH DESCRIPTION .I Exec @@ -35,10 +26,8 @@ to be executed; it must not be a directory, and the permissions must allow the current user to execute it (see .IR stat (3)). -It should also be a valid binary image, as defined in the -.IR a.out (6) -for the current machine architecture, -or a shell script +It should also be a valid binary image, as defined by the local +operating system, or a shell script (see .IR rc (1)). The first line of a @@ -106,45 +95,17 @@ into the open mode; see .IR open (3)); and the working directory and environment (see -.IR env (3)) +.IR getenv (3)) remain the same. However, a newly .I exec'ed -process has no notification handler +process has no notification handlers (see .IR notify (3)). -.PP -When the new program begins, the global cell -.B _clock -is set to the address of a cell that keeps approximate time -expended by the process at user level. -The time is measured in milliseconds but is updated at -a system-dependent lower rate. -This clock is typically used by the profiler but is available -to all programs. -.PP -The global cell -.B _privates -points to an array of -.B _nprivates -elements of per-process private data. -This storage is private for each process, even if the processes share data segments. -.PP -The above conventions apply to C programs; the raw system -interface to the new image is as follows: -the word pointed to by the stack pointer is -.BR argc ; -the words beyond that are the zeroth and subsequent elements -of -.BR argv , -followed by a terminating null pointer; and -the return register (e.g. -.B R0 -on the 68020) contains the address of the clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/exec.c .br -.B /usr/local/plan9/src/libc/port/execl.c +.B /usr/local/plan9/src/lib9/execl.c .SH SEE ALSO .IR prof (1), .IR intro (3), @@ -157,3 +118,13 @@ There can be no return from a successful or .IR execl ; the calling image is lost. +.SH BUGS +On Unix, unlike on Plan 9, +.I exec +and +.I execl +use the user's current path to locate +.IR prog . +This is a clumsy way to deal with Unix's lack of +a union directory for +.BR /bin . diff --git a/man/man3/exits.3 b/man/man3/exits.3 index 2591ff11..95e2b935 100644 --- a/man/man3/exits.3 +++ b/man/man3/exits.3 @@ -22,7 +22,10 @@ void atexitdont(void(*)(void)) .I Exits is the conventional way to terminate a process. .I _Exits -is the underlying system call. +also terminates a process but does not call the registered +.I atexit +handlers +.RI ( q.v. ). They can never return. .PP @@ -75,7 +78,18 @@ returns 0 if that limit has been reached. .I Atexitdont cancels a previous registration of an exit function. .SH SOURCE -.B /usr/local/plan9/src/libc/port/atexit.c +.B /usr/local/plan9/src/lib9/atexit.c +.br +.B /usr/local/plan9/src/lib9/_exits.c .SH "SEE ALSO" -.IR fork (3), +.IR fork (2), .IR wait (3) +.SH BUGS +Because of limitations of Unix, the exit status of a +process can only be an 8-bit integer. +Exit status 0 is used for empty exit messages, and 1 for +non-empty messages. +.PP +Exit codes 97 through 99 are used by the thread library to signal +internal synchronization errors between the main program +and a proxy process that implements backgrounding. diff --git a/man/man3/fcall.3 b/man/man3/fcall.3 index 2e09ddac..1143217d 100644 --- a/man/man3/fcall.3 +++ b/man/man3/fcall.3 @@ -303,7 +303,7 @@ and .I buf should include the second two-byte (16-bit) length field that precedes the entry when formatted in a 9P message (see -.IR stat (5)); +.IR stat (9p)); in other words, .I nbuf is 2 plus the sum of the sizes of the entry itself. @@ -349,9 +349,9 @@ multiple times, if necessary, to read an entire 9P message into The return value is 0 for end of file, or -1 for error; it does not return partial messages. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), .IR 9p (3), .IR stat (3), -.IR intro (5) +.IR intro (9p) diff --git a/man/man3/fmtinstall.3 b/man/man3/fmtinstall.3 index cc4884a8..8a437f10 100644 --- a/man/man3/fmtinstall.3 +++ b/man/man3/fmtinstall.3 @@ -297,12 +297,12 @@ formats the system error string. All these routines return zero for successful execution. Conversion routines that call these functions will work properly regardless of whether the output is bytes or runes. -.PP -.IR 2c (1) -describes the C directive -.B #pragma -.B varargck -that can be used to provide type-checking for custom print verbs and output routines. +.\" .PP +.\" .IR 2c (1) +.\" describes the C directive +.\" .B #pragma +.\" .B varargck +.\" that can be used to provide type-checking for custom print verbs and output routines. .SH EXAMPLES This function prints an error message with a variable number of arguments and then quits. @@ -362,10 +362,10 @@ main(...) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/fmt +.B /usr/local/plan9/src/lib9/fmt .SH SEE ALSO .IR print (3), -.IR utf (6), +.IR utf (7), .IR errstr (3) .SH DIAGNOSTICS These routines return negative numbers or nil for errors and set diff --git a/man/man3/fork.3 b/man/man3/fork.3 deleted file mode 100644 index e17f0d67..00000000 --- a/man/man3/fork.3 +++ /dev/null @@ -1,166 +0,0 @@ -.TH FORK 3 -.SH NAME -fork, rfork \- manipulate process resources -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.nf -.B -int fork(void) -.PP -.B -int rfork(int flags) -.fi -.SH DESCRIPTION -Forking is the only way new processes are created. -The -.I flags -argument to -.I rfork -selects which resources of the -invoking process (parent) are shared -by the new process (child) or initialized to -their default values. -The resources include -the file name space, -the open file descriptor table (which, when shared, permits processes -to open and close files for other processes), -the set of environment variables -(see -.IR env (3)), -the note group -(the set of processes that receive notes written to a member's -.B notepg -file; -see -.IR proc (3)), -the set of rendezvous tags -(see -.IR rendezvous (3)); -and open files. -.I Flags -is the logical OR of some subset of -.TF RFCNAMEG -.TP -.B RFPROC -If set a new process is created; otherwise changes affect the -current process. -.TP -.B RFNOWAIT -If set, the child process will be dissociated from the parent. Upon -exit the child will leave no -.B Waitmsg -(see -.IR wait (3)) -for the parent to collect. -.TP -.B RFNAMEG -If set, the new process inherits a copy of the parent's name space; -otherwise the new process shares the parent's name space. -Is mutually exclusive with -.BR RFCNAMEG . -.TP -.B RFCNAMEG -If set, the new process starts with a clean name space. A new -name space must be built from a mount of an open file descriptor. -Is mutually exclusive with -.BR RFNAMEG . -.TP -.B RFNOMNT -If set, subsequent mounts into the new name space and dereferencing -of pathnames starting with -.B # -are disallowed. -.TP -.B RFENVG -If set, the environment variables are copied; -otherwise the two processes share environment variables. -Is mutually exclusive with -.BR RFCENVG . -.TP -.B RFCENVG -If set, the new process starts with an empty environment. -Is mutually exclusive with -.BR RFENVG . -.TP -.B RFNOTEG -Each process is a member of a group of processes that all -receive notes when a note is written to any of their -.B notepg -files (see -.IR proc (3)). -The group of a new process is by default the same as its parent, but if -.B RFNOTEG -is set (regardless of -.BR RFPROC ), -the process becomes the first in a new group, isolated from -previous processes. -.TP -.B RFFDG -If set, the invoker's file descriptor table (see -.IR intro (3)) -is copied; otherwise the two processes share a -single table. -.TP -.B RFCFDG -If set, the new process starts with a clean file descriptor table. -Is mutually exclusive with -.BR RFFDG . -.TP -.B RFREND -If set, the process will be unable to -.IR rendezvous (3) -with any of its ancestors; its children will, however, be able to -.B rendezvous -with it. In effect, -.B RFREND -makes the process the first in a group of processes that share a space for -.B rendezvous -tags. -.TP -.B RFMEM -If set, the child and the parent will share -.B data -and -.B bss -segments. -Otherwise, the child inherits a copy of those segments. -Other segment types, in particular stack segments, will be unaffected. -May be set only with -.BR RFPROC . -.PD -.PP -File descriptors in a shared file descriptor table are kept -open until either they are explicitly closed -or all processes sharing the table exit. -.PP -If -.B RFPROC -is set, the -value returned in the parent process -is the process id -of the child process; the value returned in the child is zero. -Without -.BR RFPROC , -the return value is zero. -Process ids range from 1 to the maximum integer -.RB ( int ) -value. -.I Rfork -will sleep, if necessary, until required process resources are available. -.PP -.I Fork -is just a call of -.BR rfork(RFFDG|RFREND|RFPROC) . -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/9sys/fork.c -.SH SEE ALSO -.IR intro (3), -.IR proc (3), -.SH DIAGNOSTICS -These functions set -.IR errstr . diff --git a/man/man3/genrandom.3 b/man/man3/genrandom.3 index f8952e45..761df867 100644 --- a/man/man3/genrandom.3 +++ b/man/man3/genrandom.3 @@ -16,7 +16,6 @@ void genrandom(uchar *buf, int nbytes) .B void prng(uchar *buf, int nbytes) .SH DESCRIPTION -.PP Most security software requires a source of random or, at the very least, unguessable numbers. .PP diff --git a/man/man3/get9root.3 b/man/man3/get9root.3 new file mode 100644 index 00000000..134f3054 --- /dev/null +++ b/man/man3/get9root.3 @@ -0,0 +1,75 @@ +.TH GET9ROOT 3 +.SH NAME +get9root, unsharp \- get path to root of Plan 9 tree +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* get9root(void) +.PP +.B +char* unsharp(char *path) +.SH DESCRIPTION +This tree of Plan 9 software is conventionally installed in +.B /usr/local/plan9 +but may be installed in other places (for example, users without +the ability to write to +.B /usr/local +may with to install it in their own home directories). +The environment variable +.B $PLAN9 +should contain the path to the root. +.I Get9root +returns a static pointer to the pathname of root, first checking +.B $PLAN9 +and defaulting to +.BR /usr/local/plan9 . +.PP +The lack of a fixed location for the Plan 9 tree +makes it difficult to hard-code paths +to files. +.I Unsharp +replaces a leading +.B #9 +in +.I path +with the root of the tree. +.I Unsharp +also replaces a leading +.B #d +with the path to the underlying system's file descriptor dup device, +typically +.BR /dev/fd . +The string returned from +.IR unsharp , +if different from +.IR path , +should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +As a convention, programs should never +.I unsharp +paths obtained from user input. +.SH EXAMPLE +The +.IR plumber (4) +uses this code to find unrooted file names included by plumb rules. +.IP +.EX +snprint(buf, sizeof buf, "#9/plumb/%s", name); +fd = open(unsharp(buf), OREAD); +.EE +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4) +.SH BUGS +.I Get9root +could be smarter about finding the tree when +.B $PLAN9 +is not set. diff --git a/man/man3/getcallerpc.3 b/man/man3/getcallerpc.3 index c275fb50..8ad95a36 100644 --- a/man/man3/getcallerpc.3 +++ b/man/man3/getcallerpc.3 @@ -31,7 +31,7 @@ main(int argc, char *argv[]) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/getcallerpc.[cs] +.B /usr/local/plan9/src/lib9/ .SH BUGS The .I firstarg diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 index 315407c6..4be92ece 100644 --- a/man/man3/getenv.3 +++ b/man/man3/getenv.3 @@ -15,10 +15,8 @@ int putenv(char *name, char *val) .fi .SH DESCRIPTION .I Getenv -reads the contents of -.BI /env/ name -(see -.IR env (3)) +fetches the environment value associated with +.I name into memory allocated with .IR malloc (3), 0-terminates it, @@ -27,18 +25,18 @@ If no file exists, 0 is returned. .PP .I Putenv -creates the file -.BI /env/ name -and writes the string -.I val -to it. The terminating -.B 0 -is not written. -If the file value cannot be written, \-1 is returned. +sets the environment value associated with +.I name +to +.IR val . .SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR env (3) +.B /usr/local/plan9/src/lib9/getenv.c .SH DIAGNOSTICS Sets .IR errstr . +.SH BUGS +Defined as macros for +.I p9getenv +and +.I p9putenv +to avoid name conflicts with Unix library calls. diff --git a/man/man3/getfields.3 b/man/man3/getfields.3 index e39c775b..78052906 100644 --- a/man/man3/getfields.3 +++ b/man/man3/getfields.3 @@ -87,7 +87,7 @@ with .I delims set to \f5"\et\er\en "\fP. .SH SOURCE -.B /usr/local/plan9/src/libc/port/tokenize.c +.B /usr/local/plan9/src/lib9/tokenize.c .SH SEE ALSO .I strtok in diff --git a/man/man3/getns.3 b/man/man3/getns.3 new file mode 100644 index 00000000..cc76f2bf --- /dev/null +++ b/man/man3/getns.3 @@ -0,0 +1,22 @@ +.TH GETNS 3 +.SH NAME +getns \- get path to name space directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* getns(void) +.SH DESCRIPTION +.I Getns +returns a pointer to a malloced string that contains the +path to the name space directory for the current process. +The name space directory is a clumsy substitute +for Plan 9's per-process name spaces; see +.IR intro (4) +for details. +.SH SOURCE +.B /usr/local/plan9/src/lib9/getns.c +.SH SEE ALSO +.IR intro (4) diff --git a/man/man3/getpid.3 b/man/man3/getpid.3 deleted file mode 100644 index 44837f69..00000000 --- a/man/man3/getpid.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH GETPID 3 -.SH NAME -getpid, getppid \- get process ids -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.B -int getpid(void) -.PP -.B -int getppid(void) -.SH DESCRIPTION -.I Getpid -reads -.B /dev/pid -(see -.IR cons (3)) -and converts it to get the process id of the current process, -a number guaranteed to be unique among all running processes on the machine -executing -.IR getpid . -.PP -.I Getppid -reads -.B /dev/ppid -(see -.IR cons (3)) -and converts it to get the id of the parent of the current process. -.SH SOURCE -.B /usr/local/plan9/src/libc/9sys -.SH SEE ALSO -.IR intro (3), -.IR cons (3), -.IR proc (3) -.SH DIAGNOSTICS -Returns 0 and -sets -.I errstr -if unsuccessful. diff --git a/man/man3/getsnarf.3 b/man/man3/getsnarf.3 new file mode 100644 index 00000000..a90d5950 --- /dev/null +++ b/man/man3/getsnarf.3 @@ -0,0 +1,37 @@ +.TH GETSNARF 3 +.SH NAME +getsnarf, putsnarf \- window system snarf (cut and paste) buffer +.SH SYNOPSIS +.B #include +.PP +.B +char *getsnarf(void) +.PP +.B +void putsnarf(char *text) +.SH DESCRIPTION +.I Getsnarf +and +.I putsnarf +access the window system's snarf (cut and paste) buffer. +.PP +.I Getsnarf +returns a copy of the current buffer; +the returned pointer should be freed with +.I free +(see +.IR malloc (3)) +when no longer needed. +.PP +.I Putsnarf +sets the buffer to the text string +.IR text . +.PP +Callers should assume that the snarf buffer is UTF. +If the window system does not keep the buffer in UTF, +.I getsnarf +and +.I putsnarf +will convert as necessary. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-itrans.c diff --git a/man/man3/getuser.3 b/man/man3/getuser.3 index e09c4a49..a7ada46f 100644 --- a/man/man3/getuser.3 +++ b/man/man3/getuser.3 @@ -18,20 +18,35 @@ null-terminated name of the user who owns the current process. .I Getuser -reads -.B /dev/user -to find the name. +calls +.IR getuid (2) +and then reads +.B /etc/passwd +to find the corresponding name. .PP .I Sysname -provides the same service for the file -.BR #c/sysname , -which contains the name of the machine. +returns a pointer to static data which contains the name +of the machine on which the current process is running. +.I Sysname +looks first for an environment variable +.BR $sysname . +If there is no such variable, +.I sysname +calls +.IR gethostname (2) +and truncates the returned name at the first dot. +If +.I gethostname +fails, +.I sysname +returns the default name +.LR gnot . +.PP Unlike .IR getuser , .I sysname -caches the string, reading the file only once. +caches the string, deriving the host name only once. .SH SOURCE -.B /usr/local/plan9/src/libc/port/getuser.c -.SH SEE ALSO -.IR intro (3), -.IR cons (3) +.B /usr/local/plan9/src/lib9/getuser.c +.br +.B /usr/local/plan9/src/lib9/sysname.c diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 index 6b053fda..d9aa02b1 100644 --- a/man/man3/getwd.3 +++ b/man/man3/getwd.3 @@ -21,17 +21,10 @@ places no more than .I size bytes in the buffer provided. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/getwd.c +.B /usr/local/plan9/src/lib9/getwd.c .SH "SEE ALSO" .IR pwd (1), -.IR fd2path (3) .SH DIAGNOSTICS On error, zero is returned. .IR Errstr (3) may be consulted for more information. -.SH BUGS -Although the name returned by -.I getwd -is guaranteed to be the path used to reach the directory, -if the name space has changed underfoot, the name may be -incorrect. diff --git a/man/man3/graphics.3 b/man/man3/graphics.3 index 68245377..971303e9 100644 --- a/man/man3/graphics.3 +++ b/man/man3/graphics.3 @@ -189,7 +189,7 @@ data structure is defined in A .B Font is a set of character images, indexed by runes (see -.IR utf (6)). +.IR utf (7)). The images are organized into .BR Subfonts , each containing the images for a small, contiguous set of runes. @@ -376,24 +376,24 @@ specifies the refresh function to be used to create the window, if running under .IR rio (1) (see .IR window (3)). -.PP -The function -.I newwindow -may be called before -.I initdraw -or -.IR geninitdraw -to cause the program to occupy a newly created window rather than take over the one in -which it is running when it starts. -The -.I str -argument, if non-null, is concatenated to the string \f5\&"new\ "\fP -that is used to create the window (see -.IR rio (4)). -For example, -.B newwindow("-hide -dy 100") -will cause the program to run in a newly created, hidden window -100 pixels high. +.\" .PP +.\" The function +.\" .I newwindow +.\" may be called before +.\" .I initdraw +.\" or +.\" .IR geninitdraw +.\" to cause the program to occupy a newly created window rather than take over the one in +.\" which it is running when it starts. +.\" The +.\" .I str +.\" argument, if non-null, is concatenated to the string \f5\&"new\ "\fP +.\" that is used to create the window (see +.\" .IR rio (4)). +.\" For example, +.\" .B newwindow("-hide -dy 100") +.\" will cause the program to run in a newly created, hidden window +.\" 100 pixels high. .PP .I Initdisplay is part of @@ -484,15 +484,15 @@ point to the portion of the window inside the border; sophisticated clients may use .B _screen to make further subwindows. -Programs desiring multiple independent windows -may use the mechanisms of -.IR rio (4) -to create more windows (usually by a fresh mount of the window sytem -in a directory other than -.BR /dev ), -then use -.I gengetwindow -to connect to them. +.\" Programs desiring multiple independent windows +.\" may use the mechanisms of +.\" .IR rio (4) +.\" to create more windows (usually by a fresh mount of the window sytem +.\" in a directory other than +.\" .BR /dev ), +.\" then use +.\" .I gengetwindow +.\" to connect to them. .IR Gengetwindow 's extra arguments are the full path of the window's .B winname @@ -552,7 +552,7 @@ and .I chantostr convert between the channel descriptor strings used by -.IR image (6) +.IR image (7) and the internal .B ulong representation @@ -630,9 +630,9 @@ if(gengetwindow(display, "/tmp/winname", .IR print (3), .IR window (3), .IR draw (3), -.IR rio (4), -.IR image (6), -.IR font (6) +.\" .IR rio (4), +.IR image (7), +.IR font (7) .SH DIAGNOSTICS An error function may call .IR errstr (3) diff --git a/man/man3/ioproc.3 b/man/man3/ioproc.3 index ae21758e..5c3ebda4 100644 --- a/man/man3/ioproc.3 +++ b/man/man3/ioproc.3 @@ -8,7 +8,11 @@ iodial, ioopen, ioproc, ioread, +ioread9pmsg, ioreadn, +iorecvfd, +iosendfd, +iosleep, iowrite \- slave I/O processes for threaded programs .SH SYNOPSIS .PP @@ -26,12 +30,16 @@ typedef struct Ioproc Ioproc; .sp Ioproc* ioproc(void); .XX -int ioopen(Ioproc *io, char *file, int omode); int ioclose(Ioproc *io, int fd); +int iodial(Ioproc *io, char *addr, char *local, char *dir, char *cdfp); +int ioopen(Ioproc *io, char *file, int omode); long ioread(Ioproc *io, int fd, void *a, long n); +int ioread9pmsg(Ioproc *io, int fd, void *a, uint n); long ioreadn(Ioproc *io, int fd, void *a, long n); +int iorecvfd(int socket); +int iosendfd(int socket, int fd); +int iosleep(int milli); long iowrite(Ioproc *io, int fd, void *a, long n); -int iodial(Ioproc *io, char *addr, char *local, char *dir, char *cdfp); .XX void iointerrupt(Ioproc *io); void closeioproc(Ioproc *io); @@ -58,20 +66,28 @@ if either fails, it calls .I sysfatal rather than return an error. .PP -.IR Ioopen , -.IR ioclose , +.IR Ioclose , +.IR iodial , +.IR ioopen , .IR ioread , +.IR ioread9pmsg , .IR ioreadn , -.IR iowrite , +.IR iorecvfd , +.IR iosendfd , +.IR iosleep , and -.IR iodial -are execute the +.I iowrite +execute the similarly named library or system calls (see +.IR close (2), +.IR dial (3), .IR open (3), .IR read (3), +.IR fcall (3), +.IR sendfd (3), and -.IR dial (3)) +.IR sleep (3)) in the slave process associated with .IR io . It is an error to execute more than one call @@ -144,7 +160,6 @@ instances were running in different procs, the common access to .I tot would be unsafe. -.EE .PP Implement .IR ioread : @@ -170,10 +185,12 @@ ioread(Ioproc *io, int fd, void *a, long n) } .EE .SH SOURCE -.B /usr/local/plan9/src/libthread/io*.c +.B /usr/local/plan9/src/libthread .SH SEE ALSO .IR dial (3), .IR open (3), .IR read (3), .IR thread (3) - +.SH BUGS +.I Iointerrupt +is currently unimplemented. diff --git a/man/man3/ip.3 b/man/man3/ip.3 index b133adf8..c31c294f 100644 --- a/man/man3/ip.3 +++ b/man/man3/ip.3 @@ -1,6 +1,6 @@ .TH IP 3 .SH NAME -eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc \- Internet protocol +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, nhgetv, hnputl, hnputs, hnputv, ptclbsum, readipifc \- Internet protocol .SH SYNOPSIS .B #include .br @@ -57,12 +57,18 @@ ushort nhgets(void *p) uint nhgetl(void *p) .PP .B +uvlong nhgetv(void *p) +.PP +.B void hnputs(void *p, ushort v) .PP .B void hnputl(void *p, uint v) .PP .B +void hnputv(void *p, uvlong v) +.PP +.B ushort ptclbsum(uchar *a, int n) .PP .B @@ -211,14 +217,16 @@ converts the V6 address, to a V4 address and puts the result in .IR v4ip . .PP -.I Hnputs +.IR Hnputs , +.IR hnputl , and -.I hnputl -are used to store 16-bit and 32-bit integers into IP big-endian form. -.I Nhgets +.I hnputv +are used to store 16-, 32-, and 64-bit integers into IP big-endian form. +.IR Nhgets , +.IR nhgetl , and -.I nhgetl -convert big-endian 2 and 4 byte quantities into integers. +.I nhgetv +convert big-endian 2-, 4-, and 8-byte quantities into integers. .PP .I Pctlbsum returns the one's complement checksum used in IP protocols, typically invoked as diff --git a/man/man3/isalpharune.3 b/man/man3/isalpharune.3 index 07d99554..78bc4e63 100644 --- a/man/man3/isalpharune.3 +++ b/man/man3/isalpharune.3 @@ -35,7 +35,7 @@ in particular a subset of their properties as defined in the Unicode standard. Unicode defines some characters as alphabetic and specifies three cases: upper, lower, and title. Analogously to -.IR ctype (3) +.IR isalpha (3) for .SM ASCII\c , @@ -45,7 +45,7 @@ The names are self-explanatory. .PP The case-conversion routines return the character unchanged if it has no case. .SH SOURCE -.B /usr/local/plan9/src/libc/port/runetype.c +.B /usr/local/plan9/src/lib9/utf/runetype.c .SH "SEE ALSO -.IR ctype (3) , +.IR isalpha (3) , .IR "The Unicode Standard" . diff --git a/man/man3/keyboard.3 b/man/man3/keyboard.3 index b90f18b6..f341e50e 100644 --- a/man/man3/keyboard.3 +++ b/man/man3/keyboard.3 @@ -53,16 +53,8 @@ struct Keyboardctl .PP The argument to .I initkeyboard -is a -.I file -naming the device file from which characters may be read, -typically -.BR /dev/cons . -If -.I file -is nil, -.B /dev/cons -is assumed. +is ignored +(on Plan 9, it is the name of the keyboard device). .PP Once the .B Keyboardctl @@ -75,9 +67,9 @@ will be sent on the to report each character read from the device. .PP .I Ctlkeyboard -is used to set the state of the interface, typically to turn raw mode on and off -(see -.IR cons (3)). +is used to set the state of the interface, typically to turn raw mode on and off. +.\" (see +.\" .IR cons (3)). It writes the string .I msg to the control file associated with the device, which is assumed to be the regular device file name diff --git a/man/man3/lock.3 b/man/man3/lock.3 index d989d18c..9034229d 100644 --- a/man/man3/lock.3 +++ b/man/man3/lock.3 @@ -72,22 +72,16 @@ are spin locks, .B QLocks and .B RWLocks -are different types of queueing rendezvous locks, +are different types of queueing locks, and .B Rendezes are rendezvous points. .PP -Locks and rendezvous points work in regular programs as -well as programs that use the thread library +Locks and rendezvous points have trivial implementations in programs +not using the thread library (see -.IR thread (3)). -The thread library replaces the -.IR rendezvous (3) -system call -with its own implementation, -.IR threadrendezvous , -so that threads as well as processes may be synchronized by locking calls -in threaded programs. +.IR thread (3)), +since such programs have no concurrency. .PP Used carelessly, spin locks can be expensive and can easily generate deadlocks. Their use is discouraged, especially in programs that use the @@ -105,7 +99,7 @@ releases a lock. .B QLocks have the same interface but are not spin locks; instead if the lock is taken .I qlock -will suspend execution of the calling task until it is released. +will suspend execution of the calling thread until it is released. .PP Although .B Locks @@ -199,18 +193,39 @@ atomically decrements the .B Ref and returns zero if the resulting value is zero, non-zero otherwise. .SH SOURCE -.B /usr/local/plan9/src/libc/port/lock.c +.B /usr/local/plan9/src/lib9/qlock.c .br -.B /usr/local/plan9/src/libc/9sys/qlock.c -.br -.B /usr/local/plan9/src/libthread/ref.c -.SH SEE ALSO -.I rfork -in -.IR fork (3) +.B /usr/local/plan9/src/libthread .SH BUGS .B Locks -are not strictly spin locks. +are not always spin locks. +Instead they are usually implemented using the +.I pthreads +library's +.BR pthread_mutex_t , +whose implementation method is not defined. +.PP +On +.IR pthreads -based +systems, the implementation of +.B Lock +never calls +.I pthread_mutex_destroy +to free the +.BR pthread_mutex_t 's. +This leads to resource leaks on FreeBSD 5 +(though not on Linux 2.6, where +.I pthread_mutex_destroy +is a no-op). +.BR +.PP +On systems that do not have a usable +.I pthreads +implementation, the +.B Lock +implementation provided by +.I libthread +is still not exactly a spin lock. After each unsuccessful attempt, .I lock calls diff --git a/man/man3/mach-cmd.3 b/man/man3/mach-cmd.3 new file mode 100644 index 00000000..202ca395 --- /dev/null +++ b/man/man3/mach-cmd.3 @@ -0,0 +1,141 @@ +.TH MACH-CMD 3 +.SH NAME +attachargs, attachcore, attachdynamic, attachproc, proctextfile \- debugging processes and core files +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta +\w'\fLextern 'u +\w'\fLchar *'u +.B +int attachcore(Fhdr *hdr) +.PP +.B +int attachproc(int pid) +.PP +.B +int attachdynamic(void) +.PP +.B +char* proctextfile(int pid) +.PP +.B +int attachargs(int argc, char **argv, int omode) +.PP +.B +.nf +extern Fhdr* symhdr; +extern char* symfil; +extern Map* symmap; +extern Fhdr* fhdrlist; +.ift .sp .5 +.ifn .sp +extern Fhdr* corhdr; +extern char* corfil; +extern Map* cormap; +.ift .sp .5 +.ifn .sp +extern int corpid; +extern Regs* correg; +.SH DESCRIPTION +These routines provide access to the objects +a typical debugger manipulates: an executable binary, +some number of shared libraries, a memory image +in the form of a core dump or active process, +and a register set. +.PP +The maintained state is: +.TP +.I symhdr +The file header for the main binary. +.TP +.I symfil +The file name of the main binary. +.TP +.I symmap +The memory map of the main binary. +.TP +.I fhdrlist +A linked list (via the +.B Fhdr.next +fields) of all currently open headers +(see +.I symopen +in +.IR mach-symbol (3)). +When dynamically linked objects have been attached, +they are present in this linked list, +and therefore included in searches by +.IR indexsym , +.IR lookupsym , +and +.I findsym +(see +.IR mach-symbol (3)). +.TP +.I corhdr +The file header for the core dump, if any. +.TP +.I corfil +The file name of the core dump, if any. +.TP +.I cormap +The memory map of the core dump or attached process. +.TP +.I corpid +The process id of the attached process, if any. +.TP +.I correg +The register set of the core dump or attached process. +.PD +If these fields are not valid, they are zeroed. +.PP +.I Attachcore +and +.I attachproc +attach to an opened core file or an executing process. +They set +.IR corhdr , +.IR corfil , +.IR cormap , +.IR corpid , +and +.IR correg . +.PP +.I Proctextfile +returns the name of the main binary for the process with id +.IR pid . +.PP +.I Attachdynamic +requires that the memory image already be attached. +It reads the dynamic linker's internal run-time data structures +and then opens all the dynamic objects that are currently +loaded. +.PP +.I Attachargs +uses all of these functions while +parsing an argument vector as would be passed to +a debugger like +.IR db (1) +or +.IR acid (1). +It expects a list of executable files, core dump files, or process ids, +given in any order. +If extra arguments are given (for example, more than one executable, or both +a core dump and a process id), they are ignored and diagnostics are printed to +standard error. +If arguments are missing (for example, the process id is given without an +executable file), +.I attachargs +fills them in as best it can. +.SH SOURCE +.B /usr/local/plan9/src/libmach +.SH "SEE ALSO +.IR mach (3), +.IR mach-file (3), +.IR mach-map (3) +.SH BUGS +The interface needs to be changed to support +multiple threads, each with its own register set. diff --git a/man/man3/mach-file.3 b/man/man3/mach-file.3 index f235815e..17911ec1 100644 --- a/man/man3/mach-file.3 +++ b/man/man3/mach-file.3 @@ -1,6 +1,6 @@ .TH MACH-FILE 3 .SH NAME -crackhdr, uncrackhdr, mapfile, mapproc, detachproc, ctlproc, +crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc, procnotes \- machine-independent access to exectuable files and running processes .SH SYNOPSIS .B #include @@ -16,9 +16,13 @@ int crackhdr(int fd, Fhdr *hdr) void uncrackhdr(Fhdr *hdr) .PP .ft B -int mapfile(Map *map, ulong base, Fhdr *hdr) +int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs) .br -int mapproc(Map *map, int pid) +void unmapfile(Fhdr *hdr, Map *map) +.br +int mapproc(int pid, Map *map, Regs **regs) +.br +void unmapproc(Map *map) .br int detachproc(int pid) .br @@ -95,6 +99,12 @@ Newly-added segments are mapped on top of existing segments, so this arrangement will use the core file for the segments it contains but fall back to the executable for the rest. .PP +.I Unmapfile +removes the mappings in +.I map +corresponding to +.IR hdr . +.PP .I Mapproc attaches to a running program and adds its segments to the given map. It adds one segment for each contiguous section of @@ -103,8 +113,14 @@ On systems where this information cannot be determined, it adds a single segment covering the entire address space. Accessing areas of this segment that are actually not mapped in the process address space will cause the get/put routines to return errors. +.PP +.I Unmapproc +removes the mappings in +.I map +corresponding to +.IR pid . .I Detachproc -detaches from a previously-attached program. +detaches from all previously attached processes. .PP .I Ctlproc manipulates the process with id @@ -143,7 +159,9 @@ returns the number of pending notes. The memory at .BI * notes should be freed via -.IR free (3) +.I free +(see +.IR malloc (3)) when no longer needed. .SH SOURCE .B /usr/local/plan9/src/libmach diff --git a/man/man3/mach-map.3 b/man/man3/mach-map.3 index 8175e138..2fc8cc72 100644 --- a/man/man3/mach-map.3 +++ b/man/man3/mach-map.3 @@ -4,10 +4,9 @@ allocmap, addseg, findseg, addrtoseg, addrtosegafter, removeseg, freemap, get1, get2, get4, get8, put1, put2, put4, put8, -rget1, rget2, rget4, rget8, -rput1, rput2, rput4, rput8, -locaddr, locconst, locreg, locindir, -loccmp, loceval, locfmt, locredir, +rget, rput, fpformat, +locnone, locaddr, locconst, locreg, locindir, +loccmp, loceval, locfmt, locsimplify, lget1, lget2, lget4, lget8, lput1, lput2, lput4, lput8 \- machine-independent access to address spaces and register sets @@ -80,26 +79,16 @@ int put4(Map *map, ulong addr, u32int u) int put8(Map *map, ulong addr, u64int u) .PP .ft B -int rget1(Map *map, char *reg, u8int *u) -.br -int rget2(Map *map, char *reg, u16int *u) -.br -int rget4(Map *map, char *reg, u32int *u) -.br -int rget8(Map *map, char *reg, u64int *u) +int rget(Regs *regs, char *reg, ulong *u) .br int fpformat(Map *map, char *reg, char *a, uint n, char code); .PP .ft B -int rput1(Map *map, char *reg, u8int u) -.br -int rput2(Map *map, char *reg, u16int u) -.br -int rput4(Map *map, char *reg, u32int u) -.br -int rput8(Map *map, char *reg, u64int u) +int rput(Regs *regs, char *name, ulong u) .PP .ft B +Loc locnone(void) +.br Loc locaddr(ulong addr) .br Loc locconst(ulong con) @@ -115,7 +104,7 @@ int loceval(Map *map, Loc loc, ulong *addr) .br int locfmt(Fmt *fmt) .br -int locredir(Map *map, Loc *regs, Loc loc, Loc *newloc) +int locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc) .PP .ft B int lget1(Map *map, Loc loc, uchar *a, uint n) @@ -297,20 +286,15 @@ A \-1 return value indicates an error. .PP When representing core files or running programs, maps also provide access to the register set. -.IR Rget1 , -.IR rget2 , -.IR rget4 , -.IR rget8 , -.IR rput1 , -.IR rput2 , -.IR rput4 , -and -.IR rput8 -read or write the 1-, 2-, 4-, or 8-byte register +.IR Rget +and +.IR rput +read or write the register named by .IR reg . -If the register is not the requested size, the -behavior is undefined. +If the register is smaller than a +.BR ulong , +the high bits are ignored. .PP .I Fpformat converts the contents of a floating-point register to a string. @@ -418,3 +402,8 @@ function families as necessary. .SH DIAGNOSTICS These routines set .IR errstr . +.SH BUGS +This man page needs to describe +.B Regs +and +.B Regdesc diff --git a/man/man3/mach-stack.3 b/man/man3/mach-stack.3 index e17c6cb0..caae6bf8 100644 --- a/man/man3/mach-stack.3 +++ b/man/man3/mach-stack.3 @@ -1,7 +1,6 @@ .TH MACH-STACK 3 .SH NAME -stacktrace, -localaddr, +stacktrace, localaddr, unwindframe, windindex, windreglocs \- stack traces .SH SYNOPSIS .B #include .br @@ -14,7 +13,16 @@ localaddr, int stacktrace(Map *map, Rgetter rget, Tracer trace) .PP .ft B -int localvar(Map *map, char *fn, char *val, Loc *loc) +int localaddr(Map *map, Regs *regs, char *fn, char *val, ulong *val) +.PP +.ft B +int unwindframe(Map *map, Regs *regs, ulong *next, Symbol *sym) +.PP +.ft B +int windindex(char *regname) +.PP +.ft B +Loc* windreglocs(void) .SH DESCRIPTION .I Stacktrace provides machine-independent @@ -80,7 +88,7 @@ is as an argument to .IR lget4 , etc., when evaluating the locations of local variables. .PP -.I Localvar +.I Localaddr uses .I stacktrace to walk up the stack looking for the innermost instance of a function named @@ -88,8 +96,46 @@ to walk up the stack looking for the innermost instance of a function named once it finds the function, it looks for the parameter or local variable .IR var , -storing the location of the variable in -.IR loc . +storing the address of the variable in +.IR val . +.PP +.I Unwindframe +is the low-level function on which +.I stacktrace +is built. +Given the current memory image in +.I map +and the current register set in +.I regs , +.I unwindframe +fills in +.I next +with the values of the register set +at the time of the call to the function in the current program counter. +.I Sym +should be the symbol corresponding to the current function, +if available. +.PP +The +.I next +array holds only the +.IR "winding registers" , +typically the caller-save registers and the program counter and stack pointer. +The order of registers in the array is called the +.IR "winding order" . +The winding set can be found in the array +.IB mach -> windreg \fR, +which has +.IB mach -> nwindreg +entries. +.I Windindex +returns the index of the named register +in the winding order. +.I Windreglocs +returns an array of +.I Loc +structures corresponding to the winding registers, +in the winding order. .SH EXAMPLE The following code writes a simple stack trace to standard output, stopping after at most 20 stack frames. @@ -135,3 +181,5 @@ trace(Map *map, ulong pc, ulong callerpc, .B /usr/local/plan9/src/libmach .SH SEE ALSO .IR mach (3) +.SH BUGS +Need to talk about Regs diff --git a/man/man3/mach-symbol.3 b/man/man3/mach-symbol.3 index ad208ce0..c74ae8e5 100644 --- a/man/man3/mach-symbol.3 +++ b/man/man3/mach-symbol.3 @@ -1,6 +1,7 @@ .TH MACH-SYMBOL 3 .SH NAME -symopen, symclose, indexsym, lookupsym, findsym, +symopen, symclose, findhdr, indexsym, lookupsym, findsym, +findexsym, flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, pc2file, file2pc, line2pc, fnbound, fileline, pc2line \- symbol table access functions @@ -11,11 +12,15 @@ pc2line \- symbol table access functions .br .B #include .PP -.ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u +.ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u .ft B int symopen(Fhdr *hdr) .br void symclose(Fhdr *hdr) +.br +Fhdr *findhdr(char *name) +.br +extern Fhdr* fhdrlist; .PP .ft B int indexsym(uint n, Symbol *s) @@ -25,6 +30,13 @@ int lookupsym(char *fn, char *var, Symbol *s) int findsym(Loc loc, uint class, Symbol *s) .PP .ft B +int findexsym(Fhdr *hdr, uint n, Symbol *s) +.br +Symbol *flookupsym(Fhdr *hdr, char *name) +.br +Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +.PP +.ft B int indexlsym(Symbol *s1, uint n, Symbol *s2) .br int lookuplsym(Symbol *s1, char *name, Symbol *s2) @@ -70,6 +82,25 @@ frees the structures. The rest of the functions described here access a composite symbol table made up of all currently open tables. .PP +The set of all currently open +.BR Fhdr s +is maintained as a linked list starting at +.I fhdrlist +(chained via +.BR Fhdr.next ). +.PP +.I Findhdr +searches the currently open +.BR Fhdr s +for one whose file name ends with the path +.I name +(that is, +.B libc.so +matches +.B /usr/lib/libc.so +but not +.BR mylibc.so ). +.PP The .B Symbol data structure: @@ -190,10 +221,28 @@ Class specification .B CANY searches the text table first, then the global table. .PP +.IR Findexsym , +.IR flookupsym , +and +.I ffindsym +are similar to +.IR indexsym , +.IR lookupsym , +and +.IR findsym , +but operate only on the symbols from +.IR hdr . +.I Flookupsym +and +.I ffindsym +return pointers to data stored in the +.IR hdr , +which must not be modified or freed. +.PP .IR Indexlsym , .IR lookuplsym , and -.IR findlsym +.I findlsym are similar to .IR indexsym , .IR lookupsym , diff --git a/man/man3/mach.3 b/man/man3/mach.3 index 38918523..18147891 100644 --- a/man/man3/mach.3 +++ b/man/man3/mach.3 @@ -54,24 +54,37 @@ the various file parsers deduce the operating system from information in the binary files themselves and adjust accordingly. .PP +The supported architectures are +.B 386 +(Intel 32-bit x86) +386 and later) +and +.B power +(IBM PowerPC, typically running +Mac OS X). +.PP Other manual pages describe the library functions in detail. .PP -.I Mach-file (3) +.IR Mach-cmd (3) +describes some convenience routines for attaching to +processes and core files. +.PP +.IR Mach-file (3) describes the manipulation of binary files. .PP -.I Mach-map (3) +.IR Mach-map (3) describes the interface to address spaces and register sets in executable files and executing programs. .PP -.I Mach-stack (3) +.IR Mach-stack (3) describes support for unwinding the stack. .PP -.I Mach-swap (3) +.IR Mach-swap (3) describes helper functions for accessing data in a particular byte order. .PP -.I Mach-symbol (3) +.IR Mach-symbol (3) describes the interface to debugging symbol information. .SH SOURCE .B /usr/local/plan9/src/libmach diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 index 54e9ecc8..01493c75 100644 --- a/man/man3/malloc.3 +++ b/man/man3/malloc.3 @@ -1,6 +1,6 @@ .TH MALLOC 3 .SH NAME -malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- memory allocator .SH SYNOPSIS .B #include .br @@ -23,23 +23,16 @@ void* realloc(void *ptr, ulong size) void* calloc(ulong nelem, ulong elsize) .PP .B -ulong msize(void *ptr) -.PP -.B void setmalloctag(void *ptr, ulong tag) .PP .B -ulong getmalloctag(void *ptr, ulong tag) +ulong getmalloctag(void *ptr) .PP .B void setrealloctag(void *ptr, ulong tag) .PP .B -ulong getrealloctag(void *ptr, ulong tag) -.PP -.B -void* malloctopoolblock(void*) -.PP +ulong getrealloctag(void *ptr) .SH DESCRIPTION .I Malloc and @@ -109,12 +102,7 @@ The space is initialized to zeros. .I Free frees such a block. .PP -When a block is allocated, sometimes there is some extra unused space at the end. -.I Msize -grows the block to encompass this unused space and returns the new number -of bytes that may be used. -.PP -The memory allocator maintains two word-sized fields +The memory allocator on Plan 9 maintains two word-sized fields associated with each block, the ``malloc tag'' and the ``realloc tag''. By convention, the malloc tag is the PC that allocated the block, and the realloc tag the PC that last reallocated the block. @@ -137,24 +125,15 @@ to .IR setmalloctag ) to provide more useful information about the source of allocation. -.PP -.I Malloctopoolblock -takes the address of a block returned by -.I malloc -and returns the address of the corresponding -block allocated by the -.IR pool (3) -routines. .SH SOURCE -.B /usr/local/plan9/src/libc/port/malloc.c +.B /usr/local/plan9/src/lib9/malloc.c +.br +.B /usr/local/plan9/src/lib9/malloctag.c .SH SEE ALSO -.IR leak (1), .I trump (in .IR acid (1)), -.IR brk (3), -.IR getcallerpc (3), -.IR pool (3) +.IR getcallerpc (3) .SH DIAGNOSTICS .I Malloc, realloc and @@ -169,22 +148,6 @@ and return .BR ~0 . .PP -After including -.BR pool.h , -the call -.B poolcheck(mainmem) -can be used to scan the storage arena for inconsistencies -such as data written beyond the bounds of allocated blocks. -It is often useful to combine this with with setting -.EX - mainmem->flags |= POOL_NOREUSE; -.EE -at the beginning of your program. -This will cause malloc not to reallocate blocks even -once they are freed; -.B poolcheck(mainmem) -will then detect writes to freed blocks. -.PP The .I trump library for @@ -198,7 +161,7 @@ is bizarre. .PP User errors can corrupt the storage arena. The most common gaffes are (1) freeing an already freed block, -(3) storing beyond the bounds of an allocated block, and (3) +(2) storing beyond the bounds of an allocated block, and (3) freeing data that was not obtained from the allocator. When .I malloc diff --git a/man/man3/matrix.3 b/man/man3/matrix.3 new file mode 100644 index 00000000..87ba34c5 --- /dev/null +++ b/man/man3/matrix.3 @@ -0,0 +1,350 @@ +.TH MATRIX 3 +.SH NAME +ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport \- Geometric transformations +.SH SYNOPSIS +.PP +.B +#include +.PP +.B +#include +.PP +.B +void ident(Matrix m) +.PP +.B +void matmul(Matrix a, Matrix b) +.PP +.B +void matmulr(Matrix a, Matrix b) +.PP +.B +double determinant(Matrix m) +.PP +.B +void adjoint(Matrix m, Matrix madj) +.PP +.B +double invertmat(Matrix m, Matrix inv) +.PP +.B +Point3 xformpoint(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformpointd(Point3 p, Space *to, Space *from) +.PP +.B +Point3 xformplane(Point3 p, Space *to, Space *from) +.PP +.B +Space *pushmat(Space *t) +.PP +.B +Space *popmat(Space *t) +.PP +.B +void rot(Space *t, double theta, int axis) +.PP +.B +void qrot(Space *t, Quaternion q) +.PP +.B +void scale(Space *t, double x, double y, double z) +.PP +.B +void move(Space *t, double x, double y, double z) +.PP +.B +void xform(Space *t, Matrix m) +.PP +.B +void ixform(Space *t, Matrix m, Matrix inv) +.PP +.B +int persp(Space *t, double fov, double n, double f) +.PP +.B +void look(Space *t, Point3 eye, Point3 look, Point3 up) +.PP +.B +void viewport(Space *t, Rectangle r, double aspect) +.SH DESCRIPTION +These routines manipulate 3-space affine and projective transformations, +represented as 4\(mu4 matrices, thus: +.IP +.EX +.ta 6n +typedef double Matrix[4][4]; +.EE +.PP +.I Ident +stores an identity matrix in its argument. +.I Matmul +stores +.I a\(mub +in +.IR a . +.I Matmulr +stores +.I b\(mua +in +.IR b . +.I Determinant +returns the determinant of matrix +.IR m . +.I Adjoint +stores the adjoint (matrix of cofactors) of +.I m +in +.IR madj . +.I Invertmat +stores the inverse of matrix +.I m +in +.IR minv , +returning +.IR m 's +determinant. +Should +.I m +be singular (determinant zero), +.I invertmat +stores its +adjoint in +.IR minv . +.PP +The rest of the routines described here +manipulate +.I Spaces +and transform +.IR Point3s . +A +.I Point3 +is a point in three-space, represented by its +homogeneous coordinates: +.IP +.EX +typedef struct Point3 Point3; +struct Point3{ + double x, y, z, w; +}; +.EE +.PP +The homogeneous coordinates +.RI ( x , +.IR y , +.IR z , +.IR w ) +represent the Euclidean point +.RI ( x / w , +.IR y / w , +.IR z / w ) +if +.IR w ≠0, +and a ``point at infinity'' if +.IR w =0. +.PP +A +.I Space +is just a data structure describing a coordinate system: +.IP +.EX +typedef struct Space Space; +struct Space{ + Matrix t; + Matrix tinv; + Space *next; +}; +.EE +.PP +It contains a pair of transformation matrices and a pointer +to the +.IR Space 's +parent. The matrices transform points to and from the ``root +coordinate system,'' which is represented by a null +.I Space +pointer. +.PP +.I Pushmat +creates a new +.IR Space . +Its argument is a pointer to the parent space. Its result +is a newly allocated copy of the parent, but with its +.B next +pointer pointing at the parent. +.I Popmat +discards the +.B Space +that is its argument, returning a pointer to the stack. +Nominally, these two functions define a stack of transformations, +but +.B pushmat +can be called multiple times +on the same +.B Space +multiple times, creating a transformation tree. +.PP +.I Xformpoint +and +.I Xformpointd +both transform points from the +.B Space +pointed to by +.I from +to the space pointed to by +.IR to . +Either pointer may be null, indicating the root coordinate system. +The difference between the two functions is that +.B xformpointd +divides +.IR x , +.IR y , +.IR z , +and +.I w +by +.IR w , +if +.IR w ≠0, +making +.RI ( x , +.IR y , +.IR z ) +the Euclidean coordinates of the point. +.PP +.I Xformplane +transforms planes or normal vectors. A plane is specified by the +coefficients +.RI ( a , +.IR b , +.IR c , +.IR d ) +of its implicit equation +.IR ax+by+cz+d =0. +Since this representation is dual to the homogeneous representation of points, +.B libgeometry +represents planes by +.B Point3 +structures, with +.RI ( a , +.IR b , +.IR c , +.IR d ) +stored in +.RI ( x , +.IR y , +.IR z , +.IR w ). +.PP +The remaining functions transform the coordinate system represented +by a +.BR Space . +Their +.B Space * +argument must be non-null \(em you can't modify the root +.BR Space . +.I Rot +rotates by angle +.I theta +(in radians) about the given +.IR axis , +which must be one of +.BR XAXIS , +.B YAXIS +or +.BR ZAXIS . +.I Qrot +transforms by a rotation about an arbitrary axis, specified by +.B Quaternion +.IR q . +.PP +.I Scale +scales the coordinate system by the given scale factors in the directions of the three axes. +.IB Move +translates by the given displacement in the three axial directions. +.PP +.I Xform +transforms the coordinate system by the given +.BR Matrix . +If the matrix's inverse is known +.I a +.IR priori , +calling +.I ixform +will save the work of recomputing it. +.PP +.I Persp +does a perspective transformation. +The transformation maps the frustum with apex at the origin, +central axis down the positive +.I y +axis, and apex angle +.I fov +and clipping planes +.IR y = n +and +.IR y = f +into the double-unit cube. +The plane +.IR y = n +maps to +.IR y '=-1, +.IR y = f +maps to +.IR y '=1. +.PP +.I Look +does a view-pointing transformation. The +.B eye +point is moved to the origin. +The line through the +.I eye +and +.I look +points is aligned with the y axis, +and the plane containing the +.BR eye , +.B look +and +.B up +points is rotated into the +.IR x - y +plane. +.PP +.I Viewport +maps the unit-cube window into the given screen viewport. +The viewport rectangle +.I r +has +.IB r .min +at the top left-hand corner, and +.IB r .max +just outside the lower right-hand corner. +Argument +.I aspect +is the aspect ratio +.RI ( dx / dy ) +of the viewport's pixels (not of the whole viewport). +The whole window is transformed to fit centered inside the viewport with equal +slop on either top and bottom or left and right, depending on the viewport's +aspect ratio. +The window is viewed down the +.I y +axis, with +.I x +to the left and +.I z +up. The viewport +has +.I x +increasing to the right and +.I y +increasing down. The window's +.I y +coordinates are mapped, unchanged, into the viewport's +.I z +coordinates. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/matrix.c +.SH "SEE ALSO +.IR arith3 (3) diff --git a/man/man3/memdraw.3 b/man/man3/memdraw.3 index 78c4859c..4b59428f 100644 --- a/man/man3/memdraw.3 +++ b/man/man3/memdraw.3 @@ -231,9 +231,9 @@ element of .B Memdata points back at the .B Memdata -structure, so that the +structure, so that in the Plan 9 kernel, the memory allocator (see -.IR pool (3)) +Plan 9's \fIpool\fR(3)) can compact image memory using .IR memimagemove . @@ -294,7 +294,7 @@ writes a compressed representation of to file descriptor .IR fd . For more on bitmap formats, see -.IR image (6). +.IR image (7). .I Freememimage frees images returned by any of these routines. The @@ -433,7 +433,7 @@ In the kernel, .I iprint prints to a serial line rather than the screen, for obvious reasons. .SH SOURCE -.B /usr/local/plan9/src/libmemdraw +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR addpt (3), .IR color (3), @@ -442,9 +442,14 @@ prints to a serial line rather than the screen, for obvious reasons. .IR memlayer (3), .IR stringsize (3), .IR subfont (3), -.IR color (6), -.IR utf (6) +.IR color (7), +.IR utf (7) .SH BUGS .I Memimagestring is unusual in using a subfont rather than a font, and in having no parameter to align the source. +.PP +.I Libmemdraw +is archived into +.IR libdraw . + diff --git a/man/man3/memlayer.3 b/man/man3/memlayer.3 index 523253a8..90e63e50 100644 --- a/man/man3/memlayer.3 +++ b/man/man3/memlayer.3 @@ -294,12 +294,16 @@ bytes of data in .I buf are in compressed image format (see -.IR image (6)). +.IR image (7)). .SH SOURCE -.B /usr/local/plan9/src/libmemlayer +.B /usr/local/plan9/src/libdraw .SH SEE ALSO .IR graphics (3), .IR memdraw (3), .IR stringsize (3), .IR window (3), .IR draw (3) +.SH BUGS +.I Libmemlayer +is archived into +.IR libdraw . diff --git a/man/man3/memory.3 b/man/man3/memory.3 new file mode 100644 index 00000000..746dc7d9 --- /dev/null +++ b/man/man3/memory.3 @@ -0,0 +1,126 @@ +.TH MEMORY 3 +.SH NAME +memccpy, memchr, memcmp, memcpy, memmove, memset \- memory operations +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +void* memccpy(void *s1, void *s2, int c, long n) +.PP +.B +void* memchr(void *s, int c, long n) +.PP +.B +int memcmp(void *s1, void *s2, long n) +.PP +.B +void* memcpy(void *s1, void *s2, long n) +.PP +.B +void* memmove(void *s1, void *s2, long n) +.PP +.B +void* memset(void *s, int c, long n) +.SH DESCRIPTION +These functions operate efficiently on memory areas +(arrays of bytes bounded by a count, not terminated by a zero byte). +They do not check for the overflow of any receiving memory area. +.PP +.I Memccpy +copies bytes from memory area +.I s2 +into +.IR s1 , +stopping after the first occurrence of byte +.I c +has been copied, or after +.I n +bytes have been copied, whichever comes first. +It returns a pointer to the byte after +the copy of +.I c +in +.IR s1 , +or zero if +.I c +was not found in the first +.I n +bytes of +.IR s2 . +.PP +.I Memchr +returns a pointer to the first +occurrence of byte +.I c +in the first +.I n +bytes of memory area +.IR s, +or zero if +.I c +does not occur. +.PP +.I Memcmp +compares its arguments, looking at the first +.I n +bytes only, and returns an integer +less than, equal to, or greater than 0, +according as +.I s1 +is lexicographically less than, equal to, or +greater than +.IR s2 . +The comparison is bytewise unsigned. +.PP +.I Memcpy +copies +.I n +bytes from memory area +.I s2 +to +.IR s1 . +It returns +.IR s1 . +.PP +.I Memmove +works like +.IR memcpy , +except that it is guaranteed to work if +.I s1 +and +.IR s2 +overlap. +.PP +.I Memset +sets the first +.I n +bytes in memory area +.I s +to the value of byte +.IR c . +It returns +.IR s . +.SH SOURCE +All these routines have portable C implementations in +.BR /usr/local/plan9/src/lib9 . +.\" Most also have machine-dependent assembly language implementations in +.\" .BR /usr/local/plan9/lib9/$objtype . +.SH SEE ALSO +.IR strcat (3) +.SH BUGS +ANSI C does not require +.I memcpy +to handle overlapping source and destination; on Plan 9, it does, so +.I memmove +and +.I memcpy +behave identically. +.PP +If +.I memcpy +and +.I memmove +are handed a negative count, they abort. diff --git a/man/man3/mousescrollsize.3 b/man/man3/mousescrollsize.3 new file mode 100644 index 00000000..915a6bb1 --- /dev/null +++ b/man/man3/mousescrollsize.3 @@ -0,0 +1,62 @@ +.TH MOUSESCROLLSIZE 3 +.SH NAME +mousescrollsize \- compute mouse scroll increment +.SH SYNOPSIS +.B #include +.PP +int mousescrollsize(int maxlines) +.SH DESCRIPTION +.I Mousescrollsize +computes the number of lines of text that should be scrolled +in response to a mouse scroll wheel click. +.I Maxlines +is the number of lines visible in the text window. +.PP +The default scroll increment is one line. +This default can be overridden by setting the +.B $mousescrollsize +environment variable to an integer, which specifies +a constant number of lines, or to a real number +followed by a percent character, indicating that the +scroll increment should be a percentage of the total +number of lines in the window. +For example, setting +.B $mousescrollsize +to +.B 50% +causes a half-window scroll increment. +.PP +.I Mousescrollsize +is used by +.IR 9term (1) +and +.IR acme (1) +to set their scrolling behavior. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/scroll.c +.SH SEE ALSO +.IR 9term (1), +.IR acme (1) +.SH BUGS +.I Libdraw +expects up and down scroll wheel events to be expressed as clicks of mouse buttons 4 and 5, +but the XFree86 default is to ignore the scroll wheel. +To enable the scroll wheel, change your +.B InputDevice +section of +.B XF86Config-4 +to look like: +.IP +.EX +Section "InputDevice" + Identifier "Mouse0" + Driver "mouse" + Option "Device" "/dev/psaux" + + # next four lines enable scroll wheel as buttons 4 and 5 + Option "Buttons" "5" + Option "Emulate3Buttons" "off" + Option "Protocol" "ImPS/2" + Option "ZAxisMapping" "4 5" +EndSection +.EE diff --git a/man/man3/mp.3 b/man/man3/mp.3 index 420f0ba6..9a4ed848 100644 --- a/man/man3/mp.3 +++ b/man/man3/mp.3 @@ -1,7 +1,6 @@ .TH MP 3 .SH NAME - -mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree \- extended precision arithmetic +mpsetminbits, mpnew, mpfree, mpbits, mpnorm, mpcopy, mpassign, mprand, strtomp, mpfmt,mptoa, betomp, mptobe, letomp, mptole, mptoui, uitomp, mptoi, itomp, uvtomp, mptouv, vtomp, mptov, mpdigdiv, mpadd, mpsub, mpleft, mpright, mpmul, mpexp, mpmod, mpdiv, mpcmp, mpextendedgcd, mpinvert, mpsignif, mplowbits0, mpvecdigmuladd, mpvecdigmulsub, mpvecadd, mpvecsub, mpveccmp, mpvecmul, mpmagcmp, mpmagadd, mpmagsub, crtpre, crtin, crtout, crtprefree, crtresfree, mpfactorial \- extended precision arithmetic .SH SYNOPSIS .B #include .br @@ -163,6 +162,9 @@ void crtprefree(CRTpre *cre) void crtresfree(CRTres *res) .PP .B +mpint* mpfactorial(ulong n) +.PP +.B mpint *mpzero, *mpone, *mptwo .SH DESCRIPTION .PP @@ -573,5 +575,9 @@ free and .I CRTres structures respectively. +.PP +.I Mpfactorial +returns the factorial of +.IR n . .SH SOURCE .B /usr/local/plan9/src/libmp diff --git a/man/man3/mux.3 b/man/man3/mux.3 new file mode 100644 index 00000000..cc8de4d2 --- /dev/null +++ b/man/man3/mux.3 @@ -0,0 +1,154 @@ +.TH MUX 3 +.SH NAME +Mux, muxinit, muxrpc, muxthreads \- protocol multiplexor +.SH SYNOPSIS +.B #include +.PP +.nf +.B +.ta +4n +struct Mux +{ + uint mintag; + uint maxtag; + int (*settag)(Mux *mux, void *msg, uint tag); + int (*gettag)(Mux *mux, void *msg); + int (*send)(Mux *mux, void *msg); + void *(*recv)(Mux *mux); + void *aux; + + \&... /* private fields follow */ +}; +.ta +\w'\fLvoid* 'u +.PP +.B +void muxinit(Mux *mux); +.PP +.B +void* muxrpc(Mux *mux, void *request); +.PP +.B +void muxprocs(Mux *mux); +.SH DESCRIPTION +.I Libmux +is a generic protocol multiplexor. +A client program initializes a +.B Mux +structure with information about the protocol +(mainly in the form of helper functions) +and can then use +.I muxrpc +to execute individual RPCs without worrying +about details of multiplexing requests +and demultiplexing responses. +.PP +.I Libmux +assumes that the protocol messages contain a +.I tag +(or message ID) field that exists for the sole purpose of demultiplexing messages. +.I Libmux +chooses the tags and then calls a helper function +to put them in the outgoing messages. +.I Libmux +calls another helper function to retrieve tags +from incoming messages. +It also calls helper functions to send and receive packets. +.PP +A client should allocate a +.B Mux +structure and then call +.I muxinit +to initialize the library's private elements. +The client must initialize the following elements: +.TP +.I mintag\fR, \fPmaxtag +The range of valid tags; +.I maxtag +is the maximum valid tag plus one, so that +.IR maxtag \- mintag +is equal to the number of valid tags. +If +.I libmux +runs out of tags +(all tags are being used for RPCs currently in progress), +a new call to +.IR muxrpc +will block until an executing call finishes. +.TP +.I settag\fR, \fPgettag +Set or get the tag value in a message. +.TP +.I send\fR, \fPrecv +Send or receive protocol messages on the connection. +.I Recv +should block until a message is available and +should return nil if the connection is closed. +.I Libmux +will arrange that only one call to +.I recv +is active at a time. +.TP +.I aux +An auxiliary pointer for use by the client. +.PD +Once a client has initialized the +.B Mux +structure, it can call +.I muxrpc +to execute RPCs. +The +.I request +is the message passed to +.I settag +and +.IR send . +The return value is the response packet, +as provided by +.IR recv , +or +nil if an error occurred. +.I Muxprocs +allocates new procs +(see +.IR thread (3)) +in which to run +.I send +and +.IR recv . +After a call to +.IR muxprocs , +.I muxrpc +will run +.I send +and +.I recv +in these procs instead of in the calling proc. +This is useful if the implementation of +either (particularly +.IR recv ) +blocks an entire proc +and there are other threads in the calling proc +that need to remain active. +.SH EXAMPLE +See +.B /usr/local/plan9/src/lib9pclient/fs.c +for an example of using +.I libmux +with +9P +(see +.IR intro (9p)). +.SH SOURCE +.B /usr/local/plan9/src/libmux +.SH SEE ALSO +.IR thread (3), +.IR intro (9p) +.SH BUGS +.I Libmux +does not know how to free protocol messages, +so message arriving with unexpected or invalid +tags are leaked. +.PP +Using +.I mintag +other than zero is not well tested and probably buggy. diff --git a/man/man3/nan.3 b/man/man3/nan.3 index 2c77af00..69777e52 100644 --- a/man/man3/nan.3 +++ b/man/man3/nan.3 @@ -41,4 +41,4 @@ else negative infinity. returns true if its first argument is infinity with the same sign as the second argument. .SH SOURCE -.B /usr/local/plan9/src/libc/port/nan.c +.B /usr/local/plan9/src/lib9/nan.c diff --git a/man/man3/needstack.3 b/man/man3/needstack.3 new file mode 100644 index 00000000..31588f68 --- /dev/null +++ b/man/man3/needstack.3 @@ -0,0 +1,69 @@ +.TH NEEDSTACK 3 +.SH NAME +needstack \- check for execution stack overflow +.SH SYNOPSIS +.B +#include +.PP +.B +#include +.PP +.B +int needstack(int n) +.SH DESCRIPTION +Stack overflow in the thread library leads to bugs that are +difficult to diagnose. +The Plan 9 libraries are careful about not allocating +large structures on the stack, so typically four or eight kilobytes is plenty of stack +for a thread. +Other libraries are not always as careful. +Calling +.I needstack +indicates to the thread library that an external routine is about +to be called that will require +.I n +bytes of stack space. +If there is not enough space left on the stack, +the thread library prints an error and terminates +the program. +The call +.B needstack(0) +can be used to check whether the stack is +currently overflowed. +.PP +.I Needstack +is defined in +.B libc.h +so that library functions used in threaded and non-threaded contexts +can call it. +The implementation of +.I needstack +in +.B lib9 +is a no-op. +.PP +.I Needstack +should be thought of as a comment checked at run time, +like +.IR assert (3). +.SH EXAMPLE +The X Window library implementation of +.I XLookupString +allocates some very large buffers on the stack, so +.B /usr/local/plan9/src/libdraw/x11-itrans.c +calls +.B needstack(20*1024) +before making calls to +.IR XLookupString . +If a thread (in this case, the keyboard-reading thread used +inside the +.IR draw (3) +library) +does not allocate a large enough stack, the problem is diagnosed +immediately rather than left to corrupt memory. +.SH SOURCE +.B /usr/local/plan9/src/lib9/needstack.c +.br +.B /usr/local/plan9/src/libthread +.SH SEE ALSO +.IR thread (3) diff --git a/man/man3/notify.3 b/man/man3/notify.3 index 0286ea8f..41b84521 100644 --- a/man/man3/notify.3 +++ b/man/man3/notify.3 @@ -1,6 +1,6 @@ .TH NOTIFY 3 .SH NAME -notify, noted, atnotify \- handle asynchronous process notification +notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff \- handle asynchronous process notification .SH SYNOPSIS .B #include .br @@ -14,36 +14,34 @@ int noted(int v) .PP .B int atnotify(int (*f)(void*, char*), int in) +.PP +.B +int noteenable(char *msg) +.br +.B +int notedisable(char *msg) +.PP +.B +int notifyon(char *msg) +.br +.B +int notifyoff(char *msg) .SH DESCRIPTION When a process raises an exceptional condition such as dividing by zero or writing on a closed pipe, a .I note is posted to communicate the exception. -A note may also be posted by a -.I write -(see -.IR read (3)) -to the process's -.BI /proc/ n /note -file or to the -.BI /proc/ m /notepg -file of a process in the same process group (see -.IR proc (3)). -When the note is received -the behavior of the process depends on the origin of the note. -If the note was posted by an external process, -the process receiving the note exits; -if generated by the system the note string, -preceded by the name -and id of the process and the string -\fL"suicide: "\fP, -is printed on the process's standard error file -and the -process is suspended in the -.B Broken -state for debugging. -.PP -These default actions may be overridden. +A note may also be posted by another process +via +.IR postnote (3). +On Unix, notes are implemented as signals. +.PP +When a note is received, the action taken depends on the note. +See +.IR signal (7) +for the full description of the defaults. +.PP +The default actions may be overridden. The .I notify function registers a @@ -55,7 +53,7 @@ replaces the previous handler, if any. An argument of zero cancels a previous handler, restoring the default action. A -.IR fork (3) +.IR fork (2) system call leaves the handler registered in both the parent and the child; .IR exec (3) @@ -64,20 +62,19 @@ Handlers may not perform floating point operations. .PP After a note is posted, the handler is called with two arguments: -the first is a pointer to a +the first is unimplemented and should not be used +(on Plan 9 +it is a .B Ureg -structure (defined in -.BR /$objtype/include/ureg.h ) -giving the current values of registers; +structure +giving the current values of registers); the second is a pointer to the note itself, -a null-terminated string with no more than -.L ERRLEN -characters in it including the terminal NUL. -The -.B Ureg -argument is usually not needed; it is provided to help recover from traps such -as floating point exceptions. -Its use and layout are machine- and system-specific. +a null-terminated string. +.\" The +.\" .B Ureg +.\" argument is usually not needed; it is provided to help recover from traps such +.\" as floating point exceptions. +.\" Its use and layout are machine- and system-specific. .PP A notification handler must finish either by exiting the program or by calling .IR noted ; @@ -115,14 +112,32 @@ set up with using the .I notejmp function (see -.IR setjmp (3)), -which is implemented by modifying the saved state and calling -.BR noted(NCONT) . +.IR setjmp (3)). +.PP +Unix provides a fixed set of notes (typically there are 32) called +.IR signals . +It also allows a process to block certain notes from being delivered +(see +.IR sigprocmask (2)) +and to ignore certain notes by setting the signal hander to the special value +.B SIG_IGN +(see +.IR signal (2)). +.I Noteenable +and +.I notedisable +enable or disable receipt of a particular note by changing the current process's blocked signal mask. +Receipt of a disabled note will be postponed until it is reenabled. +.I Notifyon +and +.I notifyoff +enable or disable whether the notification handler +is called upon receipt of the note; if the handler is not called, the note is discarded. .PP Regardless of the origin of the note or the presence of a handler, if the process is being debugged (see -.IR proc (3)) +.IR ptrace (2)) the arrival of a note puts the process in the .B Stopped state and awakens the debugger. @@ -158,87 +173,67 @@ calls .I noted with argument .BR NDFLT . -.PP -.I Noted -has two other possible values for its argument. -.B NSAVE -returns from the handler and clears the note, enabling the receipt of another, -but does not return to the program. -Instead it starts a new handler with the same stack, stack pointer, -and arguments as the -original, at the address recorded in the program counter of the -.B Ureg -structure. Typically, the program counter will be overridden by the -first note handler to be the address of a separate function; -.B NSAVE -is then a `trampoline' to that handler. -That handler may executed -.B noted(NRSTR) -to return to the original program, usually after restoring the original program -counter. -.B NRSTR -is identical to -.BR NCONT -except that it can only be executed after an -.BR NSAVE . -.B NSAVE -and -.B NRSTR -are designed to improve the emulation of signals by the ANSI C/POSIX -environment; their use elsewhere is discouraged. +.\" .PP +.\" .I Noted +.\" has two other possible values for its argument. +.\" .B NSAVE +.\" returns from the handler and clears the note, enabling the receipt of another, +.\" but does not return to the program. +.\" Instead it starts a new handler with the same stack, stack pointer, +.\" and arguments as the +.\" original, at the address recorded in the program counter of the +.\" .B Ureg +.\" structure. Typically, the program counter will be overridden by the +.\" first note handler to be the address of a separate function; +.\" .B NSAVE +.\" is then a `trampoline' to that handler. +.\" That handler may executed +.\" .B noted(NRSTR) +.\" to return to the original program, usually after restoring the original program +.\" counter. +.\" .B NRSTR +.\" is identical to +.\" .BR NCONT +.\" except that it can only be executed after an +.\" .BR NSAVE . +.\" .B NSAVE +.\" and +.\" .B NRSTR +.\" are designed to improve the emulation of signals by the ANSI C/POSIX +.\" environment; their use elsewhere is discouraged. .PP The set of notes a process may receive is system-dependent, but there is a common set that includes: .PP .RS 3n .nf -.ta \w'\fLsys: write on closed pipe \fP'u -\fINote\fP \fIMeaning\fP -\fLinterrupt\fP user interrupt (DEL key) -\fLhangup\fP I/O connection closed -\fLalarm\fP alarm expired -\fLsys: breakpoint\fP breakpoint instruction -\fLsys: bad address\fP system call address argument out of range -\fLsys: odd address\fP system call address argument unaligned -\fLsys: bad sys call\fP system call number out of range -\fLsys: odd stack\fP system call user stack unaligned -\fLsys: write on closed pipe\fP write on closed pipe -\fLsys: fp: \fIfptrap\f1 floating point exception -\fLsys: trap: \fItrap\f1 other exception (see below) +.ta \w'\fLsys: write on closed pipe \fP'u \w'system call address argument out of range 'u +\fINote\fP \fIMeaning\fP \fIUnix signal\fP +\fLinterrupt\fP user interrupt (DEL key) SIGINTR +\fLhangup\fP I/O connection closed SIGHUP +\fLalarm\fP alarm expired SIGLARM +\fLquit\fP quit from keyboard SIGQUIT +\fLkill\fP process requested to exit SIGTERM +\fLsys: kill\fP process forced to exit SIGKILL +\fLsys: bus error\fP bus error SIGBUS +\fLsys: segmentation violation\fP segmentation violation SIGSEGV .fi .RE .PP +See +.B /usr/local/plan9/src/lib9/await.c +(sic) +for the full list. +.PP The notes prefixed .B sys: -are generated by the operating system. -They are suffixed by the user program counter in format -.BR pc=0x1234 . -If the note is due to a floating point exception, just before the -.BR pc -is the address of the offending instruction in format -.BR fppc=0x1234 . -Notes are limited to -.B ERRLEN -bytes; if they would be longer they are truncated but the -.B pc -is always reported correctly. -.PP -The types and syntax of the -.I trap -and -.I fptrap -portions of the notes are machine-dependent. +are usually generated by the operating system. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/notify.c .br -.B /usr/local/plan9/src/libc/port/atnotify.c +.B /usr/local/plan9/src/lib9/atnotify.c .SH SEE ALSO .IR intro (3), .I notejmp in .IR setjmp (3) -.SH BUGS -Since -.IR exec (3) -discards the notification handler, there is a window -of vulnerability to notes in a new process. diff --git a/man/man3/open.3 b/man/man3/open.3 index 46b4fe58..b964cc9a 100644 --- a/man/man3/open.3 +++ b/man/man3/open.3 @@ -94,7 +94,7 @@ bit is set. Exclusive-use files may be open for I/O by only one client at a time, but the file descriptor may become invalid if no I/O is done for an extended period; see -.IR open (5). +.IR open (9p). .PP .I Create fails if the path up to the last element of @@ -106,12 +106,12 @@ does not permit the access defined by of if there there are no free file descriptors. In the last case, the file may be created even when an error is returned. -If the file is new and the directory in which it is created is -a union directory (see -.IR intro (3)) -then the constituent directory where the file is created -depends on the structure of the union: see -.IR bind (3). +.\" If the file is new and the directory in which it is created is +.\" a union directory (see +.\" .IR intro (3)) +.\" then the constituent directory where the file is created +.\" depends on the structure of the union: see +.\" .IR bind (3). .PP Since .I create @@ -126,7 +126,7 @@ for a .IR create, the call succeeds only if the file does not already exist; see -.IR open (5) +.IR open (9p) for details. .PP .I Close @@ -138,10 +138,9 @@ Files are closed automatically upon termination of a process; .I close allows the file descriptor to be reused. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR intro (3), -.IR bind (3), .IR stat (3) .SH DIAGNOSTICS These functions set diff --git a/man/man3/opentemp.3 b/man/man3/opentemp.3 new file mode 100644 index 00000000..23e77d3d --- /dev/null +++ b/man/man3/opentemp.3 @@ -0,0 +1,48 @@ +.TH OPENTEMP 3 +.SH NAME +opentemp \- create a uniquely-named file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int opentemp(char *template) +.SH DESCRIPTION +.I Opentemp +replaces +.I template +by a unique file name, and returns the +address of the template. +The template should look like a file name with eleven trailing +.LR X s. +The +.LR X s +are replaced by a letter followed by the current process id. +Letters from +.L a +to +.L z +are tried until the name of a file that does not yet exist +(see +.IR access (2)) +is generated. +.I Opentemp +then creates the file for reading and writing +and returns the file descriptor. +.PP +If no such name can be generated, +.I opentemp +returns \-1. +.PP +.I Opentemp +avoids races. +Two simultaneous calls to +.I opentemp +will never return the same name. +.SH SOURCE +.B /usr/local/plan9/src/lib9/opentemp.c +.SH "SEE ALSO +.I create +in +.IR open (3) diff --git a/man/man3/pipe.3 b/man/man3/pipe.3 index 06d37694..993e33ab 100644 --- a/man/man3/pipe.3 +++ b/man/man3/pipe.3 @@ -25,50 +25,76 @@ is available for reading from After the pipe has been established, cooperating processes created by subsequent -.IR fork (3) +.IR fork (2) calls may pass data through the pipe with .I read and .I write calls. -The bytes placed on a pipe -by one -.I write -are contiguous even if many processes are writing. -Write boundaries are preserved: each read terminates -when the read buffer is full or after reading the last byte -of a write, whichever comes first. -.PP -The number of bytes available to a -.IR read (3) -is reported -in the -.B Length -field returned by -.I fstat -or -.I dirfstat -on a pipe (see -.IR stat (3)). +.\" The bytes placed on a pipe +.\" by one +.\" .I write +.\" are contiguous even if many processes are writing. +.\" Write boundaries are preserved: each read terminates +.\" when the read buffer is full or after reading the last byte +.\" of a write, whichever comes first. +.\" .PP +.\" The number of bytes available to a +.\" .IR read (3) +.\" is reported +.\" in the +.\" .B Length +.\" field returned by +.\" .I fstat +.\" or +.\" .I dirfstat +.\" on a pipe (see +.\" .IR stat (3)). .PP When all the data has been read from a pipe and the writer has closed the pipe or exited, .IR read (3) will return 0 bytes. Writes to a pipe with no reader will generate a note .BR "sys: write on closed pipe" . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/pipe.c .SH SEE ALSO .IR intro (3), -.IR read (3), -.IR pipe (3) +.IR read (3) .SH DIAGNOSTICS Sets .IR errstr . .SH BUGS If a read or a write of a pipe is interrupted, some unknown number of bytes may have been transferred. -.br -When a read from a pipe returns 0 bytes, it usually means end of file -but is indistinguishable from reading the result of an explicit -write of zero bytes. +.PP +.I Pipe +is a macro defined as +.I p9pipe +to avoid name conflicts with Unix's +.I pipe +system call. +.PP +Unix pipes are not guaranteed to be bidirectional. +In order to ensure a bidirectional channel, +.I p9pipe +creates Unix domain sockets via the +.IR socketpair (2) +instead of Unix pipes. +.PP +The implementation of pipes as Unix domain sockets +causes problems with some Unix implementations of +.BR /dev/fd , +Unix's dup device. If a Unix domain socket is open as file +descriptor 0, some implementations disallow the opening of +.BR /dev/fd/0 ; +instead one must +.IR connect (2) +to it. +If this functionality is important +(as it is for +.IR rc (1)), +one must +.B #undef +.B pipe +and fall back on the (possibly unidirectional) Unix pipes. diff --git a/man/man3/plumb.3 b/man/man3/plumb.3 index f75acb39..c988bbab 100644 --- a/man/man3/plumb.3 +++ b/man/man3/plumb.3 @@ -1,6 +1,6 @@ .TH PLUMB 3 .SH NAME -eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages +eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages .SH SYNOPSIS .B #include .br @@ -51,9 +51,21 @@ Plumbattr* plumbdelattr(Plumbattra *a, char *name) .PP .B int eplumb(int key, char *port) +.PP +.B +#include <9pclient.h> +.PP +.B +CFid *plumbopenfid(char *port, int omode) +.PP +.B +Plumbmsg* plumbrecvfid(CFid *fid) +.PP +.B +int plumbsendtofid(CFid *fid, Plumbmsg *m) .SH DESCRIPTION These routines manipulate -.IR plumb (6) +.IR plumb (7) messages, transmitting them, receiving them, and converting them between text and these data structures: .IP @@ -141,7 +153,7 @@ or nil for error. encodes message .I m as a character string in the format of -.IR plumb (6) , +.IR plumb (7) , setting .BI * np to the length in bytes of the string. @@ -226,15 +238,49 @@ for the first attribute with name and deletes it from the list, returning the resulting list. .I Plumbdelattr is a no-op if no such attribute exists. +.PP +The file descriptor returned by +.I plumbopen +is created with +.I fsopenfd +(see +.IR 9pclient (3)), +which masks information about read and write errors. +This is acceptable for use in +.I plumbrecv +but not for +.IR plumbsend , +which depends on seeing details of write errors. +.IR Plumbopenfid , +.IR plumbrecvfid , +and +.IR plumbsendtofid +provide an explicit interface to +.I lib9pclient +that preserves the exact error details. .SH SOURCE .B /usr/local/plan9/src/libplumb .SH SEE ALSO .IR plumb (1), .IR event (3), .IR plumber (4), -.IR plumb (6) +.IR plumb (7) .SH DIAGNOSTICS When appropriate, including when a .I plumbsend fails, these routine set .IR errstr . +.SH BUGS +To avoid rewriting clients that use +.IR plumbsend , +the call +.B plumbopen("send", +.B OWRITE) +returns a useless file descriptor +(it is opened to +.BR /dev/null ). +.I Plumbsend +looks for this particular file descriptor +and uses a static copy of the +.B CFid +instead. diff --git a/man/man3/post9pservice.3 b/man/man3/post9pservice.3 new file mode 100644 index 00000000..74404c17 --- /dev/null +++ b/man/man3/post9pservice.3 @@ -0,0 +1,29 @@ +.TH POST9PSERVICE 3 +.SH NAME +post9pservice \- post 9P service for use by clients +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int post9pservice(int fd, char *name) +.SH DESCRIPTION +.I Post9pservice +invokes +.IR 9pserve (4) +to post a new 9P service in the current +``name space'' +(see +.IR intro (4)) +named +.IR name . +Clients connecting to the posted service +are multiplexed onto a single 9P conversation with the server +on file descriptor +.IR fd . +.SH "SEE ALSO +.IR intro (4), +.IR 9pserve (4) +.SH SOURCE +.B /usr/local/plan9/src/lib9/post9p.c diff --git a/man/man3/postnote.3 b/man/man3/postnote.3 index fed339bd..535c7e6c 100644 --- a/man/man3/postnote.3 +++ b/man/man3/postnote.3 @@ -19,17 +19,16 @@ is .BR PNPROC , then .I note -is written to -.BI /proc/ pid /note\f1. +is sent to the process with id +.IR pid . If .I who is .BI PNGROUP , the note is delivered to the -process group by writing -.I note -to -.BI /proc/ pid /notepg\f1. +process group which has the process with id +.I pid +as a member. For .B PNGROUP only, if the calling process is in the target group, the note is @@ -39,11 +38,10 @@ delivered to that process. If the write is successful, zero is returned. Otherwise \-1 is returned. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/postnote.c +.B /usr/local/plan9/src/lib9/postnote.c .SH "SEE ALSO" .IR notify (3), -.IR intro (3), -.IR proc (3) +.IR intro (3) .SH DIAGNOSTICS Sets .IR errstr . diff --git a/man/man3/print.3 b/man/man3/print.3 index 1fab0ad8..b1c8545f 100644 --- a/man/man3/print.3 +++ b/man/man3/print.3 @@ -8,7 +8,7 @@ .ft R .. .SH NAME -print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output +print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output .SH SYNOPSIS .B #include .PP diff --git a/man/man3/proto.3 b/man/man3/proto.3 new file mode 100644 index 00000000..ab8d304c --- /dev/null +++ b/man/man3/proto.3 @@ -0,0 +1,131 @@ +.TH PROTO 3 +.SH NAME +rdproto \- parse and process a proto file listing +.SH SYNOPSIS +.nf +.ft L +#include +#include +#include +.ft +.PP +.B +typedef void Protoenum(char *new, char *old, Dir *d, void *a) +.PP +.B +typedef void Protowarn(char *msg, void *a) +.PP +.B +int rdproto(char *proto, char *root, Protoenum *enm, +.br +.B + Protowarn *warn, void *a) +.SH DESCRIPTION +.I Rdproto +reads and interprets the named +.I proto +file relative to the +root directory +.IR root . +.PP +Each line of the +.I proto +file specifies a file to copy. +Blank lines and lines beginning with +.B # +are ignored. +Indentation (usually tabs) is significant, +with each level of indentation corresponding to a level in the file tree. +Fields within a line are separated by white space. +The first field is the last path element in the destination file tree. +The second field specifies the permissions. +The third field is the owner of the file, +and the fourth is the group owning the file. +The fifth field is the name of the file from which to copy; +this file is read from the current name space, +not the source file tree. +All fields except the first are optional. +Specifying +.B - +for permissions, owner, or group +causes +.I rdproto +to fetch the corresponding information +from the file rather than override it. +(This is the default behavior when the fields +are not present; explicitly specifying +.B - +is useful when one wishes to set, say, +the file owner without setting the permissions.) +.PP +Names beginning with a +.L $ +are expanded as environment variables. +If the first file specified in a directory is +.LR * , +all of the files in that directory are considered listed. +If the first file is +.LR + , +all of the files are copied, and all subdirectories +are recursively considered listed. +All files are considered relative to +.IR root . +.PP +For each file named by the +.IR proto , +.I enm +is called with +.I new +pointing at the name of the file (without the root prefix), +.I old +pointing at the name of the source file (with the root prefix, +when applicable), +and +.I Dir +at the desired directory information for the new file. +Only the +.BR name , +.BR uid , +.BR gid , +.BR mode , +.BR mtime , +and +.B length +fields are guaranteed to be valid. +The argument +.I a +is the same argument passed to +.IR rdproto ; +typically it points at some extra state +used by the enumeration function. +.PP +When files or directories do not exist or +cannot be read by +.IR rdproto , +it formats a warning message, calls +.IR warn , +and continues processing; +if +.I warn +is nil, +.I rdproto +prints the warning message to standard error. +.PP +.I Rdproto +returns zero +if +.I proto +was processed, \-1 if it could not be opened. +.SH FILES +.TF /sys/lib/sysconfig/proto/portproto +.TP +.B /sys/lib/sysconfig/proto/ +directory of prototype files. +.TP +.B /sys/lib/sysconfig/proto/portproto +generic prototype file. +.SH SOURCE +.B /usr/local/plan9/src/libdisk/proto.c +.SH SEE ALSO +.IR mk9660 (8), +Plan 9's \fImkfs\fR(8) diff --git a/man/man3/pushtls.3 b/man/man3/pushtls.3 new file mode 100644 index 00000000..b92dcb6e --- /dev/null +++ b/man/man3/pushtls.3 @@ -0,0 +1,196 @@ +.TH PUSHTLS 3 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int pushtls(int fd, char *hashalg, char *encalg, +.br +.B + int isclient, char *secret, char *dir) +.PP +.B #include +.br +.B #include +.PP +.B +int tlsClient(int fd, TLSconn *conn) +.PP +.B +int tlsServer(int fd, TLSconn *conn) +.PP +.B +uchar *readcert(char *filename, int *pcertlen) +.PP +.B +PEMchain *readcertchain(char *filename) +.PP +.B +Thumbprint* initThumbprints(char *ok, char *crl) +.PP +.B +void freeThumbprints(Thumbprint *table) +.PP +.B +int okThumbprint(uchar *hash, Thumbprint *table) +.SH DESCRIPTION +Transport Layer Security (TLS) comprises a record layer protocol, +doing message digesting and encrypting in the kernel, +and a handshake protocol, +doing initial authentication and secret creation at +user level and then starting a data channel in the record protocol. +TLS is nearly the same as SSL 3.0, and the software should interoperate +with implementations of either standard. +.PP +To use just the record layer, as described in Plan 9's +\fItls\fR(3), +call +.I pushtls +to open the record layer device, connect to the communications channel +.IR fd , +and start up encryption and message authentication as specified +in +.IR hashalg , +.IR encalg , +and +.IR secret . +These parameters must have been arranged at the two ends of the +conversation by other means. +For example, +.I hashalg +could be +.BR sha1 , +.I encalg +could be +.BR rc4_128 , +and +.I secret +could be the base-64 encoding of two (client-to-server and server-to-client) +20-byte digest keys and two corresponding 16-byte encryption keys. +.I Pushtls +returns a file descriptor for the TLS data channel. Anything written to this +descriptor will get encrypted and authenticated and then written to the +file descriptor, +.IR fd . +If +.I dir +is non-zero, the path name of the connection directory is copied into +.IR dir . +This path name is guaranteed to be less than 40 bytes long. +.PP +Alternatively, call +.I tlsClient +to speak the full handshake protocol, +negotiate the algorithms and secrets, +and return a new data file descriptor for the data channel. +.I Conn +points to a (caller-allocated) struct +.EX + typedef struct TLSconn{ + char dir[40]; // OUT connection directory + uchar *cert; // IN/OUT certificate + uchar *sessionID; // IN/OUT sessionID + int certlen, sessionIDlen; + void (*trace)(char*fmt, ...); + PEMChain *chain; + } TLSconn; +.EE +defined in +.IR tls.h . +On input, the caller can provide options such as +.IR cert , +the local certificate, and +.IR sessionID , +used by a client to resume a previously negotiated security association. +On output, the connection directory is set, as with +.B listen +(see +.IR dial (3)). +The input +.I cert +is freed and a freshly allocated copy of the remote's certificate +is returned in +.IR conn , +to be checked by the caller +according to its needs. One mechanism is supplied by +.I initThumbprints +and +.I freeThumbprints +which allocate and free, respectively, a table of hashes +from files of known trusted and revoked certificates. +.I okThumbprint +confirms that a particular hash is in the table, as computed by +.PP +.EX + uchar hash[SHA1dlen]; + conn = (TLSconn*)mallocz(sizeof *conn, 1); + fd = tlsClient(fd, conn); + sha1(conn->cert, conn->certlen, hash, nil); + if(!okThumbprint(hash,table)) + exits("suspect server"); + ...application begins... +.EE +.PP +Call +.I tlsServer +to perform the corresponding function on the server side: +.PP +.EX + fd = accept(lcfd, ldir); + conn = (TLSconn*)mallocz(sizeof *conn, 1); + conn->cert = readcert("cert.pem", &conn->certlen); + fd = tlsServer(fd, conn); + ...application begins... +.EE +The private key corresponding to +.I cert.pem +should have been previously loaded into factotum. +(See +.IR rsa (3) +.\" XXX should be rsa(8) +for more about key generation.) +By setting +.EX + conn->chain = readcertchain("intermediate-certs.pem"); +.EE +the server can present extra certificate evidence +to establish the chain of trust to a root authority +known to the client. +.PP +.I Conn +is not required for the ongoing conversation and may +be freed by the application whenever convenient. +.SH FILES +.TP +.B /sys/lib/tls +thumbprints of trusted services +.TP +.B /sys/lib/ssl +PEM certificate files +.SH SOURCE +.\" .B /sys/src/libc/9sys/pushtls.c +.\" .br +.B /usr/local/plan9/src/libsec/port +.SH "SEE ALSO" +.IR dial (3), +.IR thumbprint (7); +Plan 9's +\fIfactotum\fR(4) +and +\fItls\fR(3) +.SH DIAGNOSTICS +return \-1 on failure. +.SH BUGS +.I Pushtls +is not implemented. +.PP +Client certificates and client sessionIDs are not yet +implemented. +.PP +Note that in the TLS protocol +.I sessionID +itself is public; it is used as a pointer to +secrets stored in factotum. diff --git a/man/man3/qball.3 b/man/man3/qball.3 new file mode 100644 index 00000000..8d27f21a --- /dev/null +++ b/man/man3/qball.3 @@ -0,0 +1,76 @@ +.TH QBALL 3 +.SH NAME +qball \- 3-d rotation controller +.SH SYNOPSIS +.PP +.B +#include +.PP +.B +#include +.PP +.B +void qball(Rectangle r, Mouse *mousep, +.br +.B + Quaternion *orientation, +.br +.B + void (*redraw)(void), Quaternion *ap) +.SH DESCRIPTION +.I Qball +is an interactive controller that allows arbitrary 3-space rotations to be specified with +the mouse. Imagine a sphere with its center at the midpoint of rectangle +.IR r , +and diameter the smaller of +.IR r 's +dimensions. Dragging from one point on the sphere to another specifies the endpoints of a +great-circle arc. (Mouse points outside the sphere are projected to the nearest point +on the sphere.) The axis of rotation is normal to the plane of the arc, and the +angle of rotation is twice the angle of the arc. +.PP +Argument +.I mousep +is a pointer to the mouse event that triggered the interaction. It should +have some button set. +.I Qball +will read more events into +.IR mousep , +and return when no buttons are down. +.PP +While +.I qball +is reading mouse events, it calls out to the caller-supplied routine +.IR redraw , +which is expected to update the screen to reflect the changing orientation. +Argument +.I orientation +is the orientation that +.I redraw +should examine, represented as a unit Quaternion (see +.IR quaternion(9.2)). +The caller may set it to any orientation. +It will be updated before each call to +.I redraw +(and on return) by multiplying by the rotation specified with the mouse. +.PP +It is possible to restrict +.I qball's +attention to rotations about a particular axis. +If +.I ap +is null, the rotation is unconstrained. +Otherwise, the rotation will be about the same axis as +.IR *ap . +This is accomplished by projecting points on the sphere to +the nearest point also on the plane through the sphere's center +and normal to the axis. +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/qball.c +.SH SEE ALSO +.IR quaternion (3) +.br +Ken Shoemake, +``Animating Rotation with Quaternion Curves'', +.I +SIGGRAPH '85 Conference Proceedings. diff --git a/man/man3/quaternion.3 b/man/man3/quaternion.3 new file mode 100644 index 00000000..31f4ab50 --- /dev/null +++ b/man/man3/quaternion.3 @@ -0,0 +1,152 @@ +.TH QUATERNION 3 +.SH NAME +qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt \- Quaternion arithmetic +.SH SYNOPSIS +.PP +.B +#include +.PP +.B +#include +.PP +.B +Quaternion qadd(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsub(Quaternion q, Quaternion r) +.PP +.B +Quaternion qneg(Quaternion q) +.PP +.B +Quaternion qmul(Quaternion q, Quaternion r) +.PP +.B +Quaternion qdiv(Quaternion q, Quaternion r) +.PP +.B +Quaternion qinv(Quaternion q) +.PP +.B +double qlen(Quaternion p) +.PP +.B +Quaternion qunit(Quaternion q) +.PP +.B +void qtom(Matrix m, Quaternion q) +.PP +.B +Quaternion mtoq(Matrix mat) +.PP +.B +Quaternion slerp(Quaternion q, Quaternion r, double a) +.PP +.B +Quaternion qmid(Quaternion q, Quaternion r) +.PP +.B +Quaternion qsqrt(Quaternion q) +.SH DESCRIPTION +The Quaternions are a non-commutative extension field of the Real numbers, designed +to do for rotations in 3-space what the complex numbers do for rotations in 2-space. +Quaternions have a real component +.I r +and an imaginary vector component \fIv\fP=(\fIi\fP,\fIj\fP,\fIk\fP). +Quaternions add componentwise and multiply according to the rule +(\fIr\fP,\fIv\fP)(\fIs\fP,\fIw\fP)=(\fIrs\fP-\fIv\fP\v'-.3m'.\v'.3m'\fIw\fP, \fIrw\fP+\fIvs\fP+\fIv\fP×\fIw\fP), +where \v'-.3m'.\v'.3m' and × are the ordinary vector dot and cross products. +The multiplicative inverse of a non-zero quaternion (\fIr\fP,\fIv\fP) +is (\fIr\fP,\fI-v\fP)/(\fIr\^\fP\u\s-22\s+2\d-\fIv\fP\v'-.3m'.\v'.3m'\fIv\fP). +.PP +The following routines do arithmetic on quaternions, represented as +.IP +.EX +.ta 6n +typedef struct Quaternion Quaternion; +struct Quaternion{ + double r, i, j, k; +}; +.EE +.TF qunit +.TP +Name +Description +.TP +.B qadd +Add two quaternions. +.TP +.B qsub +Subtract two quaternions. +.TP +.B qneg +Negate a quaternion. +.TP +.B qmul +Multiply two quaternions. +.TP +.B qdiv +Divide two quaternions. +.TP +.B qinv +Return the multiplicative inverse of a quaternion. +.TP +.B qlen +Return +.BR sqrt(q.r*q.r+q.i*q.i+q.j*q.j+q.k*q.k) , +the length of a quaternion. +.TP +.B qunit +Return a unit quaternion +.RI ( length=1 ) +with components proportional to +.IR q 's. +.PD +.PP +A rotation by angle \fIθ\fP about axis +.I A +(where +.I A +is a unit vector) can be represented by +the unit quaternion \fIq\fP=(cos \fIθ\fP/2, \fIA\fPsin \fIθ\fP/2). +The same rotation is represented by \(mi\fIq\fP; a rotation by \(mi\fIθ\fP about \(mi\fIA\fP is the same as a rotation by \fIθ\fP about \fIA\fP. +The quaternion \fIq\fP transforms points by +(0,\fIx',y',z'\fP) = \%\fIq\fP\u\s-2-1\s+2\d(0,\fIx,y,z\fP)\fIq\fP. +Quaternion multiplication composes rotations. +The orientation of an object in 3-space can be represented by a quaternion +giving its rotation relative to some `standard' orientation. +.PP +The following routines operate on rotations or orientations represented as unit quaternions: +.TF slerp +.TP +.B mtoq +Convert a rotation matrix (see +.IR matrix (3)) +to a unit quaternion. +.TP +.B qtom +Convert a unit quaternion to a rotation matrix. +.TP +.B slerp +Spherical lerp. Interpolate between two orientations. +The rotation that carries +.I q +to +.I r +is \%\fIq\fP\u\s-2-1\s+2\d\fIr\fP, so +.B slerp(q, r, t) +is \fIq\fP(\fIq\fP\u\s-2-1\s+2\d\fIr\fP)\u\s-2\fIt\fP\s+2\d. +.TP +.B qmid +.B slerp(q, r, .5) +.TP +.B qsqrt +The square root of +.IR q . +This is just a rotation about the same axis by half the angle. +.PD +.SH SOURCE +.B /usr/local/plan9/src/libgeometry/quaternion.c +.SH SEE ALSO +.IR matrix (3), +.IR qball (3) diff --git a/man/man3/quote.3 b/man/man3/quote.3 index 286cdd90..5a4c8d19 100644 --- a/man/man3/quote.3 +++ b/man/man3/quote.3 @@ -157,9 +157,9 @@ in .IR print (3) format strings. .SH SOURCE -.B /usr/local/plan9/src/libc/port/quote.c +.B /usr/local/plan9/src/lib9/quote.c .br -.B /usr/local/plan9/src/libc/fmt/fmtquote.c +.B /usr/local/plan9/src/lib9/fmt/fmtquote.c .SH "SEE ALSO .IR rc (1), .IR malloc (3), diff --git a/man/man3/rand.3 b/man/man3/rand.3 index 3f3e0061..25ea8a43 100644 --- a/man/man3/rand.3 +++ b/man/man3/rand.3 @@ -156,18 +156,12 @@ to return a uniform .IR x , .RI 0≤ x < val ≤ 2\u\s732\s10\d-1. .SH SOURCE -.B /usr/local/plan9/src/libc/port/*rand.c +.B /usr/local/plan9/src/lib9/ .br -.B /usr/local/plan9/src/libc/9sys/truerand.c -.br -.B /usr/local/plan9/src/libsec/port/genrandom.c -.br -.B /usr/local/plan9/src/libsec/port/prng.c -.br -.B /usr/local/plan9/src/libsec/port/*fastrand.c +.B /usr/local/plan9/src/libsec/port/ .SH "SEE ALSO -.IR cons (3), -.IR mp (3), +.\" .IR cons (3), +.IR mp (3) .SH BUGS .I Truerand and diff --git a/man/man3/read.3 b/man/man3/read.3 index aa35c659..34e65c6e 100644 --- a/man/man3/read.3 +++ b/man/man3/read.3 @@ -75,21 +75,18 @@ or By combining the operations in a single atomic call, they more closely match the 9P protocol (see -.IR intro (5)) +.IR intro (9p)) and, more important, permit multiprocess programs to execute multiple concurrent read and write operations on the same file descriptor without interference. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.br -.B /usr/local/plan9/src/libc/port/readn.c +.B /usr/local/plan9/src/lib9/readn.c .SH SEE ALSO .IR intro (3), .IR open (3), .IR dup (3), -.IR pipe (3), -.IR readv (3) +.IR pipe (3) .SH DIAGNOSTICS These functions set .IR errstr . diff --git a/man/man3/readcolmap.3 b/man/man3/readcolmap.3 new file mode 100644 index 00000000..51753c57 --- /dev/null +++ b/man/man3/readcolmap.3 @@ -0,0 +1,76 @@ +.TH READCOLMAP 3 +.SH NAME +RGB, readcolmap, writecolmap \- access display color map +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.PP +.ta \w'\fLvoid 'u +.PP +.B +int readcolmap(Display *d, RGB *map) +.PP +.B +int writecolmap(Display *d, RGB *map) +.fi +.SH DESCRIPTION +Colors are described by their red, green, and blue +light intensities, in an +.B RGB +datum: +.IP +.EX +.ta 6n +typedef +struct RGB { + ulong red; + ulong green; + ulong blue; +} RGB; +.EE +.PP +Black is represented by zero in all three positions and +white has the maximum +.B unsigned +.B long +value in all three positions. +.PP +A color map is an array of +.BR RGB s, +of length +.if t \x'-.8n'2\u\s-1\fIdepth\fP\s+1\d, +.if n 2^\fIdepth\fP, +giving the colors for pixels 0, 1, 2, etc. +On displays with color mapped pixels +(typically 8-bit displays), +one retrieves RGB color information +by treating the pixel data as an offset +into the color map. +.PP +.I Readcolmap +reads the color map for the given display into the provided +.IR map , +which must have enough space to hold it. +.I Writecolmap +associates the given color map with the given display, if possible. +(The hardware might not allow this.) +Both return 0 on success, or \-1 on error, setting +.IR errstr . +.PP +Changing the hardware color map does not change +the color map used by the +.IR draw (3) +operator to convert between +mapped and true color or greyscale images, +which is described in +.IR color (7). +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH "SEE ALSO" +.IR graphics (3), +.IR draw (3), +.IR color (7) diff --git a/man/man3/regexp.3 b/man/man3/regexp.3 index 92f07015..2d3c1a21 100644 --- a/man/man3/regexp.3 +++ b/man/man3/regexp.3 @@ -46,7 +46,7 @@ The space is allocated by and may be released by .IR free . Regular expressions are exactly as in -.IR regexp (6). +.IR regexp (7). .PP .I Regcomplit is like diff --git a/man/man3/regexp9.3 b/man/man3/regexp9.3 new file mode 100644 index 00000000..dc5e4340 --- /dev/null +++ b/man/man3/regexp9.3 @@ -0,0 +1,212 @@ +.TH REGEXP9 3 +.SH NAME +regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror \- regular expression +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLRegprog 'u +.B +Reprog *regcomp(char *exp) +.PP +.B +Reprog *regcomplit(char *exp) +.PP +.B +Reprog *regcompnl(char *exp) +.PP +.nf +.B +int regexec(Reprog *prog, char *string, Resub *match, int msize) +.PP +.nf +.B +void regsub(char *source, char *dest, int dlen, Resub *match, int msize) +.PP +.nf +.B +int rregexec(Reprog *prog, Rune *string, Resub *match, int msize) +.PP +.nf +.B +void rregsub(Rune *source, Rune *dest, int dlen, Resub *match, int msize) +.PP +.B +void regerror(char *msg) +.SH DESCRIPTION +.I Regcomp +compiles a +regular expression and returns +a pointer to the generated description. +The space is allocated by +.IR malloc (3) +and may be released by +.IR free . +Regular expressions are exactly as in +.IR regexp9 (7). +.PP +.I Regcomplit +is like +.I regcomp +except that all characters are treated literally. +.I Regcompnl +is like +.I regcomp +except that the +.B . +metacharacter matches all characters, including newlines. +.PP +.I Regexec +matches a null-terminated +.I string +against the compiled regular expression in +.IR prog . +If it matches, +.I regexec +returns +.B 1 +and fills in the array +.I match +with character pointers to the substrings of +.I string +that correspond to the +parenthesized subexpressions of +.IR exp : +.BI match[ i ].sp +points to the beginning and +.BI match[ i ].ep +points just beyond +the end of the +.IR i th +substring. +(Subexpression +.I i +begins at the +.IR i th +left parenthesis, counting from 1.) +Pointers in +.B match[0] +pick out the substring that corresponds to +the whole regular expression. +Unused elements of +.I match +are filled with zeros. +Matches involving +.LR * , +.LR + , +and +.L ? +are extended as far as possible. +The number of array elements in +.I match +is given by +.IR msize . +The structure of elements of +.I match +is: +.IP +.EX +typedef struct { + union { + char *sp; + Rune *rsp; + }; + union { + char *ep; + Rune *rep; + }; +} Resub; +.EE +.LP +If +.B match[0].sp +is nonzero on entry, +.I regexec +starts matching at that point within +.IR string . +If +.B match[0].ep +is nonzero on entry, +the last character matched is the one +preceding that point. +.PP +.I Regsub +places in +.I dest +a substitution instance of +.I source +in the context of the last +.I regexec +performed using +.IR match . +Each instance of +.BI \e n\f1, +where +.I n +is a digit, is replaced by the +string delimited by +.BI match[ n ].sp +and +.BI match[ n ].ep\f1. +Each instance of +.L & +is replaced by the string delimited by +.B match[0].sp +and +.BR match[0].ep . +The substitution will always be null terminated and +trimmed to fit into dlen bytes. +.PP +.IR Regerror , +called whenever an error is detected in +.IR regcomp , +writes the string +.I msg +on the standard error file and exits. +.I Regerror +can be replaced to perform +special error processing. +If the user supplied +.I regerror +returns rather than exits, +.I regcomp +will return 0. +.PP +.I Rregexec +and +.I rregsub +are variants of +.I regexec +and +.I regsub +that use strings of +.B Runes +instead of strings of +.BR chars . +With these routines, the +.I rsp +and +.I rep +fields of the +.I match +array elements should be used. +.SH SOURCE +.B /usr/local/plan9/src/libregexp +.SH "SEE ALSO" +.IR grep (1) +.SH DIAGNOSTICS +.I Regcomp +returns +.B 0 +for an illegal expression +or other failure. +.I Regexec +returns 0 +if +.I string +is not matched. +.SH BUGS +There is no way to specify or match a NUL character; NULs terminate patterns and strings. diff --git a/man/man3/rendezvous.3 b/man/man3/rendezvous.3 deleted file mode 100644 index 97128ce1..00000000 --- a/man/man3/rendezvous.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH RENDEZVOUS 3 -.SH NAME -rendezvous \- user level process synchronization -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.B -ulong rendezvous(ulong tag, ulong value) -.SH DESCRIPTION -The rendezvous system call allows two processes to synchronize and -exchange a value. -In conjunction with the shared memory system calls -(see -.IR segattach (3) -and -.IR fork (3)), -it enables parallel programs to control their scheduling. -.PP -Two processes wishing to synchronize call -.I rendezvous -with a common -.IR tag , -typically an address in -memory they share. -One process will arrive at the rendezvous first; -it suspends execution until a second arrives. -When a second process meets the rendezvous -the -.I value -arguments are exchanged between the processes and returned -as the result of the respective -.I rendezvous -system calls. -Both processes are awakened when -the rendezvous succeeds. -.PP -The set of tag values which two processes may use to rendezvous\(emtheir tag space\(emis -inherited when a process forks, unless -.B RFREND -is set in the argument to -.BR rfork ; -see -.IR fork (3). -.PP -If a rendezvous is interrupted the return value is -.BR ~0 , -so that value should not be used in normal communication. -.SH SOURCE -.B /usr/local/plan9/src/libc/9syscall -.SH SEE ALSO -.IR segattach (3), -.IR fork (3) -.SH DIAGNOSTICS -Sets -.IR errstr . diff --git a/man/man3/rfork.3 b/man/man3/rfork.3 new file mode 100644 index 00000000..12cedda3 --- /dev/null +++ b/man/man3/rfork.3 @@ -0,0 +1,163 @@ +.TH RFORK 3 +.SH NAME +rfork \- manipulate process state +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int rfork(int flags) +.fi +.SH DESCRIPTION +.I Rfork +is a partial implementation of the Plan 9 system call. +It can be used to manipulate some process state and to create +new processes a la +.IR fork (2). +It cannot be used to create shared-memory processes +(Plan 9's +.B RFMEM +flag); for that functionality use +.I proccreate +(see +.IR thread (3)). +.PP +The +.I flags +argument to +.I rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +.I Flags +is the logical OR of some subset of +.TF RFCNAMEG +.TP +.B RFPROC +If set a new process is created; otherwise changes affect the +current process. +.TP +.B RFNOWAIT +If set, the child process will be dissociated from the parent. Upon +exit the child will leave no +.B Waitmsg +(see +.IR wait (3)) +for the parent to collect. +.\" .TP +.\" .B RFNAMEG +.\" If set, the new process inherits a copy of the parent's name space; +.\" otherwise the new process shares the parent's name space. +.\" Is mutually exclusive with +.\" .BR RFCNAMEG . +.\" .TP +.\" .B RFCNAMEG +.\" If set, the new process starts with a clean name space. A new +.\" name space must be built from a mount of an open file descriptor. +.\" Is mutually exclusive with +.\" .BR RFNAMEG . +.\" .TP +.\" .B RFNOMNT +.\" If set, subsequent mounts into the new name space and dereferencing +.\" of pathnames starting with +.\" .B # +.\" are disallowed. +.\" .TP +.\" .B RFENVG +.\" If set, the environment variables are copied; +.\" otherwise the two processes share environment variables. +.\" Is mutually exclusive with +.\" .BR RFCENVG . +.\" .TP +.\" .B RFCENVG +.\" If set, the new process starts with an empty environment. +.\" Is mutually exclusive with +.\" .BR RFENVG . +.TP +.B RFNOTEG +Each process is a member of a group of processes that all +receive notes when a note is sent to the group +(see +.IR postnote (3) +and +.IR signal (2)). +The group of a new process is by default the same as its parent, but if +.B RFNOTEG +is set (regardless of +.BR RFPROC ), +the process becomes the first in a new group, isolated from +previous processes. +In Plan 9, a process can call +.B rfork(RFNOTEG) +and then be sure that it will no longer receive console interrupts +or other notes. +Unix job-control shells put each command in its own process group +and then relay notes to the current foreground command, making +the idiom less useful. +.TP +.B RFFDG +If set, the invoker's file descriptor table (see +.IR intro ( )) +is copied; otherwise the two processes share a +single table. +.\" .TP +.\" .B RFCFDG +.\" If set, the new process starts with a clean file descriptor table. +.\" Is mutually exclusive with +.\" .BR RFFDG . +.\" .TP +.\" .B RFREND +.\" If set, the process will be unable to +.\" .IR rendezvous (3) +.\" with any of its ancestors; its children will, however, be able to +.\" .B rendezvous +.\" with it. In effect, +.\" .B RFREND +.\" makes the process the first in a group of processes that share a space for +.\" .B rendezvous +.\" tags. +.\" .TP +.\" .B RFMEM +.\" If set, the child and the parent will share +.\" .B data +.\" and +.\" .B bss +.\" segments. +.\" Otherwise, the child inherits a copy of those segments. +.\" Other segment types, in particular stack segments, will be unaffected. +.\" May be set only with +.\" .BR RFPROC . +.PD +.PP +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.PP +If +.B RFPROC +is set, the +value returned in the parent process +is the process id +of the child process; the value returned in the child is zero. +Without +.BR RFPROC , +the return value is zero. +Process ids range from 1 to the maximum integer +.RB ( int ) +value. +.I Rfork +will sleep, if necessary, until required process resources are available. +.PP +Calling +.B rfork(RFFDG|RFPROC) +is equivalent to calling +.IR fork (2). +.SH SOURCE +.B /usr/local/plan9/src/lib9/rfork.c +.SH DIAGNOSTICS +.I Rfork +sets +.IR errstr . diff --git a/man/man3/rsa.3 b/man/man3/rsa.3 index 56ad4c7e..c0b0fe9f 100644 --- a/man/man3/rsa.3 +++ b/man/man3/rsa.3 @@ -3,8 +3,10 @@ asn1dump, asn1toRSApriv, decodepem, +decodepemchain, rsadecrypt, rsaencrypt, +rsafill,, rsagen, rsaprivalloc, rsaprivfree, @@ -12,7 +14,9 @@ rsaprivtopub, rsapuballoc, rsapubfree, X509toRSApub, +X509dump, X509gen, +X509req, X509verify \- RSA encryption algorithm .SH SYNOPSIS .B #include @@ -24,9 +28,13 @@ X509verify \- RSA encryption algorithm .B #include .PP .B +.ta +\w'\fLPEMChain* 'u RSApriv* rsagen(int nlen, int elen, int nrep) .PP .B +RSApriv* rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint *q) +.PP +.B mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) .PP .B @@ -60,6 +68,12 @@ void asn1dump(uchar *der, int len) uchar* decodepem(char *s, char *type, int *len) .PP .B +PEMChain* decodepemchain(char *s, char *type) +.PP +.B +void X509dump(uchar *cert, int ncert) +.PP +.B uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen); .PP .B @@ -113,6 +127,22 @@ public and private keys. returns a newly allocated copy of the public key corresponding to the private key. .PP +.I Rsafill +takes as input the bare minimum pieces of an RSA private key +and computes the rest +.RB ( kp , +.BR kq , +and +.BR c2 ). +It returns a new private key. +All the +.BR mpint s +in the key, +even the ones that correspond directly to +.IR rsafill 's +input parameters, +are freshly allocated, +.PP The routines .IR rsaalloc , .IR rsafree , @@ -148,6 +178,9 @@ checks the signature on .IR cert . It returns nil if successful, else an error string. .PP +.I X509dump +prints an X.509 certificate to standard ouptut. +.PP .I X509gen creates a self-signed X.509 certificate, given an RSA keypair .IR priv , @@ -162,7 +195,12 @@ The subject line is conventionally of the form "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric" .EE using the quoting conventions of -.IR tokenize (3). +.I tokenize +(see +.IR getfields (3)). +.PP +.I X509req +creates an X.509 certification request. .PP .I Asn1toRSApriv converts an ASN1 formatted RSA private key into the corresponding @@ -186,6 +224,20 @@ If not, it returns and .BI * len is undefined. +.PP +.I Decodepemchain +is similar but expects a sequence of PEM-formatted sections +and returns a linked list of the decodings: +.IP +.EX +typedef struct PEMChain PEMChain +struct PEMChain +{ + PEMChain *next; + uchar *pem; + int pemlen; +}; +.EE .SH SOURCE .B /usr/local/plan9/src/libsec .SH SEE ALSO @@ -198,5 +250,5 @@ is undefined. .IR rc4 (3), .IR sechash (3), .IR prime (3), -.IR rand (3), -.IR x509 (8) +.IR rand (3) +.\" .IR pem (8) diff --git a/man/man3/rune.3 b/man/man3/rune.3 index 46895307..bc3dbe87 100644 --- a/man/man3/rune.3 +++ b/man/man3/rune.3 @@ -182,9 +182,9 @@ is the null string, returns .IR s1 . .SH SOURCE -.B /usr/local/plan9/src/libc/port/rune.c +.B /usr/local/plan9/src/lib9/utf/rune.c .br -.B /usr/local/plan9/src/libc/port/utfrune.c +.B /usr/local/plan9/src/lib9/utf/utfrune.c .SH SEE ALSO -.IR utf (6), +.IR utf (7), .IR tcs (1) diff --git a/man/man3/runestrcat.3 b/man/man3/runestrcat.3 index f5210c2a..dadcbcd2 100644 --- a/man/man3/runestrcat.3 +++ b/man/man3/runestrcat.3 @@ -58,7 +58,7 @@ These functions are rune string analogues of the corresponding functions in .IR strcat (3). .SH SOURCE -.B /usr/local/plan9/src/libc/port +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3), diff --git a/man/man3/scsi.3 b/man/man3/scsi.3 new file mode 100644 index 00000000..5b6f24ce --- /dev/null +++ b/man/man3/scsi.3 @@ -0,0 +1,188 @@ +.TH SCSI 3 +.SH NAME +openscsi, scsiready, scsi, scsicmd, scsierror \- SCSI device operations +.SH SYNOPSIS +.nf +.ft L +#include +#include +#include +.ft +.PP +.ft L +typedef struct Scsi { + char *inquire; + int rawfd; + int nchange; + ulong changetime; +}; +.ft +.PP +.B +Scsi* openscsi(char *devdir) +.PP +.B +void closescsi(Scsi *s) +.PP +.B +int scsiready(Scsi *s) +.PP +.B +int scsi(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +int scsicmd(Scsi *s, uchar *cmd, int ncmd, +.br + void *data, int ndata, int dir) +.PP +.B +char* scsierror(int asc, int ascq) +.PP +.B +int scsiverbose; +.SH DESCRIPTION +These routines provide an interface +to a SCSI or ATAPI device via Plan 9's +\fIsd\fR(3). +.PP +.I Openscsi +attempts to open the file +.IB devdir /raw +and use it to send raw SCSI commands. +On success, it reads the device's inquiry +string and stores it in in returned +.B Scsi +structure. +.I Closescsi +closes the connection and frees the +.B Scsi +structure. +.PP +.I Scsiready +sends the ``unit ready'' command up to three times, +returning zero if the unit responds that it is ready, +or \-1 on error. +.PP +.I Scsierror +returns a textual description of the SCSI status +denoted by the ASC and ASCQ sense codes. +The description is found by consulting +.BR /sys/lib/scsicodes . +The returned string will be overwritten by +the next call to +.IR scsierror . +.PP +.I Scsi +and +.I scsicmd +execute a single SCSI command on the named device. +There should be +.I ncmd +bytes of +command data in +.IR cmd ; +if +.I dir +is +.BR Sread , +a successful operation +will store up to +.I ndata +bytes into +.IR data , +returning the number of bytes stored. +If +.I dir +is +.BR Swrite , +the +.I ndata +bytes beginning at +.I data +are transmitted as the data argument to +the command, and the +number of bytes written is returned. +If +.I dir +is +.BR Snone , +.I data +and +.I ndata +are ignored. +On error, +.I scsi +and +.I scsicmd +return \-1. +.I Scsicmd +simply issues the command and +returns the result; +.I scsi +works a bit harder and +is the more commonly used routine. +.I Scsi +attempts to send the command; +if it is successful, +.I scsi +returns what +.I scsicmd +returned. +Otherwise, +.I scsi +sends a request sense command to +obtain the reason for the failure, +sends a unit ready command in +an attempt to bring the unit out of any +inconsistent states, and tries again. +If the second try fails, +.I scsi +sends the request +sense and unit ready commands +again +and then uses +.I scsierror +to set +.I errstr +with a reason for failure. +.PP +The +.B nchange +and +.B changetime +fields +in the +.B Scsi +structure +record the number of times a media +change has been detected, and the +time when the current media was +inserted into the drive (really the +first time a SCSI command was issued +after it was inserted). +They are maintained by +.IR scsi . +.PP +If +.I scsiverbose +is set, +these commands will produce a fair +amount of debugging output on file descriptor 2 +when SCSI commands fail. +.SH FILES +.TP +.B /sys/lib/scsicodes +List of textual messages corresponding to SCSI error codes; +consulted by +.BR scsierror . +.SH SOURCE +.B /usr/local/plan9/src/libdisk/scsi.c +.SH SEE ALSO +Plan 9's +\fIsd\fR(3) and +\fIscuzz\fR(8) +.SH BUGS +SCSI devices on Unix do not present the interface expected by +these routines. diff --git a/man/man3/seek.3 b/man/man3/seek.3 index 33966385..2ce4cff0 100644 --- a/man/man3/seek.3 +++ b/man/man3/seek.3 @@ -37,7 +37,7 @@ The new file offset value is returned. Seeking in a directory is not allowed. Seeking in a pipe is a no-op. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/seek.c .SH SEE ALSO .IR intro (3), .IR open (3) diff --git a/man/man3/sendfd.3 b/man/man3/sendfd.3 new file mode 100644 index 00000000..8090dfce --- /dev/null +++ b/man/man3/sendfd.3 @@ -0,0 +1,57 @@ +.TH SENDFD 3 +.SH NAME +sendfd, recvfd \- pass file descriptors along Unix domain sockets +.SH SYNOPSIS +.B +#include +.PP +.B +#include +.PP +.B +int sendfd(int socket, int fd) +.PP +.B +int recvfd(int socket) +.SH DESCRIPTION +.I Recvfd +and +.I sendfd +can be used to pass an open file descriptor over +a Unix domain socket from one process to another. +Since +.IR pipe (3) +is implemented with +.IR socketpair (2) +instead of +.IR pipe (2), +.I socket +can be a file descriptor obtained from +.IR pipe (3). +.PP +.I Sendfd +sends the file descriptor +.I fd +along the socket to a process calling +.I recvfd +on the other end. +.PP +It is assumed that the two sides have coordinated +and agreed to transfer a file descriptor already, so +that the +.I sendfd +is met with a +.I recvfd +instead of an ordinary +.IR read . +.PP +The file descriptor number may change on its way +between processes, but the kernel structure it represents +will not. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sendfd.c +.SH SEE ALSO +.IR socketpair (2), +.I sendmsg +in +.IR send (2) diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 index b451c296..0ed7845f 100644 --- a/man/man3/setjmp.3 +++ b/man/man3/setjmp.3 @@ -86,9 +86,7 @@ setlabel(void) } .EE .SH SOURCE -.B /usr/local/plan9/src/libc/$objtype/setjmp.s -.br -.B /usr/local/plan9/src/libc/$objtype/notejmp.c +.B /usr/local/plan9/src/lib9/jmp.c .SH SEE ALSO .IR notify (3) .SH BUGS diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 index 1872ab51..da2e6956 100644 --- a/man/man3/sleep.3 +++ b/man/man3/sleep.3 @@ -37,7 +37,7 @@ A zero argument clears the alarm. The return value is the amount of time previously remaining in the alarm clock. .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/sleep.c .SH SEE ALSO .IR intro (3) .SH DIAGNOSTICS diff --git a/man/man3/stat.3 b/man/man3/stat.3 index a815550e..03f3abea 100644 --- a/man/man3/stat.3 +++ b/man/man3/stat.3 @@ -46,7 +46,7 @@ and are the system calls; they deal with machine-independent .IR "directory entries" . Their format is defined by -.IR stat (5). +.IR stat (9p). .I Stat and .I fstat @@ -67,7 +67,7 @@ write information back, thus changing file attributes according to the contents .IR edir . The data returned from the kernel includes its leading 16-bit length field as described in -.IR intro (5). +.IR intro (9p). For symmetry, this field must also be present when passing data to the kernel in a call to .I wstat and @@ -242,19 +242,15 @@ can be changed: by the owner if also a member of the new group; or by the group leader of the file's current group if also leader of the new group (see -.IR intro (5) -for more information about permissions and -.IR users (6) -for users and groups). +.IR intro (9p) +for more information about permissions, users, and groups). The .B length can be changed by anyone with write permission, provided the operation is implemented by the server. (See -.IR intro (5) -for permission information, and -.IR users (6) -for user and group information). +.IR intro (9p) +for permission, user, and group information). .PP Special values in the fields of the .B Dir @@ -281,21 +277,12 @@ it is not necessary to use .I stat to retrieve the initial values first. .SH SOURCE -.TF /usr/local/plan9/src/libc/9syscall -.TP -.B /usr/local/plan9/src/libc/9syscall -for the -.RB non- dir -routines -.TP -.B /usr/local/plan9/src/libc/9sys -for the routines prefixed -.B dir +.B /usr/local/plan9/src/lib9/dirstat.c .SH SEE ALSO .IR intro (3), .IR fcall (3), .IR dirread (3), -.IR stat (5) +.IR stat (9p) .SH DIAGNOSTICS The .I dir diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 index 6e16158d..8fcf2ca6 100644 --- a/man/man3/strcat.3 +++ b/man/man3/strcat.3 @@ -242,11 +242,7 @@ returns .I Cistrstr operates analogously, but ignores ASCII case differences when comparing strings. .SH SOURCE -All these routines have portable C implementations in -.BR /usr/local/plan9/src/libc/port . -Many also have machine-dependent assembly language -implementations in -.BR /usr/local/plan9/src/libc/$objtype . +.B /usr/local/plan9/src/lib9 .SH SEE ALSO .IR memory (3), .IR rune (3), diff --git a/man/man3/string.3 b/man/man3/string.3 index 0782b260..0b39d5c8 100644 --- a/man/man3/string.3 +++ b/man/man3/string.3 @@ -1,6 +1,6 @@ .TH STRING 3 .SH NAME -s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline \- extensible strings +s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline, s_allocinstack, s_freeinstack, s_rdinstack \- extensible strings .SH SYNOPSIS .B #include .br @@ -8,6 +8,7 @@ s_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_na .br .B #include .PP +.ta +\w'\fLSinstack* 'u .B String* s_new(void) .br @@ -61,6 +62,15 @@ String* s_incref(String *s) String* s_unique(String *s) .PP .B +Sinstack* s_allocinstack(char *file) +.br +.B +void s_freeinstack(Sinstack *stack) +.br +.B +char* s_rdinstack(Sinstack *stack, String *s) +.PP +.B #include .PP .B @@ -222,14 +232,39 @@ An eof or error terminates the read. The string is null terminated. .PP .I S_getline -reads up to the next newline and returns +reads up to the next newline, appends the input to +.IR s , +and returns a pointer to the beginning of the bytes read. Leading spaces and tabs and the trailing newline are all discarded. .I S_getline -will recursively read through files included with +discards blank lines and lines beginning with +.LR # . +.I S_getline +ignores +newlines escaped by immediately-preceding backslashes. +.PP +.I S_allocinstack +allocates an input stack with the single file +.I file +open for reading. +.I S_freeinstack +frees an input stack. +.I S_rdinstack +reads a line from an input stack. +It follows the same rules as +.I s_getline +except that when it encounters a line of the form .B #include -and discard all other lines beginning with -.BR # . +.IR newfile , +.I s_getline +pushes +.I newfile +onto the input stack, postponing further reading of the current +file until +.I newfile +has been read. +The input stack has a maximum depth of 32 nested include files. .SH SOURCE .B /usr/local/plan9/src/libString .SH SEE ALSO diff --git a/man/man3/stringsize.3 b/man/man3/stringsize.3 index ac57f4a8..448df993 100644 --- a/man/man3/stringsize.3 +++ b/man/man3/stringsize.3 @@ -62,8 +62,8 @@ are analogous, but accept an array of runes rather than .IR subfont (3), .IR draw (3), .IR draw (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS Because strings are loaded dynamically, these routines may generate I/O to the server and produce calls to the graphics error function. diff --git a/man/man3/subfont.3 b/man/man3/subfont.3 index 980b93b2..4933c0d6 100644 --- a/man/man3/subfont.3 +++ b/man/man3/subfont.3 @@ -150,7 +150,7 @@ Although it is principally a routine internal to the library, may be substituted by the application to provide a less file-oriented subfont naming scheme. .PP The format of a subfont file is described in -.IR font (6). +.IR font (7). Briefly, it contains a image with all the characters in it, followed by a subfont header, followed by character information. .I Readsubfont @@ -228,8 +228,8 @@ bitmap font file tree .IR allocimage (3), .IR draw (3), .IR cachechars (3), -.IR image (6), -.IR font (6) +.IR image (7), +.IR font (7) .SH DIAGNOSTICS All of the functions use the graphics error function (see .IR graphics (3)). diff --git a/man/man3/sysfatal.3 b/man/man3/sysfatal.3 new file mode 100644 index 00000000..ea1a3df8 --- /dev/null +++ b/man/man3/sysfatal.3 @@ -0,0 +1,39 @@ +.TH SYSFATAL 3 +.SH NAME +sysfatal \- system error messages +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +void sysfatal(char *fmt, ...) +.SH DESCRIPTION +.I Sysfatal +prints to standard error the name of the running program, +a colon and a space, +the message described by the +.IR print (3) +format string +.I fmt +and subsequent arguments, and a newline. +It then calls +.IR exits (3) +with the formatted message as argument. +The program's name is the value of +.BR argv0 , +which will be set if the program uses the +.IR arg (3) +interface to process its arguments. +If +.B argv0 +is null, it is ignored and the following colon and space are suppressed. +.SH SOURCE +.B /usr/local/plan9/src/lib9/sysfatal.c +.SH "SEE ALSO" +.IR intro (3), +.IR errstr (3), +the +.B %r +format in +.IR print (3) diff --git a/man/man3/thread.3 b/man/man3/thread.3 index 84ca69f8..05c19022 100644 --- a/man/man3/thread.3 +++ b/man/man3/thread.3 @@ -5,12 +5,10 @@ chancreate, chanfree, chaninit, chanprint, +chansetname, mainstacksize, proccreate, procdata, -procexec, -procexecl, -procrfork, recv, recvp, recvul, @@ -25,6 +23,8 @@ nbsendp, nbsendul, threadcreate, threaddata, +threadexec, +threadexecl, threadexits, threadexitsall, threadgetgrp, @@ -33,12 +33,15 @@ threadint, threadintgrp, threadkill, threadkillgrp, +threadlinklibrary, threadmain, threadnotify, threadid, threadpid, threadsetgrp, threadsetname, +threadsetstate, +threadspawn, threadwaitchan, yield \- thread and proc management .SH SYNOPSIS @@ -71,6 +74,7 @@ struct Alt { int op; Channel **tag; int entryno; + char *name; }; .fi .de XX @@ -126,8 +130,9 @@ int nbsendp(Channel *c, void *v) int nbsendul(Channel *c, ulong v) int chanprint(Channel *c, char *fmt, ...) .XX -int procexecl(Channel *cpid, char *file, ...) -int procexec(Channel *cpid, char *file, char *args[]) +int threadspawn(int fd[3], char *file, char *args[]) +int threadexecl(Channel *cpid, int fd[3], char *file, ...) +int threadexec(Channel *cpid, int fd[3], char *file, char *args[]) Channel* threadwaitchan(void) .XX int threadnotify(int (*f)(void*, char*), int in) @@ -179,31 +184,31 @@ on a stack of size .IR stacksize . Thread stacks are allocated in shared memory, making it valid to pass pointers to stack variables between threads and procs. -.I Procrfork +.I Proccreate creates a new proc, and inside that proc creates a single thread as .I threadcreate would, returning the id of the created thread. -.I Procrfork -creates the new proc by calling -.B rfork -(see -.IR fork (3)) -with flags -.BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. -(The thread library depends on all its procs -running in the same rendezvous group. -Do not include -.B RFREND -in -.IR rforkflag .) -.I Proccreate -is identical to -.I procrfork -with -.I rforkflag -set to zero. +.\" .I Procrfork +.\" creates the new proc by calling +.\" .B rfork +.\" (see +.\" .IR fork (3)) +.\" with flags +.\" .BR RFPROC|RFMEM|RFNOWAIT| \fIrforkflag\fR. +.\" (The thread library depends on all its procs +.\" running in the same rendezvous group. +.\" Do not include +.\" .B RFREND +.\" in +.\" .IR rforkflag .) +.\" .I Proccreate +.\" is identical to +.\" .I procrfork +.\" with +.\" .I rforkflag +.\" set to zero. Be aware that the calling thread may continue execution before the newly created proc and thread @@ -226,6 +231,11 @@ using .I status as the exit status. .PP +When the last thread in +.IR threadmain 's +proc exits, the program will appear to its parent to have exited. +The remaining procs will still run together, but as a background program. +.PP The threads in a proc are coroutines, scheduled nonpreemptively in a round-robin fashion. A thread must explicitly relinquish control of the processor @@ -233,9 +243,10 @@ before another thread in the same proc is run. Calls that do this are .IR yield , .IR proccreate , -.IR procexec , -.IR procexecl , +.IR threadexec , +.IR threadexecl , .IR threadexits , +.IR threadspawn , .IR alt , .IR send , and @@ -307,6 +318,17 @@ The pointer returned by is only valid until the next call to .IR threadsetname . .PP +Also for debugging, +threads have a string state associated with them. +.I Threadsetstate +sets the state string. +There is no +.IR threadgetstate ; +since the thread scheduler resets the state to +.B Running +every time it runs the thread, +it is only useful for debuggers to inspect the state. +.PP .I Threaddata returns a pointer to a per-thread pointer that may be modified by threaded programs for @@ -315,9 +337,9 @@ Similarly, .I procdata returns a pointer to a per-proc pointer. .PP -.I Procexecl +.I Threadexecl and -.I procexec +.I threadexec are threaded analogues of .I exec and @@ -325,30 +347,67 @@ and (see .IR exec (3)); on success, -they replace the calling thread (which must be the only thread in its proc) +they replace the calling thread and invoke the external program, never returning. +(Unlike on Plan 9, the calling thread need not be the only thread in its proc\(emthe other +threads will continue executing.) On error, they return \-1. If .I cpid is not null, the pid of the invoked program will be sent along .I cpid +(using +.IR sendul ) once the program has been started, or \-1 will be sent if an error occurs. -.I Procexec +.I Threadexec and -.I procexecl +.I threadexecl will not access their arguments after sending a result along .IR cpid . Thus, programs that malloc the .I argv passed to -.I procexec +.I threadexec can safely free it once they have received the .I cpid response. +.PP +.I Threadexecl +and +.I threadexec +will duplicate +(see +.IR dup (3)) +the three file descriptors in +.I fd +onto standard input, output, and error for the external program +and then close them in the calling thread. +Beware of code that sets +.IP +.EX +fd[0] = 0; +fd[1] = 1; +fd[2] = 2; +.EE +to use the current standard files. The correct code is +.IP +.EX +fd[0] = dup(0, -1); +fd[1] = dup(1, -1); +fd[2] = dup(2, -1); +.EE +.PP +.I Threadspawn +is like +.I threadexec +but does not replace the current thread. +It returns the pid of the invoked program on success, or +\-1 on error. +.PP .I Threadwaitchan returns a channel of pointers to .B Waitmsg @@ -398,6 +457,14 @@ blocked on it until that thread unblocks (but .I chanfree returns immediately). .PP +The +.B name +element in the +.B Channel +structure is a description intended for use in debugging. +.I Chansetname +sets the name. +.PP .I Send sends the element pointed at by .I v @@ -536,49 +603,97 @@ in place of .IR notify (3)). .PP It is safe to use -.B sysfatal -(see -.IR perror (3)) +.IR sysfatal (3) in threaded programs. .I Sysfatal will print the error string and call .IR threadexitsall . .PP -It is safe to use +It is not safe to call .IR rfork -(see -.IR fork (3)) -to manage the namespace, file descriptors, note group, and environment of a -single process. -That is, it is safe to call -.I rfork -with the flags -.BR RFNAMEG , -.BR RFFDG , -.BR RFCFDG , -.BR RFNOTEG , -.BR RFENVG , -and -.BR RFCENVG. -(To create new processes, use -.I proccreate -and -.IR procrfork .) -As mentioned above, -the thread library depends on all procs being in the -same rendezvous group; do not change the rendezvous -group with -.IR rfork . +in a threaded program, except to call +.B rfork(RFNOTEG) +from the main proc before any other procs have been created. +To create new processes, use +.IR proccreate . +.\" .PP +.\" It is safe to use +.\" .IR rfork +.\" (see +.\" .IR fork (3)) +.\" to manage the namespace, file descriptors, note group, and environment of a +.\" single process. +.\" That is, it is safe to call +.\" .I rfork +.\" with the flags +.\" .BR RFNAMEG , +.\" .BR RFFDG , +.\" .BR RFCFDG , +.\" .BR RFNOTEG , +.\" .BR RFENVG , +.\" and +.\" .BR RFCENVG. +.\" (To create new processes, use +.\" .I proccreate +.\" and +.\" .IR procrfork .) +.\" As mentioned above, +.\" the thread library depends on all procs being in the +.\" same rendezvous group; do not change the rendezvous +.\" group with +.\" .IR rfork . .SH FILES .B /usr/local/plan9/acid/thread contains useful .IR acid (1) functions for debugging threaded programs. .PP -.B /usr/local/plan9/src/libthread/example.c -contains a full example program. +.B /usr/local/plan9/src/libthread/test +contains some example programs. .SH SOURCE .B /usr/local/plan9/src/libthread .SH SEE ALSO .IR intro (3), .IR ioproc (3) +.SH BUGS +A program that intends to use the thread library +but does not call any of its functions will not cause Unix linkers +to link the thread library, resulting in the unintelligible error: +.IP +.EX +/usr/local/plan9/lib/lib9.a(main.o)(.text+0x17): In function `main': +/usr/local/plan9/src/lib9/main.c:10: undefined reference to `p9main' +.EE +.LP +or similar. To force the thread library to be linked properly in such cases, +insert a call to the no-op function +.I threadlinklibrary +somewhere in your program. +.PP +To avoid name conflicts, +.IR alt , +.IR nbrecv , +.IR nbrecvp , +.IR nbrecvul , +.IR nbsend , +.IR nbsendp , +.IR nbsendul , +.IR recv , +.IR recvp , +.IR recvul , +.IR send , +.IR sendp , +and +.IR sendul +are defined as macros that expand to +.IR chanalt , +.IR channbrecv , +and so on. +Similarly, +.I yield +is defined as a macro that expands to +.IR threadyield . +.PP +The implementation of +.I threadnotify +may not be correct. diff --git a/man/man3/time.3 b/man/man3/time.3 index 90ec7311..6f3cbcd2 100644 --- a/man/man3/time.3 +++ b/man/man3/time.3 @@ -26,20 +26,8 @@ if is not zero then .BI * tp is also set to the answer. -.PP -These functions work by reading -.BR /dev/bintime , -opening that file when -.I they -are first called. .SH SOURCE -.B /usr/local/plan9/src/libc/9sys/time.c -.br -.B /usr/local/plan9/src/libc/9sys/nsec.c -.SH SEE ALSO -.IR cons (3) +.B /usr/local/plan9/src/lib9/time.c .SH DIAGNOSTICS -Sets +These functions set .IR errstr . -.SH BUGS -These routines maintain a static file descriptor. diff --git a/man/man3/udpread.3 b/man/man3/udpread.3 new file mode 100644 index 00000000..3a0a7ea6 --- /dev/null +++ b/man/man3/udpread.3 @@ -0,0 +1,68 @@ +.TH UDPREAD 3 +.SH NAME +udpread, udpwrite \- read and write UDP packets +.SH SYNOPSIS +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B +.nf +.ta +4n +8n +typedef struct Udphdr Udphdr; +struct Udphdr +{ + uchar raddr[IPaddrlen]; /* remote address and port */ + uchar laddr[IPaddrlen]; /* local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.PP +.B +long udpread(int fd, Udphdr *hdr, void *data, long n) +.PP +.B +long udpwrite(int fd, Udphdr *hdr, void *data, long n) +.SH DESCRIPTION +.I Udpread +and +.I udpwrite +read and write UDP packets from the UDP network connection +established on file descriptor +.IR fd . +.PP +.I Udpread +reads at most +.I n +bytes of packet body into +.I data , +stores the header in +.IR hdr , +and returns the number of bytes stored in +.IR data . +.PP +.I Udpwrite +writes the +.I n +bytes stored in +.I data +in a UDP packet with header +.IR hdr . +.PP +Note that the +.B Udphdr +frames the addresses as local and remote +instead of source and destination. +Thus the +.I hdr +filled in for a packet read by +.I udpread +can be used unchanged in +.I udpwrite +to send a response back to the sender of the original packet. +.SH SOURCE +.B /usr/local/plan9/src/lib9/udp.c +.SH SEE ALSO +.IR ip (3) diff --git a/man/man3/wait.3 b/man/man3/wait.3 index b8b5c7fd..03b55bf2 100644 --- a/man/man3/wait.3 +++ b/man/man3/wait.3 @@ -1,6 +1,6 @@ .TH WAIT 3 .SH NAME -await, wait, waitpid \- wait for a process to exit +await, awaitnohang, awaitfor, wait, waitnohang, waitfor, waitpid \- wait for a process to exit .SH SYNOPSIS .B #include .br @@ -10,14 +10,28 @@ await, wait, waitpid \- wait for a process to exit Waitmsg* wait(void) .PP .B +Waitmsg* waitnohang(void) +.PP +.B +Waitmsg* waitfor(int pid) +.PP +.B int waitpid(void) .PP .B int await(char *s, int n) +.PP +.B +int awaitnohang(char *s, int n) +.PP +.B +int awaitfor(int pid, char *s, int n) .SH DESCRIPTION .I Wait causes a process to wait for any child process (see -.IR fork (3)) +.IR fork (2) +and +.IR rfork (3)) to exit. It returns a .B Waitmsg @@ -70,16 +84,33 @@ For programs that only need the pid of the exiting program, .I waitpid returns just the pid and discards the rest of the information. .PP -The underlying system call is +.I Waitnohang +is like +.I wait +but does not block if there are no more children to wait for. +Instead it returns immediately and sets +.IR errstr . +.PP +.I Waitfor +is like +.I wait +but waits for a particular +.IR pid . +.PP +The underlying calls are .IR await , -which fills in the n-byte buffer +.IR awaitnohang , +and +.IR awaitfor , +which fill in the +.IR n -byte +buffer .I s with a textual representation of the pid, times, and exit string. There is no terminal NUL. The return value is the length, in bytes, of the data. .PP -The buffer filled in by -.I await +The filled-in buffer may be parsed (after appending a NUL) using .IR tokenize (see @@ -104,14 +135,12 @@ If the calling process has no living children, returns .BR -1 . .SH SOURCE -.B /usr/local/plan9/src/libc/9syscall +.B /usr/local/plan9/src/lib9/wait.c +.PP +.B /usr/local/plan9/src/lib9/await.c .SH "SEE ALSO" -.IR fork (3), +.IR rfork (3), .IR exits (3), -the -.B wait -file in -.IR proc (3) .SH DIAGNOSTICS These routines set .IR errstr . diff --git a/man/man3/wctl.3 b/man/man3/wctl.3 new file mode 100644 index 00000000..dfed6fcb --- /dev/null +++ b/man/man3/wctl.3 @@ -0,0 +1,39 @@ +.TH WCTL 3 +.SH NAME +drawresizewindow, drawsetlabel, drawtopwindow \- window management +.SH SYNOPSIS +.B #include +.PP +.B +void drawresizewindow(Rectangle r) +.PP +.B +int drawsetlabel(Display *d, char *name) +.PP +.B +void drawtopwindow(void) +.SH DESCRIPTION +These routines interact with a window manager +to set the properties of the window running the current program. +They substitute for interacting directly with the Plan 9 +.IR rio 's +.BR /dev/wctl . +.PP +.I Drawresizewindow +requests that the program's window be resized to have the +width and height of the rectangle +.IR r . +Only the width and height +are important; the offset is ignored. +.PP +.I Drawsetlabel +requests that the program's window title be set to +.IR name . +.PP +.I Drawtopwindow +requests that the program's window be moved +above all other windows and given the input focus. +.SH SOURCE +.B /usr/local/plan9/src/libdraw/x11-init.c +.br +.B /usr/local/plan9/src/libdraw/x11-wsys.c diff --git a/man/man3/window.3 b/man/man3/window.3 new file mode 100644 index 00000000..6f140603 --- /dev/null +++ b/man/man3/window.3 @@ -0,0 +1,244 @@ +.TH WINDOW 3 +.SH NAME +Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow \- window management +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.PP +.ft L +.nf +typedef +struct Screen +{ + Display *display; /* display holding data */ + int id; /* id of system-held Screen */ + Image *image; /* unused; for reference only */ + Image *fill; /* color to paint behind windows */ +} Screen; +.fi +.ta \w'\fLScreen* 'u +.PP +.B +Screen* allocscreen(Image *image, Image *fill, int public) +.PP +.B +Screen* publicscreen(Display *d, int id, ulong chan) +.PP +.B +int freescreen(Screen *s) +.PP +.B +Image* allocwindow(Screen *s, Rectangle r, int ref, int val) +.PP +.B +void bottomwindow(Image *w) +.PP +.B +void bottomnwindows(Image **wp, int nw) +.PP +.B +void topwindow(Image *w) +.PP +.B +void topnwindows(Image **wp, int nw) +.PP +.B +int originwindow(Image *w, Point log, Point scr) +.PP +.ft L +.nf +enum +{ + /* refresh methods */ + Refbackup = 0, + Refnone = 1, + Refmesg = 2 +}; +.fi +.ft P +.SH DESCRIPTION +Windows are represented as +.B Images +and may be treated as regular images for all drawing operations. +The routines discussed here permit the creation, deletion, and shuffling +of windows, facilities that do not apply to regular images. +.PP +To create windows, it is first necessary to allocate a +.B Screen +data structure to gather them together. +A +.B Screen +turns an arbitrary image into something that may have windows upon it. +It is created by +.BR allocscreen , +which takes an +.I image +upon which to place the windows (typically +.BR display->image ), +a +.I fill +image to paint the background behind all the windows on the image, +and a flag specifying whether the result should be publicly visible. +If it is public, an arbitrary other program connected to the same +display may acquire a pointer to the same screen by calling +.B publicscreen +with the +.B Display +pointer and the +.I id +of the published +.BR Screen , +as well as the expected channel descriptor, as a safety check. +It will usually require some out-of-band coordination for programs to share a screen profitably. +.B Freescreen +releases a +.BR Screen , +although it may not actually disappear from view until all the windows upon it have also been deallocated. +.PP +Unlike +.BR allocwindow , +.B allocscreen +does +.I not +initialize the appearance of the +.BR Screen . +.PP +Windows are created by +.BR allocwindow , +which takes a pointer to the +.B Screen +upon which to create the window, a rectangle +.I r +defining its geometry, an integer pixel value +.I val +to color the window initially, and a refresh method +.BR ref . +The refresh methods are +.BR Refbackup , +which provides backing store and is the method used by +.IR rio (1) +for its clients; +.BR Refnone , +which provides no refresh and is designed for temporary uses +such as sweeping a display rectangle, for windows that are +completely covered by other windows, and for windows that +are already protected by backing store; and +.BR Refmesg , +which causes messages to be delivered to the owner of the window +when it needs to be repainted. +.B Refmesg +is not fully implemented. +.PP +The result of +.B allocwindow +is an +.B Image +pointer that may be treated like any other image. +In particular, it is freed by calling +.B freeimage +(see +.IR allocimage (3)). +The following functions, however, apply only to windows, not regular images. +.PP +.B Bottomwindow +pushes window +.I w +to the bottom of the stack of windows on its +.BR Screen , +perhaps obscuring it. +.B Topwindow +pulls window +.I w +to the top, making it fully visible on its +.BR Screen . +(This +.B Screen +may itself be within a window that is not fully visible; +.B topwindow +will not affect the stacking of this parent window.) +.B Bottomnwindows +and +.B Topnwindows +are analogous, but push or pull a group of +.I nw +windows listed in the array +.IR wp . +The order within +.IR wp +is unaffected. +.PP +Each window is created as an +.B Image +whose +.B Rectangle +.B r +corresponds to the rectangle given to +.B allocwindow +when it was created. Thus, a newly created window +.I w +resides on its +.B Screen->image +at +.IB w ->r +and has internal coordinates +.IB w ->r . +Both these may be changed by a call to +.BR originwindow . +The two +.B Point +arguments to +.B originwindow +define the upper left corner of the logical coordinate system +.RI ( log ) +and screen position +.RI ( scr ). +Their usage is shown in the Examples section. +.PP +.IR Rio (1) +creates its client windows with backing store, +.BR Refbackup . +The graphics initialization routine, +.B initdraw +(see +.IR graphics (3)), +builds a +.B Screen +upon this, and then allocates upon that another window indented +to protect the border. That window is created +.BR Refnone , +since the backing store created by +.B rio +protects its contents. That window is the one known in the +library by the global name +.B screen +(a historic but confusing choice). +.SH EXAMPLES +To move a window to the upper left corner of the display, +.EX + originwindow(w, w->r.min, Pt(0, 0)); +.EE +To leave a window where it is on the screen but change its internal +coordinate system so (0,\ 0) is the upper left corner of the window, +.EX + originwindow(w, Pt(0, 0), w->r.min); +.EE +After this is done, +.B w->r +is translated to the origin and there will be no way to discover the +actual screen position of the window unless it is recorded separately. +.SH SOURCE +.B /usr/local/plan9/src/libdraw +.SH SEE ALSO +.IR graphics (3), +.IR draw (3), +.IR cachechars (3), +.IR draw (3) +.SH BUGS +The refresh method +.B Refmesg +should be finished. diff --git a/man/man4/0intro.4 b/man/man4/0intro.4 new file mode 100644 index 00000000..1e4c81d2 --- /dev/null +++ b/man/man4/0intro.4 @@ -0,0 +1,82 @@ +.TH INTRO 4 +.SH NAME +intro \- introduction to file servers +.SH DESCRIPTION +A Plan 9 +.I "file server" +provides a file tree to processes. +This section of the manual describes servers that can be +mounted in a name space to give a file-like interface to interesting services. +A file server may be a provider of a conventional file system, +with files maintained on permanent storage, +or it may also be a process that synthesizes files in some manner. +.PP +In Plan 9, the kernel mount device +\fImnt\fR(3) +acts as a client to the 9P servers mounted in the current name space, +translating system calls such as +.IR open (2) +into 9P transactions such as +.IR open (9p). +The kernel also multiplexes the potentially many processes onto a single 9P conversation +with each server. +Finally, the kernel provides each process with its own private +.I name space +which it can customize at will. +Modern Unix systems do not provide these niceties, so +the Unix port of these Plan 9 file servers provides them via other means. +.PP +On Unix, 9P clients do not access servers via the traditional +file system call interface. Only the Unix name space can be accessed +that way. +Instead, 9P clients use the +.IR 9pclient (3) +library to connect and interact directly with particular 9P servers. +The +.IR 9p (1) +command-line client is useful for interactive use and in shell scripts. +.PP +To preserve the façade of a single 9P conversation with each server, +9P servers invoke +.IR 9pserve (4), +typically via +.IR post9pservice (3). +.I 9pserve +announces a 9P service at a particular +network address and multiplexes the clients that connect to +that address onto a single 9P conversation with the server. +.PP +Each ported program operates in a pseudo-name space +that determines which 9P servers it is using. +The name space of a ported program is represented by a +directory containing Unix domain sockets, one for each 9P server. +The directory defaults to +.BR /tmp/ns.$USER.$DISPLAY , +meaning that all programs in an X Windows login session +share a single name space. +Setting the +.B $NAMESPACE +environment variable overrides this default. +The +.IR namespace (1) +command prints the current name space directory. +.PP +Occasionally it is useful to be able to connect the input or output +of a standard Unix program to a file served by a 9P server. +The new +.IR openfd (9p) +9P transaction, which depends on file descriptor passing, +provides a sufficient workaround in many cases. +.IR 9pserve 's +implementation of +.I openfd +(see also +.I fsopenfd +in +.IR 9pclient (3)) +returns the read or write end of a pipe; +a helper process transfers data between the other end of the pipe +and the 9P server. +Note that since the data is being transferred via a pipe, +9P read and write errors cannot be passed on to the Unix program. +The Unix program sees only end-of-file or a closed pipe. diff --git a/man/man4/9pserve.4 b/man/man4/9pserve.4 new file mode 100644 index 00000000..81cfc262 --- /dev/null +++ b/man/man4/9pserve.4 @@ -0,0 +1,46 @@ +.TH 9PSERVE 4 +.SH NAME +9pserve \- announce and multiplex 9P service +.SH SYNOPSIS +.B 9pserve +[ +.B -v +] +.I addr +.SH DESCRIPTION +On Plan 9, when a user-level file server mounts itself into a name space +or posts itself in +.BR /srv , +the Plan 9 kernel multiplexes the potentially many processes +accessing the server into a single 9P conversation. +The user-level server need not concern itself with how many +processes are accessing it or with cleaning up after a process when it +exits unexpectedly. +On Unix, +.I 9pserve +takes the place of the Plan 9 kernel, multiplexing clients onto +a single server conversation and cleaning up after clients when +they hang up unexpectedly. +.PP +.I 9pserve +announces a 9P service on +.I addr +and multiplexes any 9P clients connecting to +.I addr +into a single conversation with a 9P server on +.IR 9pserve 's +standard input and output. +When a client hangs up, +.I 9pserve +flushes any outstanding 9P transactions +and clunks any outstanding fids belonging to the client. +.PP +.I 9pserve +is typically not invoked directly; use +.IR post9pservice (3) +instead. +.SH "SEE ALSO +.IR intro (4), +.IR intro (9p) +.SH SOURCE +.B /usr/local/plan9/src/cmd/9pserve.c diff --git a/man/man4/INDEX b/man/man4/INDEX new file mode 100644 index 00000000..bd0f7bc1 --- /dev/null +++ b/man/man4/INDEX @@ -0,0 +1,6 @@ +0intro 0intro.4 +intro 0intro.4 +9pserve 9pserve.4 +acme acme.4 +plumber plumber.4 +ramfs ramfs.4 diff --git a/man/man4/acme.4 b/man/man4/acme.4 new file mode 100644 index 00000000..f6a48538 --- /dev/null +++ b/man/man4/acme.4 @@ -0,0 +1,406 @@ +.TH ACME 4 +.SH NAME +acme \- control files for text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] [ +.B -F +.I fixfont +] +[ +.I file +\&... ] +.SH DESCRIPTION +The text window system +.IR acme (1) +serves a variety of files for reading, writing, and controlling +windows. +Some of them are virtual versions of system files for dealing +with the virtual console; others control operations +of +.I acme +itself. +When a command is run under +.IR acme , +a directory holding these files is mounted on +.B /mnt/acme +(also bound to +.BR /mnt/wsys ) +and also +.BR /dev ; +the files mentioned here +appear in both those directories. +.PP +Some of these files supply virtual versions of services available from the underlying +environment, in particular the character terminal files in Plan 9's +\fIcons\fR(3). +(Unlike in Plan 9's \fIrio\fR(1), +each command under +.I acme +sees the same set of files; there is not a distinct +.B /dev/cons +for each window.) +Other files are unique to +.IR acme . +.TP +.B acme +is a subdirectory used by +.B win +(see +.IR acme (1)) +as a mount point for the +.I acme +files associated with the window in which +.B win +is running. +It has no specific function under +.I acme +itself. +.TP +.B cons +is the standard and diagnostic output file for all commands +run under +.IR acme . +(Input for commands is redirected to +.BR /dev/null .) +Text written to +.B cons +appears in a window labeled +.IB dir /+Errors\f1, +where +.I dir +is the directory in which the command +was run. +The window is created if necessary, but not until text is actually written. +.TP +.B consctl +Is an empty unwritable file present only for compatibility; there is no way +to turn off `echo', for example, under +.IR acme . +.TP +.B index +holds a sequence of lines of text, one per window. Each line has 5 decimal numbers, +each formatted in 11 characters plus a blank\(emthe window ID; +number of characters (runes) in the tag; +number of characters in the body; +a 1 if the window is a directory, 0 otherwise; +and a 1 if the window is modified, 0 +otherwise\(emfollowed by the tag up to a newline if present. +Thus at character position 5×12 starts the name of the window. +If a file has multiple zeroxed windows open, +only the most recently used will appear in the +.B index +file. +.TP +.B label +is an empty file, writable without effect, present only for compatibility with +.BR rio . +.TP +.B new +A directory analogous to the numbered directories +.RI ( q.v. ). +Accessing any +file in +.B new +creates a new window. Thus to cause text to appear in a new window, +write it to +.BR /dev/new/body . +For more control, open +.BR /dev/new/ctl +and use the interface described below. +.LP +.PP +Each +.I acme +window has associated a directory numbered by its ID. +Window IDs are chosen sequentially and may be discovered by the +.B ID +command, by +reading the +.B ctl +file, or +indirectly through the +.B index +file. The files in the numbered directories are as follows. +.TP +.B addr +may be written with any textual address (line number, regular expression, etc.), +in the format understood by button 3 but without the initial colon, including compound addresses, +to set the address for text accessed through the +.B data +file. +When read, it returns the value of the address that would next be read +or written through the +.B data +file, in the format +.BI # m ,# n +where +.I m +and +.I n +are character (not byte) offsets. If +.I m +and +.I n +are identical, the format is just +.BI # m\f1. +Thus a regular expression may be evaluated by writing it to +.B addr +and reading it back. +The +.B addr +address has no effect on the user's selection of text. +.TP +.B body +holds contents of the window body. It may be read at any byte offset. +Text written to +.B body +is always appended; the file offset is ignored. +.TP +.B ctl +may be read to recover the five numbers as held in the +.B index +file, described above, plus two more fields: the width of the +window in pixels and the name of the font used in the window. +Text messages may be written to +.B ctl +to affect the window. +Each message is terminated by a newline and multiple +messages may be sent in a single write. +.RS .5i +.TF limit=addr +.TP +.B addr=dot +Set the +.B addr +address to that of the user's selected text in the window. +.TP +.B clean +Mark the window clean as though it has just been written. +.TP +.B dirty +Mark the window dirty, the opposite of clean. +.TP +.B cleartag +Remove all text in the tag after the vertical bar. +.TP +.B del +Equivalent to the +.B Del +interactive command. +.TP +.B delete +Equivalent to the +.B Delete +interactive command. +.TP +.B dot=addr +Set the user's selected text in the window to the text addressed by the +.B addr +address. +.TP +.BI dump " command +Set the command string to recreate the window from a dump file. +.TP +.BI dumpdir " directory +Set the directory in which to run the command to recreate the window from a dump file. +.TP +.B get +Equivalent to the +.B Get +interactive command with no arguments; accepts no arguments. +.TP +.B limit=addr +When the +.B ctl +file is first opened, regular expression context searches in +.B addr +addresses examine the whole file; this message restricts subsequent +searches to the current +.B addr +address. +.TP +.B mark +Cancel +.BR nomark , +returning the window to the usual state wherein each modification to the +body must be undone individually. +.TP +.BI name " name +Set the name of the window to +.IR name . +.TP +.B nomark +Turn off automatic `marking' of changes, so a set of related changes +may be undone in a single +.B Undo +interactive command. +.TP +.B noscroll +Turn off automatic `scrolling' of the window to show text written to the body. +.TP +.B put +Equivalent to the +.B Put +interactive command with no arguments; accepts no arguments. +.TP +.B scroll +Cancel a +.B noscroll +message, returning the window to the default state wherein each write +to the +.B body +file causes the window to `scroll' to display the new text. +.TP +.B show +Guarantee at least some of the selected text is visible on the display. +.RE +.PD +.TP +.B data +is used in conjunction with +.B addr +for random access to the contents of the body. +The file offset is ignored when writing the +.B data +file; instead the location of the data to be read or written is determined by the state of the +.B addr +file. +Text, which must contain only whole characters (no `partial runes'), +written to +.B data +replaces the characters addressed by the +.B addr +file and sets the address to the null string at the end of the written text. +A read from +.B data +returns as many whole characters as the read count will permit starting +at the beginning of the +.B addr +address (the end of the address has no effect) +and sets the address to the null string at the end of the returned +characters. +.TP +.B event +When a window's +.B event +file is open, changes to the window occur as always but the +actions are also reported as +messages to the reader of the file. Also, user actions with buttons 2 and 3 +(other than chorded +.B Cut +and +.BR Paste , +which behave normally) have no immediate effect on the window; +it is expected that the program reading the +.B event +file will interpret them. +The messages have a fixed format: +a character indicating the origin or cause of the action, +a character indicating the type of the action, +four free-format blank-terminated decimal numbers, +optional text, and a newline. +The first and second numbers are the character addresses of the action, +the third is a flag, +and the final is a count of the characters in the optional text, which +may itself contain newlines. +The origin characters are +.B E +for writes to the +.B body +or +.B tag +file, +.B F +for actions through the window's other files, +.B K +for the keyboard, and +.B M +for the mouse. +The type characters are +.B D +for text deleted from the body, +.B d +for text deleted from the tag, +.B I +for text inserted to the body, +.B i +for text inserted to the tag, +.B L +for a button 3 action in the body, +.B l +for a button 3 action in the tag, +.B X +for a button 2 action in the body, and +.B x +for a button 2 action in the tag. +.IP +If the relevant text has less than 256 characters, it is included in the message; +otherwise it is elided, the fourth number is 0, and the program must read +it from the +.B data +file if needed. No text is sent on a +.B D +or +.B d +message. +.IP +For +.BR D , +.BR d , +.BR I , +and +.BR i +the flag is always zero. +For +.BR X +and +.BR x , +the flag is a bitwise OR (reported decimally) of the following: +1 if the text indicated is recognized as an +.I acme +built-in command; +2 if the text indicated is a null string that has a non-null expansion; +if so, another complete message will follow describing the expansion +exactly as if it had been indicated explicitly (its flag will always be 0); +8 if the command has an extra (chorded) argument; if so, +two more complete messages will follow reporting the argument (with +all numbers 0 except the character count) and where it originated, in the form of +a fully-qualified button 3 style address. +.IP +For +.B L +and +.BR l , +the flag is the bitwise OR of the following: +1 if +.I acme +can interpret the action without loading a new file; +2 if a second (post-expansion) message follows, analogous to that with +.B X +messages; +4 if the text is a file or window name (perhaps with address) rather than +plain literal text. +.IP +For messages with the 1 bit on in the flag, +writing the message back to the +.B event +file, but with the flag, count, and text omitted, +will cause the action to be applied to the file exactly as it would +have been if the +.B event +file had not been open. +.TP +.B tag +holds contents of the window tag. It may be read at any byte offset. +Text written to +.B tag +is always appended; the file offset is ignored. +.SH SOURCE +.B /usr/local/plan9/src/cmd/acme +.SH SEE ALSO +.IR rio (1), +.IR acme (1) diff --git a/man/man4/plumber.4 b/man/man4/plumber.4 new file mode 100644 index 00000000..681bd5e2 --- /dev/null +++ b/man/man4/plumber.4 @@ -0,0 +1,121 @@ +.TH PLUMBER 4 +.SH NAME +plumber \- file system for interprocess messaging +.SH SYNOPSIS +.B plumber +[ +.B -p +.I plumbing +] +.SH DESCRIPTION +The +.I plumber +is a user-level file server that receives, examines, rewrites, and dispatches +.IR plumb (7) +messages between programs. +Its behavior is programmed by a +.I plumbing +file (default +.BR /usr/$user/lib/plumbing ) +in the format of +.IR plumb (7). +.PP +Its services are posted via +.IR 9pserve (4) +as +.BR plumb . +and consist of two +pre-defined files, +.B plumb/send +and +.BR plumb/rules , +and a set of output +.I ports +for dispatching messages to applications. +.PP +Programs use +.B fswrite +(see +.IR 9pclient (3)) +to deliver messages to the +.B send +file, and +.I fsread +to receive them from the corresponding port. +For example, +.IR sam (1)'s +.B plumb +menu item or the +.B B +command cause a message to be sent to +.BR plumb/send ; +.B sam +in turn reads from, by convention, +.B plumb/edit +to receive messages about files to open. +.PP +A copy of each message is sent to each client that has the corresponding port open. +If none has it open, and the rule has a +.B plumb +.B client +or +.B plumb +.B start +rule, that rule is applied. +A +.B plumb +.B client +rule causes the specified command to be run +and the message to be held for delivery when the port is opened. +A +.B plumb +.B start +rule runs the command but discards the message. +If neither +.B start +or +.B client +is specified and the port is not open, +the message is discarded and a write error is returned to the sender. +.PP +The set of output ports is determined dynamically by the +specification in the plumbing rules file: a port is created for each unique +destination of a +.B plumb +.B to +rule. +.PP +The set of rules currently active may be examined by reading the file +.BR plumb/rules ; +appending to this file adds new rules to the set, while +creating it (opening it with +.BR OTRUNC ) +clears the rule set. +Thus the rule set may be edited dynamically with a traditional text editor. +However, ports are never deleted dynamically; if a new set of rules does not +include a port that was defined in earlier rules, that port will still exist (although +no new messages will be delivered there). +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /usr/local/plan9/plumb +directory to search for files in +.B include +statements +.TP +.B plumb +mount name for +.IR plumber (4). +.SH SOURCE +.B /usr/local/plan9/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (3), +.IR plumb (7) +.\" .SH BUGS +.\" .IR Plumber 's +.\" file name space is fixed, so it is difficult to plumb +.\" messages that involve files in newly mounted services. diff --git a/man/man4/ramfs.4 b/man/man4/ramfs.4 new file mode 100644 index 00000000..32405de1 --- /dev/null +++ b/man/man4/ramfs.4 @@ -0,0 +1,50 @@ +.TH RAMFS 4 +.SH NAME +ramfs \- memory file system +.SH SYNOPSIS +.B ramfs +[ +.B -i +] +[ +.B -S +.I service +] +.SH DESCRIPTION +.I Ramfs +starts a 9P file server +keeping all files in memory. +Initially the file tree is empty. +.PP +By default +.I ramfs +posts its service as +.B ramfs +using +.IR 9pserve (4). +.PP +The +.B -S +flag specifies an alternate service name for ramfs to use. +.PP +The +.B -i +flag tells +.I ramfs +to use file descriptors 0 and 1 for its communication channel +rather than create a pipe. +This makes it possible to use +.I ramfs +as a file server on a remote machine: the file descriptors 0 +and 1 will be the network channel from +.I ramfs +to the client machine. +.PP +This program is useful mainly as an example of how +to write a user-level file server. +It can also be used to provide high-performance temporary files. +.SH SOURCE +.B /usr/local/plan9/src/cmd/ramfs.c +.SH "SEE ALSO" +.IR 9p (3), +.IR 9pserve (4) diff --git a/man/man5/INDEX b/man/man5/INDEX new file mode 100644 index 00000000..6f515233 --- /dev/null +++ b/man/man5/INDEX @@ -0,0 +1 @@ +[a-z0-9:]* [a-z0-9:]* diff --git a/man/man7/INDEX b/man/man7/INDEX new file mode 100644 index 00000000..79302660 --- /dev/null +++ b/man/man7/INDEX @@ -0,0 +1,18 @@ +color color.7 +face face.7 +font font.7 +subfont font.7 +image image.7 +man man.7 +map map.7 +ms ms.7 +plot plot.7 +plumb plumb.7 +regexp regexp.7 +regexp9 regexp9.7 +thumbprint thumbprint.7 +ASCII utf.7 +UTF utf.7 +Unicode utf.7 +rune utf.7 +utf utf.7 diff --git a/man/man7/color.7 b/man/man7/color.7 new file mode 100644 index 00000000..c8b536a0 --- /dev/null +++ b/man/man7/color.7 @@ -0,0 +1,150 @@ +.TH COLOR 7 +.SH NAME +color \- representation of pixels and colors +.SH DESCRIPTION +To address problems of consistency and portability among applications, +Plan 9 uses a fixed color map, called +.BR rgbv , +on 8-bit-per-pixel displays. +Although this avoids problems caused by multiplexing color maps between +applications, it requires that the color map chosen be suitable for most purposes +and usable for all. +Other systems that use fixed color maps tend to sample the color cube +uniformly, which has advantages\(emmapping from a (red, green, blue) triple +to the color map and back again is easy\(embut ignores an important property +of the human visual system: eyes are +much more sensitive to small changes in intensity than +to changes in hue. +Sampling the color cube uniformly gives a color map with many different +hues, but only a few shades of each. +Continuous tone images converted into such maps demonstrate conspicuous +artifacts. +.PP +Rather than dice the color cube into subregions of +size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4 +(as in previous releases of Plan 9), picking 1 color in each, +the +.B rgbv +color map uses a 4\(mu4\(mu4 subdivision, with +4 shades in each subcube. +The idea is to reduce the color resolution by dicing +the color cube into fewer cells, and to use the extra space to increase the intensity +resolution. +This results in 16 grey shades (4 grey subcubes with +4 samples in each), 13 shades of each primary and secondary color (3 subcubes +with 4 samples plus black) and a reasonable selection of colors covering the +rest of the color cube. +The advantage is better representation of +continuous tones. +.PP +The following function computes the 256 3-byte entries in the color map: +.IP +.EX +.ta 6n +6n +6n +6n +void +setmaprgbv(uchar cmap[256][3]) +{ + uchar *c; + int r, g, b, v; + int num, den; + int i, j; + + for(r=0,i=0; r!=4; r++) + for(v=0; v!=4; v++,i+=16) + for(g=0,j=v-r; g!=4; g++) + for(b=0; b!=4; b++,j++){ + c = cmap[i+(j&15)]; + den = r; + if(g > den) + den = g; + if(b > den) + den = b; + if(den == 0) /* would divide check; pick grey shades */ + c[0] = c[1] = c[2] = 17*v; + else{ + num = 17*(4*den+v); + c[0] = r*num/den; + c[1] = g*num/den; + c[2] = b*num/den; + } + } +} +.EE +.PP +There are 4 nested loops to pick the (red,green,blue) coordinates of the subcube, +and the value (intensity) within the subcube, indexed by +.BR r , +.BR g , +.BR b , +and +.BR v , +whence +the name +.IR rgbv . +The peculiar order in which the color map is indexed is designed to distribute the +grey shades uniformly through the map\(emthe +.IR i 'th +grey shade, +.RI 0<= i <=15 +has index +.IR i ×17, +with black going to 0 and white to 255. +Therefore, when a call to +.B draw +converts a 1, 2 or 4 bit-per-pixel picture to 8 bits per pixel (which it does +by replicating the pixels' bits), the converted pixel values are the appropriate +grey shades. +.PP +The +.B rgbv +map is not gamma-corrected, for two reasons. First, photographic +film and television are both normally under-corrected, the former by an +accident of physics and the latter by NTSC's design. +Second, we require extra color resolution at low intensities because of the +non-linear response and adaptation of the human visual system. +Properly +gamma-corrected displays with adequate low-intensity resolution pack the +high-intensity parts of the color cube with colors whose differences are +almost imperceptible. +Either reason suggests concentrating +the available intensities at the low end of the range. +.PP +On `true-color' displays with separate values for the red, green, and blue +components of a pixel, the values are chosen so 0 represents no intensity (black) and the +maximum value (255 for an 8-bit-per-color display) represents full intensity (e.g., full red). +Common display depths are 24 bits per pixel, with 8 bits per color in order +red, green, blue, and 16 bits per pixel, with 5 bits of red, 6 bits of green, and 5 bits of blue. +.PP +Colors may also be created with an opacity factor called +.BR alpha , +which is scaled so 0 represents fully transparent and 255 represents opaque color. +The alpha is +.I premultiplied +into the other channels, as described in the paper by Porter and Duff cited in +.IR draw (3). +The function +.B setalpha +(see +.IR allocimage (3)) +aids the initialization of color values with non-trivial alpha. +.PP +The packing of pixels into bytes and words is odd. +For compatibility with VGA frame buffers, the bits within a +pixel byte are in big-endian order (leftmost pixel is most +significant bits in byte), while bytes within a pixel are packed in little-endian +order. Pixels are stored in contiguous bytes. This results +in unintuitive pixel formats. For example, for the RGB24 format, +the byte ordering is blue, green, red. +.PP +To maintain a constant external representation, +the +.IR draw (3) +interface +as well as the +various graphics libraries represent colors +by 32-bit numbers, as described in +.IR color (3). +.SH "SEE ALSO" +.IR color (3), +.IR graphics (3), +.IR draw (3) diff --git a/man/man7/face.7 b/man/man7/face.7 new file mode 100644 index 00000000..08b04a46 --- /dev/null +++ b/man/man7/face.7 @@ -0,0 +1,115 @@ +.TH FACE 7 +.SH NAME +face \- face files +.SH DESCRIPTION +The directories +.B /usr/$user/lib/face +and +.B /lib/face +contain a hierarchy of images of people. +In those directories are subdirectories named by the sizes of +the corresponding image files: +.B 48x48x1 +(48 by 48 pixels, one bit per pixel); +.B 48x48x2 +(48 by 48 pixels, two (grey) bits per pixel); +.B 48x48x4 +(48 by 48 pixels, four (grey) bits per pixel); +.B 48x48x8 +(48 by 48 pixels, eight (color-mapped) bits per pixel); +.B 512x512x8 +(512 by 512 pixels, eight (color-mapped) bits per pixel); +.B 512x512x24 +(512 by 512 pixels, twenty-four bits per pixel (3 times 8 bits +per color)). +The large files serve no special purpose; they are stored +as images +(see +.IR image (7)). +The small files are the `icons' displayed by +.B faces +and +.B seemail +(see Plan 9's +\fIfaces\fR(1)); +for depths less than 4, their format is special. +.PP +One- and two-bit deep icons are stored as text, one line of the file to one scan line +of display. +Each line is divided into 8-bit, 16-bit, or 32-bit big-endian words, +stored as a list of comma-separated hexadecimal C constants, +such as: +.IP +.EX +0x9200, 0x1bb0, 0x003e, +.EE +.PP +This odd format is historical and the programs that read it +are somewhat forgiving about blanks and the need for commas. +.PP +The files +.BR lib/face/*/.dict +hold a correspondence between users at machines +and face files. +The format is +.IP +.EX +.I machine\fB/\fPuser directory\fB/\fPfile\fB.\fPver +.EE +.PP +The +.I machine +is the domain name of the machine sending the message, +and +.I user +the name of the user sending it. +The +.I directory +is a further subdirectory of (say) +.BR /lib/face/48x48x1 , +named by a single letter corresponding to the first character +of the user names. The +.I file +is the name of the file, typically but not always the user name, +and +.I ver +is a number to distinguish different images, for example to +distinguish the image for Bill Gates from the image for Bill Joy, +both of which might otherwise be called +.BR b/bill . +For example, Bill Gates might be represented by the line +.IP +.EX +microsoft.com/bill b/bill.1 +.EE +.PP +If multiple entries exist for a user in the various +.B .dict +files, +.I faces +chooses the highest pixel size less than or equal to that of the +display on which it is running. +.PP +Finally, or rather firstly, the file +.B /lib/face/.machinelist +contains a list of machine/domain pairs, one per line, +to map any of a set of machines to a single domain name to +be looked up in the +.B .dict +files. The machine name may be a regular expression, +so for example the entry +.IP +.EX +\&.*research\e.bell-labs\e.com astro +.EE +.PP +maps any of the machines in Bell Labs Research into the +shorthand name +.BR astro , +which then appears as a domain name in the +.B .dict +files. +.SH "SEE ALSO" +.IR mail (1), +.IR tweak (1), +.IR image (7) diff --git a/man/man7/font.7 b/man/man7/font.7 new file mode 100644 index 00000000..f651a58a --- /dev/null +++ b/man/man7/font.7 @@ -0,0 +1,87 @@ +.TH FONT 7 +.SH NAME +font, subfont \- external format for fonts and subfonts +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Fonts and subfonts are described in +.IR cachechars (3). +.PP +External fonts are described by a plain text file that can be read using +.IR openfont . +The format of the file is a header followed by any number of +subfont range specifications. +The header contains two numbers: the height and the ascent, both in pixels. +The height is the inter-line spacing and the ascent is the distance +from the top of the line to the baseline. These numbers are chosen +to display consistently all the subfonts of the font. +A subfont range specification contains two or three numbers and a file name. +The numbers are the inclusive range of characters covered by the subfont, +with an optional starting position within the subfont, +and the file name names an external file suitable for +.I readsubfont +(see +.IR graphics (3)). +The minimum number of a covered range is mapped to the specified starting position +(default zero) of the +corresponding subfont. +If the subfont file name does not begin with a slash, it is taken relative to the +directory containing the font file. +Each field must be followed by some white space. +Each numeric field may be C-format decimal, octal, or hexadecimal. +.PP +External subfonts are represented in a more rigid format +that can be read and written using +.I readsubfont +and +.I writesubfont +(see +.IR subfont (3)). +The format for subfont files is: an image containing character glyphs, +followed by a subfont header, followed by character information. +The image has the format for external image files described in +.IR image (7). +The subfont header has 3 +decimal strings: +.BR n , +.BR height , +and +.BR ascent . +Each number is right-justified and blank padded in 11 characters, followed by a blank. +The character +.B info +consists of +.BR n +1 +6-byte entries, each giving the +.B Fontchar +.B x +(2 bytes, low order byte first), +.BR top , +.BR bottom , +.BR left , +and +.BR width . +The +.B x +field of the last +.B Fontchar +is used to calculate the image width +of the previous character; the other fields in the last +.B Fontchar +are irrelevant. +.PP +Note that the convention of using the character with value zero (NUL) to represent +characters of zero width (see +.IR draw (3)) +means that fonts should have, as their zeroth character, +one with non-zero width. +.SH FILES +.TF /lib/font/bit/* +.TP +.B /lib/font/bit/* +font directories +.SH "SEE ALSO" +.IR graphics (3), +.IR draw (3), +.IR cachechars (3), +.IR subfont (3) diff --git a/man/man7/image.7 b/man/man7/image.7 new file mode 100644 index 00000000..6e613f9c --- /dev/null +++ b/man/man7/image.7 @@ -0,0 +1,205 @@ +.TH IMAGE 7 +.SH NAME +image \- external format for images +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Images are described in +.IR graphics (3), +and the definition of pixel values is in +.IR color (7). +Fonts and images are stored in external files +in machine-independent formats. +.PP +Image files are read and written using +.B readimage +and +.B writeimage +(see +.IR allocimage (3)), or +.B readmemimage +and +.B writememimage +(see +.IR memdraw (3)). +An uncompressed image file starts with 5 +strings: +.BR chan , +.BR r.min.x , +.BR r.min.y , +.BR r.max.x , +and +.BR r.max.y . +Each is right-justified and blank padded in 11 characters, followed by a blank. +The +.B chan +value is a textual string describing the pixel format +(see +.B strtochan +in +.IR graphics (3) +and the discussion of channel descriptors below), +and the rectangle coordinates are decimal strings. +The rest of the file contains the +.B r.max.y-r.min.y +rows of pixel data. +A +.I row +consists of the byte containing pixel +.B r.min.x +and all the bytes up to and including the byte containing pixel +.BR r.max.x -1. +For images with depth +.I d +less than eight, a pixel with x-coordinate = +.I x +will appear as +.I d +contiguous bits in a byte, with the pixel's high order bit +starting at the byte's bit number +.if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)), +.if n w*(x mod (8/w)), +where bits within a byte are numbered 0 to 7 from the +high order to the low order bit. +Rows contain integral number of bytes, so there may be some unused +pixels at either end of a row. +If +.I d +is greater than 8, the definition of images requires that it will a multiple of 8, so +pixel values take up an integral number of bytes. +.PP +The +.B loadimage +and +.B unloadimage +functions described in +.IR allocimage (3) +also deal with rows in this format, stored in user memory. +.PP +The channel format string is a sequence of two-character channel descriptions, +each comprising a letter +.RB ( r +for red, +.B g +for green, +.B b +for blue, +.B a +for alpha, +.B m +for color-mapped, +.B k +for greyscale, +and +.B x +for ``don't care'') +followed by a number of bits per pixel. +The sum of the channel bits per pixel is the +depth of the image, which must be either +a divisor or a multiple of eight. +It is an error to have more than +one of any channel but +.BR x . +An image must have either a greyscale channel; a color mapped channel; +or red, green, and blue channels. +If the alpha channel is present, it must be at least as deep as any other channel. +.PP +The channel string defines the format of the pixels in the file, +and should not be confused with ordering of bytes in the file. +In particular +.B 'r8g8b8' +pixels have byte ordering blue, green, and red within the file. +See +.IR color (7) +for more details of the pixel format. +.PP +A venerable yet deprecated format replaces the channel string +with a decimal +.IR ldepth , +which is the base two logarithm of the number +of bits per pixel in the image. +In this case, +.IR ldepth s +0, 1, 2, and 3 +correspond to channel descriptors +.BR k1 , +.BR k2 , +.BR k4 , +and +.BR m8 , +respectively. +.PP +Compressed image files start with a line of text containing the word +.BR compressed , +followed by a header as described above, followed by the image data. +The data, when uncompressed, is laid out in the usual form. +.PP +The data is represented by a string of compression blocks, each encoding +a number of rows of the image's pixel data. Compression blocks +are at most 6024 bytes long, so that they fit comfortably in a +single 9P message. Since a compression block must encode a +whole number of rows, there is a limit (about 5825 bytes) to the width of images +that may be encoded. Most wide images are in subfonts, +which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide. +.PP +A compression block begins with two decimal strings of twelve bytes each. +The first number is one more than the +.B y +coordinate of the last row in the block. The second is the number +of bytes of compressed data in the block, not including the two decimal strings. +This number must not be larger than 6000. +.PP +Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77, +best described in J A Storer & T G Szymanski +`Data Compression via Textual Substitution', +JACM 29#4, pp. 928-951. +.PP +The compression block is a string of variable-length +code words encoding substrings of the pixel data. A code word either gives the +substring directly or indicates that it is a copy of data occurring +previously in the pixel stream. +.PP +In a code word whose first byte has the high-order bit set, the rest of the +byte indicates the length of a substring encoded directly. +Values from 0 to 127 encode lengths from 1 to 128 bytes. +Subsequent bytes are the literal pixel data. +.PP +If the high-order bit is zero, the next 5 bits encode +the length of a substring copied from previous pixels. Values from 0 to 31 +encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and +the 8 bits of the next byte encode an offset backward from the current +position in the pixel data at which the copy is to be found. Values from +0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient', +with the length larger than the offset, which works just fine: the new data +is identical to the data at the given offset, even though the two strings overlap. +.PP +Some small images, in particular 48\(mu48 face files +as used by +.I seemail +(see Plan 9's +\fIfaces\fR(1) +and +.IR face (7)) +and 16\(mu16 +cursors, can be stored textually, suitable for inclusion in C source. +Each line of text represents one scan line as a +comma-separated sequence of hexadecimal +bytes, shorts, or words in C format. +For cursors, each line defines a pair of bytes. +(It takes two images to define a cursor; each must be stored separately +to be processed by programs such as +.IR tweak (1).) +Face files of one bit per pixel are stored as a sequence of shorts, +those of larger pixel sizes as a sequence of longs. +Software that reads these files must deduce the image size from +the input; there is no header. +These formats reflect history rather than design. +.SH "SEE ALSO" +.IR jpg (1), +.IR tweak (1), +.IR graphics (3), +.IR draw (3), +.IR allocimage (3), +.IR color (7), +.IR face (7), +.IR font (7) diff --git a/man/man7/man.7 b/man/man7/man.7 new file mode 100644 index 00000000..fbfa9f2a --- /dev/null +++ b/man/man7/man.7 @@ -0,0 +1,249 @@ +.TH MAN 7 +.SH NAME +man \- macros to typeset manual +.SH SYNOPSIS +.B nroff -man +.I file ... +.PP +.B troff -man +.I file ... +.SH DESCRIPTION +These macros are used to format pages of this manual. +.PP +Except in +.L .LR +and +.L .RL +requests, any text argument denoted +.I t +in the request summary may be zero to six words. +Quotes +\fL"\fP ... \fL"\fP +may be used to include blanks in a `word'. +If +.I t +is empty, +the special treatment is applied to +the next text input line (the next line that doesn't begin with dot). +In this way, for example, +.B .I +may be used to italicize a line of more than 6 words, or +.B .SM +followed by +.B .B +to make small letters in `bold' font. +.PP +A prevailing indent distance is remembered between +successive indented paragraphs, +and is reset to default value upon reaching a non-indented paragraph. +Default units for indents +.I i +are ens. +.PP +The fonts are +.TP +.B R +roman, the main font, preferred for diagnostics +.PD 0 +.TP +.B I +italic, preferred for parameters, short names of commands, +names of manual pages, +and naked function names +.TP +.L B +`bold', actually the constant width font, +preferred for examples, file names, declarations, keywords, names of +.B struct +members, and literals +(numbers are rarely literals) +.TP +.B L +also the constant width font. +In +.I troff +.BR L = B ; +in +.I nroff +arguments of the macros +.BR .L , +.BR .LR , +and +.B .RL +are printed in quotes; +preferred only where quotes really help (e.g. lower-case literals and +punctuation). +.PD +.LP +Type font and size are reset to default values +before each paragraph, and after processing +font- or size-setting macros. +.PP +The +.B -man +macros admit equations and tables in the style of +.IR eqn (1) +and +.IR tbl (1), +but do not support arguments on +.B .EQ +and +.B .TS +macros. +.PP +These strings are predefined by +.BR -man : +.TP +.B \e*R +.if t `\*R', `(Reg)' in +.if t .IR nroff . +.if n `(Reg)', trademark symbol in +.if n .IR troff . +.br +.ns +.TP +.B \e*S +Change to default type size. +.SH FILES +.B /sys/lib/tmac/tmac.an +.SH SEE ALSO +.IR troff (1), +.IR man (1) +.SH REQUESTS +.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u +.di xx + \ka +.br +.di +.in \nau +.ti0 +Request Cause If no Explanation +.ti0 + Break Argument +.ti0 +\&\fL.B\fR \fIt\fR no \fIt\fR=n.t.l.* Text +.I t +is `bold'. +.ti0 +\&\fL.BI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and italic. +.ti0 +\&\fL.BR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating bold and Roman. +.ti0 +\&\fL.DT\fR no Restore default tabs. +.ti0 +\&\fL.EE\fR yes End displayed example +.ti0 +\&\fL.EX\fR yes Begin displayed example +.ti0 +\&\fL.HP\fR \fIi\fR yes \fIi\fR=p.i.* Set prevailing indent to +.IR i . +Begin paragraph with hanging indent. +.ti0 +\&\fL.I\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is italic. +.ti0 +\&\fL.IB\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and bold. +.ti0 +\&\fL.IP\fR \fIx i\fR yes \fIx\fR="" Same as \fL.TP\fP with tag +.IR x . +.ti0 +\&\fL.IR\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating italic and Roman. +.ti0 +\&\fL.L\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is literal. +.ti0 +\&\fL.LP\fR yes Same as \fL.PP\fP. +.ti0 +\&\fL.LR\fR \fIt\fR no Join 2 +words of +.I t +alternating literal and Roman. +.ti0 +\&\fL.PD\fR \fId\fR no \fId\fR=\fL.4v\fP Interparagraph distance is +.IR d . +.ti0 +\&\fL.PP\fR yes Begin paragraph. +Set prevailing indent to default. +.ti0 +\&\fL.RE\fR yes End of relative indent. +Set prevailing indent to amount of starting \fL.RS\fP. +.ti0 +\&\fL.RI\fR \fIt\fR no \fIt\fR=n.t.l. Join +words of +.I t +alternating Roman and italic. +.ti0 +\&\fL.RL\fR \fIt\fR no Join 2 or 3 +words of +.I t +alternating Roman and literal. +.ti0 +\&\fL.RS\fR \fIi\fR yes \fIi\fR=p.i. Start relative indent, +move left margin in distance +.IR i . +Set prevailing indent to default for nested indents. +.ti0 +\&\fL.SH\fR \fIt\fR yes \fIt\fR="" Subhead; reset paragraph distance. +.ti0 +\&\fL.SM\fR \fIt\fR no \fIt\fR=n.t.l. Text +.I t +is small. +.ti0 +\&\fL.SS\fR \fIt\fR no \fIt\fR="" Secondary subhead. +.ti0 +\&\fL.TF\fR \fIs\fR yes Prevailing indent is wide as +string +.I s +in font +.BR L ; +paragraph distance is 0. +.ti0 +\&\fL.TH\fR \fIn c x\fR yes Begin page named +.I n +of chapter +.IR c; +.I x +is extra commentary, e.g. `local', for page head. +Set prevailing indent and tabs to default. +.ti0 +\&\fL.TP\fR \fIi\fR yes \fIi\fR=p.i. Set prevailing indent to +.IR i . +Restore default indent if +.IR i =0. +Begin indented paragraph +with hanging tag given by next text line. +If tag doesn't fit, place it on separate line. +.ti0 +\&\fL.1C\fR yes Equalize columns and return to 1-column output +.ti0 +\&\fL.2C\fR yes Start 2-column nofill output +.PP +.ti0 +* n.t.l. = next text line; p.i. = prevailing indent +.SH BUGS +There's no way to fool +.I troff +into handling literal double quote marks +.B \&" +in font-alternation macros, such as +.LR .BI . +.br +There is no direct way to suppress column widows in 2-column +output; the column lengths may be adjusted by inserting +.L .sp +requests before the closing +.LR .1C . diff --git a/man/man7/map.7 b/man/man7/map.7 new file mode 100644 index 00000000..80e1eebf --- /dev/null +++ b/man/man7/map.7 @@ -0,0 +1,87 @@ +.TH MAP 7 +.SH NAME +map \- digitized map formats +.SH DESCRIPTION +Files used by +.IR map (7) +are a sequence of structures of the form: +.PP +.EX +struct { + signed char patchlatitude; + signed char patchlongitude; + short n; + union { + struct { + short latitude; + short longitude; + } point[n]; + struct { + short latitude; + short longitude; + struct { + signed char latdiff; + signed char londiff; + } point[\-n]; + } highres; + } segment; +}; +.EE +where +.B short +stands for 16-bit integers and there is no padding within or between +.BR structs . +Shorts are stored in little-endian order, low byte first. +To assure portability, +.I map +accesses them bytewise. +.PP +Fields +.L patchlatitude +and +.L patchlongitude +tell to what +10-degree by 10-degree +patch of the earth's surface a segment belongs. +Their values range from \-9 to 8 and from \-18 to 17, +respectively, and indicate the coordinates of the +southeast corner of the patch in units of 10 degrees. +.PP +Each segment of +.RB | n | +points is connected; consecutive segments +are not necessarily related. +Latitude and longitude +are measured in units of 0.0001 radian. +If +.B n +is negative, then +differences to the first and succeeding points +are measured in units of 0.00001 radian. +Latitude is counted positive to the north and +longitude positive to the west. +.PP +The patches are ordered lexicographically by +.L patchlatitude +then +.LR patchlongitude . +A printable +index to the first segment of each patch +in a file named +.I data +is kept in an associated file named +.IB data .x\f1. +Each line of an index file contains +.L patchlatitude, +.L patchlongitude +and the byte position +of the patch +in the map file. +Both the map file and the index file are ordered by +patch latitude and longitude. +.SH "SEE ALSO" +.IR map (7) +.br +The data comes from the World Data Bank I and II and +U.S. Government sources: the Census Bureau, Geological +Survey, and CIA. diff --git a/man/man7/ms.7 b/man/man7/ms.7 new file mode 100644 index 00000000..b6c6788e --- /dev/null +++ b/man/man7/ms.7 @@ -0,0 +1,308 @@ +.TH MS 7 +.hc % +.SH NAME +ms \- macros for formatting manuscripts +.SH SYNOPSIS +.B "nroff -ms" +[ +.I options +] +.I file ... +.br +.B "troff -ms" +[ +.I options +] +.I file ... +.SH DESCRIPTION +This package of +.I nroff +and +.IR troff (1) +macro definitions provides a canned formatting +facility for tech%nical papers in various formats. +.PP +The macro requests are defined below. +Many +.I nroff +and +.I troff +requests are unsafe in conjunction with +this package, but the following requests may be used with +impunity after the first +.BR .PP : +.LR .bp , +.LR .br , +.LR .sp , +.LR .ls , +.LR .na . +.PP +Output of the +.IR eqn (1), +.IR tbl (1), +.IR pic (1) +and +.IR grap (1) +preprocessors +for equations, tables, pictures, and graphs is acceptable as input. +.SH FILES +.B /sys/lib/tmac/tmac.s +.SH "SEE ALSO" +.br +M. E. Lesk, +``Typing Documents on the UNIX System: Using the \-ms Macros with Troff and Nroff'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.br +.IR eqn (1), +.IR troff (1), +.IR tbl (1), +.IR pic (1) +.SH REQUESTS +.ta \w'..ND \fIdate\fR 'u +\w'Initial 'u +\w'Cause 'u +.br +.di x + \ka +.br +.di +.in \nau +.ti0 +Request Initial Cause Explanation +.ti0 + Value Break +.br +.in \nau +.ti0 +\fL\&.1C\fP yes yes One column format on a new page. +.ti0 +\fL\&.2C\fP no yes Two column format. +.ti0 +\fL\&.AB\fP no yes Begin abstract. +.ti0 +\fL\&.AE\fP - yes End abstract. +.ti0 +\fL\&.AI\fP no yes Author's institution follows. +Suppressed in +.BR .TM . +.ti0 +\fL\&.AT\fP no yes Print `Attached' and turn off line filling. +.ti0 +\fL\&.AU\fP\fP\fP \fIx y\fR no yes Author's name follows. +.IR x " is location and " y " is" +extension, ignored except in +.BR TM . +.ti0 +\fL\&.B\fP \fIx y\fR no no Print +.I x +in boldface, append +.IR y ; +if no argument switch to boldface. +.ti0 +\fL\&.B1\fP no yes Begin text to be enclosed in a box. +.ti0 +\fL\&.B2\fP no yes End boxed text. +.ti0 +\fL\&.BI\fP \fIx y\fR no no Print +.I x +in bold italic and append +.IR y ; +if no argument switch to bold italic. +.ti0 +\fL\&.BT\fP date no Bottom title, automatically invoked at +foot of page. +May be redefined. +.ti0 +\fL\&.BX\fP \fIx\fR no no Print +.I x +in a box. +.ti0 +\fL\&.CW\fP \fIx y\fR no no Constant width font for +.IR x , +append +.IR y ; +if no argument switch to constant width. +.ti0 +\fL\&.CT\fP no yes Print `Copies to' and turn off line filling. +.ti0 +\fL\&.DA\fP \fIx\fR nroff no `Date line' at bottom of page +is +.IR x . +Default is today. +.ti0 +\fL\&.DE\fP - yes End displayed text. +Implies +.BR .KE . +.ti0 +\fL\&.DS\fP \fIx\fR no yes Start of displayed text, +to appear verbatim line-by-line: +.L I +indented (default), +.L L +left-justified, +.L C +centered, +.L B +(block) centered with straight left margin. +Implies +.BR .KS . +.ti0 +\fL\&.EG\fP no - Print document in BTL format for `Engineer's Notes.' Must be first. +.ti0 +\fL\&.EN\fP - yes Space after equation +produced by +.I neqn +or +.IR eqn (1). +.ti0 +\fL\&.EQ\fP \fIx y\fR - yes Display equation. +Equation number is +.IR y . +Optional +.I x +is +.BR I ", " L ", " C +as in +.BR .DS . +.ti0 +\fL\&.FE\fP - yes End footnote. +.ti0 +\fL\&.FP\fP \fIx\fR - no Set font positions for a family, e.g., +.L .FP lucidasans +.ti0 +\fL\&.FS\fP no no Start footnote. +The note will be moved to the bottom of the page. +.ti0 +\fL\&.HO\fP - no `Bell Laboratories, Holmdel, +New Jersey 07733'. +.ti0 +\fL\&.I\fP \fIx y\fR no no Italicize +.IR x , +append +.IR y ; +if no argument switch to italic. +.ti0 +\fL\&.IH\fP no no `Bell Laboratories, Naperville, Illinois 60540' +.ti0 +\fL\&.IM\fP no no Print document in BTL format for an internal memorandum. Must be first. +.ti0 +\fL\&.IP\fP \fIx y\fR no yes Start indented paragraph, +with hanging tag +.IR x . +Indentation is +.I y +ens (default 5). +.ti0 +\fL\&.KE\fP - yes End keep. +Put kept text on next page if not enough room. +.ti0 +\fL\&.KF\fP no yes Start floating keep. +If the kept text must be moved to the next page, +float later text back to this page. +.ti0 +\fL\&.KS\fP no yes Start keeping following text. +.ti0 +\fL\&.LG\fP no no Make letters larger. +.ti0 +\fL\&.LP\fP yes yes Start left-blocked paragraph. +.ti0 +\fL\&.LT\fP no yes Start a letter; a non-empty first argument +produces a full Lucent letterhead, a second argument is a room number, +a third argument is a telephone number. +.ti0 +\fL\&.MF\fP - - Print document in BTL format for `Memorandum for File.' Must be first. +.ti0 +\fL\&.MH\fP - no `Bell Laboratories, Murray Hill, +New Jersey 07974'. +.ti0 +\fL\&.MR\fP - - Print document in BTL format for `Memorandum for Record.' Must be first. +.ti0 +\fL\&.ND\fP \fIdate\fR troff no Use date supplied (if any) only in +special BTL format positions; omit from page footer. +.ti0 +\fL\&.NH\fP \fIn\fR - yes Same as +.BR .SH , +with automatic section +numbers like `1.2.3'; +.I n +is subsection level (default 1). +.ti0 +\fL\&.NL\fP yes no Make letters normal size. +.ti0 +\fL\&.P1\fP - yes Begin program display in constant width font. +.ti0 +\fL\&.P2\fP - yes End program display. +.ti0 +\fL\&.PE\fP - yes End picture; see +.IR pic (1). +.ti0 +\fL\&.PF\fP - yes End picture; restore vertical +position. +.ti0 +\fL\&.PP\fP no yes Begin paragraph. +First line indented. +.ti0 +\fL\&.PS\fP \fIh w\fR - yes Start picture; height +and width in inches. +.ti0 +\fL\&.PY\fP - no `Bell Laboratories, Piscataway, New Jersey 08854' +.ti0 +\fL\&.QE\fP - yes End quoted material. +.ti0 +\fL\&.QP\fP - yes Begin quoted paragraph (indent both margins). +.ti0 +\fL\&.QS\fP - yes Begin quoted material (indent both margins). +.ti0 +\fL\&.R\fP yes no Roman text follows. +.ti0 +\fL\&.RE\fP - yes End relative indent level. +.ti0 +\fL\&.RP\fP no - Cover sheet and first page for released +paper. +Must precede other requests. +.ti0 +\fL\&.RS\fP - yes Start level of relative indentation +from which subsequent indentation is measured. +.ti0 +\fL\&.SG\fP \fIx\fR no yes Insert signature(s) of author(s), +ignored except in +.B .TM +and +.BR .LT . +.IR x " is the reference line (initials of author and typist)." +.ti0 +\fL\&.SH\fP - yes Section head follows, +font automatically bold. +.ti0 +\fL\&.SM\fP no no Make letters smaller. +.ti0 +\fL\&.TA\fP\ \fIx\fR... 5... no Set tabs in ens. +Default is 5 10 15 ... +.ti0 +\fL\&.TE\fP - yes End table; see +.IR tbl (1). +.ti0 +\fL\&.TH\fP - yes End heading section of table. +.ti0 +\fL\&.TL\fP no yes Title follows. +.ti0 +\fL\&.TM\fP\ \fIx\fR... no - Print document in BTL technical memorandum format. +Arguments are TM number, (quoted list of) case number(s), and file number. +Must precede other requests. +.ti0 +\fL\&.TR\fP \fIx\fR - - Print in BTL technical report format; report number is \fIx\fR. Must be first. +.ti0 +\fL\&.TS\fP \fIx\fR - yes Begin table; if +.I x +is +.B H +table heading is repeated on new pages. +.ti0 +\fL\&.UL\fP \fIx\fR - no Underline argument (even in troff). +.ti0 +\fL\&.UX\fP\ \fIy z\fP - no `\fIz\fRUNIX\fIy\fP'; +first use gives registered trademark notice. +.ti0 +\fL\&.WH\fP - no `Bell Laboratories, Whippany, +New Jersey 07981'. +.hc diff --git a/man/man7/plot.7 b/man/man7/plot.7 new file mode 100644 index 00000000..452ab197 --- /dev/null +++ b/man/man7/plot.7 @@ -0,0 +1,336 @@ +.TH PLOT 7 +.SH NAME +plot \- graphics interface +.SH DESCRIPTION +Files of this format are interpreted by +.IR plot (1) +to draw graphics on the screen. +A +.I plot +file is a +.SM UTF +stream of +instruction lines. +Arguments are delimited by spaces, tabs, or commas. +Numbers may be floating point. +Punctuation marks (except +.LR : ) +, +spaces, and tabs at the beginning of lines are ignored. +Comments run from +.L : +to newline. +Extra letters appended to a valid instruction are ignored. +Thus +.LR ...line , +.LR line , and +.L li +all mean the same thing. +Arguments are interpreted as follows: +.TP +1. +If an instruction requires no arguments, the rest of the line is ignored. +.TP +2. +If it requires a string argument, then all the line +after the first field separator is passed as argument. +Quote marks may be used to preserve leading blanks. +Strings may include newlines represented as +.LR \en . +.TP +3. +Between numeric arguments alphabetic characters and +punctuation marks are ignored. +Thus +.L +line from 5 6 to 7 8 +draws a line from (5, 6) to (7, 8). +.TP +4. +Instructions with numeric arguments remain in effect until +a new instruction is read. +Such commands may spill over many lines. Thus +the following sequence will draw a polygon +with vertices +(4.5, 6.77), (5.8, 5.6), (7.8, 4.55), and (10.0, 3.6). +.IP +.EX +move 4.5 6.77 +vec 5.8, 5.6 7.8 +4.55 10.0, 3.6 4.5, 6.77 +.EE +.PP +The instructions are executed in order. +The last designated point in a +.BR line ", " move ", " rmove , +.BR vec ", " rvec ", " arc , +or +.B point +command becomes the `current point' +.RI ( X,Y ) +for the next command. +.SS "Open & Close" +.PD0 +.TP 10 +.BI o " string" +Open plotting device. +For +.IR troff , +.I string +specifies the size of the plot +(default is +.LR 6i ). +.TP 10 +.B cl +Close plotting device. +.PD +.SS "Basic Plotting Commands" +.PD0 +.TP 10 +.B e +Start another frame of output. +.TP 10 +.BI m " x y" +(move) Current point becomes +.I "x y." +.TP 10 +.BI rm " dx dy" +Current point becomes +.I "X+dx Y+dy." +.TP 10 +.BI poi " x y" +Plot the point +.I "x y" +and make it the current point. +.TP 10 +.BI v " x y" +Draw a vector from the current point to +.I "x y." +.TP 10 +.BI rv " dx dy" +Draw vector from current point to +.RI X + dx +.RI Y + dy +.TP 10 +.BI li " x1 y1 x2 y2" +Draw a line from +.I "x1 y1" +to +.I "x2 y2." +Make the current point +.I "x2 y2." +.TP 10 +.BI t " string" +Place the +.I string +so that its +first character is centered on the current point (default). +If +.I string +begins with +.L \eC +.RL ( \eR ), +it is centered (right-adjusted) on the current point. +A backslash at the beginning of the string may +be escaped with another backslash. +.TP 10 +.BI a " x1 y1 x2 y2 xc yc r" +Draw a circular arc from +.I "x1 y1" +to +.I "x2 y2" +with center +.I "xc yc" +and radius +.IR r . +If the radius is positive, the arc is drawn counterclockwise; +negative, clockwise. +The starting point is exact but the ending point is approximate. +.TP 10 +.BI ci " xc yc r" +Draw a circle centered at +.I "xc yc" +with radius +.IR r . +If the range and frame parameters do not specify a square, +the `circle' will be elliptical. +.TP 10 +.BI di " xc yc r" +Draw a disc centered at +.I "xc yc" +with radius +.I r +using the filling color (see +.B cfill +below). +.TP 10 +.BI bo " x1 y1 x2 y2" +Draw a box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2." +.TP 10 +.BI sb " x1 y1 x2 y2" +Draw a solid box with lower left corner at +.I "x1 y1" +and upper right corner at +.I "x2 y2" +using the filling color (see +.B cfill +below). +.TP 10 +.BI par " x1 y1 x2 y2 xg yg" +Draw a parabola from +.I "x1 y1" +to +.I "x2 y2" +`guided' by +.I "xg yg." +The parabola passes through the midpoint of the line joining +.I "xg yg" +with the midpoint of the line +joining +.I "x1 y1" +and +.I "x2 y2" +and is tangent to the lines from +.I "xg yg" +to the endpoints. +.TP 10 +.BI "pol { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Draw polygons with vertices +.I "x1 y1 ... xn yn" +and +.I "X1 Y1 ... Xm Ym." +If only one polygon is specified, the inner brackets are +not needed. +.TP 10 +.BI "fi { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI" +Fill a polygon. +The arguments are the same as those for +.B pol +except that the first vertex is automatically repeated to +close each polygon. +The polygons do not have to be connected. +Enclosed polygons appear as holes. +.TP 10 +.BI "sp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with simple endpoints. +.TP 10 +.BI "fsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double first endpoint. +.TP 10 +.BI "lsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double last endpoint. +.TP 10 +.BI "dsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +Draw a parabolic spline guided by +.I "x1 y1 ... xn yn" +with double endpoints. +.TP 10 +.BI "csp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI" +.TP 10 +.BI in " filename" +(include) Take commands from +.IR filename . +.TP 10 +.BI de " string " { " commands " } +Define +.I string +as +.IR commands . +.TP 10 +.BI ca " string scale" +Invoke commands defined as +.I string +applying +.I scale +to all coordinates. +.PD +.SS "Commands Controlling the Environment" +.PD0 +.TP 10 +.BI co " string" +Use color given by first character of +.IR string , +one of +.BR red , +.BR yellow , +.BR green , +.BR blue , +.BR cyan , +.BR magenta , +.BR white , +and +.BR kblack . +.TP 10 +.BI pe " string" +Use +.I string +as the style for drawing lines. +The available pen styles are: +.BR solid , +.BR dott [ed], +.BR short , +.BR long , +.BR dotd [ashed] , +.BR cdash , +.BR ddash +.TP 10 +.BI cf " string" +Color for filling (see +.BR co , +above). +.TP 10 +.BI ra " x1 y1 x2 y2" +The data will fall between +.I "x1 y1" +and +.I "x2 y2." +The plot will be magnified or reduced to fit +the device as closely as possible. +.IP +Range settings that exactly fill the plotting area +with unity scaling appear below for +devices supported by the filters of +.IR plot (1). +The upper limit is just outside the plotting area. +In every case the plotting area is taken to be square; +points outside may be displayable on +devices with nonsquare faces. +.TP 10 +.BI fr " px1 py1 px2 py2" +Plot the data in the fraction of the display +specified by +.I "px1 py1" +for lower left corner +and +.I "px2 py2" +for upper right corner. +Thus +.L frame .5 0 1. .5 +plots in the lower right +quadrant of the display; +.L frame 0. 1. 1. 0. +uses the whole display but +inverts the +.I y +coordinates. +.TP 10 +.B sa +Save the current environment, and move to a new one. +The new environment inherits the old one. +There are 7 levels. +.TP 10 +.B re +Restore previous environment. +.PD +.SH "SEE ALSO" +.IR plot (1), +.IR graph (1) diff --git a/man/man7/plumb.7 b/man/man7/plumb.7 new file mode 100644 index 00000000..a3c10e11 --- /dev/null +++ b/man/man7/plumb.7 @@ -0,0 +1,417 @@ +.TH PLUMB 7 +.SH NAME +plumb \- format of plumb messages and rules +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +.SS "Message format +The messages formed by the +.IR plumb (3) +library are formatted for transmission between +processes into textual form, using newlines to separate +the fields. +Only the data field may contain embedded newlines. +The fields occur in a specified order, +and each has a name, corresponding to the elements +of the +.B Plumbmsg +structure, that is used in the plumbing rules. +The fields, in order, are: +.RS +.TF ndata +.TP +.B src +application/service generating message +.TP +.B dst +destination `port' for message +.TP +.B wdir +working directory (used if data is a file name) +.TP +.B type +form of the data, e.g. +.B text +.TP +.B attr +attributes of the message, in +.IB name = value +pairs separated by white space +(the value must follow the usual quoting convention if it contains +white space or quote characters or equal signs; it cannot contain a newline) +.TP +.B ndata +number of bytes of data +.TP +.B data +the data itself +.RE +At the moment, only textual data +.RB ( type=text ) +is supported. +.PD +.PP +All fields are optional, but +.B type +should usually be set since it describes the form of the data, and +.B ndata +must be an accurate count (possibly zero) of the number of bytes of data. +A missing field is represented by an empty line. +.SS "Plumbing rules +The +.B plumber +(see +.IR plumb (1)) +receives messages on its +.B send +port (applications +.I send +messages there), interprets and reformats them, and (typically) emits them from a destination port. +Its behavior is determined by a plumbing rules file, default +.BR /usr/$user/lib/plumbing , +which defines a set of pattern/action rules with which to analyze, rewrite, and dispatch +received messages. +.PP +The file is a sequence of rule sets, each of which is a set of one-line rules +called patterns and actions. +There must be at least one pattern and one action in each rule set. +(The only exception is that a rule set may contain nothing but +.B plumb +.B to +rules; such a rule set declares the named ports but has no other effect.) +A blank line terminates a rule set. +Lines beginning with a +.B # +character are commentary and are regarded as blank lines. +.PP +A line of the form +.EX + include \f2file\fP +.EE +substitutes the contents of +.I file +for the line, much as in a C +.B #include +statement. Unlike in C, the file name is not quoted. +If +.I file +is not an absolute path name, or one beginning +.B ./ +or +.BR ../ , +.I file +is looked for first in the directory in which the plumber is executing, +and then in +.BR /sys/lib/plumb . +.PP +When a message is received by the +.BR plumber , +the rule sets are examined in order. +For each rule set, if the message matches all the patterns in the rule set, +the actions associated with the rule set are triggered to dispose of the message. +If a rule set is triggered, the rest are ignored for this message. +If none is triggered, the message is discarded (giving a write error to the sender) +unless it has a +.B dst +field that specifies an existing port, in which case the message is emitted, unchanged, from there. +.PP +Patterns and actions all consist of three components: an +.IR object , +a +.IR verb , +and arguments. +These are separated by white space on the line. +The arguments may contain quoted strings and variable substitutions, +described below, and in some cases contain multiple words. +The object and verb are single words from a pre-defined set. +.PP +The object in a pattern is the name of an element of the message, such as +.B src +or +.BR data , +or the special case +.BR arg , +which refers to the argument component of the current rule. +The object in an action is always the word +.BR plumb . +.PP +The verbs in the pattern rules +describe how the objects and arguments are to be interpreted. +Within a rule set, the patterns are evaluated in sequence; if one fails, +the rule set fails. +Some verbs are predicates that check properties of the message; others rewrite +components of the message and implicitly always succeed. +Such rewritings are permanent, so rules that specify them should be placed after +all pattern-matching rules in the rule set. +.RS +.TF delete +.TP +.B add +The object must be +.BR attr . +Append the argument, which must be a sequence of +.IB name = value +pairs, to the list of attributes of the message. +.TP +.B delete +The object must be +.BR attr . +If the message has an attribute whose name is the argument, +delete it from the list of attributes of the message. +(Even if the message does not, the rule matches the message.) +.TP +.B is +If the text of the object is identical to the text of the argument, +the rule matches. +.TP +.B isdir +If the text of the object +is the name of an existing directory, the rule matches and +sets the variable +.B $dir +to that directory name. +.TP +.B isfile +If the text of the object is the name of an existing file (not a directory), +the rule matches and sets the variable +.B $file +to that file name. +.TP +.B matches +If the entire text of the object matches the regular expression +specified in the argument, the rule matches. +This verb is described in more detail below. +.TP +.B set +The value of the object is set to the value of the argument. +.RE +.PP +The +.B matches +verb has special properties that enable the rules to select which portion of the +data is to be sent to the destination. +By default, a +.B data +.B matches +rule requires that the entire text matches the regular expression. +If, however, the message has an attribute named +.BR click , +that reports that the message was produced by a mouse click within the +text and that the regular expressions in the rule set should be used to +identify what portion of the data the user intended. +Typically, a program such as an editor will send a white-space delimited +block of text containing the mouse click, using the value of the +.B click +attribute (a number starting from 0) to indicate where in the textual data the user pointed. +.PP +When the message has a +.B click +attribute, the +.B data +.B matches +rules extract the longest leftmost match to the regular expression that contains or +abuts the textual location identified by the +.BR click . +For a sequence of such rules within a given rule set, each regular expression, evaluated +by this specification, must match the same subset of the data for the rule set to match +the message. +For example, here is a pair of patterns that identify a message whose data contains +the name of an existing file with a conventional ending for an encoded picture file: +.EX + data matches '[a-zA-Z0-9_\-./]+' + data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)' +.EE +The first expression extracts the largest subset of the data around the click that contains +file name characters; the second sees if it ends with, for example, +.BR \&.jpeg . +If only the second pattern were present, a piece of text +.B horse.gift +could be misinterpreted as an image file named +.BR horse.gif . +.PP +If a +.B click +attribute is specified in a message, it will be deleted by the +.B plumber +before sending the message if the +.B data +.B matches +rules expand the selection. +.PP +The action rules all have the object +.BR plumb . +There are only three verbs for action rules: +.RS +.TF client +.TP +.B to +The argument is the name of the port to which the message will be sent. +If the message has a destination specified, it must match the +.B to +port of the rule set or the entire rule set will be skipped. +(This is the only rule that is evaluated out of order.) +.TP +.B client +If no application has the port open, the arguments to a +.B plumb +.B start +rule specify a shell program to run in response to the message. +The message will be held, with the supposition that the program +will eventually open the port to retrieve it. +.TP +.B start +Like +.BR client , +but the message is discarded. +Only one +.B start +or +.B client +rule should be specified in a rule set. +.RE +.PP +The arguments to all rules may contain quoted strings, exactly as in +.IR rc (1). +They may also contain simple string variables, identified by a leading dollar sign +.BR $ . +Variables may be set, between rule sets, by assignment statements in the style of +.BR rc . +Only one variable assignment may appear on a line. +The +.B plumber +also maintains some built-in variables: +.RS +.TF $wdir +.TP +.B $0 +The text that matched the entire regular expression in a previous +.B data +.B matches +rule. +.BR $1 , +.BR $2 , +etc. refer to text matching the first, second, etc. parenthesized subexpression. +.TP +.B $attr +The textual representation of the attributes of the message. +.TP +.B $data +The contents of the data field of the message. +.TP +.B $dir +The directory name resulting from a successful +.B isdir +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $dst +The contents of the +.B dst +field of the message. +.TP +.B $file +The file name resulting from a successful +.B isfile +rule. +If no such rule has been applied, it is the string constructed +syntactically by interpreting +.B data +as a file name in +.BR wdir . +.TP +.B $type +The contents of the +.B type +field of the message. +.TP +.B $src +The contents of the +.B src +field of the message. +.TP +.B $wdir +The contents of the +.B wdir +field of the message. +.RE +.SH EXAMPLE +The following is a modest, representative file of plumbing rules. +.EX +# these are generally in order from most specific to least, +# since first rule that fires wins. + +addr=':(#?[0-9]+)' +protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)' +domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\e-]+' +file='([:.][a-zA-Z0-9_?,%#~&/\e-]+)*' + +# image files go to page +type is text +data matches '[a-zA-Z0-9_\e-./]+' +data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)' +arg isfile $0 +plumb to image +plumb start page -w $file + +# URLs go to web browser +type is text +data matches $protocol://$domain$file +plumb to web +plumb start window webbrowser $0 + +# existing files, possibly tagged by line number, go to edit/sam +type is text +data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?' +arg isfile $1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file + +# .h files are looked up in /sys/include and passed to edit/sam +type is text +data matches '([a-zA-Z0-9]+\e.h)('$addr')?' +arg isfile /sys/include/$1 +data set $file +attr add addr=$3 +plumb to edit +plumb start window sam $file +.EE +.PP +The following simple plumbing rules file is a good beginning set of rules. +.EX +# to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules + +editor = acme +# or editor = sam +include basic +.EE +.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). +.TP +.B /sys/lib/plumb +directory for +.B include +files. +.TP +.B /sys/lib/plumb/fileaddr +public macro definitions. +.TP +.B /sys/lib/plumb/basic +basic rule set. +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (3), +.IR plumber (4), +.IR regexp (7) diff --git a/man/man7/regexp.7 b/man/man7/regexp.7 index 14a90d0f..75640b9c 100644 --- a/man/man7/regexp.7 +++ b/man/man7/regexp.7 @@ -1,4 +1,4 @@ -.TH REGEXP9 7 +.TH REGEXP 7 .de EX .nf .ft B @@ -17,11 +17,11 @@ .if n .RB ` \\$1 ' .. .SH NAME -regexp9 \- Plan 9 regular expression notation +regexp \- Plan 9 regular expression notation .SH DESCRIPTION This manual page describes the regular expression syntax used by the Plan 9 regular expression library -.IR regexp9 (3). +.IR regexp (3). It is the form used by .IR egrep (1) before @@ -147,4 +147,4 @@ A match to any part of a regular expression extends as far as possible without preventing a match to the remainder of the regular expression. .SH "SEE ALSO" -.IR regexp9 (3) +.IR regexp (3) diff --git a/man/man7/regexp9.7 b/man/man7/regexp9.7 new file mode 100644 index 00000000..14a90d0f --- /dev/null +++ b/man/man7/regexp9.7 @@ -0,0 +1,150 @@ +.TH REGEXP9 7 +.de EX +.nf +.ft B +.. +.de EE +.fi +.ft R +.. +.de LR +.if t .BR \\$1 \\$2 +.if n .RB ` \\$1 '\\$2 +.. +.de L +.nh +.if t .B \\$1 +.if n .RB ` \\$1 ' +.. +.SH NAME +regexp9 \- Plan 9 regular expression notation +.SH DESCRIPTION +This manual page describes the regular expression +syntax used by the Plan 9 regular expression library +.IR regexp9 (3). +It is the form used by +.IR egrep (1) +before +.I egrep +got complicated. +.PP +A +.I "regular expression" +specifies +a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. In many applications +a delimiter character, commonly +.LR / , +bounds a regular expression. +In the following specification for regular expressions +the word `character' means any character (rune) but newline. +.PP +The syntax for a regular expression +.B e0 +is +.IP +.EX +e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')' + +e2: e3 + | e2 REP + +REP: '*' | '+' | '?' + +e1: e2 + | e1 e2 + +e0: e1 + | e0 '|' e1 +.EE +.PP +A +.B literal +is any non-metacharacter, or a metacharacter +(one of +.BR .*+?[]()|\e^$ ), +or the delimiter +preceded by +.LR \e . +.PP +A +.B charclass +is a nonempty string +.I s +bracketed +.BI [ \|s\| ] +(or +.BI [^ s\| ]\fR); +it matches any character in (or not in) +.IR s . +A negated character class never +matches newline. +A substring +.IB a - b\f1, +with +.I a +and +.I b +in ascending +order, stands for the inclusive +range of +characters between +.I a +and +.IR b . +In +.IR s , +the metacharacters +.LR - , +.LR ] , +an initial +.LR ^ , +and the regular expression delimiter +must be preceded by a +.LR \e ; +other metacharacters +have no special meaning and +may appear unescaped. +.PP +A +.L . +matches any character. +.PP +A +.L ^ +matches the beginning of a line; +.L $ +matches the end of the line. +.PP +The +.B REP +operators match zero or more +.RB ( * ), +one or more +.RB ( + ), +zero or one +.RB ( ? ), +instances respectively of the preceding regular expression +.BR e2 . +.PP +A concatenated regular expression, +.BR "e1\|e2" , +matches a match to +.B e1 +followed by a match to +.BR e2 . +.PP +An alternative regular expression, +.BR "e0\||\|e1" , +matches either a match to +.B e0 +or a match to +.BR e1 . +.PP +A match to any part of a regular expression +extends as far as possible without preventing +a match to the remainder of the regular expression. +.SH "SEE ALSO" +.IR regexp9 (3) diff --git a/man/man7/thumbprint.7 b/man/man7/thumbprint.7 new file mode 100644 index 00000000..743172de --- /dev/null +++ b/man/man7/thumbprint.7 @@ -0,0 +1,41 @@ +.TH THUMBPRINT 7 +.SH NAME +thumbprint \- public key thumbprints +.SH DESCRIPTION +.PP +Applications in Plan 9 that use public keys for authentication, +for example by calling +.B tlsClient +and +.B okThumbprint +(see +.IR pushtls (3)), +check the remote side's public key by comparing against +thumbprints from a trusted list. +The list is maintained by people who set local policies +about which servers can be trusted for which applications, +thereby playing the role taken by certificate authorities +in PKI-based systems. +By convention, these lists are stored as files in +.B /sys/lib/tls/ +and protected by normal file system permissions. +.PP +Such a thumbprint file comprises lines made up of +attribute/value pairs of the form +.IB attr = value +or +.IR attr . +The first attribute must be +.B x509 +and the second must be +.BI sha1= {hex checksum of binary certificate}. +All other attributes are treated as comments. +The file may also contain lines of the form +.BI #include file +.PP +For example, a web server might have thumbprint +.EX +x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell-labs.com +.EE +.SH "SEE ALSO" +.IR pushtls (3) diff --git a/man/man7/utf.7 b/man/man7/utf.7 index 97b7b1e7..a2409457 100644 --- a/man/man7/utf.7 +++ b/man/man7/utf.7 @@ -57,7 +57,7 @@ in order to work properly with non-\c .SM ASCII input. See -.IR rune (2). +.IR rune (3). .PP Letting numbers be binary, a rune x is converted to a multibyte diff --git a/man/man8/INDEX b/man/man8/INDEX new file mode 100644 index 00000000..9ca1d026 --- /dev/null +++ b/man/man8/INDEX @@ -0,0 +1,2 @@ +dump9660 mk9660.8 +mk9660 mk9660.8 diff --git a/man/man8/mk9660.8 b/man/man8/mk9660.8 new file mode 100644 index 00000000..85edf2df --- /dev/null +++ b/man/man8/mk9660.8 @@ -0,0 +1,233 @@ +.TH MK9660 8 +.SH NAME +dump9660, mk9660 \- create an ISO-9660 CD image +.SH SYNOPSIS +.B disk/mk9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -b +.I bootfile +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +.I image +.PP +.B disk/dump9660 +[ +.B -:D +] +[ +.B -9cjr +] +[ +.B -p +.I proto +] +[ +.B -s +src +] +[ +.B -v +volume +] +[ +.B -m +.I maxsize +] +[ +.B -n +.I now +] +.I image +.SH DESCRIPTION +.I Mk9660 +writes to the random access file +.I image +an ISO-9660 CD image containing the +files named in +.I proto +(by default, +.BR /sys/lib/sysconfig/proto/allproto ) +from the file tree +.I src +(by default, +the current directory). +The +.I proto +file is formatted as described in +.IR proto (3). +.PP +The created CD image will be in ISO-9660 +format, but by default the file names will +be stored in UTF-8 with no imposed length +or character restrictions. +The +.B -c +flag causes +.I mk9660 +to use only file names in ``8.3'' form +that use digits, letters, and underscore. +File names that do not conform are changed +to +.BI D nnnnnn +(for directories) +or +.BI F nnnnnn +(for files); +a key file +.B _CONFORM.MAP +is created in the root +directory to ease the reverse process. +.PP +If the +.B -9 +flag is given, the system use fields at the end of +each directory entry will be populated with +Plan directory information (owner, group, mode, +full name); this is interpreted by +.IR 9660srv . +.PP +If the +.B -j +flag is given, the usual directory tree is written, +but an additional tree in Microsoft Joliet format is +also added. +This second tree can contain long Unicode file names, +and can be read by +.I 9660srv +as well as most versions of Windows +and many Unix clones. +The characters +.BR * , +.BR : , +.BR ; , +.BR ? , +and +.B \e +are allowed in Plan 9 file names but not in Joliet file names; +non-conforming file names are translated +and a +.B _CONFORM.MAP +file written +as in the case of the +.B -c +option. +.PP +If the +.B -r +flag is given, Rock Ridge extensions are written in the +format of the system use sharing protocol; +this format provides Posix-style file metadata and is +common on Unix platforms. +.PP +The options +.BR -c , +.BR -9 , +.BR -j , +and +.B -r +may be mixed freely with the exception that +.B -9 +and +.B -r +are mutually exclusive. +.PP +The +.B -v +flag sets the volume title; +if unspecified, the base name of +.I proto +is used. +.PP +The +.B -: +flag causes +.B mk9660 +to replace colons in scanned file names with spaces; +this is the inverse of the map applied by Plan 9's +\fIdossrv\fR(4) +and is useful for writing Joliet CDs containing data +from FAT file systems. +.PP +The +.B -b +option creates a bootable CD. +Bootable CDs contain pointers to floppy images which are +loaded and booted by the BIOS. +.I Bootfile +should be the name of the floppy image to use; +it is a path relative to the root of the created CD. +That is, the boot floppy image must be listed in the +.I proto +file already: +the +.B -b +flag just creates a pointer to it. +.PP +The +.B -D +flag creates immense amounts of debugging output +on standard error. +.PP +.I Dump9660 +is similar in specification to +.I mk9660 +but creates and updates backup CD images in the style of +the +.I dump +file system +(see Plan 9's \fIfs\fR(4)). +The dump is file-based rather than block-based: +if a file's contents have not changed since the last +backup, only its directory entry will be rewritten. +.PP +The +.B -n +option specifies a time (in seconds since January 1, 1970) +to be used for naming the dump directory. +.PP +The +.B -m +option specifies a maximum size for the image; +if a backup would cause the image to grow larger than +.IR maxsize , +it will not be written, and +.I dump9660 +will exit with a non-empty status. +.SH EXAMPLE +.PP +Create an image of the Plan 9 source tree, +including a conformant ISO-9660 directory tree, +Plan 9 extensions in the system use fields, and +a Joliet directory tree. +.IP +.EX +disk/mk9660 -9cj -s /n/bootes \e + -p /sys/lib/sysconfig/srcproto cdimage +.EE +.SH SOURCE +/usr/local/plan9/src/cmd/9660 +.SH "SEE ALSO +.IR proto (3) +.\" .SH "SEE ALSO" +.\" .I 9660srv +.\" (in +.\" .IR dossrv (4)), +.\" .IR cdfs (4), +.\" .IR proto (3) diff --git a/man/man9/0intro.9p b/man/man9/0intro.9p new file mode 100644 index 00000000..397486f8 --- /dev/null +++ b/man/man9/0intro.9p @@ -0,0 +1,630 @@ +.TH INTRO 9P +.SH NAME +intro \- introduction to the Plan 9 File Protocol, 9P +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +A Plan 9 +.I server +is an agent that provides one or more hierarchical file systems +\(em file trees \(em +that may be accessed by Plan 9 processes. +A server responds to requests by +.I clients +to navigate the hierarchy, +and to create, remove, read, and write files. +The prototypical server is a separate machine that stores +large numbers of user files on permanent media; +such a machine is called, somewhat confusingly, a +.I file +.IR server . +Another possibility for a server is to synthesize +files on demand, perhaps based on information on data structures +maintained in memory; the +.IR plumber (4) +server is an example of such a server. +.PP +A +.I connection +to a server is a bidirectional communication path from the client to the server. +There may be a single client or +multiple clients sharing the same connection. +.PP +The +.IR "Plan 9 File Protocol" , +9P, is used for messages between +.I clients +and +.IR servers . +A client transmits +.I requests +.RI ( T-messages ) +to a server, which +subsequently returns +.I replies +.RI ( R-messages ) +to the client. +The combined acts of transmitting (receiving) a request of a particular type, +and receiving (transmitting) +its reply is called a +.I transaction +of that type. +.PP +Each message consists of a sequence of bytes. +Two-, four-, and eight-byte fields hold unsigned +integers represented in little-endian order +(least significant byte first). +Data items of larger or variable lengths are represented +by a two-byte field specifying a count, +.IR n , +followed by +.I n +bytes of data. +Text strings are represented this way, +with the text itself stored as a UTF-8 +encoded sequence of Unicode characters (see +.IR utf (7)). +Text strings in 9P messages are not +.SM NUL\c +-terminated: +.I n +counts the bytes of UTF-8 data, which include no final zero byte. +The +.SM NUL +character is illegal in all text strings in 9P, and is therefore +excluded from file names, user names, and so on. +.PP +Each 9P message begins with a four-byte size field +specifying the length in bytes of the complete message including +the four bytes of the size field itself. +The next byte is the message type, one of the constants +in the enumeration in the include file +.BR . +The next two bytes are an identifying +.IR tag , +described below. +The remaining bytes are parameters of different sizes. +In the message descriptions, the number of bytes in a field +is given in brackets after the field name. +The notation +.IR parameter [ n ] +where +.I n +is not a constant represents a variable-length parameter: +.IR n [2] +followed by +.I n +bytes of data forming the +.IR parameter . +The notation +.IR string [ s ] +(using a literal +.I s +character) +is shorthand for +.IR s [2] +followed by +.I s +bytes of UTF-8 text. +(Systems may choose to reduce the set of legal characters +to reduce syntactic problems, +for example to remove slashes from name components, +but the protocol has no such restriction. +Plan 9 names may contain any printable character (that is, any character +outside hexadecimal 00-1F and 80-9F) +except slash.) +Messages are transported in byte form to allow for machine independence; +.IR fcall (3) +describes routines that convert to and from this form into a machine-dependent +C structure. +.SH MESSAGES +.ta \w'\fLTsession 'u +.IP +.ne 2v +.IR size [4] +.B Tversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.br +.IR size [4] +.B Rversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.IP +.ne 2v +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.IP +.ne 2v +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.IP +.ne 2v +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.IP +.ne 2v +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( wqid [13]) +.IP +.ne 2v +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Topenfd +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropenfd +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IR unixfd [4] +.IP +.ne 2v +.IR size [4] +.B Tcreate +.IR tag [2] +.IR fid [4] +.IR name [ s ] +.IR perm [4] +.IR mode [1] +.br +.IR size [4] +.B Rcreate +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Tread +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.br +.IR size [4] +.B Rread +.IR tag [2] +.IR count [4] +.IR data [ count ] +.IP +.ne 2v +.IR size [4] +.B Twrite +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.IR data [ count ] +.br +.IR size [4] +.B Rwrite +.IR tag [2] +.IR count [4] +.IP +.ne 2v +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.IP +.ne 2v +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.PP +Each T-message has a +.I tag +field, chosen and used by the client to identify the message. +The reply to the message will have the same tag. +Clients must arrange that no two outstanding messages +on the same connection have the same tag. +An exception is the tag +.BR NOTAG , +defined as +.B (ushort)~0 +in +.BR : +the client can use it, when establishing a connection, +to +override tag matching in +.B version +messages. +.PP +The type of an R-message will either be one greater than the type +of the corresponding T-message or +.BR Rerror , +indicating that the request failed. +In the latter case, the +.I ename +field contains a string describing the reason for failure. +.PP +The +.B version +message identifies the version of the protocol and indicates +the maximum message size the system is prepared to handle. +It also initializes the connection and +aborts all outstanding I/O on the connection. +The set of messages between +.B version +requests is called a +.IR session . +.PP +Most T-messages contain a +.IR fid , +a 32-bit unsigned integer that the client uses to identify +a ``current file'' on the server. +Fids are somewhat like file descriptors in a user process, +but they are not restricted to files open for I/O: +directories being examined, files being accessed by +.IR stat (3) +calls, and so on \(em all files being manipulated by the operating +system \(em are identified by fids. +Fids are chosen by the client. +All requests on a connection share the same fid space; +when several clients share a connection, +the agent managing the sharing must arrange +that no two clients choose the same fid. +.PP +The fid supplied in an +.B attach +message +will be taken by the server to refer to the root of the served file tree. +The +.B attach +identifies the user +to the server and may specify a particular file tree served +by the server (for those that supply more than one). +.PP +Permission to attach to the service is proven by providing a special fid, called +.BR afid , +in the +.B attach +message. This +.B afid +is established by exchanging +.B auth +messages and subsequently manipulated using +.B read +and +.B write +messages to exchange authentication information not defined explicitly by 9P. +Once the authentication protocol is complete, the +.B afid +is presented in the +.B attach +to permit the user to access the service. +.PP +A +.B walk +message causes the server to change the current file associated +with a fid to be a file in the directory that is the old current file, or one of +its subdirectories. +.B Walk +returns a new fid that refers to the resulting file. +Usually, a client maintains a fid for the root, +and navigates by +.B walks +from the root fid. +.PP +A client can send multiple T-messages without waiting for the corresponding +R-messages, but all outstanding T-messages must specify different tags. +The server may delay the response to a request +and respond to later ones; +this is sometimes necessary, for example when the client reads +from a file that the server synthesizes from external events +such as keyboard characters. +.PP +Replies (R-messages) to +.BR auth , +.BR attach , +.BR walk , +.BR open , +and +.B create +requests convey a +.I qid +field back to the client. +The qid represents the server's unique identification for the +file being accessed: +two files on the same server hierarchy are the same if and only if their qids +are the same. +(The client may have multiple fids pointing to a single file on a server +and hence having a single qid.) +The thirteen-byte qid fields hold a one-byte type, +specifying whether the file is a directory, append-only file, etc., +and two unsigned integers: +first the four-byte qid +.IR version , +then the eight-byte qid +.IR path . +The path is an integer unique among all files in the hierarchy. +If a file is deleted and recreated with the +same name in the same directory, the old and new path components of the qids +should be different. +The version is a version number for a file; +typically, it is incremented every time the file is modified. +.PP +An existing file can be +.BR opened , +or a new file may be +.B created +in the current (directory) file. +I/O of a given number of bytes +at a given offset +on an open file is done by +.B read +and +.BR write . +.PP +A client should +.B clunk +any fid that is no longer needed. +The +.B remove +transaction deletes files. +.PP +.B Openfd +is an extension used by Unix utilities to allow traditional Unix programs +to have their input or output attached to fids on 9P servers. +See +.IR openfd (9p) +and +.IR 9pclient (3) +for details. +.PP +The +.B stat +transaction retrieves information about the file. +The +.I stat +field in the reply includes the file's +name, +access permissions (read, write and execute for owner, group and public), +access and modification times, and +owner and group identifications +(see +.IR stat (3)). +The owner and group identifications are textual names. +The +.B wstat +transaction allows some of a file's properties +to be changed. +.PP +A request can be aborted with a +flush +request. +When a server receives a +.BR Tflush , +it should not reply to the message with tag +.I oldtag +(unless it has already replied), +and it should immediately send an +.BR Rflush . +The client must wait +until it gets the +.B Rflush +(even if the reply to the original message arrives in the interim), +at which point +.I oldtag +may be reused. +.PP +Because the message size is negotiable and some elements of the +protocol are variable length, it is possible (although unlikely) to have +a situation where a valid message is too large to fit within the negotiated size. +For example, a very long file name may cause a +.B Rstat +of the file or +.B Rread +of its directory entry to be too large to send. +In most such cases, the server should generate an error rather than +modify the data to fit, such as by truncating the file name. +The exception is that a long error string in an +.B Rerror +message should be truncated if necessary, since the string is only +advisory and in some sense arbitrary. +.PP +Most programs do not see the 9P protocol directly; +on Plan 9, calls to library +routines that access files are +translated by the kernel's mount driver +into 9P messages. +.SS Unix +On Unix, 9P services are posted as Unix domain sockets in a +well-known directory (see +.IR getns (3) +and +.IR 9pserve (4)). +Clients connect to these servers using a 9P client library +(see +.IR 9pclient (3)). +.SH DIRECTORIES +Directories are created by +.B create +with +.B DMDIR +set in the permissions argument (see +.IR stat (9P)). +The members of a directory can be found with +.IR read (9P). +All directories must support +.B walks +to the directory +.B .. +(dot-dot) +meaning parent directory, although by convention directories +contain no explicit entry for +.B .. +or +.B . +(dot). +The parent of the root directory of a server's tree is itself. +.SH "ACCESS PERMISSIONS" +This section describes the access permission conventions +implemented by most Plan 9 file servers. These conventions +are not enforced by the protocol and may differ between servers, +especially servers built on top of foreign operating systems. +.PP +Each file server maintains a set of user and group names. +Each user can be a member of any number of groups. +Each group has a +.I group leader +who has special privileges (see +.IR stat (9P) +and +Plan 9's \fIusers\fR(6)). +Every file request has an implicit user id (copied from the original +.BR attach ) +and an implicit set of groups (every group of which the user is a member). +.PP +Each file has an associated +.I owner +and +.I group +id and +three sets of permissions: +those of the owner, those of the group, and those of ``other'' users. +When the owner attempts to do something to a file, the owner, group, +and other permissions are consulted, and if any of them grant +the requested permission, the operation is allowed. +For someone who is not the owner, but is a member of the file's group, +the group and other permissions are consulted. +For everyone else, the other permissions are used. +Each set of permissions says whether reading is allowed, +whether writing is allowed, and whether executing is allowed. +A +.B walk +in a directory is regarded as executing the directory, +not reading it. +Permissions are kept in the low-order bits of the file +.IR mode : +owner read/write/execute permission represented as 1 in bits 8, 7, and 6 +respectively (using 0 to number the low order). +The group permissions are in bits 5, 4, and 3, +and the other permissions are in bits 2, 1, and 0. +.PP +The file +.I mode +contains some additional attributes besides the permissions. +If bit 31 +.RB ( DMDIR ) +is set, the file is a directory; +if bit 30 +.RB ( DMAPPEND ) +is set, the file is append-only (offset is ignored in writes); +if bit 29 +.RB ( DMEXCL ) +is set, the file is exclusive-use (only one client may have it +open at a time); +if bit 27 +.RB ( DMAUTH ) +is set, the file is an authentication file established by +.B auth +messages; +if bit 26 +.RB ( DMTMP ) +is set, the contents of the file (or directory) are not included in nightly archives. +(Bit 28 is skipped for historical reasons.) +These bits are reproduced, from the top bit down, in the type byte of the Qid: +.BR QTDIR , +.BR QTAPPEND , +.BR QTEXCL , +(skipping one bit) +.BR QTAUTH , +and +.BR QTTMP . +The name +.BR QTFILE , +defined to be zero, +identifies the value of the type for a plain file. diff --git a/man/man9/INDEX b/man/man9/INDEX new file mode 100644 index 00000000..2e331bf0 --- /dev/null +++ b/man/man9/INDEX @@ -0,0 +1,16 @@ +0intro 0intro.9p +intro 0intro.9p +attach attach.9p +auth attach.9p +clunk clunk.9p +error error.9p +flush flush.9p +create open.9p +open open.9p +read read.9p +write read.9p +remove remove.9p +stat stat.9p +wstat stat.9p +version version.9p +walk walk.9p diff --git a/man/man9/attach.9p b/man/man9/attach.9p new file mode 100644 index 00000000..ddcf7476 --- /dev/null +++ b/man/man9/attach.9p @@ -0,0 +1,168 @@ +.TH ATTACH 9P +.SH NAME +attach, auth \- messages to establish a connection +.SH SYNOPSIS +.ta \w'\fLTauth 'u +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.PP +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.SH DESCRIPTION +.PP +The +.B attach +message serves as a fresh introduction from a user on +the client machine to the server. +The message identifies the user +.RI ( uname ) +and may select +the file tree to access +.RI ( aname ). +The +.I afid +argument specifies a fid previously established by an +.B auth +message, as described below. +.PP +As a result of the +.B attach +transaction, the client will have a connection to the root +directory of the desired file tree, +represented by +.IR fid . +An error is returned if +.I fid +is already in use. +The server's idea of the root of the file tree is represented by the returned +.IR qid . +.PP +If the client does not wish to authenticate the connection, or knows that +authentication is not required, the +.I afid +field in the +.B attach +message should be set to +.BR NOFID , +defined as +.B (u32int)~0 +in +.BR . +If the client does wish to authenticate, it must acquire and validate an +.I afid +using an +.B auth +message before doing the +.BR attach . +.PP +The +.B auth +message contains +.IR afid , +a new fid to be established for authentication, and the +.I uname +and +.I aname +that will be those of the following +.B attach +message. +If the server does not require authentication, it returns +.B Rerror +to the +.B Tauth +message. +.PP +If the server does require authentication, it returns +.I aqid +defining a file of type +.B QTAUTH +(see +.IR intro (9P)) +that may be read and written (using +.B read +and +.B write +messages in the usual way) to execute an authentication protocol. +That protocol's definition is not part of 9P itself. +.PP +Once the protocol is complete, the same +.I afid +is presented in the +.B attach +message for the user, granting entry. +The same validated +.I afid +may be used for multiple +.B attach +messages with the same +.I uname +and +.IR aname . +.SH ENTRY POINTS +.I Fsmount +and +.I fsauth +(see +.IR 9pclient (3)) +generate +.B attach +and +.B auth +transactions. +.\" An +.\" .B attach +.\" transaction will be generated for kernel devices +.\" (see +.\" .IR intro (3)) +.\" when a system call evaluates a file name +.\" beginning with +.\" .LR # . +.\" .IR Pipe (2) +.\" generates an attach on the kernel device +.\" .IR pipe (3). +.\" The +.\" .I mount +.\" system call +.\" (see +.\" .IR bind (2)) +.\" generates an +.\" .B attach +.\" message to the remote file server. +.\" When the kernel boots, an +.\" .I attach +.\" is made to the root device, +.\" .IR root (3), +.\" and then an +.\" .B attach +.\" is made to the requested file server machine. +.\" .PP +.\" An +.\" .B auth +.\" transaction is generated by the +.\" .IR fauth (2) +.\" system call or by the first +.\" .B mount +.\" system call on an uninitialized connection. +.SH SEE ALSO +.IR 9pclient (3), +.IR version (9P), +Plan 9's \fIauthsrv\fR(6) diff --git a/man/man9/clunk.9p b/man/man9/clunk.9p new file mode 100644 index 00000000..ef3ecdc4 --- /dev/null +++ b/man/man9/clunk.9p @@ -0,0 +1,55 @@ +.TH CLUNK 9P +.SH NAME +clunk \- forget about a fid +.SH SYNOPSIS +.ta \w'\fLTclunk 'u +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.SH DESCRIPTION +The +.B clunk +request informs the file server +that the current file represented by +.I fid +is no longer needed by the client. +The actual file is not removed on the server unless the fid had been opened with +.BR ORCLOSE . +.PP +Once a fid has been clunked, +the same fid can be reused in a new +.B walk +or +.B attach +request. +.PP +Even if the +.B clunk +returns an error, the +.I fid +is no longer valid. +.SH ENTRY POINTS +.B Clunk +transactions are +generated by +.I fsclose +and +.I fsunmount +(see +.IR 9pclient (3)) +and indirectly by other actions such as failed +.I fsopen +calls. +.\" +.\" A +.\" .B clunk +.\" message is generated by +.\" .I close +.\" and indirectly by other actions such as failed +.\" .I open +.\" calls. diff --git a/man/man9/error.9p b/man/man9/error.9p new file mode 100644 index 00000000..6380f64f --- /dev/null +++ b/man/man9/error.9p @@ -0,0 +1,28 @@ +.TH ERROR 9P +.SH NAME +error \- return an error +.SH SYNOPSIS +.ta \w'\fLRerror 'u +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.SH DESCRIPTION +The +.B Rerror +message +(there is no +.BR Terror ) +is used to return an error string +describing the +failure of a transaction. +It replaces the corresponding reply message +that would accompany a successful call; its tag is that +of the failing request. +.PP +By convention, clients may truncate error messages after +.B ERRMAX-1 +bytes; +.B ERRMAX +is defined in +.BR . diff --git a/man/man9/flush.9p b/man/man9/flush.9p new file mode 100644 index 00000000..9d3ea267 --- /dev/null +++ b/man/man9/flush.9p @@ -0,0 +1,109 @@ +.TH FLUSH 9P +.SH NAME +flush \- abort a message +.SH SYNOPSIS +.ta \w'\fLTflush 'u +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.SH DESCRIPTION +When the response to a request is no longer needed, such as when +a user interrupts a process doing a +.IR read (9p), +a +.B Tflush +request is sent to the server to purge the pending response. +The message being flushed is identified by +.IR oldtag . +The semantics of +.B flush +depends on messages arriving in order. +.PP +The server should answer the +.B flush +message immediately. +If it recognizes +.I oldtag +as the tag of a pending transaction, it should abort any pending response +and discard that tag. +In either case, it should respond with an +.B Rflush +echoing the +.I tag +(not +.IR oldtag ) +of the +.B Tflush +message. +A +.B Tflush +can never be responded to by an +.B Rerror +message. +.PP +The server may respond to the pending request before +responding to the +.BR Tflush . +It is possible for a client to send multiple +.B Tflush +messages for a particular pending request. Each +subsequent +.B Tflush +must contain as +.I oldtag +the tag of the pending request (not a previous +.BR Tflush ). +Should multiple +.BR Tflush es +be received for a pending request, they must be answered in +order. A +.B Rflush +for any of the multiple +.BR Tflush es +implies an answer for all previous ones. Therefore, should +a server receive a request and then multiple flushes for that +request, it need respond only to the last flush. +.PP +When the client sends a +.BR Tflush , +it must wait to receive the corresponding +.B Rflush +before reusing +.I oldtag +for subsequent messages. +If a response to the flushed request is received before the +.BR Rflush , +the client must honor the response +as if it had not been flushed, +since the completed request may signify a state change in the server. +For instance, +.B Tcreate +may have created a file and +.B Twalk +may have allocated a fid. +If no response is received before the +.BR Rflush , +the flushed transaction is considered to have been canceled, +and should be treated as though it had never been sent. +.PP +Several exceptional conditions are handled correctly by the above specification: +sending multiple flushes for a single tag, +flushing after a transaction is completed, +flushing a +.BR Tflush , +and flushing an invalid tag. +.SH ENTRY POINTS +The +.IR 9pclient (3) +library does not generate +.B flush +transactions.. +.IR 9pserve (4) +generates +.B flush +transactions to cancel transactions pending when a client hangs up. diff --git a/man/man9/open.9p b/man/man9/open.9p new file mode 100644 index 00000000..b8ed973a --- /dev/null +++ b/man/man9/open.9p @@ -0,0 +1,249 @@ +.TH OPEN 9P +.SH NAME +open, create \- prepare a fid for I/O on an existing or new file +.SH SYNOPSIS +.ta \w'\fLTcreate 'u +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.PP +.IR size [4] +.B Tcreate +.IR tag [2] +.IR fid [4] +.IR name [ s ] +.IR perm [4] +.IR mode [1] +.br +.IR size [4] +.B Rcreate +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.SH DESCRIPTION +The +.B open +request asks the file server to check permissions and +prepare a fid for I/O with subsequent +.B read +and +.B write +messages. +The +.I mode +field determines the type of I/O: +0 +(called +.BR OREAD +in +.BR ), +1 +.RB ( OWRITE ), +2 +.RB ( ORDWR ), +and 3 +.RB ( OEXEC ) +mean +.I +read access, write access, read and write access, +and +.I +execute access, +to be checked against the permissions for the file. +In addition, if +.I mode +has the +.B OTRUNC +.RB ( 0x10 ) +bit set, +the file is to be truncated, which requires write permission +(if +the file is append-only, and permission is granted, the +.B open +succeeds but the file will not be truncated); +if the +.I mode +has the +.B ORCLOSE +.RB ( 0x40 ) +bit set, the file is to be removed when the fid +is clunked, which requires permission to remove the file from its directory. +All other bits in +.I mode +should be zero. +It is illegal to write a directory, truncate it, or attempt to remove it on close. +If the file is marked for exclusive use (see +.IR stat (9P)), +only one client can have the file open at any time. +That is, after such a file has been opened, +further opens will fail until +.I fid +has been clunked. +All these permissions are checked at the time of the +.B open +request; subsequent changes to the permissions of files do not affect +the ability to read, write, or remove an open file. +.PP +The +.B create +request asks the file server to create a new file +with the +.I name +supplied, in the directory +.RI ( dir ) +represented by +.IR fid , +and requires write permission in the directory. +The owner of the file is the implied user id of the request, +the group of the file is the same as +.IR dir , +and the permissions are the value of +.ce +.B "perm & (~0666 | (dir.perm & 0666))" +if a regular file is being created and +.ce +.B "perm & (~0777 | (dir.perm & 0777))" +if a directory is being created. +This means, for example, that if the +.B create +allows read permission to others, but the containing directory +does not, then the created file will not allow others to read the file. +.PP +Finally, the newly created file is opened according to +.IR mode , +and +.I fid +will represent the newly opened file. +.I Mode +is not checked against the permissions in +.IR perm . +The +.I qid +for the new file is returned with the +.B create +reply message. +.PP +Directories are created by setting the +.B DMDIR +bit +.RB ( 0x80000000 ) +in the +.IR perm . +.PP +The names +.B . +and +.B .. +are special; it is illegal to create files with these names. +.PP +It is an error for either of these messages if the fid +is already the product of a successful +.B open +or +.B create +message. +.PP +An attempt to +.B create +a file in a directory where the given +.I name +already exists will be rejected; +in this case, the +.I fscreate +call +(see +.IR 9pclient (3)) +uses +.B open +with truncation. +The algorithm used by the +.IR create +system call +is: +first walk to the directory to contain the file. +If that fails, return an error. +Next +.B walk +to the specified file. +If the +.B walk +succeeds, send a request to +.B open +and truncate the file and return the result, successful or not. +If the +.B walk +fails, send a create message. +If that fails, it may be because the file was created by another +process after the previous walk failed, so (once) try the +.B walk +and +.B open +again. +.\" .PP +.\" For the behavior of +.\" .I create +.\" on a union directory, see +.\" .IR bind (2). +.\" .PP +.\" The +.\" .B iounit +.\" field returned by +.\" .B open +.\" and +.\" .B create +.\" may be zero. +.\" If it is not, it is the maximum number of bytes that are guaranteed to +.\" be read from or written to the file without breaking the I/O transfer +.\" into multiple 9P messages; see +.\" .IR read (9P). +.SH ENTRY POINTS +.I Fsopen +and +.I fscreate +(see +.IR 9pclient (3)) +both generate +.B open +messages; only +.I fscreate +generates a +.B create +message. +The +.B iounit +associated with an open file may be discovered by calling +.IR fsiounit . +.PP +For programs that need atomic file creation, without the race +that exists in the +.B open-create +sequence described above, +.IR fscreate +does the following. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.I fscreate +call, +the +.B open +message is not sent; the kernel issues only the +.BR create . +Thus, if the file exists, +.I fscreate +will draw an error, but if it doesn't and the +.I fscreate +call succeeds, the process issuing the +.I fscreate +is guaranteed to be the one that created the file. diff --git a/man/man9/read.9p b/man/man9/read.9p new file mode 100644 index 00000000..a68f153e --- /dev/null +++ b/man/man9/read.9p @@ -0,0 +1,126 @@ +.TH READ 9P +.SH NAME +read, write \- transfer data from and to a file +.SH SYNOPSIS +.ta \w'\fLTwrite 'u +.IR size [4] +.B Tread +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.br +.IR size [4] +.B Rread +.IR tag [2] +.IR count [4] +.IR data [ count ] +.PP +.IR size [4] +.B Twrite +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.IR data [ count ] +.br +.IR size [4] +.B Rwrite +.IR tag [2] +.IR count [4] +.SH DESCRIPTION +The +.B read +request +asks for +.I count +bytes of data +from the file identified by +.IR fid , +which must be opened for reading, +starting +.I offset +bytes after the beginning of the file. +The bytes are returned with the +.B read +reply message. +.PP +The +.I count +field in the reply indicates the number of bytes returned. +This may be less than the requested amount. +If the +.I offset +field is greater than or equal to the number of bytes in the file, +a count of zero will be returned. +.PP +For directories, +.B read +returns an integral number of +directory entries exactly as in +.B stat +(see +.IR stat (9P)), +one for each member of the directory. +The +.B read +request message must have +.B offset +equal to zero or the value of +.B offset +in the previous +.B read +on the directory, plus the number of bytes +returned in the previous +.BR read . +In other words, seeking other than to the beginning +is illegal in a directory. +.PP +The +.B write +request asks that +.I count +bytes of data be recorded in the file identified by +.IR fid , +which must be opened for writing, starting +.I offset +bytes after the beginning of the file. +If the file is append-only, +the data will be placed at the end of the file regardless of +.IR offset . +Directories may not be written. +.PP +The +.B write +reply records the number of bytes actually written. +It is usually an error +if this is not the same as requested. +.PP +Because 9P implementations may limit the size of individual +messages, +more than one message may be produced by a single +.I read +or +.I write +call. +The +.I iounit +field returned by +.IR open (9P), +if non-zero, reports the maximum size that is guaranteed +to be transferred atomically. +.SH ENTRY POINTS +.I Fsread +and +.I fswrite +(see +.IR 9pclient (3)) +generate the corresponding messages. +Because they take an offset parameter, the +.I fspread +and +.I fspwrite +calls correspond more directly to the 9P messages. +Although +.I fsseek +affects the offset, it does not generate a message. diff --git a/man/man9/remove.9p b/man/man9/remove.9p new file mode 100644 index 00000000..a9a844a1 --- /dev/null +++ b/man/man9/remove.9p @@ -0,0 +1,51 @@ +.TH REMOVE 9P +.SH NAME +remove \- remove a file from a server +.SH SYNOPSIS +.ta \w'\fLTremove 'u +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.SH DESCRIPTION +The +.B remove +request asks the file server both to remove the file represented by +.I fid +and to +.B clunk +the +.IR fid , +even if the remove fails. +This request will fail if the client does not have write permission +in the parent directory. +.PP +It is correct to consider +.B remove +to be a +.B clunk +with the side effect of removing the file if permissions allow. +.PP +If a file has been opened as multiple fids, +possibly on different connections, +and one fid is used to remove the file, +whether the other fids continue to provide access to the file +is implementation-defined. +The Plan 9 file servers +remove the file immediately: attempts to use the other fids +will yield a +``phase error.'' +.IR U9fs +follows the semantics of the underlying Unix file system, +so other fids typically remain usable. +.SH ENTRY POINTS +.I Fsremove +(see +.IR 9pclient (3)) +generates +.B remove +messages. diff --git a/man/man9/stat.9p b/man/man9/stat.9p new file mode 100644 index 00000000..ab68133d --- /dev/null +++ b/man/man9/stat.9p @@ -0,0 +1,297 @@ +.TH STAT 9P +.SH NAME +stat, wstat \- inquire or change file attributes +.SH SYNOPSIS +.ta \w'\fLTwstat 'u +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.PP +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.SH DESCRIPTION +The +.B stat +transaction inquires about the file +identified by +.IR fid . +The reply will contain a +machine-independent +.I directory +.IR entry , +.IR stat , +laid out as follows: +.TP +.I size\f1[2]\fP +total byte count of the following data +.TP +.I type\f1[2]\fP +for kernel use +.TP +.I dev\f1[4]\fP +for kernel use +.TP +.I qid.type\f1[1]\fP +the type of the file (directory, etc.), represented as a bit vector +corresponding to the high 8 bits of the file's mode word. +.TP +.I qid.vers\f1[4]\fP +version number for given path +.TP +.I qid.path\f1[8]\fP +the file server's unique identification for the file +.TP +.I mode\f1[4]\fP +permissions and flags +.TP +.I atime\f1[4]\fP +last access time +.TP +.I mtime\f1[4]\fP +last modification time +.TP +.I length\f1[8]\fP +length of file in bytes +.TP +.I name\f1[ s ]\fP +file name; must be +.B / +if the file is the root directory of the server +.TP +.I uid\f1[ s ]\fP +owner name +.TP +.I gid\f1[ s ]\fP +group name +.TP +.I muid\f1[ s ]\fP +name of the user who last modified the file +.PD +.PP +Integers in this encoding are in little-endian order (least +significant byte first). +The +.I convM2D +and +.I convD2M +routines (see +.IR fcall (3)) +convert between directory entries and a C structure called a +.BR Dir . +.PP +The +.I mode +contains permission bits as described in +.IR intro (9P) +and the following: +.B 0x80000000 +.RB ( DMDIR , +this file is a directory), +.B 0x40000000 +.RB ( DMAPPEND , +append only), +.B 0x20000000 +.RB ( DMEXCL , +exclusive use), +.B 0x04000000 +.RB ( DMTMP , +temporary); +these are echoed in +.BR Qid.type . +Writes to append-only files always place their data at the +end of the file; the +.I offset +in the +.B write +message is ignored, as is the +.B OTRUNC +bit in an open. +Exclusive use files may be open for I/O by only one fid at a time +across all clients of the server. If a second open is attempted, +it draws an error. Servers may implement a timeout on the lock +on an exclusive use file: if the fid holding the file open has +been unused for an extended period (of order at least minutes), +it is reasonable to break the lock and deny the initial fid +further I/O. +Temporary files are not included in nightly archives +(see Plan 9's \fIfossil\fR(4)). +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +The +.I mtime +field reflects the time of the last change of content (except when later changed by +.BR wstat ). +For a plain file, +.I mtime +is the time of the most recent +.BR create , +.B open +with truncation, +or +.BR write ; +for a directory it is the time of the most recent +.BR remove , +.BR create , +or +.B wstat +of a file in the directory. +Similarly, the +.I atime +field records the last +.B read +of the contents; +also it is set whenever +.I mtime +is set. +In addition, for a directory, it is set by +an +.BR attach , +.BR walk , +or +.BR create , +all whether successful or not. +.PP +The +.I muid +field names the user whose actions most recently changed the +.I mtime +of the file. +.PP +The +.I length +records the number of bytes in the file. +Directories and most files representing devices have a conventional +length of 0. +.PP +The +.B stat +request requires no special permissions. +.PP +The +.B wstat +request can change some of the file status information. +The +.I name +can be changed by anyone with write permission in the parent directory; +it is an error to change the name to that of an existing file. +The +.I length +can be changed (affecting the actual length of the file) by anyone with +write permission on the file. +It is an error to attempt to set the length of a directory to a non-zero value, +and servers may decide to reject length changes for other reasons. +The +.I mode +and +.I mtime +can be changed by the owner of the file or the group leader of the file's current +group. +The directory bit cannot be changed by a +.BR wstat ; +the other defined permission and mode bits can. +The +.I gid +can be changed: by the owner if also a member of the new group; or +by the group leader of the file's current group +if also leader of the new group +(see +.IR intro (9P) +for more information about permissions, users, and groups). +None of the other data can be altered by a +.B wstat +and attempts to change them will trigger an error. +In particular, +it is illegal to attempt to change the owner of a file. +(These conditions may be +relaxed when establishing the initial state of a file server; see +Plan 9's \fIfsconfig\fR(8).) +.PP +Either all the changes in +.B wstat +request happen, or none of them does: if the request succeeds, +all changes were made; if it fails, none were. +.PP +A +.B wstat +request can avoid modifying some properties of the file +by providing explicit ``don't touch'' values in the +.B stat +data that is sent: zero-length strings for text values and +the maximum unsigned value of appropriate size +for integral values. +As a special case, if +.I all +the elements of the directory entry in a +.B Twstat +message are ``don't touch'' values, the server may interpret it +as a request to guarantee that the contents of the associated +file are committed to stable storage before the +.B Rwstat +message is returned. +(Consider the message to mean, ``make the state of the file +exactly what it claims to be.'') +.PP +A +.I read +of a directory yields an integral number of directory entries in +the machine independent encoding given above +(see +.IR read (9P)). +.PP +Note that since the +.B stat +information is sent as a 9P variable-length datum, it is limited to a maximum of +65535 bytes. +.SH ENTRY POINTS +.B Stat +messages are generated by +.I fsdirfstat +and +.IR fsdirstat +(see +.IR 9pclient (3)). +.PP +.B Wstat +messages are generated by +.I fsdirfwstat +and +.IR fsdirwstat . +.SH BUGS +To make the contents of a directory, such as returned by +.IR read (9P), +easy to parse, each +directory entry begins with a size field. +For consistency, the entries in +.B Twstat +and +.B Rstat +messages also contain +their size, which means the size appears twice. +For example, the +.B Rstat +message is formatted as +.RI ``(4+1+2+2+ n )[4] +.B Rstat +.IR tag [2] +.IR n [2] +.RI ( n -2)[2] +.IR type [2] +.IR dev [4]...,'' +where +.I n +is the value returned by +.BR convD2M . diff --git a/man/man9/version.9p b/man/man9/version.9p new file mode 100644 index 00000000..c4961217 --- /dev/null +++ b/man/man9/version.9p @@ -0,0 +1,99 @@ +.TH VERSION 9P +.SH NAME +version \- negotiate protocol version +.SH SYNOPSIS +.ta \w'\fLTversion 'u +.IR size [4] +.B Tversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.br +.IR size [4] +.B Rversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.SH DESCRIPTION +The +.B version +request negotiates the protocol version and message size +to be used on the connection and initializes the connection for I/O. +.B Tversion +must be the first message sent on the 9P connection, +and the client cannot issue any further requests until it has received the +.B Rversion +reply. +The +.I tag +should be +.B NOTAG +(value +.BR (ushort)~0 ) +for a +.B version +message. +.PP +The client suggests a maximum message size, +.BR msize , +that is the maximum length, in bytes, +it will ever generate or expect to receive in a single 9P message. +This count includes all 9P protocol data, starting from the +.B size +field and extending through the message, +but excludes enveloping transport protocols. +The server responds with its own maximum, +.BR msize , +which must be less than or equal to the client's value. +Thenceforth, both sides of the connection must honor this limit. +.PP +The +.B version +string identifies the level of the protocol. +The string must always begin with the two characters +.RB `` 9P ''. +If the server does not understand the client's version string, +it should respond with an +.B Rversion +message (not +.BR Rerror ) +with the +.B version +string the 7 characters +.RB `` unknown ''. +.PP +The server may respond with the client's version string, +or a version string identifying +an earlier defined protocol version. +Currently, the only defined version is the 6 characters +.RB `` 9P2000 ''. +Version strings are defined such that, if the client string contains +one or more period characters, the initial substring up to but not including +any single period in the version string defines a version of the protocol. +After stripping any such period-separated suffix, the server is allowed to respond +with a string of the form +.BI 9P nnnn\f1, +where +.I nnnn +is less than or equal to the digits sent by the client. +.PP +The client and server will use the protocol version defined by the +server's response for all subsequent communication on the connection. +.PP +A successful +.B version +request initializes the connection. +All outstanding I/O on the connection is aborted; all active fids are freed (`clunked') automatically. +The set of messages between +.B version +requests is called a +.IR session . +.SH ENTRY POINTS +.I Fsversion +(see +.IR 9pclient (3)) +generates +.B version +messages; +it is called automatically by +.IR fsmount . diff --git a/man/man9/walk.9p b/man/man9/walk.9p new file mode 100644 index 00000000..49777f21 --- /dev/null +++ b/man/man9/walk.9p @@ -0,0 +1,189 @@ +.TH WALK 9P +.SH NAME +walk \- descend a directory hierarchy +.SH SYNOPSIS +.ta \w'\fLTwalk 'u +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( qid [13]) +.SH DESCRIPTION +The +.B walk +request carries as arguments an existing +.IR fid +and a proposed +.I newfid +(which must not be in use unless it is the same as +.IR fid ) +that the client wishes to associate with +the result of traversing the directory hierarchy +by `walking' the hierarchy using the successive path name +elements +.BR wname . +The +.I fid +must represent a directory unless zero path name elements are specified. +.PP +The +.I fid +must be valid in the current session and must not have been opened for I/O +by an +.B open +or +.B create +message. +If the full sequence of +.B nwname +elements is walked successfully, +.I newfid +will represent the file that results. +If not, +.I newfid +(and +.BR fid ) +will be unaffected. +However, if +.I newfid +is in use or otherwise illegal, an +.B Rerror +is returned. +.PP +The name +.RB `` .. '' +(dot-dot) represents the parent directory. +The name +.RB `` . '' +(dot), meaning the current directory, is not used in the protocol. +.PP +It is legal for +.B nwname +to be zero, in which case +.I newfid +will represent the same file as +.I fid +and the +.B walk +will usually succeed; this is equivalent to walking to dot. +The rest of this discussion assumes +.B nwname +is greater than zero. +.PP +The +.B nwname +path name elements +.B wname +are walked in order, ``elementwise''. +For the first elementwise walk +to succeed, the file identified by +.I fid +must be a directory, +and the implied user of the request must have permission +to search the directory (see +.IR intro (9P)). +Subsequent elementwise walks have equivalent restrictions +applied to the implicit fid that results from the preceding elementwise walk. +.PP +If the first element cannot be walked for any reason, +.B Rerror +is returned. +Otherwise, the walk will return an +.B Rwalk +message containing +.I nwqid +qids corresponding, in order, to the files that are visited by the +.I nwqid +successful elementwise walks; +.I nwqid +is therefore either +.B nwname +or the index of the first elementwise walk that failed. +The value of +.I nwqid +cannot be zero unless +.B nwname +is zero. +Also, +.I nwqid +will always be less than or equal to +.BR nwname . +Only if it is equal, however, will +.I newfid +be affected, in which case +.I newfid +will represent the file +reached by the final elementwise walk requested in the message. +.PP +A +.B walk +of the name +.RB `` .. '' +in the root directory of a server is equivalent to a walk with no name elements. +.PP +If +.I newfid +is the same as +.IR fid , +the above discussion applies, with the obvious difference +that if the walk changes the state of +.IR newfid , +it also changes the state of +.IR fid ; +and if +.I newfid +is unaffected, then +.I fid +is also unaffected. +.PP +To simplify the implementation of the servers, a maximum of sixteen name elements or qids +may be packed in a single message. +This constant is called +.B MAXWELEM +in +.IR fcall (3). +Despite this restriction, the system imposes no limit on the number of elements in a file name, +only the number that may be transmitted in a single message. +.SH ENTRY POINTS +.I Fswalk +(see +.IR 9pclient (3)) +generates walk messages. +One or more walk messages may be generated by +any call that evaluates file names: +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +.IR fsdirwstat . +.\" +.\" A call to +.\" .IR chdir (2) +.\" causes a +.\" .BR walk . +.\" One or more +.\" .B walk +.\" messages may be generated by +.\" any of the following calls, which evaluate file names: +.\" .IR bind , +.\" .IR create , +.\" .IR exec , +.\" .IR mount , +.\" .IR open , +.\" .IR remove , +.\" .IR stat , +.\" .IR unmount , +.\" .IR wstat . +.\" The file name element +.\" .B . +.\" (dot) is interpreted locally and +.\" is not transmitted in +.\" .B walk +.\" messages. -- cgit v1.2.3