From 97d5c458cfa039d857301e1ca7d5af3beb37131d Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sun, 26 Apr 2026 16:38:00 -0400 Subject: build: Better Build System --- static/plan9-4e/Makefile | 13 + static/plan9-4e/man1/0intro.1 | 398 ++++++++ static/plan9-4e/man1/2a.1 | 55 ++ static/plan9-4e/man1/2c.1 | 398 ++++++++ static/plan9-4e/man1/2l.1 | 193 ++++ static/plan9-4e/man1/INDEX.1 | 291 ++++++ static/plan9-4e/man1/INDEX.html.1 | 561 +++++++++++ static/plan9-4e/man1/Makefile | 3 + static/plan9-4e/man1/aan.1 | 88 ++ static/plan9-4e/man1/acid.1 | 472 ++++++++++ static/plan9-4e/man1/acme.1 | 683 ++++++++++++++ static/plan9-4e/man1/ar.1 | 183 ++++ static/plan9-4e/man1/ascii.1 | 161 ++++ static/plan9-4e/man1/awk.1 | 527 +++++++++++ static/plan9-4e/man1/basename.1 | 35 + static/plan9-4e/man1/bc.1 | 292 ++++++ static/plan9-4e/man1/bind.1 | 201 ++++ static/plan9-4e/man1/bitsyload.1 | 146 +++ static/plan9-4e/man1/bundle.1 | 53 ++ static/plan9-4e/man1/cal.1 | 46 + static/plan9-4e/man1/calendar.1 | 44 + static/plan9-4e/man1/cat.1 | 82 ++ static/plan9-4e/man1/chgrp.1 | 36 + static/plan9-4e/man1/chmod.1 | 104 ++ static/plan9-4e/man1/cleanname.1 | 32 + static/plan9-4e/man1/cmp.1 | 57 ++ static/plan9-4e/man1/colors.1 | 73 ++ static/plan9-4e/man1/comm.1 | 47 + static/plan9-4e/man1/con.1 | 238 +++++ static/plan9-4e/man1/cp.1 | 92 ++ static/plan9-4e/man1/cpp.1 | 116 +++ static/plan9-4e/man1/cpu.1 | 162 ++++ static/plan9-4e/man1/crop.1 | 147 +++ static/plan9-4e/man1/date.1 | 58 ++ static/plan9-4e/man1/db.1 | 1018 ++++++++++++++++++++ static/plan9-4e/man1/dc.1 | 257 +++++ static/plan9-4e/man1/dd.1 | 187 ++++ static/plan9-4e/man1/deroff.1 | 117 +++ static/plan9-4e/man1/diff.1 | 155 +++ static/plan9-4e/man1/doc2txt.1 | 53 ++ static/plan9-4e/man1/doctype.1 | 56 ++ static/plan9-4e/man1/du.1 | 97 ++ static/plan9-4e/man1/echo.1 | 20 + static/plan9-4e/man1/ed.1 | 683 ++++++++++++++ static/plan9-4e/man1/emacs.1 | 17 + static/plan9-4e/man1/eqn.1 | 339 +++++++ static/plan9-4e/man1/faces.1 | 93 ++ static/plan9-4e/man1/factor.1 | 66 ++ static/plan9-4e/man1/file.1 | 117 +++ static/plan9-4e/man1/fmt.1 | 79 ++ static/plan9-4e/man1/fortune.1 | 23 + static/plan9-4e/man1/freq.1 | 40 + static/plan9-4e/man1/grap.1 | 416 ++++++++ static/plan9-4e/man1/graph.1 | 148 +++ static/plan9-4e/man1/grep.1 | 103 ++ static/plan9-4e/man1/gs.1 | 276 ++++++ static/plan9-4e/man1/gzip.1 | 160 ++++ static/plan9-4e/man1/hget.1 | 68 ++ static/plan9-4e/man1/history.1 | 81 ++ static/plan9-4e/man1/hoc.1 | 144 +++ static/plan9-4e/man1/idiff.1 | 72 ++ static/plan9-4e/man1/join.1 | 148 +++ static/plan9-4e/man1/jpg.1 | 204 ++++ static/plan9-4e/man1/kill.1 | 70 ++ static/plan9-4e/man1/ktrace.1 | 62 ++ static/plan9-4e/man1/leak.1 | 141 +++ static/plan9-4e/man1/lens.1 | 39 + static/plan9-4e/man1/lex.1 | 78 ++ static/plan9-4e/man1/look.1 | 86 ++ static/plan9-4e/man1/lp.1 | 185 ++++ static/plan9-4e/man1/ls.1 | 155 +++ static/plan9-4e/man1/mail.1 | 1268 +++++++++++++++++++++++++ static/plan9-4e/man1/man.1 | 97 ++ static/plan9-4e/man1/mc.1 | 40 + static/plan9-4e/man1/mk.1 | 654 +++++++++++++ static/plan9-4e/man1/mkdir.1 | 25 + static/plan9-4e/man1/ms2html.1 | 41 + static/plan9-4e/man1/netstat.1 | 39 + static/plan9-4e/man1/news.1 | 63 ++ static/plan9-4e/man1/nm.1 | 104 ++ static/plan9-4e/man1/ns.1 | 44 + static/plan9-4e/man1/p.1 | 33 + static/plan9-4e/man1/page.1 | 229 +++++ static/plan9-4e/man1/passwd.1 | 74 ++ static/plan9-4e/man1/pcc.1 | 185 ++++ static/plan9-4e/man1/pic.1 | 344 +++++++ static/plan9-4e/man1/pipefile.1 | 101 ++ static/plan9-4e/man1/plot.1 | 61 ++ static/plan9-4e/man1/plumb.1 | 92 ++ static/plan9-4e/man1/pr.1 | 110 +++ static/plan9-4e/man1/prof.1 | 132 +++ static/plan9-4e/man1/proof.1 | 134 +++ static/plan9-4e/man1/ps.1 | 109 +++ static/plan9-4e/man1/pwd.1 | 46 + static/plan9-4e/man1/rc.1 | 959 +++++++++++++++++++ static/plan9-4e/man1/replica.1 | 304 ++++++ static/plan9-4e/man1/resample.1 | 58 ++ static/plan9-4e/man1/rio.1 | 513 ++++++++++ static/plan9-4e/man1/rm.1 | 28 + static/plan9-4e/man1/rtstats.1 | 117 +++ static/plan9-4e/man1/sam.1 | 885 +++++++++++++++++ static/plan9-4e/man1/secstore.1 | 107 +++ static/plan9-4e/man1/sed.1 | 385 ++++++++ static/plan9-4e/man1/seq.1 | 69 ++ static/plan9-4e/man1/size.1 | 28 + static/plan9-4e/man1/sleep.1 | 31 + static/plan9-4e/man1/sort.1 | 260 +++++ static/plan9-4e/man1/spell.1 | 96 ++ static/plan9-4e/man1/spin.1 | 149 +++ static/plan9-4e/man1/split.1 | 76 ++ static/plan9-4e/man1/src.1 | 83 ++ static/plan9-4e/man1/ssh.1 | 338 +++++++ static/plan9-4e/man1/stop.1 | 36 + static/plan9-4e/man1/strings.1 | 28 + static/plan9-4e/man1/strip.1 | 19 + static/plan9-4e/man1/sum.1 | 77 ++ static/plan9-4e/man1/syscall.1 | 77 ++ static/plan9-4e/man1/tail.1 | 87 ++ static/plan9-4e/man1/tapefs.1 | 100 ++ static/plan9-4e/man1/tar.1 | 110 +++ static/plan9-4e/man1/tbl.1 | 285 ++++++ static/plan9-4e/man1/tcs.1 | 167 ++++ static/plan9-4e/man1/tee.1 | 28 + static/plan9-4e/man1/tel.1 | 110 +++ static/plan9-4e/man1/test.1 | 174 ++++ static/plan9-4e/man1/time.1 | 21 + static/plan9-4e/man1/touch.1 | 35 + static/plan9-4e/man1/tr.1 | 97 ++ static/plan9-4e/man1/troff.1 | 198 ++++ static/plan9-4e/man1/troff2html.1 | 97 ++ static/plan9-4e/man1/tweak.1 | 167 ++++ static/plan9-4e/man1/uniq.1 | 59 ++ static/plan9-4e/man1/units.1 | 108 +++ static/plan9-4e/man1/vac.1 | 122 +++ static/plan9-4e/man1/vi.1 | 170 ++++ static/plan9-4e/man1/vnc.1 | 153 +++ static/plan9-4e/man1/vt.1 | 109 +++ static/plan9-4e/man1/wc.1 | 53 ++ static/plan9-4e/man1/who.1 | 22 + static/plan9-4e/man1/xd.1 | 87 ++ static/plan9-4e/man1/yacc.1 | 167 ++++ static/plan9-4e/man1/yesterday.1 | 122 +++ static/plan9-4e/man2/0intro.2 | 465 +++++++++ static/plan9-4e/man2/9p.2 | 678 +++++++++++++ static/plan9-4e/man2/9pfid.2 | 204 ++++ static/plan9-4e/man2/9pfile.2 | 224 +++++ static/plan9-4e/man2/INDEX.2 | 1274 +++++++++++++++++++++++++ static/plan9-4e/man2/INDEX.html.2 | 565 +++++++++++ static/plan9-4e/man2/Makefile | 3 + static/plan9-4e/man2/abort.2 | 18 + static/plan9-4e/man2/abs.2 | 33 + static/plan9-4e/man2/access.2 | 64 ++ static/plan9-4e/man2/addpt.2 | 188 ++++ static/plan9-4e/man2/aes.2 | 50 + static/plan9-4e/man2/allocimage.2 | 348 +++++++ static/plan9-4e/man2/arg.2 | 122 +++ static/plan9-4e/man2/arith3.2 | 269 ++++++ static/plan9-4e/man2/assert.2 | 25 + static/plan9-4e/man2/atof.2 | 146 +++ static/plan9-4e/man2/auth.2 | 395 ++++++++ static/plan9-4e/man2/authsrv.2 | 217 +++++ static/plan9-4e/man2/bin.2 | 99 ++ static/plan9-4e/man2/bind.2 | 236 +++++ static/plan9-4e/man2/bio.2 | 349 +++++++ static/plan9-4e/man2/blowfish.2 | 51 + static/plan9-4e/man2/brk.2 | 62 ++ static/plan9-4e/man2/cachechars.2 | 313 ++++++ static/plan9-4e/man2/chdir.2 | 32 + static/plan9-4e/man2/cleanname.2 | 34 + static/plan9-4e/man2/color.2 | 56 ++ static/plan9-4e/man2/control.2 | 1829 ++++++++++++++++++++++++++++++++++++ static/plan9-4e/man2/cputime.2 | 34 + static/plan9-4e/man2/ctime.2 | 129 +++ static/plan9-4e/man2/ctype.2 | 160 ++++ static/plan9-4e/man2/debugger.2 | 386 ++++++++ static/plan9-4e/man2/des.2 | 143 +++ static/plan9-4e/man2/dial.2 | 331 +++++++ static/plan9-4e/man2/dirread.2 | 103 ++ static/plan9-4e/man2/disk.2 | 172 ++++ static/plan9-4e/man2/draw.2 | 779 +++++++++++++++ static/plan9-4e/man2/dup.2 | 42 + static/plan9-4e/man2/elgamal.2 | 92 ++ static/plan9-4e/man2/encode.2 | 82 ++ static/plan9-4e/man2/encrypt.2 | 76 ++ static/plan9-4e/man2/errstr.2 | 75 ++ static/plan9-4e/man2/event.2 | 384 ++++++++ static/plan9-4e/man2/exec.2 | 159 ++++ static/plan9-4e/man2/exits.2 | 81 ++ static/plan9-4e/man2/exp.2 | 62 ++ static/plan9-4e/man2/fauth.2 | 66 ++ static/plan9-4e/man2/fcall.2 | 351 +++++++ static/plan9-4e/man2/fd2path.2 | 57 ++ static/plan9-4e/man2/fgetc.2 | 211 +++++ static/plan9-4e/man2/flate.2 | 207 ++++ static/plan9-4e/man2/floor.2 | 58 ++ static/plan9-4e/man2/fmtinstall.2 | 372 ++++++++ static/plan9-4e/man2/fopen.2 | 352 +++++++ static/plan9-4e/man2/fork.2 | 166 ++++ static/plan9-4e/man2/fprintf.2 | 504 ++++++++++ static/plan9-4e/man2/frame.2 | 362 +++++++ static/plan9-4e/man2/frexp.2 | 47 + static/plan9-4e/man2/fscanf.2 | 402 ++++++++ static/plan9-4e/man2/fversion.2 | 72 ++ static/plan9-4e/man2/genrandom.2 | 44 + static/plan9-4e/man2/getcallerpc.2 | 38 + static/plan9-4e/man2/getenv.2 | 44 + static/plan9-4e/man2/getfcr.2 | 125 +++ static/plan9-4e/man2/getfields.2 | 88 ++ static/plan9-4e/man2/getpid.2 | 41 + static/plan9-4e/man2/getuser.2 | 37 + static/plan9-4e/man2/getwd.2 | 37 + static/plan9-4e/man2/graphics.2 | 632 +++++++++++++ static/plan9-4e/man2/html.2 | 1420 ++++++++++++++++++++++++++++ static/plan9-4e/man2/httpd.2 | 307 ++++++ static/plan9-4e/man2/hypot.2 | 21 + static/plan9-4e/man2/intmap.2 | 126 +++ static/plan9-4e/man2/iounit.2 | 37 + static/plan9-4e/man2/ip.2 | 335 +++++++ static/plan9-4e/man2/isalpharune.2 | 51 + static/plan9-4e/man2/keyboard.2 | 104 ++ static/plan9-4e/man2/lock.2 | 180 ++++ static/plan9-4e/man2/mach.2 | 393 ++++++++ static/plan9-4e/man2/malloc.2 | 198 ++++ static/plan9-4e/man2/matrix.2 | 350 +++++++ static/plan9-4e/man2/memdraw.2 | 450 +++++++++ static/plan9-4e/man2/memlayer.2 | 305 ++++++ static/plan9-4e/man2/memory.2 | 126 +++ static/plan9-4e/man2/mktemp.2 | 40 + static/plan9-4e/man2/mouse.2 | 249 +++++ static/plan9-4e/man2/mp.2 | 568 +++++++++++ static/plan9-4e/man2/muldiv.2 | 31 + static/plan9-4e/man2/nan.2 | 44 + static/plan9-4e/man2/ndb.2 | 366 ++++++++ static/plan9-4e/man2/notify.2 | 243 +++++ static/plan9-4e/man2/object.2 | 150 +++ static/plan9-4e/man2/open.2 | 148 +++ static/plan9-4e/man2/perror.2 | 92 ++ static/plan9-4e/man2/pipe.2 | 74 ++ static/plan9-4e/man2/plumb.2 | 240 +++++ static/plan9-4e/man2/pool.2 | 329 +++++++ static/plan9-4e/man2/postnote.2 | 49 + static/plan9-4e/man2/prime.2 | 104 ++ static/plan9-4e/man2/print.2 | 445 +++++++++ static/plan9-4e/man2/privalloc.2 | 36 + static/plan9-4e/man2/proto.2 | 131 +++ static/plan9-4e/man2/pushssl.2 | 45 + static/plan9-4e/man2/pushtls.2 | 177 ++++ static/plan9-4e/man2/qball.2 | 76 ++ static/plan9-4e/man2/qsort.2 | 33 + static/plan9-4e/man2/quaternion.2 | 152 +++ static/plan9-4e/man2/quote.2 | 159 ++++ static/plan9-4e/man2/rand.2 | 172 ++++ static/plan9-4e/man2/rc4.2 | 54 ++ static/plan9-4e/man2/read.2 | 95 ++ static/plan9-4e/man2/readcolmap.2 | 76 ++ static/plan9-4e/man2/readv.2 | 82 ++ static/plan9-4e/man2/regexp.2 | 212 +++++ static/plan9-4e/man2/remove.2 | 31 + static/plan9-4e/man2/rendezvous.2 | 57 ++ static/plan9-4e/man2/rsa.2 | 149 +++ static/plan9-4e/man2/rune.2 | 190 ++++ static/plan9-4e/man2/runestrcat.2 | 67 ++ static/plan9-4e/man2/scribble.2 | 162 ++++ static/plan9-4e/man2/scsi.2 | 184 ++++ static/plan9-4e/man2/sechash.2 | 150 +++ static/plan9-4e/man2/seek.2 | 46 + static/plan9-4e/man2/segattach.2 | 173 ++++ static/plan9-4e/man2/segbrk.2 | 43 + static/plan9-4e/man2/segflush.2 | 42 + static/plan9-4e/man2/setjmp.2 | 98 ++ static/plan9-4e/man2/sin.2 | 64 ++ static/plan9-4e/man2/sinh.2 | 23 + static/plan9-4e/man2/sleep.2 | 45 + static/plan9-4e/man2/stat.2 | 326 +++++++ static/plan9-4e/man2/strcat.2 | 268 ++++++ static/plan9-4e/man2/string.2 | 231 +++++ static/plan9-4e/man2/stringsize.2 | 69 ++ static/plan9-4e/man2/subfont.2 | 235 +++++ static/plan9-4e/man2/symbol.2 | 436 +++++++++ static/plan9-4e/man2/thread.2 | 578 ++++++++++++ static/plan9-4e/man2/time.2 | 45 + static/plan9-4e/man2/tmpfile.2 | 58 ++ static/plan9-4e/man2/wait.2 | 117 +++ static/plan9-4e/man2/window.2 | 244 +++++ static/plan9-4e/man3/0intro.3 | 92 ++ static/plan9-4e/man3/INDEX.3 | 35 + static/plan9-4e/man3/INDEX.html.3 | 137 +++ static/plan9-4e/man3/Makefile | 3 + static/plan9-4e/man3/apm.3 | 60 ++ static/plan9-4e/man3/arch.3 | 65 ++ static/plan9-4e/man3/audio.3 | 129 +++ static/plan9-4e/man3/cap.3 | 81 ++ static/plan9-4e/man3/cons.3 | 346 +++++++ static/plan9-4e/man3/draw.3 | 782 +++++++++++++++ static/plan9-4e/man3/dup.3 | 58 ++ static/plan9-4e/man3/env.3 | 64 ++ static/plan9-4e/man3/ether.3 | 96 ++ static/plan9-4e/man3/floppy.3 | 54 ++ static/plan9-4e/man3/i82365.3 | 41 + static/plan9-4e/man3/ip.3 | 926 ++++++++++++++++++ static/plan9-4e/man3/kprof.3 | 66 ++ static/plan9-4e/man3/loopback.3 | 88 ++ static/plan9-4e/man3/lpt.3 | 43 + static/plan9-4e/man3/mnt.3 | 72 ++ static/plan9-4e/man3/mouse.3 | 213 +++++ static/plan9-4e/man3/pipe.3 | 59 ++ static/plan9-4e/man3/pnp.3 | 146 +++ static/plan9-4e/man3/proc.3 | 328 +++++++ static/plan9-4e/man3/realtime.3 | 316 +++++++ static/plan9-4e/man3/root.3 | 39 + static/plan9-4e/man3/rtc.3 | 40 + static/plan9-4e/man3/sd.3 | 209 ++++ static/plan9-4e/man3/segment.3 | 117 +++ static/plan9-4e/man3/srv.3 | 74 ++ static/plan9-4e/man3/ssl.3 | 124 +++ static/plan9-4e/man3/tls.3 | 272 ++++++ static/plan9-4e/man3/uart.3 | 97 ++ static/plan9-4e/man3/usb.3 | 235 +++++ static/plan9-4e/man3/vga.3 | 209 ++++ static/plan9-4e/man4/0intro.4 | 14 + static/plan9-4e/man4/INDEX.4 | 71 ++ static/plan9-4e/man4/INDEX.html.4 | 157 ++++ static/plan9-4e/man4/Makefile | 3 + static/plan9-4e/man4/acme.4 | 408 ++++++++ static/plan9-4e/man4/archfs.4 | 46 + static/plan9-4e/man4/cdfs.4 | 172 ++++ static/plan9-4e/man4/cfs.4 | 95 ++ static/plan9-4e/man4/consolefs.4 | 216 +++++ static/plan9-4e/man4/dossrv.4 | 217 +++++ static/plan9-4e/man4/execnet.4 | 67 ++ static/plan9-4e/man4/exportfs.4 | 205 ++++ static/plan9-4e/man4/factotum.4 | 679 +++++++++++++ static/plan9-4e/man4/fs.4 | 148 +++ static/plan9-4e/man4/ftpfs.4 | 173 ++++ static/plan9-4e/man4/import.4 | 121 +++ static/plan9-4e/man4/iostats.4 | 64 ++ static/plan9-4e/man4/keyfs.4 | 248 +++++ static/plan9-4e/man4/kfs.4 | 132 +++ static/plan9-4e/man4/lnfs.4 | 55 ++ static/plan9-4e/man4/namespace.4 | 384 ++++++++ static/plan9-4e/man4/nntpfs.4 | 107 +++ static/plan9-4e/man4/paqfs.4 | 76 ++ static/plan9-4e/man4/plumber.4 | 126 +++ static/plan9-4e/man4/ramfs.4 | 74 ++ static/plan9-4e/man4/ratfs.4 | 174 ++++ static/plan9-4e/man4/rdbfs.4 | 67 ++ static/plan9-4e/man4/rio.4 | 403 ++++++++ static/plan9-4e/man4/sacfs.4 | 59 ++ static/plan9-4e/man4/snap.4 | 103 ++ static/plan9-4e/man4/srv.4 | 237 +++++ static/plan9-4e/man4/tapefs.4 | 100 ++ static/plan9-4e/man4/telco.4 | 226 +++++ static/plan9-4e/man4/u9fs.4 | 250 +++++ static/plan9-4e/man4/usb.4 | 154 +++ static/plan9-4e/man4/usbd.4 | 35 + static/plan9-4e/man4/vacfs.4 | 72 ++ static/plan9-4e/man4/webcookies.4 | 166 ++++ static/plan9-4e/man4/webfs.4 | 307 ++++++ static/plan9-4e/man4/wikifs.4 | 338 +++++++ static/plan9-4e/man5/0intro.5 | 603 ++++++++++++ static/plan9-4e/man5/INDEX.5 | 16 + static/plan9-4e/man5/INDEX.html.5 | 53 ++ static/plan9-4e/man5/Makefile | 3 + static/plan9-4e/man5/attach.5 | 159 ++++ static/plan9-4e/man5/clunk.5 | 43 + static/plan9-4e/man5/error.5 | 27 + static/plan9-4e/man5/flush.5 | 76 ++ static/plan9-4e/man5/open.5 | 247 +++++ static/plan9-4e/man5/read.5 | 125 +++ static/plan9-4e/man5/remove.5 | 35 + static/plan9-4e/man5/stat.5 | 291 ++++++ static/plan9-4e/man5/version.5 | 101 ++ static/plan9-4e/man5/walk.5 | 178 ++++ static/plan9-4e/man6/0intro.6 | 8 + static/plan9-4e/man6/INDEX.6 | 33 + static/plan9-4e/man6/INDEX.html.6 | 113 +++ static/plan9-4e/man6/Makefile | 3 + static/plan9-4e/man6/a.out.6 | 252 +++++ static/plan9-4e/man6/ar.6 | 99 ++ static/plan9-4e/man6/authsrv.6 | 373 ++++++++ static/plan9-4e/man6/color.6 | 150 +++ static/plan9-4e/man6/face.6 | 114 +++ static/plan9-4e/man6/font.6 | 87 ++ static/plan9-4e/man6/image.6 | 205 ++++ static/plan9-4e/man6/keyboard.6 | 198 ++++ static/plan9-4e/man6/man.6 | 249 +++++ static/plan9-4e/man6/map.6 | 87 ++ static/plan9-4e/man6/mpictures.6 | 151 +++ static/plan9-4e/man6/ms.6 | 308 ++++++ static/plan9-4e/man6/namespace.6 | 82 ++ static/plan9-4e/man6/ndb.6 | 285 ++++++ static/plan9-4e/man6/plot.6 | 336 +++++++ static/plan9-4e/man6/plumb.6 | 417 ++++++++ static/plan9-4e/man6/regexp.6 | 129 +++ static/plan9-4e/man6/rewrite.6 | 154 +++ static/plan9-4e/man6/smtpd.6 | 306 ++++++ static/plan9-4e/man6/snap.6 | 98 ++ static/plan9-4e/man6/thumbprint.6 | 41 + static/plan9-4e/man6/users.6 | 69 ++ static/plan9-4e/man6/utf.6 | 98 ++ static/plan9-4e/man6/venti.conf.6 | 67 ++ static/plan9-4e/man6/vgadb.6 | 486 ++++++++++ static/plan9-4e/man7/0intro.7 | 8 + static/plan9-4e/man7/INDEX.7 | 8 + static/plan9-4e/man7/INDEX.html.7 | 33 + static/plan9-4e/man7/Makefile | 3 + static/plan9-4e/man7/astro.7 | 122 +++ static/plan9-4e/man7/dict.7 | 163 ++++ static/plan9-4e/man7/juke.7 | 52 + static/plan9-4e/man7/map.7 | 676 +++++++++++++ static/plan9-4e/man7/scat.7 | 335 +++++++ static/plan9-4e/man8/0intro.8 | 8 + static/plan9-4e/man8/9load.8 | 407 ++++++++ static/plan9-4e/man8/9pcon.8 | 160 ++++ static/plan9-4e/man8/INDEX.8 | 157 ++++ static/plan9-4e/man8/INDEX.html.8 | 237 +++++ static/plan9-4e/man8/Makefile | 3 + static/plan9-4e/man8/apm.8 | 111 +++ static/plan9-4e/man8/auth.8 | 194 ++++ static/plan9-4e/man8/boot.8 | 258 +++++ static/plan9-4e/man8/booting.8 | 158 ++++ static/plan9-4e/man8/buildindex.8 | 62 ++ static/plan9-4e/man8/checkarenas.8 | 34 + static/plan9-4e/man8/checkindex.8 | 52 + static/plan9-4e/man8/cpurc.8 | 67 ++ static/plan9-4e/man8/cron.8 | 111 +++ static/plan9-4e/man8/dhcpd.8 | 272 ++++++ static/plan9-4e/man8/drawterm.8 | 124 +++ static/plan9-4e/man8/fmtarenas.8 | 64 ++ static/plan9-4e/man8/fmtindex.8 | 60 ++ static/plan9-4e/man8/fmtisect.8 | 50 + static/plan9-4e/man8/fs.8 | 678 +++++++++++++ static/plan9-4e/man8/fsconfig.8 | 249 +++++ static/plan9-4e/man8/httpd.8 | 196 ++++ static/plan9-4e/man8/init.8 | 87 ++ static/plan9-4e/man8/ipconfig.8 | 205 ++++ static/plan9-4e/man8/ipserv.8 | 239 +++++ static/plan9-4e/man8/kfscmd.8 | 198 ++++ static/plan9-4e/man8/listen.8 | 172 ++++ static/plan9-4e/man8/lp.8 | 126 +++ static/plan9-4e/man8/mk9660.8 | 231 +++++ static/plan9-4e/man8/mkfs.8 | 187 ++++ static/plan9-4e/man8/mkpaqfs.8 | 52 + static/plan9-4e/man8/mksacfs.8 | 38 + static/plan9-4e/man8/mouse.8 | 120 +++ static/plan9-4e/man8/na.8 | 33 + static/plan9-4e/man8/ndb.8 | 459 +++++++++ static/plan9-4e/man8/newuser.8 | 119 +++ static/plan9-4e/man8/nfsserver.8 | 164 ++++ static/plan9-4e/man8/pcmcia.8 | 23 + static/plan9-4e/man8/ping.8 | 146 +++ static/plan9-4e/man8/plan9.ini.8 | 815 ++++++++++++++++ static/plan9-4e/man8/ppp.8 | 275 ++++++ static/plan9-4e/man8/prep.8 | 657 +++++++++++++ static/plan9-4e/man8/qer.8 | 226 +++++ static/plan9-4e/man8/rdarena.8 | 30 + static/plan9-4e/man8/reboot.8 | 20 + static/plan9-4e/man8/replica.8 | 303 ++++++ static/plan9-4e/man8/scanmail.8 | 447 +++++++++ static/plan9-4e/man8/scuzz.8 | 370 ++++++++ static/plan9-4e/man8/secstore.8 | 47 + static/plan9-4e/man8/securenet.8 | 128 +++ static/plan9-4e/man8/snoopy.8 | 170 ++++ static/plan9-4e/man8/stats.8 | 145 +++ static/plan9-4e/man8/swap.8 | 30 + static/plan9-4e/man8/timesync.8 | 95 ++ static/plan9-4e/man8/tlssrv.8 | 38 + static/plan9-4e/man8/udpecho.8 | 16 + static/plan9-4e/man8/update.8 | 127 +++ static/plan9-4e/man8/venti.8 | 196 ++++ static/plan9-4e/man8/vga.8 | 189 ++++ 471 files changed, 84349 insertions(+) create mode 100644 static/plan9-4e/Makefile create mode 100644 static/plan9-4e/man1/0intro.1 create mode 100644 static/plan9-4e/man1/2a.1 create mode 100644 static/plan9-4e/man1/2c.1 create mode 100644 static/plan9-4e/man1/2l.1 create mode 100644 static/plan9-4e/man1/INDEX.1 create mode 100644 static/plan9-4e/man1/INDEX.html.1 create mode 100644 static/plan9-4e/man1/Makefile create mode 100644 static/plan9-4e/man1/aan.1 create mode 100644 static/plan9-4e/man1/acid.1 create mode 100644 static/plan9-4e/man1/acme.1 create mode 100644 static/plan9-4e/man1/ar.1 create mode 100644 static/plan9-4e/man1/ascii.1 create mode 100644 static/plan9-4e/man1/awk.1 create mode 100644 static/plan9-4e/man1/basename.1 create mode 100644 static/plan9-4e/man1/bc.1 create mode 100644 static/plan9-4e/man1/bind.1 create mode 100644 static/plan9-4e/man1/bitsyload.1 create mode 100644 static/plan9-4e/man1/bundle.1 create mode 100644 static/plan9-4e/man1/cal.1 create mode 100644 static/plan9-4e/man1/calendar.1 create mode 100644 static/plan9-4e/man1/cat.1 create mode 100644 static/plan9-4e/man1/chgrp.1 create mode 100644 static/plan9-4e/man1/chmod.1 create mode 100644 static/plan9-4e/man1/cleanname.1 create mode 100644 static/plan9-4e/man1/cmp.1 create mode 100644 static/plan9-4e/man1/colors.1 create mode 100644 static/plan9-4e/man1/comm.1 create mode 100644 static/plan9-4e/man1/con.1 create mode 100644 static/plan9-4e/man1/cp.1 create mode 100644 static/plan9-4e/man1/cpp.1 create mode 100644 static/plan9-4e/man1/cpu.1 create mode 100644 static/plan9-4e/man1/crop.1 create mode 100644 static/plan9-4e/man1/date.1 create mode 100644 static/plan9-4e/man1/db.1 create mode 100644 static/plan9-4e/man1/dc.1 create mode 100644 static/plan9-4e/man1/dd.1 create mode 100644 static/plan9-4e/man1/deroff.1 create mode 100644 static/plan9-4e/man1/diff.1 create mode 100644 static/plan9-4e/man1/doc2txt.1 create mode 100644 static/plan9-4e/man1/doctype.1 create mode 100644 static/plan9-4e/man1/du.1 create mode 100644 static/plan9-4e/man1/echo.1 create mode 100644 static/plan9-4e/man1/ed.1 create mode 100644 static/plan9-4e/man1/emacs.1 create mode 100644 static/plan9-4e/man1/eqn.1 create mode 100644 static/plan9-4e/man1/faces.1 create mode 100644 static/plan9-4e/man1/factor.1 create mode 100644 static/plan9-4e/man1/file.1 create mode 100644 static/plan9-4e/man1/fmt.1 create mode 100644 static/plan9-4e/man1/fortune.1 create mode 100644 static/plan9-4e/man1/freq.1 create mode 100644 static/plan9-4e/man1/grap.1 create mode 100644 static/plan9-4e/man1/graph.1 create mode 100644 static/plan9-4e/man1/grep.1 create mode 100644 static/plan9-4e/man1/gs.1 create mode 100644 static/plan9-4e/man1/gzip.1 create mode 100644 static/plan9-4e/man1/hget.1 create mode 100644 static/plan9-4e/man1/history.1 create mode 100644 static/plan9-4e/man1/hoc.1 create mode 100644 static/plan9-4e/man1/idiff.1 create mode 100644 static/plan9-4e/man1/join.1 create mode 100644 static/plan9-4e/man1/jpg.1 create mode 100644 static/plan9-4e/man1/kill.1 create mode 100644 static/plan9-4e/man1/ktrace.1 create mode 100644 static/plan9-4e/man1/leak.1 create mode 100644 static/plan9-4e/man1/lens.1 create mode 100644 static/plan9-4e/man1/lex.1 create mode 100644 static/plan9-4e/man1/look.1 create mode 100644 static/plan9-4e/man1/lp.1 create mode 100644 static/plan9-4e/man1/ls.1 create mode 100644 static/plan9-4e/man1/mail.1 create mode 100644 static/plan9-4e/man1/man.1 create mode 100644 static/plan9-4e/man1/mc.1 create mode 100644 static/plan9-4e/man1/mk.1 create mode 100644 static/plan9-4e/man1/mkdir.1 create mode 100644 static/plan9-4e/man1/ms2html.1 create mode 100644 static/plan9-4e/man1/netstat.1 create mode 100644 static/plan9-4e/man1/news.1 create mode 100644 static/plan9-4e/man1/nm.1 create mode 100644 static/plan9-4e/man1/ns.1 create mode 100644 static/plan9-4e/man1/p.1 create mode 100644 static/plan9-4e/man1/page.1 create mode 100644 static/plan9-4e/man1/passwd.1 create mode 100644 static/plan9-4e/man1/pcc.1 create mode 100644 static/plan9-4e/man1/pic.1 create mode 100644 static/plan9-4e/man1/pipefile.1 create mode 100644 static/plan9-4e/man1/plot.1 create mode 100644 static/plan9-4e/man1/plumb.1 create mode 100644 static/plan9-4e/man1/pr.1 create mode 100644 static/plan9-4e/man1/prof.1 create mode 100644 static/plan9-4e/man1/proof.1 create mode 100644 static/plan9-4e/man1/ps.1 create mode 100644 static/plan9-4e/man1/pwd.1 create mode 100644 static/plan9-4e/man1/rc.1 create mode 100644 static/plan9-4e/man1/replica.1 create mode 100644 static/plan9-4e/man1/resample.1 create mode 100644 static/plan9-4e/man1/rio.1 create mode 100644 static/plan9-4e/man1/rm.1 create mode 100644 static/plan9-4e/man1/rtstats.1 create mode 100644 static/plan9-4e/man1/sam.1 create mode 100644 static/plan9-4e/man1/secstore.1 create mode 100644 static/plan9-4e/man1/sed.1 create mode 100644 static/plan9-4e/man1/seq.1 create mode 100644 static/plan9-4e/man1/size.1 create mode 100644 static/plan9-4e/man1/sleep.1 create mode 100644 static/plan9-4e/man1/sort.1 create mode 100644 static/plan9-4e/man1/spell.1 create mode 100644 static/plan9-4e/man1/spin.1 create mode 100644 static/plan9-4e/man1/split.1 create mode 100644 static/plan9-4e/man1/src.1 create mode 100644 static/plan9-4e/man1/ssh.1 create mode 100644 static/plan9-4e/man1/stop.1 create mode 100644 static/plan9-4e/man1/strings.1 create mode 100644 static/plan9-4e/man1/strip.1 create mode 100644 static/plan9-4e/man1/sum.1 create mode 100644 static/plan9-4e/man1/syscall.1 create mode 100644 static/plan9-4e/man1/tail.1 create mode 100644 static/plan9-4e/man1/tapefs.1 create mode 100644 static/plan9-4e/man1/tar.1 create mode 100644 static/plan9-4e/man1/tbl.1 create mode 100644 static/plan9-4e/man1/tcs.1 create mode 100644 static/plan9-4e/man1/tee.1 create mode 100644 static/plan9-4e/man1/tel.1 create mode 100644 static/plan9-4e/man1/test.1 create mode 100644 static/plan9-4e/man1/time.1 create mode 100644 static/plan9-4e/man1/touch.1 create mode 100644 static/plan9-4e/man1/tr.1 create mode 100644 static/plan9-4e/man1/troff.1 create mode 100644 static/plan9-4e/man1/troff2html.1 create mode 100644 static/plan9-4e/man1/tweak.1 create mode 100644 static/plan9-4e/man1/uniq.1 create mode 100644 static/plan9-4e/man1/units.1 create mode 100644 static/plan9-4e/man1/vac.1 create mode 100644 static/plan9-4e/man1/vi.1 create mode 100644 static/plan9-4e/man1/vnc.1 create mode 100644 static/plan9-4e/man1/vt.1 create mode 100644 static/plan9-4e/man1/wc.1 create mode 100644 static/plan9-4e/man1/who.1 create mode 100644 static/plan9-4e/man1/xd.1 create mode 100644 static/plan9-4e/man1/yacc.1 create mode 100644 static/plan9-4e/man1/yesterday.1 create mode 100644 static/plan9-4e/man2/0intro.2 create mode 100644 static/plan9-4e/man2/9p.2 create mode 100644 static/plan9-4e/man2/9pfid.2 create mode 100644 static/plan9-4e/man2/9pfile.2 create mode 100644 static/plan9-4e/man2/INDEX.2 create mode 100644 static/plan9-4e/man2/INDEX.html.2 create mode 100644 static/plan9-4e/man2/Makefile create mode 100644 static/plan9-4e/man2/abort.2 create mode 100644 static/plan9-4e/man2/abs.2 create mode 100644 static/plan9-4e/man2/access.2 create mode 100644 static/plan9-4e/man2/addpt.2 create mode 100644 static/plan9-4e/man2/aes.2 create mode 100644 static/plan9-4e/man2/allocimage.2 create mode 100644 static/plan9-4e/man2/arg.2 create mode 100644 static/plan9-4e/man2/arith3.2 create mode 100644 static/plan9-4e/man2/assert.2 create mode 100644 static/plan9-4e/man2/atof.2 create mode 100644 static/plan9-4e/man2/auth.2 create mode 100644 static/plan9-4e/man2/authsrv.2 create mode 100644 static/plan9-4e/man2/bin.2 create mode 100644 static/plan9-4e/man2/bind.2 create mode 100644 static/plan9-4e/man2/bio.2 create mode 100644 static/plan9-4e/man2/blowfish.2 create mode 100644 static/plan9-4e/man2/brk.2 create mode 100644 static/plan9-4e/man2/cachechars.2 create mode 100644 static/plan9-4e/man2/chdir.2 create mode 100644 static/plan9-4e/man2/cleanname.2 create mode 100644 static/plan9-4e/man2/color.2 create mode 100644 static/plan9-4e/man2/control.2 create mode 100644 static/plan9-4e/man2/cputime.2 create mode 100644 static/plan9-4e/man2/ctime.2 create mode 100644 static/plan9-4e/man2/ctype.2 create mode 100644 static/plan9-4e/man2/debugger.2 create mode 100644 static/plan9-4e/man2/des.2 create mode 100644 static/plan9-4e/man2/dial.2 create mode 100644 static/plan9-4e/man2/dirread.2 create mode 100644 static/plan9-4e/man2/disk.2 create mode 100644 static/plan9-4e/man2/draw.2 create mode 100644 static/plan9-4e/man2/dup.2 create mode 100644 static/plan9-4e/man2/elgamal.2 create mode 100644 static/plan9-4e/man2/encode.2 create mode 100644 static/plan9-4e/man2/encrypt.2 create mode 100644 static/plan9-4e/man2/errstr.2 create mode 100644 static/plan9-4e/man2/event.2 create mode 100644 static/plan9-4e/man2/exec.2 create mode 100644 static/plan9-4e/man2/exits.2 create mode 100644 static/plan9-4e/man2/exp.2 create mode 100644 static/plan9-4e/man2/fauth.2 create mode 100644 static/plan9-4e/man2/fcall.2 create mode 100644 static/plan9-4e/man2/fd2path.2 create mode 100644 static/plan9-4e/man2/fgetc.2 create mode 100644 static/plan9-4e/man2/flate.2 create mode 100644 static/plan9-4e/man2/floor.2 create mode 100644 static/plan9-4e/man2/fmtinstall.2 create mode 100644 static/plan9-4e/man2/fopen.2 create mode 100644 static/plan9-4e/man2/fork.2 create mode 100644 static/plan9-4e/man2/fprintf.2 create mode 100644 static/plan9-4e/man2/frame.2 create mode 100644 static/plan9-4e/man2/frexp.2 create mode 100644 static/plan9-4e/man2/fscanf.2 create mode 100644 static/plan9-4e/man2/fversion.2 create mode 100644 static/plan9-4e/man2/genrandom.2 create mode 100644 static/plan9-4e/man2/getcallerpc.2 create mode 100644 static/plan9-4e/man2/getenv.2 create mode 100644 static/plan9-4e/man2/getfcr.2 create mode 100644 static/plan9-4e/man2/getfields.2 create mode 100644 static/plan9-4e/man2/getpid.2 create mode 100644 static/plan9-4e/man2/getuser.2 create mode 100644 static/plan9-4e/man2/getwd.2 create mode 100644 static/plan9-4e/man2/graphics.2 create mode 100644 static/plan9-4e/man2/html.2 create mode 100644 static/plan9-4e/man2/httpd.2 create mode 100644 static/plan9-4e/man2/hypot.2 create mode 100644 static/plan9-4e/man2/intmap.2 create mode 100644 static/plan9-4e/man2/iounit.2 create mode 100644 static/plan9-4e/man2/ip.2 create mode 100644 static/plan9-4e/man2/isalpharune.2 create mode 100644 static/plan9-4e/man2/keyboard.2 create mode 100644 static/plan9-4e/man2/lock.2 create mode 100644 static/plan9-4e/man2/mach.2 create mode 100644 static/plan9-4e/man2/malloc.2 create mode 100644 static/plan9-4e/man2/matrix.2 create mode 100644 static/plan9-4e/man2/memdraw.2 create mode 100644 static/plan9-4e/man2/memlayer.2 create mode 100644 static/plan9-4e/man2/memory.2 create mode 100644 static/plan9-4e/man2/mktemp.2 create mode 100644 static/plan9-4e/man2/mouse.2 create mode 100644 static/plan9-4e/man2/mp.2 create mode 100644 static/plan9-4e/man2/muldiv.2 create mode 100644 static/plan9-4e/man2/nan.2 create mode 100644 static/plan9-4e/man2/ndb.2 create mode 100644 static/plan9-4e/man2/notify.2 create mode 100644 static/plan9-4e/man2/object.2 create mode 100644 static/plan9-4e/man2/open.2 create mode 100644 static/plan9-4e/man2/perror.2 create mode 100644 static/plan9-4e/man2/pipe.2 create mode 100644 static/plan9-4e/man2/plumb.2 create mode 100644 static/plan9-4e/man2/pool.2 create mode 100644 static/plan9-4e/man2/postnote.2 create mode 100644 static/plan9-4e/man2/prime.2 create mode 100644 static/plan9-4e/man2/print.2 create mode 100644 static/plan9-4e/man2/privalloc.2 create mode 100644 static/plan9-4e/man2/proto.2 create mode 100644 static/plan9-4e/man2/pushssl.2 create mode 100644 static/plan9-4e/man2/pushtls.2 create mode 100644 static/plan9-4e/man2/qball.2 create mode 100644 static/plan9-4e/man2/qsort.2 create mode 100644 static/plan9-4e/man2/quaternion.2 create mode 100644 static/plan9-4e/man2/quote.2 create mode 100644 static/plan9-4e/man2/rand.2 create mode 100644 static/plan9-4e/man2/rc4.2 create mode 100644 static/plan9-4e/man2/read.2 create mode 100644 static/plan9-4e/man2/readcolmap.2 create mode 100644 static/plan9-4e/man2/readv.2 create mode 100644 static/plan9-4e/man2/regexp.2 create mode 100644 static/plan9-4e/man2/remove.2 create mode 100644 static/plan9-4e/man2/rendezvous.2 create mode 100644 static/plan9-4e/man2/rsa.2 create mode 100644 static/plan9-4e/man2/rune.2 create mode 100644 static/plan9-4e/man2/runestrcat.2 create mode 100644 static/plan9-4e/man2/scribble.2 create mode 100644 static/plan9-4e/man2/scsi.2 create mode 100644 static/plan9-4e/man2/sechash.2 create mode 100644 static/plan9-4e/man2/seek.2 create mode 100644 static/plan9-4e/man2/segattach.2 create mode 100644 static/plan9-4e/man2/segbrk.2 create mode 100644 static/plan9-4e/man2/segflush.2 create mode 100644 static/plan9-4e/man2/setjmp.2 create mode 100644 static/plan9-4e/man2/sin.2 create mode 100644 static/plan9-4e/man2/sinh.2 create mode 100644 static/plan9-4e/man2/sleep.2 create mode 100644 static/plan9-4e/man2/stat.2 create mode 100644 static/plan9-4e/man2/strcat.2 create mode 100644 static/plan9-4e/man2/string.2 create mode 100644 static/plan9-4e/man2/stringsize.2 create mode 100644 static/plan9-4e/man2/subfont.2 create mode 100644 static/plan9-4e/man2/symbol.2 create mode 100644 static/plan9-4e/man2/thread.2 create mode 100644 static/plan9-4e/man2/time.2 create mode 100644 static/plan9-4e/man2/tmpfile.2 create mode 100644 static/plan9-4e/man2/wait.2 create mode 100644 static/plan9-4e/man2/window.2 create mode 100644 static/plan9-4e/man3/0intro.3 create mode 100644 static/plan9-4e/man3/INDEX.3 create mode 100644 static/plan9-4e/man3/INDEX.html.3 create mode 100644 static/plan9-4e/man3/Makefile create mode 100644 static/plan9-4e/man3/apm.3 create mode 100644 static/plan9-4e/man3/arch.3 create mode 100644 static/plan9-4e/man3/audio.3 create mode 100644 static/plan9-4e/man3/cap.3 create mode 100644 static/plan9-4e/man3/cons.3 create mode 100644 static/plan9-4e/man3/draw.3 create mode 100644 static/plan9-4e/man3/dup.3 create mode 100644 static/plan9-4e/man3/env.3 create mode 100644 static/plan9-4e/man3/ether.3 create mode 100644 static/plan9-4e/man3/floppy.3 create mode 100644 static/plan9-4e/man3/i82365.3 create mode 100644 static/plan9-4e/man3/ip.3 create mode 100644 static/plan9-4e/man3/kprof.3 create mode 100644 static/plan9-4e/man3/loopback.3 create mode 100644 static/plan9-4e/man3/lpt.3 create mode 100644 static/plan9-4e/man3/mnt.3 create mode 100644 static/plan9-4e/man3/mouse.3 create mode 100644 static/plan9-4e/man3/pipe.3 create mode 100644 static/plan9-4e/man3/pnp.3 create mode 100644 static/plan9-4e/man3/proc.3 create mode 100644 static/plan9-4e/man3/realtime.3 create mode 100644 static/plan9-4e/man3/root.3 create mode 100644 static/plan9-4e/man3/rtc.3 create mode 100644 static/plan9-4e/man3/sd.3 create mode 100644 static/plan9-4e/man3/segment.3 create mode 100644 static/plan9-4e/man3/srv.3 create mode 100644 static/plan9-4e/man3/ssl.3 create mode 100644 static/plan9-4e/man3/tls.3 create mode 100644 static/plan9-4e/man3/uart.3 create mode 100644 static/plan9-4e/man3/usb.3 create mode 100644 static/plan9-4e/man3/vga.3 create mode 100644 static/plan9-4e/man4/0intro.4 create mode 100644 static/plan9-4e/man4/INDEX.4 create mode 100644 static/plan9-4e/man4/INDEX.html.4 create mode 100644 static/plan9-4e/man4/Makefile create mode 100644 static/plan9-4e/man4/acme.4 create mode 100644 static/plan9-4e/man4/archfs.4 create mode 100644 static/plan9-4e/man4/cdfs.4 create mode 100644 static/plan9-4e/man4/cfs.4 create mode 100644 static/plan9-4e/man4/consolefs.4 create mode 100644 static/plan9-4e/man4/dossrv.4 create mode 100644 static/plan9-4e/man4/execnet.4 create mode 100644 static/plan9-4e/man4/exportfs.4 create mode 100644 static/plan9-4e/man4/factotum.4 create mode 100644 static/plan9-4e/man4/fs.4 create mode 100644 static/plan9-4e/man4/ftpfs.4 create mode 100644 static/plan9-4e/man4/import.4 create mode 100644 static/plan9-4e/man4/iostats.4 create mode 100644 static/plan9-4e/man4/keyfs.4 create mode 100644 static/plan9-4e/man4/kfs.4 create mode 100644 static/plan9-4e/man4/lnfs.4 create mode 100644 static/plan9-4e/man4/namespace.4 create mode 100644 static/plan9-4e/man4/nntpfs.4 create mode 100644 static/plan9-4e/man4/paqfs.4 create mode 100644 static/plan9-4e/man4/plumber.4 create mode 100644 static/plan9-4e/man4/ramfs.4 create mode 100644 static/plan9-4e/man4/ratfs.4 create mode 100644 static/plan9-4e/man4/rdbfs.4 create mode 100644 static/plan9-4e/man4/rio.4 create mode 100644 static/plan9-4e/man4/sacfs.4 create mode 100644 static/plan9-4e/man4/snap.4 create mode 100644 static/plan9-4e/man4/srv.4 create mode 100644 static/plan9-4e/man4/tapefs.4 create mode 100644 static/plan9-4e/man4/telco.4 create mode 100644 static/plan9-4e/man4/u9fs.4 create mode 100644 static/plan9-4e/man4/usb.4 create mode 100644 static/plan9-4e/man4/usbd.4 create mode 100644 static/plan9-4e/man4/vacfs.4 create mode 100644 static/plan9-4e/man4/webcookies.4 create mode 100644 static/plan9-4e/man4/webfs.4 create mode 100644 static/plan9-4e/man4/wikifs.4 create mode 100644 static/plan9-4e/man5/0intro.5 create mode 100644 static/plan9-4e/man5/INDEX.5 create mode 100644 static/plan9-4e/man5/INDEX.html.5 create mode 100644 static/plan9-4e/man5/Makefile create mode 100644 static/plan9-4e/man5/attach.5 create mode 100644 static/plan9-4e/man5/clunk.5 create mode 100644 static/plan9-4e/man5/error.5 create mode 100644 static/plan9-4e/man5/flush.5 create mode 100644 static/plan9-4e/man5/open.5 create mode 100644 static/plan9-4e/man5/read.5 create mode 100644 static/plan9-4e/man5/remove.5 create mode 100644 static/plan9-4e/man5/stat.5 create mode 100644 static/plan9-4e/man5/version.5 create mode 100644 static/plan9-4e/man5/walk.5 create mode 100644 static/plan9-4e/man6/0intro.6 create mode 100644 static/plan9-4e/man6/INDEX.6 create mode 100644 static/plan9-4e/man6/INDEX.html.6 create mode 100644 static/plan9-4e/man6/Makefile create mode 100644 static/plan9-4e/man6/a.out.6 create mode 100644 static/plan9-4e/man6/ar.6 create mode 100644 static/plan9-4e/man6/authsrv.6 create mode 100644 static/plan9-4e/man6/color.6 create mode 100644 static/plan9-4e/man6/face.6 create mode 100644 static/plan9-4e/man6/font.6 create mode 100644 static/plan9-4e/man6/image.6 create mode 100644 static/plan9-4e/man6/keyboard.6 create mode 100644 static/plan9-4e/man6/man.6 create mode 100644 static/plan9-4e/man6/map.6 create mode 100644 static/plan9-4e/man6/mpictures.6 create mode 100644 static/plan9-4e/man6/ms.6 create mode 100644 static/plan9-4e/man6/namespace.6 create mode 100644 static/plan9-4e/man6/ndb.6 create mode 100644 static/plan9-4e/man6/plot.6 create mode 100644 static/plan9-4e/man6/plumb.6 create mode 100644 static/plan9-4e/man6/regexp.6 create mode 100644 static/plan9-4e/man6/rewrite.6 create mode 100644 static/plan9-4e/man6/smtpd.6 create mode 100644 static/plan9-4e/man6/snap.6 create mode 100644 static/plan9-4e/man6/thumbprint.6 create mode 100644 static/plan9-4e/man6/users.6 create mode 100644 static/plan9-4e/man6/utf.6 create mode 100644 static/plan9-4e/man6/venti.conf.6 create mode 100644 static/plan9-4e/man6/vgadb.6 create mode 100644 static/plan9-4e/man7/0intro.7 create mode 100644 static/plan9-4e/man7/INDEX.7 create mode 100644 static/plan9-4e/man7/INDEX.html.7 create mode 100644 static/plan9-4e/man7/Makefile create mode 100644 static/plan9-4e/man7/astro.7 create mode 100644 static/plan9-4e/man7/dict.7 create mode 100644 static/plan9-4e/man7/juke.7 create mode 100644 static/plan9-4e/man7/map.7 create mode 100644 static/plan9-4e/man7/scat.7 create mode 100644 static/plan9-4e/man8/0intro.8 create mode 100644 static/plan9-4e/man8/9load.8 create mode 100644 static/plan9-4e/man8/9pcon.8 create mode 100644 static/plan9-4e/man8/INDEX.8 create mode 100644 static/plan9-4e/man8/INDEX.html.8 create mode 100644 static/plan9-4e/man8/Makefile create mode 100644 static/plan9-4e/man8/apm.8 create mode 100644 static/plan9-4e/man8/auth.8 create mode 100644 static/plan9-4e/man8/boot.8 create mode 100644 static/plan9-4e/man8/booting.8 create mode 100644 static/plan9-4e/man8/buildindex.8 create mode 100644 static/plan9-4e/man8/checkarenas.8 create mode 100644 static/plan9-4e/man8/checkindex.8 create mode 100644 static/plan9-4e/man8/cpurc.8 create mode 100644 static/plan9-4e/man8/cron.8 create mode 100644 static/plan9-4e/man8/dhcpd.8 create mode 100644 static/plan9-4e/man8/drawterm.8 create mode 100644 static/plan9-4e/man8/fmtarenas.8 create mode 100644 static/plan9-4e/man8/fmtindex.8 create mode 100644 static/plan9-4e/man8/fmtisect.8 create mode 100644 static/plan9-4e/man8/fs.8 create mode 100644 static/plan9-4e/man8/fsconfig.8 create mode 100644 static/plan9-4e/man8/httpd.8 create mode 100644 static/plan9-4e/man8/init.8 create mode 100644 static/plan9-4e/man8/ipconfig.8 create mode 100644 static/plan9-4e/man8/ipserv.8 create mode 100644 static/plan9-4e/man8/kfscmd.8 create mode 100644 static/plan9-4e/man8/listen.8 create mode 100644 static/plan9-4e/man8/lp.8 create mode 100644 static/plan9-4e/man8/mk9660.8 create mode 100644 static/plan9-4e/man8/mkfs.8 create mode 100644 static/plan9-4e/man8/mkpaqfs.8 create mode 100644 static/plan9-4e/man8/mksacfs.8 create mode 100644 static/plan9-4e/man8/mouse.8 create mode 100644 static/plan9-4e/man8/na.8 create mode 100644 static/plan9-4e/man8/ndb.8 create mode 100644 static/plan9-4e/man8/newuser.8 create mode 100644 static/plan9-4e/man8/nfsserver.8 create mode 100644 static/plan9-4e/man8/pcmcia.8 create mode 100644 static/plan9-4e/man8/ping.8 create mode 100644 static/plan9-4e/man8/plan9.ini.8 create mode 100644 static/plan9-4e/man8/ppp.8 create mode 100644 static/plan9-4e/man8/prep.8 create mode 100644 static/plan9-4e/man8/qer.8 create mode 100644 static/plan9-4e/man8/rdarena.8 create mode 100644 static/plan9-4e/man8/reboot.8 create mode 100644 static/plan9-4e/man8/replica.8 create mode 100644 static/plan9-4e/man8/scanmail.8 create mode 100644 static/plan9-4e/man8/scuzz.8 create mode 100644 static/plan9-4e/man8/secstore.8 create mode 100644 static/plan9-4e/man8/securenet.8 create mode 100644 static/plan9-4e/man8/snoopy.8 create mode 100644 static/plan9-4e/man8/stats.8 create mode 100644 static/plan9-4e/man8/swap.8 create mode 100644 static/plan9-4e/man8/timesync.8 create mode 100644 static/plan9-4e/man8/tlssrv.8 create mode 100644 static/plan9-4e/man8/udpecho.8 create mode 100644 static/plan9-4e/man8/update.8 create mode 100644 static/plan9-4e/man8/venti.8 create mode 100644 static/plan9-4e/man8/vga.8 (limited to 'static/plan9-4e') diff --git a/static/plan9-4e/Makefile b/static/plan9-4e/Makefile new file mode 100644 index 00000000..6c84e472 --- /dev/null +++ b/static/plan9-4e/Makefile @@ -0,0 +1,13 @@ +SUBDIRS = man1 \ + man2 \ + man3 \ + man4 \ + man5 \ + man6 \ + man7 \ + man8 + +export OS="Plan9 4th Edition" + +include ../subdir.mk + diff --git a/static/plan9-4e/man1/0intro.1 b/static/plan9-4e/man1/0intro.1 new file mode 100644 index 00000000..dd69caa4 --- /dev/null +++ b/static/plan9-4e/man1/0intro.1 @@ -0,0 +1,398 @@ +.TH INTRO 1 +.SH NAME +intro \- introduction to Plan 9 +.SH DESCRIPTION +Plan 9 is a distributed computing environment assembled from +separate machines acting as terminals, +CPU servers, and file servers. +A user works at a terminal, running a window system on a raster display. +Some windows are connected to CPU servers; the intent is that heavy computing +should be done in those windows but it is also possible to compute on the terminal. +A separate file server provides file storage for terminals and +CPU servers alike. +.SS Name Spaces +In Plan 9, almost all objects look like files. +The object retrieved by a given name is determined by a mapping called the +.IR name space . +A quick tour of the standard name space is in +.IR namespace (4). +Every program running in Plan 9 belongs to a +.I process group +(see +.I rfork +in +.IR fork (2)), +and the name space for each process group can be independently +customized. +.PP +A name space is hierarchically structured. +A full file name (also called a +.IR "full path name" ) +has the form +.IP +.RI / e1 / e2 /.../ en +.PP +This represents an object in a tree of files: the tree has a root, +represented by the first +.LR / ; +the root has a child file named +.IR e1 , +which in turn has child +.IR e2 , +and so on; the descendent +.I en +is the object represented by the path name. +.PP +There are a number of Plan 9 +.I services +available, each of which provides a tree of files. +A name space is built by +.I binding +services (or subtrees of services) to names in the name-space-so-far. +Typically, a user's home file server is bound to the root of the name space, +and other services are bound to conventionally named subdirectories. +For example, there is a service resident in the operating system for accessing +hardware devices and that is bound to +.B /dev +by convention. +Kernel services have names (outside the name space) that are a +.L # +sign followed by a single letter; +for example, +.B #c +is conventionally bound to +.BR /dev . +.PP +Plan 9 has +.IR "union directories" : +directories made of several directories all bound to the +same name. +The directories making up a union directory are ordered in a list. +When the bindings are made +(see +.IR bind (1)), +flags specify whether a newly bound member goes at the head or the tail of the list +or completely replaces the list. +To look up a name in a union directory, each member directory is searched +in list order until the name is found. +A bind +flag specifies whether file creation is allowed in a member directory: +a file created in the union directory goes in +the first member directory in list order that allows creation, if any. +.PP +The glue that holds Plan 9 together is a network protocol called +.IR 9P , +described in section 5 of this manual. +All Plan 9 servers read and respond to 9P requests to navigate through +a file tree and to perform operations such as reading and writing +files within the tree. +.SS Booting +When a terminal is powered on or reset, +it must be told the name of a file server to boot from, +the operating system kernel to boot, +and a user name and password. +How this dialog proceeds is environment- and machine-dependent. +Once it is complete, +the terminal loads a Plan 9 kernel, +which sets some environment variables (see +.IR env (3)) +and builds an initial name space. +See +.IR namespace (4), +.IR boot (8), +and +.IR init (8) +for details, but some important aspects of the initial name space are: +.IP \(bu +The environment variable +.B $cputype +is set to the name of the kernel's CPU's architecture: one of +.BR alpha , +.BR mips , +.BR sparc , +.B power +(Power PC), +.BR 386 +(386, 486, Pentium, ...) +etc. +The environment variable +.B $objtype +is initially the same as +.BR $cputype . +.IP \(bu +The environment variable +.B $terminal +is set to a description of the machine running the kernel, +such as +.BR "generic pc" . +Sometimes the middle word of +.B $terminal +encodes the file from which the kernel is booted; +e.g. +.B "alpha apc axp +is bootstrapped from +.BR /alpha/bapc . +.IP \(bu +The environment variable +.B $service +is set to +.BR terminal . +(Other ways of accessing Plan 9 may set +.B $service +to one of +.BR cpu , +.BR con , +or +.BR rx .) +.IP \(bu +The environment variable +.B $user +is set to the name of the user who booted the terminal. +The environment variable +.B $home +is set to that user's home directory. +.IP \(bu +.B /$cputype/bin +and +.B /rc/bin +are unioned into +.BR /bin . +.PD +.PP +After booting, the terminal runs the command interpreter, +.IR rc (1), +on +.B /usr/$user/lib/profile +after moving to the user's home directory. +.PP +Here is a typical profile: +.IP +.EX +bind -a $home/bin/rc /bin +bind -a $home/bin/$cputype /bin +bind -c $home/tmp /tmp +font = /lib/font/bit/pelm/euro.9.font +upas/fs +switch($service){ +case terminal + plumber + prompt=('term% ' ' ') + exec rio -f $font +case cpu + bind /mnt/term/dev/cons /dev/cons + bind /mnt/term/dev/consctl /dev/consctl + bind -a /mnt/term/mnt/wsys /dev + prompt=('cpu% ' ' ') + news +case con + prompt=('cpu% ' ' ') + news +} +.EE +.PD +.PP +The first three lines replace +.B /tmp +with a +.B tmp +in the user's home directory +and union personal +.B bin +directories with +.BR /bin , +to be searched after the standard +.B bin +directories. +The next starts the mail file system; see +.IR mail (1). +Then different things happen, depending on the +.B $service +environment variable, +such as running the window system +.IR rio (1) +on a terminal. +.PP +To do heavy work such as compiling, the +.IR cpu (1) +command connects a window to a CPU server; +the same environment variables are set (to different values) +and the same profile is run. +The initial directory is the current directory in the terminal window +where +.I cpu +was typed. +The value of +.B $service +will be +.BR cpu , +so the second arm of the profile switch is executed. +The root of the terminal's name space is accessible through +.BR /mnt/term , +so the +.I bind +is a way of making the window system's graphics interface (see +.IR draw (3)) +available to programs running on the CPU server. +The +.IR news (1) +command reports current Plan 9 affairs. +.PP +The third possible service type, +.BR con , +is set when the CPU server is called from a non-Plan-9 machine, +such as through +.I telnet +(see +.IR con (1)). +.SS Using Plan 9 +The user commands of Plan 9 are reminiscent of those in Research Unix, version 10. +There are a number of differences, however. +.PP +The standard shell is +.IR rc (1), +not the Bourne shell. +The most noticeable differences appear only when programming and macro processing. +.PP +The character-delete character is backspace, and the line-kill character is +control-U; these cannot be changed. +.PP +DEL is the interrupt character: typing it sends an interrupt to processes running in that window. +See +.IR keyboard (6) +for instructions on typing characters like DEL on the various keyboards. +.PP +If a program dies with something like an address error, it enters a `Broken' +state. It lingers, available for debugging with +.IR db (1) +or +.IR acid (1). +.I Broke +(see +.IR kill (1)) +cleans up broken processes. +.PP +The standard editor is one of +.IR acme (1) +or +.IR sam (1). +There is a variant of +.I sam +that permits running the file-manipulating part of +.I sam +on a non-Plan-9 system: +.IP +.EX +sam -r tcp!kremvax +.EE +.PP +For historical reasons, +.I sam +uses a tab stop setting of 8 spaces, while the other editors and window systems use 4 spaces. +These defaults can be overridden by setting the value of the environment variable +.B $tabstop +to the desired number of spaces per tab. +.PP +Machine names may be prefixed by the network name, +here +.BR tcp ; +.B il +for the Plan 9 Internet protocol and +.B net +for the system default. +.PP +Login connections and remote execution on non-Plan-9 machines are usually +done by saying, for example, +.IP +.EX +con kremvax +.EE +.PP +or +.IP +.EX +rx deepthought chess +.EE +.PP +(see +.IR con (1)). +.PP +.I 9fs +connects to file systems of remote systems +(see +.IR srv (4)). +For example, +.IP +.EX +9fs kremvax +.EE +.PP +sets things up so that the root of +.BR kremvax 's +file tree is visible locally in +.BR /n/kremvax . +.PP +.IR Faces (1) +gives graphical notification of arriving mail. +.PP +The Plan 9 file server has an integrated backup facility. +The command +.IP +.EX +9fs dump +.EE +.PP +binds to +.B /n/dump +a tree containing the daily backups on the file server. +The dump tree has years as top level file names, and month-day +as next level file names. +For example, +.B /n/dump/2000/0120 +is the root of the file system as it appeared at dump time on +January 20, 2000. +If more than one dump is taken on the same day, dumps after +the first have an extra digit. +To recover the version of this file as it was on June 15, 1999, +.IP +.EX +cp /n/dump/1999/0615/sys/man/1/0intro . +.EE +.PP +or use +.IR yesterday (1). +.SH SEE ALSO +This section for general publicly accessible commands. +.br +Section (2) for library functions, including system calls. +.br +Section (3) for kernel devices (accessed via +.IR bind (1)). +.br +Section (4) for file services (accessed via +.IR mount ). +.br +Section (5) for the Plan 9 file protocol. +.br +Section (6) for file formats. +.br +Section (7) for databases and database access programs. +.br +Section (8) for things related to administering Plan 9. +.br +.B /sys/doc +for copies of papers referenced in this manual. +.PP +The back of this volume has a permuted index to aid searches. +.SH DIAGNOSTICS +Upon termination each program returns a string called the +.IR "exit status" . +It was either supplied by a call to +.IR exits (2) +or was written to the command's +.BI /proc/ pid /note +file +(see +.IR proc (3)), +causing an abnormal termination. +The empty string is customary for successful execution; +a non-empty string gives a clue to the failure of the command. diff --git a/static/plan9-4e/man1/2a.1 b/static/plan9-4e/man1/2a.1 new file mode 100644 index 00000000..30d3e076 --- /dev/null +++ b/static/plan9-4e/man1/2a.1 @@ -0,0 +1,55 @@ +.TH 2A 1 +.SH NAME +0a, 1a, 2a, 4a, 5a, 6a, 7a, 8a, 9a, ka, qa, va, xa \- assemblers +.SH SYNOPSIS +.B 2a +[ +.I option ... +] +[ +.I name ... +] +.br +etc. +.SH DESCRIPTION +These programs +assemble the named files into object files +for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 0 , +.RB 1 , +etc.) that specifies it. +The assemblers handle the most common C preprocessor directives and the associated +command-line options +.BR -D +and +.BR -I . +Other options are: +.TP +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input path name, +strip any trailing +.BR .s , +and append +.RI . O , +where +.I O +is first letter of the assembler's name. +.SH FILES +The directory +.B /sys/include +is searched for include files after +machine-dependent files in +.BR /$objtype/include . +.SH SOURCE +.BR /sys/src/cmd/2a , +etc. +.SH SEE ALSO +.IR 2c (1), +.IR 2l (1). +.PP +Rob Pike, ``A manual for the Plan 9 assembler'' diff --git a/static/plan9-4e/man1/2c.1 b/static/plan9-4e/man1/2c.1 new file mode 100644 index 00000000..4be23f5e --- /dev/null +++ b/static/plan9-4e/man1/2c.1 @@ -0,0 +1,398 @@ +.TH 2C 1 +.SH NAME +0c, 1c, 2c, 4c, 5c, 6c, 7c, 8c, 9c, kc, qc, vc, xc \- C compilers +.SH SYNOPSIS +.B 2c +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands compile the named C +.I files +into object files for the corresponding architecture. +Associated with each compiler is a string +.IR objtype : +.TP 1.5i +.B "0c spim +little-endian MIPS 4000 family +.TP +.B "1c 68000 +Motorola MC68000 +.TP +.B "2c 68020 +Motorola MC68020 +.TP +.B "4c mips2 +big-endian MIPS 4000 family +.TP +.B "5c arm +ARM 7500 +.TP +.B "6c 960 +Intel i960 +.TP +.B "7c alpha +Digital Alpha APX +.TP +.B "8c 386 +Intel i386, i486, Pentium, etc. +.TP +.B "9c 29000 +AMD 29000 family +.TP +.B "kc sparc +Sun SPARC +.TP +.B "qc power +Power PC, +.TP +.B "vc mips +big-endian MIPS 3000 family +.TP +.B "xc 3210 +AT&T DSP 3210. +.PP +The compilers handle most preprocessing directives themselves; a complete +preprocessor is available in +.IR cpp (1), +which must be run separately. +.PP +Let the first letter of the compiler name be +.IR O = +.BR 0 , +.BR 1 , +.BR 2 , +.BR 4 , +.BR 5 , +.BR 6 , +.BR 7 , +.BR 8 , +.BR 9 , +.BR k , +.BR q , +.BR v , +or +.BR x . +The output object files end in +.RI . O . +The letter is also the prefix of related programs: +.IB O a +is the assembler, +.IB O l +is the loader. +Plan 9 conventionally sets the +.B $objtype +environment variable to the +.I objtype +string appropriate to the current machine's type. +Plan 9 also conventionally has +.RI / objtype +directories, which contain among other things: +.BR include , +for machine-dependent include files; +.BR lib , +for public object code libraries; +.BR bin , +for public programs; +and +.BR mkfile , +for preconditioning +.IR mk (1). +.PP +The compiler options are: +.TP 1i +.BI -o " obj" +Place output in file +.I obj +(allowed only if there is just one input file). +Default is to take the last element of the input file name, +strip any trailing +.BR .c , +and append +.RI . O . +.TP +.B -w +Print warning messages about unused variables, etc. +.TP +.B -B +Accept functions without a new-style +ANSI C function prototype. +By default, the compilers reject functions +used without a defined prototype, +although ANSI C permits them. +.TP +.BI -D\*S name=def +.br +.ns +.TP +.BI -D \*Sname +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -F +Enable type-checking of calls to +.IR print (2) +and other formatted print routines. See the discussion +of extensions, below. +.TP +.BI -I \*Sdir +An +.L #include +file whose name does not begin with +slash +or is enclosed in double quotes +is always +sought first in the directory +of the +.I file +argument. If this fails, or the name is enclosed in +.BR <> , +it is then sought +in directories named in +.B -I +options, +then in +.BR /sys/include , +and finally in +.BR /$objtype/include . +.TP +.B -N +Suppress automatic registerization and optimization. +.TP +.B -S +Print an assembly language version of the object code +on standard output as well as generating the +.RI . O +file. +.TP +.B -V +By default, the compilers are non-standardly lax about type equality between +.B void* +values and other pointers; this flag requires ANSI C conformance. +.TP +.B -p +Invoke a standard ANSI C preprocessor before compiling. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except suppress information about structures +declared in included header files. +.PP +The compilers support several extensions to ANSI C: +.TP +\- +A structure or union may contain unnamed substructures and subunions. +The fields of the substructures or +subunions can then be used as if they were members of the parent +structure or union (the resolution of a name conflict is unspecified). +When a pointer to the outer structure or union is used in a context +that is only legal for the unnamed substructure, the compiler promotes +the type and adjusts the pointer value to point at the substructure. +If the unnamed structure or union is of a type with a tag name specified by a +.B typedef +statement, +the unnamed structure or union can be explicitly referenced +by .. +.TP +\- +A structure value can be formed with an expression such as +.EX + (struct S){v1, v2, v3} +.EE +where the list elements are values for the fields of struct +.BR S . +.TP +\- +Array initializers can specify the indices of the array in square +brackets, as +.EX + int a[] = { [3] 1, [10] 5 }; +.EE +which initializes the third and tenth elements of the eleven-element array +.BR a . +.TP +\- +Structure initializers can specify the structure element by using the name +following a period, as +.EX + int struct { int x; int y; } s = { .y 1, .x 5 }; +.EE +which initializes elements +.B y +and then +.B x +of the structure +.BR s . +These forms also accept the new ANSI C notation, which includes an equal sign: +.EX + int a[] = { [3] = 1, [10] = 5 }; + int struct { int x; int y; } s = { .y = 1, .x = 5 }; +.EE +.TP +\- +A global variable can be dedicated to a register +by declaring it +.B "extern register" +in +.I all +modules and libraries. +.TP +\- +A +.B #pragma +of the form +.EX + #pragma lib "libbio.a" +.EE +records that the program needs to be loaded with file +.BR /$objtype/lib/libbio.a ; +such lines, typically placed in library header files, obviate the +.B -l +option of the loaders. To help identify files in non-standard directories, +within the file names in the +.B #pragmas +the string +.B $M +represents the name of the architecture +(e.g., +.BR mips ) +and +.B $O +represents its identifying character +(e.g., +.BR v ). +.TP +\- +A +.B #pragma +of the form +.EX + #pragma varargck argpos error 2 +.EE +tells the compiler that the second argument to +.B error +is a +.BR print -like +format string (see +.IR print (2)) +that identifies the handling of subsequent arguments. +The +.B #pragma +.EX + #pragma varargck type "s" char* +.EE +says that the format verb +.B s +processes an argument of type +.BR char *. +The +.B #pragma +.EX + #pragma varargck flag 'c' +.EE +says that +.B c +is a flag character. +These +.B #pragmas +are used, if the +.B -F +option is enabled, to type-check calls to +.B print +and other such routines. +.TP +\- +The C++ comment +.RB ( // +to end of line) +is accepted as well as the normal +convention of +.B /* +.BR */ . +.TP +\- +The compilers accept +.B long +.B long +variables as a 64-bit type. +The standard header typedefs this to +.BR vlong . +Arithmetic on +.B vlong +values is usually emulated by a run-time library. +.SH EXAMPLE +For the 68020, produce a program +.B prog +from C files +.BR main.c +and +.BR sub.c : +.IP +.EX +2c -FVw main.c sub.c +2l -o prog main.2 sub.2 +.EE +.SH FILES +.TF /$objtype/include +.TP +.B /sys/include +system area for machine-independent +.B #include +directives. +.TP +.B /$objtype/include +system area for machine-dependent +.B #include +directives. +.SH SOURCE +.TF /sys/src/cmd/2c,\ etc. +.TP +.B /sys/src/cmd/cc +machine-independent part +.TP +.BR /sys/src/cmd/2c ,\ etc. +machine-dependent part +.SH "SEE ALSO" +.IR 2a (1), +.IR 2l (1), +.IR cpp (1), +.IR mk (1), +.IR nm (1), +.IR pcc (1), +.IR db (1), +.IR acid (1), +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' +.SH BUGS +The i960 compiler has been used only to program one I/O controller +and is certainly buggy. +.PP +The default preprocessor only handles +.LR #define , +.LR #include , +.LR #undef , +.LR #ifdef , +.LR #line , +and +.LR #ifndef . +For a full ANSI preprocessor, use +the +.B p +option. diff --git a/static/plan9-4e/man1/2l.1 b/static/plan9-4e/man1/2l.1 new file mode 100644 index 00000000..3fb70e74 --- /dev/null +++ b/static/plan9-4e/man1/2l.1 @@ -0,0 +1,193 @@ +.TH 2L 1 +.SH NAME +0l, 1l, 2l, 4l, 5l, 6l, 7l, 8l, 9l, kl, ql, vl, xl \- loaders +.SH SYNOPSIS +.B 2l +[ +.I option ... +] +[ +.I file ... +] +.br +etc. +.SH DESCRIPTION +These commands +load the named +.I files +into executable files for the corresponding architectures; see +.IR 2c (1) +for the correspondence between an architecture and the character +.RB ( 0 , +.RB 1 , +etc.) that specifies it. +The files should be object files or libraries (archives of object files) +for the appropriate architecture. +Also, a name like +.BI -l ext +represents the library +.BI lib ext .a +in +.BR /$objtype/lib , +where +.I objtype +is one of +.BR 68000 , +etc. as listed in +.IR 2c (1). +The libraries must have tables of contents +(see +.IR ar (1)). +.PP +In practice, +.B -l +options are rarely necessary as the header files for +the libraries cause their archives to be included automatically in the load +(see +.IR 2c (1)). +For example, any program that includes header file +.B libc.h +causes the loader +to search the C library +.BR /$objtype/lib/libc.a . +Also, the loader creates an undefined symbol +.B _main +(or +.B _mainp +if profiling is enabled) to force loading of the +startup linkage from the C library. +.PP +The order of search to resolve undefined symbols is to load all files and libraries +mentioned explicitly on the command line, and then to resolve remaining symbols +by searching in topological order +libraries mentioned in header files included by files already loaded. +When scanning such libraries, the algorithm is to scan each library repeatedly until +no new undefined symbols are picked up, then to start on the next library. Thus if library +.I A +needs +.I B +which needs +.I A +again, it may be necessary to mention +.I A +explicitly so it will be read a second time. +.PP +The loader options are: +.TP 1i +.B -l +(As a bare option.) +Suppress the default loading of the startup linkage and libraries +specified by header files. +.TP +.BI -o " out" +Place output in file +.IR out . +Default is +.IB O .out\f1, +where +.I O +is the first letter of the loader name. +.TP +.B -p +Insert profiling code into the executable output; no special action is needed +during compilation or assembly. +.TP +.B -s +Strip the symbol tables from the output file. +.TP +.B -a +Print the object code in assembly language, with addresses. +.TP +.B -v +Print debugging output that annotates the activities of the load. +.TP +.BI -c function +.RI ( Xl +only) Place the +.I function +in the internal RAM of the DSP3210. +.TP +.BI -M +.RI ( Kl +only) Generate instructions rather than calls to emulation routines +for multiply and divide. +.TP +.BI -m size +.RI ( Xl +only) Use +.I size +(default 0, maximum 8192) +bytes of internal RAM of the DSP3210 for functions and small data items. +.TP +.BI -E symbol +The entry point for the binary is +.I symbol +(default +.BR _main ; +.B _mainp +under +.BR -p ). +.TP +.BI -H n +Executable header is type +.IR n . +The meaning of the types is architecture-dependent; typically +type 1 is Plan 9 boot format and type 2 is the +regular Plan 9 format, the default. These are reversed on the MIPS. +The Next boot format is 3. Type 4 in +.I vl +creates a MIPS executable for an SGI Unix system. +.TP +.BI -T t +The text segment starts at address +.IR t . +.TP +.BI -D d +The data segment starts at address +.IR d . +.TP +.BI -R r +The text segment is rounded to a multiple of +.I r +(if +.I r +is nonzero). +.PP +The numbers in the above options can begin with +.L 0x +or +.L 0 +to change the default base from decimal to hexadecimal or octal. +The defaults for the values depend on the compiler and the +header type. +.PP +The loaded image has several symbols inserted by the loader: +.B etext +is the address of the end of the text segment; +.B bdata +is the address of the beginning of the data segment; +.B edata +is the address of the end of the data segment; +and +.B end +is the address of the end of the bss segment, and of the program. +.SH FILES +.TF /$objtype/lib +.TP +.B /$objtype/lib +for +.BI -l lib +arguments. +.SH SOURCE +.B /sys/src/cmd/2l +etc. +.SH "SEE ALSO" +.IR 2c (1), +.IR 2a (1), +.IR ar (1), +.IR nm (1), +.IR db (1), +.IR prof (1) +.PP +Rob Pike, +``How to Use the Plan 9 C Compiler'' diff --git a/static/plan9-4e/man1/INDEX.1 b/static/plan9-4e/man1/INDEX.1 new file mode 100644 index 00000000..eccc8cae --- /dev/null +++ b/static/plan9-4e/man1/INDEX.1 @@ -0,0 +1,291 @@ +0intro 0intro +intro 0intro +0a 2a +1a 2a +2a 2a +4a 2a +5a 2a +6a 2a +7a 2a +8a 2a +9a 2a +ka 2a +qa 2a +va 2a +xa 2a +0c 2c +1c 2c +2c 2c +4c 2c +5c 2c +6c 2c +7c 2c +8c 2c +9c 2c +kc 2c +qc 2c +vc 2c +xc 2c +0l 2l +1l 2l +2l 2l +4l 2l +5l 2l +6l 2l +7l 2l +8l 2l +9l 2l +kl 2l +ql 2l +vl 2l +xl 2l +aan aan +acid acid +trump acid +truss acid +acme acme +awd acme +win acme +ar ar +ascii ascii +unicode ascii +awk awk +basename basename +bc bc +bind bind +mount bind +unmount bind +bitsyload bitsyload +keyboard bitsyload +light bitsyload +params bitsyload +pencal bitsyload +prompter bitsyload +bundle bundle +cal cal +calendar calendar +cat cat +read cat +chgrp chgrp +chmod chmod +cleanname cleanname +cmp cmp +colors colors +getmap colors +comm comm +con con +rx con +telnet con +xmr con +xms con +cp cp +mv cp +cpp cpp +cpu cpu +crop crop +iconv crop +clock date +date date +db db +dc dc +dd dd +delatex deroff +deroff deroff +diff diff +doc2txt doc2txt +mswordstrings doc2txt +olefs doc2txt +doctype doctype +du du +echo echo +ed ed +emacs emacs +eqn eqn +faces faces +seemail faces +vwhois faces +factor factor +primes factor +file file +fmt fmt +htmlfmt fmt +fortune fortune +freq freq +grap grap +graph graph +grep grep +gs gs + +bunzip2 gzip +bzip2 gzip +gunzip gzip +gzip gzip +unzip gzip +zip gzip +hget hget +history history +hoc hoc +idiff idiff +join join +gif jpg +jpg jpg +png jpg +ppm jpg +togif jpg +topng jpg +toppm jpg +broke kill +kill kill +slay kill +ktrace ktrace +leak leak +lens lens +lex lex +look look +lp lp +lc ls +ls ls +aliasmail mail +biff mail +deliver mail +filter mail +fs mail +list mail +mail mail +marshal mail +ml mail +mlmgr mail +mlowner mail +nedmail mail +pop3 mail +send mail +smtp mail +smtpd mail +token mail +vf mail +vwhois mail +lookman man +man man +mc mc +membername mk +mk mk +mkdir mkdir +html2ms ms2html +ms2html ms2html +netstat netstat +news news +nm nm +ns ns +p p +page page +iam passwd +netkey passwd +passwd passwd +pcc pcc +pic pic +tpic pic +pipefile pipefile +plot plot +plumb plumb +pr pr +kprof prof +prof prof +tprof prof +proof proof +ps ps +psu ps +pbd pwd +pwd pwd +. rc +cd rc +eval rc +exec rc +exit rc +flag rc +rc rc +rfork rc +shift rc +wait rc +whatis rc +~ rc +changes replica +pull replica +push replica +replica replica +scan replica +resample resample +label rio +rio rio +window rio +wloc rio +rm rm +rtstats rtstats +B sam +sam sam +sam.save sam +aescbc secstore +secstore secstore +sed sed +seq seq +size size +sleep sleep +sort sort +spell spell +sprog spell +spin spin +split split +src src +scp ssh +ssh ssh +ssh_genkey ssh +sshnet ssh +sshserve ssh +start stop +stop stop +strings strings +strip strip +md5sum sum +sha1sum sum +sum sum +syscall syscall +tail tail +32vfs tapefs +cpiofs tapefs +tapefs tapefs +tapfs tapefs +tarfs tapefs +tpfs tapefs +v10fs tapefs +v6fs tapefs +tar tar +tbl tbl +tcs tcs +tee tee +iwhois tel +ppq tel +tel tel +test test +time time +touch touch +tr tr +nroff troff +troff troff +troff2html troff2html +tweak tweak +uniq uniq +units units +vac vac +0i vi +5i vi +ki vi +vi vi +vnc vnc +vncs vnc +vncv vnc +vt vt +wc wc +who who +whois who +xd xd +yacc yacc +yesterday yesterday diff --git a/static/plan9-4e/man1/INDEX.html.1 b/static/plan9-4e/man1/INDEX.html.1 new file mode 100644 index 00000000..dad882ad --- /dev/null +++ b/static/plan9-4e/man1/INDEX.html.1 @@ -0,0 +1,561 @@ + +plan 9 man section 1 + + +[manual index] +

Plan 9 from Bell Labs - Section 1 - Commands

+
+
+
0intro +- introduction to Plan 9 +
intro + +
2a +- assemblers +
0a, 1a, 2a, 4a, 5a, 6a, 7a, 8a, 9a, ka, qa, va, xa + +
2c +- C compilers +
0c, 1c, 2c, 4c, 5c, 6c, 7c, 8c, 9c, kc, qc, vc, xc + +
2l +- loaders +
0l, 1l, 2l, 4l, 5l, 6l, 7l, 8l, 9l, kl, ql, vl, xl + +
aan +- always available network +
aan + +
acid +- debugger +
acid, truss, trump + +
acme +- interactive text windows +
acme, win, awd + +
ar +- archive and library maintainer +
ar + +
ascii +- interpret ASCII, Unicode characters +
ascii, unicode + +
awk +- pattern-directed scanning and processing language +
awk + +
basename +- strip file name affixes +
basename + +
bc +- arbitrary-precision arithmetic language +
bc + +
bind +- change name space +
bind, mount, unmount + +
bitsyload +- bitsy-specific utilities +
bitsyload, light, pencal, keyboard, params, prompter + +
bundle +- collect files for distribution +
bundle + +
cal +- print calendar +
cal + +
calendar +- print upcoming events +
calendar + +
cat +- catenate files +
cat, read + +
chgrp +- change file group +
chgrp + +
chmod +- change mode +
chmod + +
cleanname +- clean a path name +
cleanname + +
cmp +- compare two files +
cmp + +
colors +- display color map +
getmap, colors + +
comm +- select or reject lines common to two sorted files +
comm + +
con +- remote login, execution, and XMODEM file transfer +
con, telnet, rx, xms, xmr + +
cp +- copy, move files +
cp, mv + +
cpp +- C language preprocessor +
cpp + +
cpu +- connection to cpu server +
cpu + +
crop +- frame, crop, and convert image +
crop, iconv + +
date +- date and time +
date, clock + +
db +- debugger +
db + +
dc +- desk calculator +
dc + +
dd +- convert and copy a file +
dd + +
deroff +- remove formatting requests +
deroff, delatex + +
diff +- differential file comparator +
diff + +
doc2txt +- extract printable strings from Microsoft Word documents +
doc2txt, olefs, mswordstrings + +
doctype +- intuit command line for formatting a document +
doctype + +
du +- disk usage +
du + +
echo +- print arguments +
echo + +
ed +- text editor +
ed + +
emacs +- editor macros +
emacs + +
eqn +- typeset mathematics +
eqn + +
faces +- mailbox interface +
faces, seemail, vwhois + +
factor +- factor a number, generate large primes +
factor, primes + +
file +- determine file type +
file + +
fmt +- simple text formatters +
fmt, htmlfmt + +
fortune +- sample lines from a file +
fortune + +
freq +- print histogram of character frequencies +
freq + +
grap +- pic preprocessor for drawing graphs +
grap + +
graph +- draw a graph +
graph + +
grep +- search a file for a pattern +
grep + +
gs +- Aladdin Ghostscript (PostScript and PDF language interpreter) +
gs + +
gzip +- compress and expand data +
gzip, gunzip, bzip2, bunzip2, zip, unzip, + +
hget +- retrieve a web page corresponding to a url +
hget + +
history +- print file names from the dump +
history + +
hoc +- interactive floating point language +
hoc + +
idiff +- interactive diff +
idiff + +
join +- relational database operator +
join + +
jpg +- view and convert pictures +
jpg, gif, png, ppm, togif, toppm, topng + +
kill +- print commands to kill processes +
kill, slay, broke + +
ktrace +- interpret kernel stack dumps +
ktrace + +
leak +- examine family of processes for memory leaks +
leak + +
lens +- interactive screen magnifier +
lens + +
lex +- generator of lexical analysis programs +
lex + +
look +- find lines in a sorted list +
look + +
lp +- printer output +
lp + +
ls +- list contents of directory +
ls, lc + +
mail +- mail commands +
mail, marshal, nedmail, send, aliasmail, smtp, smtpd, vwhois, filter, fs, biff, pop3, ml, mlmgr, mlowner, list, deliver, token, vf + +
man +- print or find pages of this manual +
man, lookman + +
mc +- multicolumn print +
mc + +
mk +- maintain (make) related files +
mk, membername + +
mkdir +- make a directory +
mkdir + +
ms2html +- convert between troff's ms macros and html +
ms2html, html2ms + +
netstat +- summarize network connections +
netstat + +
news +- print news items +
news + +
nm +- name list (symbol table) +
nm + +
ns +- display name space +
ns + +
p +- paginate +
p + +
page +- view FAX, image, graphic, PostScript, PDF, and typesetter output files +
page + +
passwd +- change user password +
passwd, netkey, iam + +
pcc +- APE C compiler driver +
pcc + +
pic +- troff and tex preprocessors for drawing pictures +
pic, tpic + +
pipefile +- attach filter to file in name space +
pipefile + +
plot +- graphics filter +
plot + +
plumb +- send message to plumber +
plumb + +
pr +- print file +
pr + +
prof +- display profiling data +
prof, tprof, kprof + +
proof +- troff output interpreter +
proof + +
ps +- process status +
ps, psu + +
pwd +- working directory +
pwd, pbd + +
rc +- command language +
rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ + +
replica +- client-server replica management +
changes, pull, push, scan + +
resample +- resample a picture +
resample + +
rio +- window system +
rio, label, window, wloc + +
rm +- remove files +
rm + +
rtstats +- show real-time process behavior +
rtstats + +
sam +- screen editor with structural regular expressions +
sam, B, sam.save + +
secstore +- secstore commands +
aescbc, secstore + +
sed +- stream editor +
sed + +
seq +- print sequences of numbers +
seq + +
size +- print size of executable files +
size + +
sleep +- suspend execution for an interval +
sleep + +
sort +- sort and/or merge files +
sort + +
spell +- find spelling errors +
spell, sprog + +
spin +- verification tool for concurrent systems +
spin + +
split +- split a file into pieces +
split + +
src +- find source code for executable +
src + +
ssh +- secure login and file copy from/to Unix or Plan 9 +
ssh, sshnet, scp, sshserve, ssh_genkey + +
stop +- print commands to stop and start processes +
stop, start + +
strings +- extract printable strings +
strings + +
strip +- remove symbols from binary files +
strip + +
sum +- sum and count blocks in a file +
sum, md5sum, sha1sum + +
syscall +- test a system call +
syscall + +
tail +- deliver the last part of a file +
tail + +
tapefs +- mount archival file systems +
32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs + +
tar +- archiver +
tar + +
tbl +- format tables for nroff or troff +
tbl + +
tcs +- translate character sets +
tcs + +
tee +- pipe fitting +
tee + +
tel +- look in phone book +
tel, ppq, iwhois + +
test +- set status according to condition +
test + +
time +- time a command +
time + +
touch +- set modification date of a file +
touch + +
tr +- translate characters +
tr + +
troff +- text formatting and typesetting +
troff, nroff + +
troff2html +- convert troff output into HTML +
troff2html + +
tweak +- edit image files, subfont files, face files, etc. +
tweak + +
uniq +- report repeated lines in a file +
uniq + +
units +- conversion program +
units + +
vac +- create a vac archive on Venti +
vac + +
vi +- instruction simulators +
0i, 5i, ki, vi + +
vnc +- remote frame buffer server and viewer for Virtual Network Computing (VNC) +
vncs, vncv + +
vt +- emulate a VT-100 or VT-220 terminal +
vt + +
wc +- word count +
wc + +
who +- who is using the machine +
who, whois + +
xd +- hex, octal, decimal, or ASCII dump +
xd + +
yacc +- yet another compiler-compiler +
yacc + +
yesterday +- print file names from the dump +
yesterday + +
diff --git a/static/plan9-4e/man1/Makefile b/static/plan9-4e/man1/Makefile new file mode 100644 index 00000000..31e80e19 --- /dev/null +++ b/static/plan9-4e/man1/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.1) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man1/aan.1 b/static/plan9-4e/man1/aan.1 new file mode 100644 index 00000000..a55bfd4e --- /dev/null +++ b/static/plan9-4e/man1/aan.1 @@ -0,0 +1,88 @@ +.TH AAN 1 +.SH NAME +aan \- always available network +.SH SYNOPSIS +.B aan +[ +.B -d +] +[ +.B -c +] +[ +.B -m maxto +] +.I dialstring +| +handle +.SH DESCRIPTION +.I Aan +tunnels traffic between a client and a server through a persistent +network connection. If the connection breaks (voluntarily or +due to networking problems), the aan client re-establishes the +connection by redialing the server. +.PP +.I Aan +uses a unique protocol to make sure no data is ever lost even +when the connection breaks. +After a reconnection, +.I aan +retransmits all unacknowledged data between client and server. +.PP +A connection can be broken voluntarily (e.g. by roaming over IP networks), +or a connection can break when the IP service is unreliable. +In either case +.I aan +re-establishes the client's connection automatically. +.PP +When the server part has not heard from the client in +.I maxto +seconds, the server part of +.I aan +exits. The default +.I maxto +is one day. +The client side (option +.BR -c ) +calls the server by its +.IR dialstring , +while +the server side listens on +.IR handle . +.PP +.I Aan +is usually run automatically through the +.B -p +option of +.IR import (4). +.SH EXAMPLE +Assume the server part of aan is encapsulated in exportfs on the +machine +.B sob +and started through +.B aux/listen +as follows: +.IP +.EX +netdir=`{echo $3 | sed 's;/[0-9]+$;!*!0;'} +exec exportfs -a -A $netdir +.EE +.PP +Then machine +.BR astro6 's +name space can be imported through +.I aan +using this command: +.IP +.EX +import -p /net/tcp!astro6 / /mnt/term +.EE +.SH FILES +.TP +.B /sys/log/aan +Log file +.SH SOURCE +.B /sys/src/cmd/aan.c +.SH SEE ALSO +.IR import (4), +.IR exportfs (4) diff --git a/static/plan9-4e/man1/acid.1 b/static/plan9-4e/man1/acid.1 new file mode 100644 index 00000000..624c0140 --- /dev/null +++ b/static/plan9-4e/man1/acid.1 @@ -0,0 +1,472 @@ +.TH ACID 1 +.SH NAME +acid, truss, trump \- debugger +.SH SYNOPSIS +.B acid +[ +.BI -l " libfile +] +[ +.B -wq +] [ +.B -m +.I machine +] [ +.I pid +] +[ +.I textfile +] +.PP +.B acid +.B -l +.B truss +.I textfile +.PP +.B acid +.B -l +.B trump +[ +.I pid +] +[ +.I textfile +] +.SH DESCRIPTION +.I Acid +is a programmable symbolic debugger. +It can inspect one or more processes that share an address space. +A program to be debugged may be specified by the process id of +a running or defunct process, +or by the name of the program's text file +.RB ( 8.out +by default). +At the prompt, +.I acid +will store function definitions or print the value of expressions. +Options are +.TP .9i +.B -w +Allow the textfile to be modified. +.TP +.B -q +Don't print variable renamings at startup. +.TP +.BI -l " library +Load from +.I library +at startup; see below. +.TP +.BI -m " machine +Assume instructions are for the given CPU type +(one of +.BR 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 +the CPU type. +.TP +.BI -k +Debug the kernel state for the process, rather than the user state. +.PP +At startup, +.I acid +obtains standard function definitions from the library file +.BR /sys/lib/acid/port , +architecture-dependent functions from +.BR /sys/lib/acid/$objtype , +user-specified functions from +.BR $home/lib/acid , +and further functions from +.B -l +files. +Definitions in any file may override previously defined functions. +If the function +.IR acidinit () +is defined, it will be invoked after all modules have been loaded. +See +.IR 2c (1) +for information about creating +.I acid +functions for examining data structures. +.SS Language +Symbols of the program being debugged become integer +variables whose values are addresses. +Contents of addresses are obtained by indirection. +Local variables are qualified by +function name, for example +.BR main:argv . +When program symbols conflict with +.I acid +words, distinguishing +.B $ +signs are prefixed. +Such renamings are reported at startup; option +.B -q +suppresses them. +.PP +Variable types +.RI ( "integer, float, list, string" ) +and formats are inferred from assignments. +Truth values false/true are attributed to zero/nonzero +integers or floats and to empty/nonempty lists or strings. +Lists are sequences of expressions surrounded by +.BR {\^} +and separated by commas. +.PP +Expressions are much as in C, +but yield both a value and a format. +Casts to complex types are allowed. +Lists admit the following operators, with +subscripts counted from 0. +.IP +.BI head " list +.br +.BI tail " list +.br +.BI append " list", " element +.br +.BI delete " list", " subscript +.PP +Format codes are the same as in +.IR db (1). +Formats may be attached to (unary) expressions with +.BR \e , +e.g. +.BR (32*7)\eD . +There are two indirection operators, +.B * +to address a core image, +.B @ +to address a text file. +The type and format of the result are determined by the format of the operand, +whose type must be integer. +.PP +Statements are +.IP +.BI if " expr " then " statement " "\fR[ \fPelse\fI statement \fR] +.br +.BI while " expr " do " statement +.br +.BI loop " expr" , " expr " do " statement +.br +.BI defn " name" ( args ") {" " statement \fP} +.br +.BI local " name +.br +.BI return " expr +.br +.BR whatis " [ \fI name \fP] +.PP +Here is a partial list of functions; see the manual for a complete list. +.TF asm(address) +.TP +.B stk() +Print a stack trace for current process. +.TP +.B lstk() +Print a stack trace with values of local variables. +.TP +.B gpr() +Print general registers. +Registers can also be accessed by name, for example +.BR *R0 . +.TP +.B spr() +Print special registers such as program counter and stack pointer. +.TP +.B fpr() +Print floating-point registers. +.TP +.B regs() +Same as +.BR spr();gpr() . +.TP +.BI fmt( expr , format ) +Expression +.I expr +with format given by the character value of expression +.IR format . +.TP +.BI src( address ) +Print 10 lines of source around the program address. +.TP +.BI Bsrc( address ) +Get the source line for the program address +into a window of a running +.IR sam (1) +and select it. +.TP +.BI line( address ) +Print source line nearest to the program address. +.TP +.B source() +List current source directories. +.TP +.BI addsrcdir( string ) +Add a source directory to the list. +.TP +.BI filepc( where ) +Convert a string of the form +.IB sourcefile : linenumber +to a machine address. +.TP +.BI pcfile( address ) +Convert a machine address to a source file name. +.TP +.BI pcline( address ) +Convert a machine address to a source line number. +.TP +.BI bptab() +List breakpoints set in the current process. +.TP +.BI bpset( address ) +Set a breakpoint in the current process at the given address. +.TP +.BI bpdel( address ) +Delete a breakpoint from the current process. +.TP +.B cont() +Continue execution of current process and wait for it to stop. +.TP +.B step() +Execute a single machine instruction in the current process. +.TP +.B func() +Step repeatedly until after a function return. +.TP +.BI stopped( pid ) +This replaceable function is called automatically when the given process +stops. +It normally prints the program counter and returns to the prompt. +.TP +.BI asm( address ) +Disassemble 30 machine instructions beginning at the given address. +.TP +.BI mem( address , string ) +Print a block of memory +interpreted according to a string of format codes. +.TP +.BI dump( address , n , string\fP) +Like +.BR mem (), +repeated for +.I n +consecutive blocks. +.TP +.BI print( expr , ... ) +Print the values of the expressions. +.TP +.BI newproc( arguments ) +Start a new process with arguments given as a string +and halt at the first instruction. +.TP +.B new() +Like +.IR newproc (), +but take arguments (except +.BR argv[0] ) +from string variable +.BR progargs . +.TP +.B win() +Like +.IR new (), +but run the process in a separate window. +.TP +.BI start( pid ) +Start a stopped process. +.TP +.BI kill( pid ) +Kill the given process. +.TP +.BI setproc( pid ) +Make the given process current. +.TP +.BI rc( string ) +Escape to the shell, +.IR rc (1), +to execute the command string. +.SS Libraries +There are a number of +.I acid +`libraries' that provide higher-level debugging facilities. Two notable +examples are +.I truss +and +.IR trump , +which use +.I acid +to trace system calls +.RI ( truss ) +and memory allocation +.RI ( trump ). +Both require starting +.I acid +on the program, either by attaching to a running process or by +executing +.B new() +on a binary (perhaps after setting +.BR progargs ), +stopping the process, and then running +.B truss() +or +.B trump() +to execute the program under the scaffolding. +The output will be a trace of the system calls +.RI ( truss ) +or memory allocation and free calls +.RI ( trump ) +executed by the program. +When finished tracing, stop the process and execute +.B untruss() +or +.B untrump() +followed by +.B cont() +to resume execution. +.SH EXAMPLES +Start to debug +.BR /bin/ls ; +set some breakpoints; run up to the first one: +.IP +.EX +% acid /bin/ls +/bin/ls: mips plan 9 executable +/sys/lib/acid/port +/sys/lib/acid/mips +acid: new() +70094: system call _main ADD $-0x14,R29 +70094: breakpoint main+0x4 MOVW R31,0x0(R29) +acid: pid +70094 +acid: argv0 = **main:argv\es +acid: whatis argv0 +integer variable format s +acid: *argv0 +/bin/ls +acid: bpset(ls) +acid: cont() +70094: breakpoint ls ADD $-0x16c8,R29 +acid: +.EE +.PP +Display elements of a linked list of structures: +.IP +.EX +complex Str { 'D' 0 val; 'X' 4 next; }; +complex Str s; +s = *headstr; +while s != 0 do{ + print(s.val, "\en"); + s = s.next; +} +.EE +.PP +Note the use of the +.B . +operator instead of +.BR -> . +.PP +Display an array of bytes declared in C as +.BR "char array[]" . +.IP +.EX +*(array\es) +.EE +.PP +This example gives +.B array +string format, then prints the string beginning at the address (in +.I acid +notation) +.BR *array . +.PP +Trace the system calls executed by +.IR ls (1): +.IP +.EX +% acid -l truss /bin/ls +/bin/ls:386 plan 9 executable + +/sys/lib/acid/port +/sys/lib/acid/kernel +/sys/lib/acid/truss +/sys/lib/acid/386 +acid: progargs = "-l lib/profile" +acid: new() +acid: truss() +open("#c/pid", 0) + return value: 3 +pread(3, 0x7fffeeac, 20, -1) + return value: 12 + data: " 166 " +\&... +stat("lib/profile", 0x0000f8cc, 113) + return value: 65 +open("/env/timezone", 0) + return value: 3 +pread(3, 0x7fffd7c4, 1680, -1) + return value: 1518 + data: "EST -18000 EDT -14400 + 9943200 25664400 41392800 57718800 73447200 89168400 + 104896800 ..." +close(3) + return value: 0 +pwrite(1, "--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile +", 54, -1) +--rw-rw-r-- M 9 rob rob 2519 Mar 22 10:29 lib/profile + return value: 54 +\&... +166: breakpoint _exits+0x5 INTB $0x40 +acid: cont() +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.br +.B /sys/lib/acid/$objtype +.br +.B /sys/lib/acid/port +.br +.B /sys/lib/acid/kernel +.br +.B /sys/lib/acid/trump +.br +.B /sys/lib/acid/truss +.br +.B $home/lib/acid +.SH SOURCE +.B /sys/src/cmd/acid +.SH "SEE ALSO" +.IR 2a (1), +.IR 2c (1), +.IR 2l (1), +.IR mk (1), +.IR db (1) +.br +Phil Winterbottom, +``Acid Manual''. +.SH DIAGNOSTICS +At termination, kill commands are proposed +for processes that are still active. +.SH BUGS +There is no way to redirect the standard input and standard output +of a new process. +.br +Source line selection near the beginning of a file may pick +an adjacent file. +.br +With the extant stepping commands, one cannot step through instructions +outside the text segment and it is hard to debug across process forks. diff --git a/static/plan9-4e/man1/acme.1 b/static/plan9-4e/man1/acme.1 new file mode 100644 index 00000000..5cae0036 --- /dev/null +++ b/static/plan9-4e/man1/acme.1 @@ -0,0 +1,683 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -c +.I ncol +] +[ +.B -b +] +[ +.B -l +.I file +| +.I file +\&... ] +.LP +.B win +[ +.I command +] +.LP +.B awd +[ +.I label +] +.SH DESCRIPTION +.I Acme +manages windows of text that may be edited interactively or by external programs. +The interactive interface uses the keyboard and mouse; external programs +use a set of files served by +.IR acme ; +these are discussed in +.IR acme (4). +.PP +Any named +.I files +are read into +.I acme +windows before +.I acme +accepts input. +With the +.B -l +option, the state of the entire system is loaded +from +.IR file , +which should have been created by a +.B Dump +command (q.v.), +and subsequent +.I file +names are ignored. +Plain files display as text; directories display as columnated lists of the +names of their components, as in +.B "ls -p directory|mc +except that the names of subdirectories have a slash appended. +.PP +The +.B -f +.RB ( -F ) +option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); +the default is +.B /lib/font/bit/lucidasans/euro.8.font +.RB ( \&.../lucm/unicode.9.font ). +Tab intervals are set to the width of 4 (or the value of +.BR $tabstop ) +numeral zeros in the appropriate font. +.PP +.SS Windows +.I Acme +windows are in two parts: a one-line +.I tag +above a multi-line +.IR body . +The body typically contains an image of a file, as in +.IR sam (1), +or the output of a +program, as in an +.IR rio (1) +window. +The tag contains a number of +blank-separated words, followed by a vertical bar character, followed by anything. +The first word is the name of the window, typically the name of the associated +file or directory, and the other words are commands available in that window. +Any text may be added after the bar; examples are strings to search for or +commands to execute in that window. +Changes to the text left of the bar will be ignored, +unless the result is to change the name of the +window. +.PP +If a window holds a directory, the name (first word of the tag) will end with +a slash. +.SS Scrolling +Each window has a scroll bar to the left of the body. +The scroll bar behaves much as in +.IR sam (1) +or +.IR rio (1) +except that scrolling occurs when the button is pressed, rather than released, +and continues +as long as the mouse button is held down in the scroll bar. +For example, to scroll slowly through a file, +hold button 3 down near the top of the scroll bar. Moving the mouse +down the scroll bar speeds up the rate of scrolling. +.SS Layout +.I Acme +windows are arranged in columns. By default, it creates two columns when starting; +this can be overridden with the +.B -c +option. +Placement is automatic but may be adjusted +using the +.I layout box +in the upper left corner of each window and column. +Pressing and holding any mouse button in the box drags +the associated window or column. +For windows, just +clicking in the layout box grows the window in place: button 1 +grows it a little, button 2 grows it as much as it can, still leaving all other +tags in that column visible, and button 3 takes over the column completely, +temporarily hiding other windows in the column. +(They will return +.I en masse +if any of them needs attention.) +The layout box in a window is normally white; when it is black in the center, +it records that the file is `dirty': +.I Acme +believes it is modified from its original +contents. +.PP +Tags exist at the top of each column and across the whole display. +.I Acme +pre-loads them with useful commands. +Also, the tag across the top maintains a list of executing long-running commands. +.SS Typing +The behavior of typed text is similar to that in +.IR rio (1) +except that the characters are delivered to the tag or body under the mouse; there is no +`click to type'. +(The experimental option +.B -b +causes typing to go to the most recently clicked-at or made window.) +The usual backspacing conventions apply. +As in +.IR sam (1) +but not +.IR rio , +the ESC key selects the text typed since the last mouse action, +a feature particularly useful when executing commands. +A side effect is that typing ESC with text already selected is identical +to a +.B Cut +command +.RI ( q.v. ). +.PP +Most text, including the names of windows, may be edited uniformly. +The only exception is that the command names to the +left of the bar in a tag are maintained automatically; changes to them are repaired +by +.IR acme . +.SS "Directory context +Each window's tag names a directory: explicitly if the window +holds a directory; implicitly if it holds a regular file +(e.g. the directory +.B /adm +if the window holds +.BR /adm/users ). +This directory provides a +.I context +for interpreting file names in that window. +For example, the string +.B users +in a window labeled +.B /adm/ +or +.B /adm/keys +will be interpreted as the file name +.BR /adm/users . +The directory is defined purely textually, so it can be a non-existent +directory or a real directory associated with a non-existent file +(e.g. +.BR /adm/not-a-file ). +File names beginning with a slash +are assumed to be absolute file names. +.SS Errors +Windows whose names begin with +.B - +or +.B + +conventionally hold diagnostics and other data +not directly associated with files. +A window labeled +.B +Errors +receives all diagnostics produced by +.I acme +itself. +Diagnostics from commands run by +.I acme +appear in a window named +.IB directory /+Errors +where +.I directory +is identified by the context of the command. +These error windows are created when needed. +.SS "Mouse button 1 +Mouse button 1 selects text just as in +.IR sam (1) +or +.IR rio (1) , +including the usual double-clicking conventions. +.SS "Mouse button 2 +By an +action similar to selecting text with button 1, +button 2 indicates text to execute as a command. +If the indicated text has multiple white-space-separated words, +the first is the command name and the second and subsequent +are its arguments. +If button 2 is `clicked'\(emindicates a null string\(em\c +.I acme +.I expands +the indicated text to find a command to run: +if the click is within button-1-selected text, +.I acme +takes that selection as the command; +otherwise it takes the largest string of valid file name characters containing the click. +Valid file name characters are alphanumerics and +.B _ +.B . +.B - +.B + +.BR / . +This behavior is similar to double-clicking with button 1 but, +because a null command is meaningless, only a single click is required. +.PP +Some commands, all by convention starting with a capital letter, are +.I built-ins +that are executed directly by +.IR acme : +.TP +.B Cut +Delete most recently selected text and place in snarf buffer. +.TP +.B Del +Delete window. If window is dirty, instead print a warning; a second +.B Del +will succeed. +.TP +.B Delcol +Delete column and all its windows, after checking that windows are not dirty. +.TP +.B Delete +Delete window without checking for dirtiness. +.TP +.B Dump +Write the state of +.I acme +to the file name, if specified, or +.B $home/acme.dump +by default. +.TP +.B Edit +Treat the argument as a text editing command in the style of +.IR sam (1). +The full +.B Sam +language is implemented except for the commands +.BR k , +.BR n , +.BR q , +and +.BR ! . +The +.B = +command is slightly different: it includes the file name and +gives only the line address unless the command is explicitly +.BR =# . +The `current window' for the command is the body of the window in which the +.B Edit +command is executed. +Usually the +.B Edit +command would be typed in a tag; longer commands may be prepared in a +scratch window and executed, with +.B Edit +itself in the current window, using the 2-1 chord described below. +.TP +.B Exit +Exit +.I acme +after checking that windows are not dirty. +.TP +.B Font +With no arguments, change the font of the associated window from fixed-spaced to +proportional-spaced or +.I vice +.IR versa . +Given a file name argument, change the font of the window to that stored in the named file. +If the file name argument is prefixed by +.B var +.RB ( fix ), +also set the default proportional-spaced (fixed-spaced) font for future use to that font. +Other existing windows are unaffected. +.TP +.B Get +Load file into window, replacing previous contents (after checking for dirtiness as in +.BR Del ). +With no argument, use the existing file name of the window. +Given an argument, use that file but do not change the window's file name. +.TP +.B ID +Print window ID number +.RI ( q.v. ). +.TP +.B Incl +When opening `include' files +(those enclosed in +.BR <> ) +with button 3, +.I acme +searches in directories +.B /$objtype/include +and +.BR /sys/include . +.B Incl +adds its arguments to a supplementary list of include directories, analogous to +the +.B -I +option to the compilers. +This list is per-window and is inherited when windows are created by actions in that window, so +.I Incl +is most usefully applied to a directory containing relevant source. +With no arguments, +.I Incl +prints the supplementary list. +This command is largely superseded by plumbing +(see +.IR plumb (6)). +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.TP +.B Local +When prefixed to a command +run the +command in the same file name space and environment variable group as +.IR acme . +The environment of the command +is restricted but is sufficient to run +.IR bind (1), +.IR 9fs +(see +.IR srv (4)), +.IR import (4), +etc., +and to set environment variables such as +.BR $objtype . +.TP +.B Load +Restore the state of +.I acme +from a file (default +.BR $home/acme.dump ) +created by the +.B Dump +command. +.TP +.B Look +Search in body for occurrence of literal text indicated by the argument or, +if none is given, by the selected text in the body. +.TP +.B New +Make new window. With arguments, load the named files into windows. +.TP +.B Newcol +Make new column. +.TP +.B Paste +Replace most recently selected text with contents of snarf buffer. +.TP +.B Put +Write window to the named file. +With no argument, write to the file named in the tag of the window. +.TP +.B Putall +Write all dirty windows whose names indicate existing regular files. +.TP +.B Redo +Complement of +.BR Undo . +.TP +.B Send +Append selected text or snarf buffer to end of body; used mainly with +.IR win . +.TP +.B Snarf +Place selected text in snarf buffer. +.TP +.B Sort +Arrange the windows in the column from top to bottom in lexicographical +order based on their names. +.TP +.B Tab +Set the width of tab stops for this window to the value of the argument, in units of widths of the zero +character. +With no arguments, it prints the current value. +.TP +.B Undo +Undo last textual change or set of changes. +.TP +.B Zerox +Create a copy of the window containing most recently selected text. +.PP +A common place to store text for commands is in the tag; in fact +.I acme +maintains a set of commands appropriate to the state of the window +to the left of the bar in the tag. +.PP +If the text indicated with button 2 is not a recognized built-in, it is executed as +a shell command. For example, indicating +.B date +with button 2 runs +.IR date (1). +The standard +and error outputs of commands are sent to the error window associated with +the directory from which the command was run, which will be created if +necessary. +For example, in a window +.B /adm/users +executing +.B pwd +will produce the output +.B /adm +in a (possibly newly-created) window labeled +.BR /adm/+Errors ; +in a window containing +.B /sys/src/cmd/sam/sam.c +executing +.B mk +will run +.IR mk (1) +in +.BR /sys/src/cmd/sam , +producing output in a window labeled +.BR /sys/src/cmd/sam/+Errors . +The environment of such commands contains the variable +.B $% +with value set to the filename of the window in which the command is run. +.SS "Mouse button 3 +Pointing at text with button 3 instructs +.I acme +to locate or acquire the file, string, etc. described by the indicated text and +its context. +This description follows the actions taken when +button 3 is released after sweeping out some text. +In the description, +.I text +refers to the text of the original sweep or, if it was null, the result of +applying the same expansion rules that apply to button 2 actions. +.PP +If the text names an existing window, +.I acme +moves the mouse cursor to the selected text in the body of that window. +If the text names an existing file with no associated window, +.I acme +loads the file into a new window and moves the mouse there. +If the text is a file name contained in angle brackets, +.I acme +loads the indicated include file from the directory appropriate to the +suffix of the file name of the window holding the text. +(The +.B Incl +command adds directories to the standard list.) +.PP +If the text begins with a colon, it is taken to be an address, in +the style of +.IR sam (1), +within the body of the window containing the text. +The address is evaluated, the resulting text highlighted, and the mouse moved to it. +Thus, in +.IR acme , +one must type +.B :/regexp +or +.B :127 +not just +.B /regexp +or +.BR 127 . +(There is an easier way to locate literal text; see below.) +.PP +If the text is a file name followed by a colon and an address, +.I acme +loads the file and evaluates the address. For example, clicking button 3 anywhere +in the text +.B file.c:27 +will open +.BR file.c , +select line +27, and put the mouse at the beginning of the line. The rules about Error +files, directories, and so on all combine to make this an efficient way to +investigate errors from compilers, etc. +.PP +If the text is not an address or file, it is taken to +be literal text, which is then searched for in the body of the window +in which button 3 was clicked. If a match is found, it is selected and the mouse is +moved there. Thus, to search for occurrences of a word in a file, +just click button 3 on the word. Because of the rule of using the +selection as the button 3 action, subsequent clicks will find subsequent +occurrences without moving the mouse. +.PP +In all these actions, the mouse motion is not done if the text is a null string +within a non-null selected string in the tag, so that (for example) complex regular expressions +may be selected and applied repeatedly to the +body by just clicking button 3 over them. +.SS "Chords of mouse buttons +Several operations are bound to multiple-button actions. +After selecting text, with button 1 still down, pressing button 2 +executes +.B Cut +and button 3 executes +.BR Paste . +After clicking one button, the other undoes +the first; thus (while holding down button 1) 2 followed by 3 is a +.B Snarf +that leaves the file undirtied; +3 followed by 2 is a no-op. +These actions also apply to text selected by double-clicking because +the double-click expansion is made when the second +click starts, not when it ends. +.PP +Commands may be given extra arguments by a mouse chord with buttons 2 and 1. +While holding down button 2 on text to be executed as a command, clicking button 1 +appends the text last pointed to by button 1 as a distinct final argument. +For example, to search for literal +.B text +one may execute +.B Look text +with button 2 or instead point at +.B text +with button 1 in any window, release button 1, +then execute +.BR Look , +clicking button 1 while 2 is held down. +.PP +When an external command (e.g. +.IR echo (1)) +is executed this way, the extra argument is passed as expected and an +environment variable +.B $acmeaddr +is created that holds, in the form interpreted by button 3, +the fully-qualified address of the extra argument. +.SS "Support programs +.I Win +creates a new +.I acme +window and runs a +.I command +(default +.BR /bin/rc ) +in it, turning the window into something analogous to an +.IR rio (1) +window. +Executing text in a +.I win +window with button +2 is similar to using +.BR Send . +.PP +.I Awd +loads the tag line of its window with the directory in which it's running, suffixed +.BI - label +(default +.BR rc ); +it is +intended to be executed by a +.B cd +function for use in +.I win +windows. An example definition is +.EX + fn cd { builtin cd $1 && awd $sysname } +.EE +.SS "Applications and guide files +In the directory +.B /acme +live several subdirectories, each corresponding to a program or +set of related programs that employ +.I acme's +user interface. +Each subdirectory includes source, binaries, and a +.B readme +file for further information. +It also includes a +.BR guide , +a text file holding sample commands to invoke the programs. +The idea is to find an example in the guide that best matches +the job at hand, edit it to suit, and execute it. +.PP +Whenever a command is executed by +.IR acme , +the default search path includes the directory of the window containing +the command and its subdirectory +.BR $cputype . +The program directories in +.B /acme +contain appropriately labeled subdirectories of binaries, +so commands named +in the guide files will be found automatically when run. +Also, +.I acme +binds the directories +.B /acme/bin +and +.B /acme/bin/$cputype +to the end of +.B /bin +when it starts; this is where +.IR acme -specific +programs such as +.I win +and +.I awd +reside. +.SH FILES +.TF $home/acme.dump +.TP +.B $home/acme.dump +default file for +.B Dump +and +.BR Load ; +also where state is written if +.I acme +dies or is killed unexpectedly, e.g. by deleting its window. +.TP +.B /acme/*/guide +template files for applications +.TP +.B /acme/*/readme +informal documentation for applications +.TP +.B /acme/*/src +source for applications +.TP +.B /acme/*/mips +MIPS-specific binaries for applications +.SH SOURCE +.B /sys/src/cmd/acme +.br +.B /acme/bin/source/win +.br +.B /sys/src/cmd/awd.c +.SH SEE ALSO +.IR acme (4) +.br +Rob Pike, +.I +Acme: A User Interface for Programmers. +.SH BUGS +With the +.B -l +option or +.B Load +command, +the recreation of windows under control of external programs +such as +.I win +is just to rerun the command; information may be lost. diff --git a/static/plan9-4e/man1/ar.1 b/static/plan9-4e/man1/ar.1 new file mode 100644 index 00000000..a01604db --- /dev/null +++ b/static/plan9-4e/man1/ar.1 @@ -0,0 +1,183 @@ +.TH AR 1 +.SH NAME +ar \- archive and library maintainer +.SH SYNOPSIS +.B ar +.I key +[ +.I posname +] +.I afile +[ +.I file ... +] +.SH DESCRIPTION +.I Ar +maintains groups of files +combined into a single archive file, +.IR afile . +try this out +The main use of +.I ar +is to create and update library files for the loaders +.IR 2l (1), +etc. +It can be used, though, for any similar purpose. +.PP +.I Key +is one character from the set +.BR drqtpmx , +optionally concatenated with +one or more of +.BR vuaibclo . +The +.I files +are constituents of the archive +.IR afile . +The meanings of the +.I key +characters are: +.TP +.B d +Delete +.I files +from the archive file. +.TP +.B r +Replace +.I files +in the archive file, or add them if missing. +Optional modifiers are +.RS +.PD0 +.TP +.B u +Replace only files with +modified dates later than that of +the archive. +.TP +.B a +Place new files after +.I posname +in the archive rather than at the end. +.TP +.BR b " or " i +Place new files before +.I posname +in the archive. +.RE +.PD +.TP +.B q +Quick. Append +.I files +to the end of the archive without checking for duplicates. +Avoids quadratic behavior in +.LR "for (i in *.v) ar r lib.a $i" . +.TP +.B t +List a table of contents of the archive. +If names are given, only those files are listed. +.TP +.B p +Print the named files in the archive. +.TP +.B m +Move the named files to the end or elsewhere, +specified as with +.LR r . +.TP +.B o +Preserve the access and modification times of files +extracted with the +.B x +command. +.TP +.B x +Extract the named files. +If no names are given, all files in the archive are +extracted. +In neither case does +.B x +alter the archive file. +.TP +.B v +Verbose. +Give a file-by-file +description of the making of a +new archive file from the old archive and the constituent files. +With +.BR p , +precede each file with a name. +With +.BR t , +give a long listing of all information about the files, +somewhat like a listing by +.IR ls (1), +showing +.br +.ns +.IP +.B + mode uid/gid size date name +.TP +.B c +Create. +Normally +.I ar +will create a new archive when +.I afile +does not exist, and give a warning. +Option +.B c +discards any old contents and suppresses the warning. +.TP +.B l +Local. +Normally +.I ar +places its temporary files in the directory +.BR /tmp . +This option causes them to be placed in the local directory. +.PP +When a +.BR d , +.BR r , +or +.BR m +.I key +is specified and all members of the archive are valid object files for +the same architecture, +.I ar +inserts a table of contents, required by the loaders, at +the front of the library. +The table of contents is +rebuilt whenever the archive is modified, except +when the +.B q +.I key +is specified or when the table of contents is +explicitly moved or deleted. +.SH EXAMPLE +.TP +.L +ar cr lib.a *.v +Replace the contents of library +.L lib.a +with the object files in the current directory. +.SH FILES +.TF /tmp/vxxxx +.TP +.B /tmp/v* +temporaries +.SH SOURCE +.B /sys/src/cmd/ar.c +.SH "SEE ALSO" +.IR 2l (1), +.IR ar (6) +.SH BUGS +If the same file is mentioned twice in an argument list, +it may be put in the archive twice. +.br +This command predates Plan 9 and makes some invalid assumptions, +for instance that user id's are numeric. diff --git a/static/plan9-4e/man1/ascii.1 b/static/plan9-4e/man1/ascii.1 new file mode 100644 index 00000000..47fd3550 --- /dev/null +++ b/static/plan9-4e/man1/ascii.1 @@ -0,0 +1,161 @@ +.TH ASCII 1 +.SH NAME +ascii, unicode \- interpret ASCII, Unicode characters +.SH SYNOPSIS +.B ascii +[ +.B -8 +] +[ +.BI -oxdb n +] +[ +.B -nct +] +[ +.I text +] +.PP +.B unicode +[ +.B -nt +] +.IB hexmin - hexmax +.PP +.B unicode +[ +.B -t +] +.I hex +[ +\&... +] +.PP +.B unicode +[ +.B -n +] +.I characters +.PP +.B look +.I hex +.B /lib/unicode +.SH DESCRIPTION +.I Ascii +prints the +.SM ASCII +values corresponding to characters and +.I vice +.IR versa ; +under the +.B -8 +option, the +.SM ISO +Latin-1 extensions (codes 0200-0377) are included. +The values are interpreted in a settable numeric base; +.B -o +specifies octal, +.B -d +decimal, +.B -x +hexadecimal (the default), and +.BI -b n +base +.IR n . +.PP +With no arguments, +.I ascii +prints a table of the character set in the specified base. +Characters of +.I text +are converted to their +.SM ASCII +values, one per line. If, however, the first +.I text +argument is a valid number in the specified base, conversion +goes the opposite way. +Control characters are printed as two- or three-character mnemonics. +Other options are: +.TP +.B -n +Force numeric output. +.TP +.B -c +Force character output. +.TP +.B -t +Convert from numbers to running text; do not interpret +control characters or insert newlines. +.PP +.I Unicode +is similar; it converts between +.SM UTF +and character values from the Unicode Standard (see +.IR utf (6)). +If given a range of hexadecimal numbers, +.I unicode +prints a table of the specified Unicode characters \(em their values and +.SM UTF +representations. +Otherwise it translates from +.SM UTF +to numeric value or vice versa, +depending on the appearance of the supplied text; +the +.B -n +option forces numeric output to avoid ambiguity with numeric characters. +If converting to +.SM UTF , +the characters are printed one per line unless the +.B -t +flag is set, in which case the output is a single string +containing only the specified characters. +Unlike +.IR ascii , +.I unicode +treats no characters specially. +.PP +The output of +.I ascii +and +.I unicode +may be unhelpful if the characters printed are not available in the current font. +.PP +The file +.B /lib/unicode +contains a +table of characters and descriptions, sorted in hexadecimal order, +suitable for +.IR look (1) +on the lower case +.I hex +values of characters. +.SH EXAMPLES +.TP +.B "ascii -d" +Print the +.SM ASCII +table base 10. +.TP +.B "unicode p" +Print the hex value of `p'. +.TP +.B "unicode 2200-22f1" +Print a table of miscellaneous mathematical symbols. +.TP +.B "look 039 /lib/unicode" +See the start of the Greek alphabet's encoding in the Unicode Standard. +.SH FILES +.TF /lib/unicode +.TP +.B /lib/unicode +table of characters and descriptions. +.SH SOURCE +.B /sys/src/cmd/ascii.c +.br +.B /sys/src/cmd/unicode.c +.SH "SEE ALSO" +.IR look (1) +.IR tcs (1), +.IR utf (6), +.IR font (6) diff --git a/static/plan9-4e/man1/awk.1 b/static/plan9-4e/man1/awk.1 new file mode 100644 index 00000000..a0ea5e41 --- /dev/null +++ b/static/plan9-4e/man1/awk.1 @@ -0,0 +1,527 @@ +.TH AWK 1 +.SH NAME +awk \- pattern-directed scanning and processing language +.SH SYNOPSIS +.B awk +[ +.BI -F fs +] +[ +.BI -v +.I var=value +] +[ +.BI -mr n +] +[ +.BI -mf n +] +[ +.B -f +.I prog +[ +.I prog +] +[ +.I file ... +] +.SH DESCRIPTION +.I Awk +scans each input +.I file +for lines that match any of a set of patterns specified literally in +.IR prog +or in one or more files +specified as +.B -f +.IR file . +With each pattern +there can be an associated action that will be performed +when a line of a +.I file +matches the pattern. +Each line is matched against the +pattern portion of every pattern-action statement; +the associated action is performed for each matched pattern. +The file name +.L - +means the standard input. +Any +.IR file +of the form +.I var=value +is treated as an assignment, not a file name, +and is executed at the time it would have been opened if it were a file name. +The option +.B -v +followed by +.I var=value +is an assignment to be done before +.I prog +is executed; +any number of +.B -v +options may be present. +.B \-F +.IR fs +option defines the input field separator to be the regular expression +.IR fs . +.PP +An input line is normally made up of fields separated by white space, +or by regular expression +.BR FS . +The fields are denoted +.BR $1 , +.BR $2 , +\&..., while +.B $0 +refers to the entire line. +If +.BR FS +is null, the input line is split into one field per character. +.PP +To compensate for inadequate implementation of storage management, +the +.B \-mr +option can be used to set the maximum size of the input record, +and the +.B \-mf +option to set the maximum number of fields. +.PP +A pattern-action statement has the form +.IP +.IB pattern " { " action " } +.PP +A missing +.BI { " action " } +means print the line; +a missing pattern always matches. +Pattern-action statements are separated by newlines or semicolons. +.PP +An action is a sequence of statements. +A statement can be one of the following: +.PP +.EX +.ta \w'\fLdelete array[expression]'u +if(\fI expression \fP)\fI statement \fP\fR[ \fPelse\fI statement \fP\fR]\fP +while(\fI expression \fP)\fI statement\fP +for(\fI expression \fP;\fI expression \fP;\fI expression \fP)\fI statement\fP +for(\fI var \fPin\fI array \fP)\fI statement\fP +do\fI statement \fPwhile(\fI expression \fP) +break +continue +{\fR [\fP\fI statement ... \fP\fR] \fP} +\fIexpression\fP #\fR commonly\fP\fI var = expression\fP +print\fR [ \fP\fIexpression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +printf\fI format \fP\fR[ \fP,\fI expression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP +return\fR [ \fP\fIexpression \fP\fR]\fP +next #\fR skip remaining patterns on this input line\fP +nextfile #\fR skip rest of this file, open next, start at top\fP +delete\fI array\fP[\fI expression \fP] #\fR delete an array element\fP +delete\fI array\fP #\fR delete all elements of array\fP +exit\fR [ \fP\fIexpression \fP\fR]\fP #\fR exit immediately; status is \fP\fIexpression\fP +.EE +.DT +.PP +Statements are terminated by +semicolons, newlines or right braces. +An empty +.I expression-list +stands for +.BR $0 . +String constants are quoted \&\fL"\ "\fR, +with the usual C escapes recognized within. +Expressions take on string or numeric values as appropriate, +and are built using the operators +.B + \- * / % ^ +(exponentiation), and concatenation (indicated by white space). +The operators +.B +! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?: +are also available in expressions. +Variables may be scalars, array elements +(denoted +.IB x [ i ] ) +or fields. +Variables are initialized to the null string. +Array subscripts may be any string, +not necessarily numeric; +this allows for a form of associative memory. +Multiple subscripts such as +.B [i,j,k] +are permitted; the constituents are concatenated, +separated by the value of +.BR SUBSEP . +.PP +The +.B print +statement prints its arguments on the standard output +(or on a file if +.BI > file +or +.BI >> file +is present or on a pipe if +.BI | cmd +is present), separated by the current output field separator, +and terminated by the output record separator. +.I file +and +.I cmd +may be literal names or parenthesized expressions; +identical string values in different statements denote +the same open file. +The +.B printf +statement formats its expression list according to the format +(see +.IR fprintf (2)) . +The built-in function +.BI close( expr ) +closes the file or pipe +.IR expr . +The built-in function +.BI fflush( expr ) +flushes any buffered output for the file or pipe +.IR expr . +.PP +The mathematical functions +.BR exp , +.BR log , +.BR sqrt , +.BR sin , +.BR cos , +and +.BR atan2 +are built in. +Other built-in functions: +.TF length +.TP +.B length +the length of its argument +taken as a string, +or of +.B $0 +if no argument. +.TP +.B rand +random number on (0,1) +.TP +.B srand +sets seed for +.B rand +and returns the previous seed. +.TP +.B int +truncates to an integer value +.TP +.B utf +converts its numerical argument, a character number, to a +.SM UTF +string +.TP +.BI substr( s , " m" , " n\fL) +the +.IR n -character +substring of +.I s +that begins at position +.IR m +counted from 1. +.TP +.BI index( s , " t" ) +the position in +.I s +where the string +.I t +occurs, or 0 if it does not. +.TP +.BI match( s , " r" ) +the position in +.I s +where the regular expression +.I r +occurs, or 0 if it does not. +The variables +.B RSTART +and +.B RLENGTH +are set to the position and length of the matched string. +.TP +.BI split( s , " a" , " fs\fL) +splits the string +.I s +into array elements +.IB a [1]\f1, +.IB a [2]\f1, +\&..., +.IB a [ n ]\f1, +and returns +.IR n . +The separation is done with the regular expression +.I fs +or with the field separator +.B FS +if +.I fs +is not given. +An empty string as field separator splits the string +into one array element per character. +.TP +.BI sub( r , " t" , " s\fL) +substitutes +.I t +for the first occurrence of the regular expression +.I r +in the string +.IR s . +If +.I s +is not given, +.B $0 +is used. +.TP +.B gsub +same as +.B sub +except that all occurrences of the regular expression +are replaced; +.B sub +and +.B gsub +return the number of replacements. +.TP +.BI sprintf( fmt , " expr" , " ...\fL) +the string resulting from formatting +.I expr ... +according to the +.I printf +format +.I fmt +.TP +.BI system( cmd ) +executes +.I cmd +and returns its exit status +.TP +.BI tolower( str ) +returns a copy of +.I str +with all upper-case characters translated to their +corresponding lower-case equivalents. +.TP +.BI toupper( str ) +returns a copy of +.I str +with all lower-case characters translated to their +corresponding upper-case equivalents. +.PD +.PP +The ``function'' +.B getline +sets +.B $0 +to the next input record from the current input file; +.B getline +.BI < file +sets +.B $0 +to the next record from +.IR file . +.B getline +.I x +sets variable +.I x +instead. +Finally, +.IB cmd " | getline +pipes the output of +.I cmd +into +.BR getline ; +each call of +.B getline +returns the next line of output from +.IR cmd . +In all cases, +.B getline +returns 1 for a successful input, +0 for end of file, and \-1 for an error. +.PP +Patterns are arbitrary Boolean combinations +(with +.BR "! || &&" ) +of regular expressions and +relational expressions. +Regular expressions are as in +.IR regexp (6). +Isolated regular expressions +in a pattern apply to the entire line. +Regular expressions may also occur in +relational expressions, using the operators +.BR ~ +and +.BR !~ . +.BI / re / +is a constant regular expression; +any string (constant or variable) may be used +as a regular expression, except in the position of an isolated regular expression +in a pattern. +.PP +A pattern may consist of two patterns separated by a comma; +in this case, the action is performed for all lines +from an occurrence of the first pattern +though an occurrence of the second. +.PP +A relational expression is one of the following: +.IP +.I expression matchop regular-expression +.br +.I expression relop expression +.br +.IB expression " in " array-name +.br +.BI ( expr , expr,... ") in " array-name +.PP +where a +.I relop +is any of the six relational operators in C, +and a +.I matchop +is either +.B ~ +(matches) +or +.B !~ +(does not match). +A conditional is an arithmetic expression, +a relational expression, +or a Boolean combination +of these. +.PP +The special patterns +.B BEGIN +and +.B END +may be used to capture control before the first input line is read +and after the last. +.B BEGIN +and +.B END +do not combine with other patterns. +.PP +Variable names with special meanings: +.TF FILENAME +.TP +.B CONVFMT +conversion format used when converting numbers +(default +.BR "%.6g" ) +.TP +.B FS +regular expression used to separate fields; also settable +by option +.BI \-F fs\f1. +.TP +.BR NF +number of fields in the current record +.TP +.B NR +ordinal number of the current record +.TP +.B FNR +ordinal number of the current record in the current file +.TP +.B FILENAME +the name of the current input file +.TP +.B RS +input record separator (default newline) +.TP +.B OFS +output field separator (default blank) +.TP +.B ORS +output record separator (default newline) +.TP +.B OFMT +output format for numbers (default +.BR "%.6g" ) +.TP +.B SUBSEP +separates multiple subscripts (default 034) +.TP +.B ARGC +argument count, assignable +.TP +.B ARGV +argument array, assignable; +non-null members are taken as file names +.TP +.B ENVIRON +array of environment variables; subscripts are names. +.PD +.PP +Functions may be defined (at the position of a pattern-action statement) thus: +.IP +.L +function foo(a, b, c) { ...; return x } +.PP +Parameters are passed by value if scalar and by reference if array name; +functions may be called recursively. +Parameters are local to the function; all other variables are global. +Thus local variables may be created by providing excess parameters in +the function definition. +.SH EXAMPLES +.TP +.L +length($0) > 72 +Print lines longer than 72 characters. +.TP +.L +{ print $2, $1 } +Print first two fields in opposite order. +.PP +.EX +BEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 } +.EE +.ns +.IP +Same, with input fields separated by comma and/or blanks and tabs. +.PP +.EX + { s += $1 } +END { print "sum is", s, " average is", s/NR } +.EE +.ns +.IP +Add up first column, print sum and average. +.TP +.L +/start/, /stop/ +Print all lines between start/stop pairs. +.PP +.EX +BEGIN { # Simulate echo(1) + for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i] + printf "\en" + exit } +.EE +.SH SOURCE +.B /sys/src/cmd/awk +.SH SEE ALSO +.IR sed (1), +.IR regexp (6), +.br +A. V. Aho, B. W. Kernighan, P. J. Weinberger, +.I +The AWK Programming Language, +Addison-Wesley, 1988. ISBN 0-201-07981-X +.SH BUGS +There are no explicit conversions between numbers and strings. +To force an expression to be treated as a number add 0 to it; +to force it to be treated as a string concatenate +\&\fL""\fP to it. +.br +The scope rules for variables in functions are a botch; +the syntax is worse. diff --git a/static/plan9-4e/man1/basename.1 b/static/plan9-4e/man1/basename.1 new file mode 100644 index 00000000..c72638f1 --- /dev/null +++ b/static/plan9-4e/man1/basename.1 @@ -0,0 +1,35 @@ +.TH BASENAME 1 +.SH NAME +basename \- strip file name affixes +.SH SYNOPSIS +.B basename +[ +.B -d +] +.I string +[ +.I suffix +] +.SH DESCRIPTION +.PP +.I Basename +deletes any prefix ending in slash +.RB ( / ) +and the +.IR suffix , +if present in +.IR string , +from +.IR string , +and prints the result on the standard output. +.PP +The +.B -d +option instead prints the directory component, +that is, +.I string +up to but not including the final slash. +If the string contains no slash, +a period and newline are printed. +.SH SOURCE +.B /sys/src/cmd/basename.c diff --git a/static/plan9-4e/man1/bc.1 b/static/plan9-4e/man1/bc.1 new file mode 100644 index 00000000..0797c54c --- /dev/null +++ b/static/plan9-4e/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 /sys/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/static/plan9-4e/man1/bind.1 b/static/plan9-4e/man1/bind.1 new file mode 100644 index 00000000..a430ba5d --- /dev/null +++ b/static/plan9-4e/man1/bind.1 @@ -0,0 +1,201 @@ +.TH BIND 1 +.SH NAME +bind, mount, unmount \- change name space +.SH SYNOPSIS +.B bind +[ +.I option ... +] +.I new old +.PP +.B mount +[ +.I option ... +] +.I servename old +[ +.I spec +] +.PP +.B unmount +[ +.I new +] +.I old +.SH DESCRIPTION +.I Bind +and +.I mount +modify the file name space of the current process +and other processes in the same name space group +(see +.IR fork (2)). +For both calls, +.I old +is the name of an existing file or directory in the +current name space where the modification is to be made. +.PP +For +.IR bind , +.I new +is the name of another (or possibly the same) +existing file or directory in +the current name space. +After a successful +.IR bind , +the file name +.I old +is an alias for the object originally named by +.IR new ; +if the modification doesn't hide it, +.I new +will also still refer to its original file. +The evaluation of +.I new +(see +.IR intro (2)) +happens at the time of the +.IR bind , +not when the binding is later used. +.PP +The +.I servename +argument to +.I mount +is the name of a file that, when opened, yields an +existing connection to a file server. +Almost always, +.I servename +will be a file in +.B /srv +(see +.IR srv (3)). +In the discussion below, +.I new +refers to the file named by the +.I new +argument to +.I bind +or the root directory of the service +available in +.I servename +after a +.IR mount . +Either both +.I old +and +.I new +files must be directories, +or both must not be directories. +.PP +Options control aspects of the modification to the name space: +.TP 10 +(none) +Replace the +.I old +file by the new one. +Henceforth, an evaluation of +.I old +will be translated to the new file. +If they are directories (for +.IR mount , +this condition is true by definition), +.I old +becomes a +.I "union directory" +consisting of one directory (the new file). +.TP +.B -b +Both files must be directories. +Add the new directory to the beginning +of the union directory represented by the old file. +.TP +.B -a +Both files must be directories. +Add the new directory to the end +of the union directory represented by the old file. +.TP +.B -c +This can be used in addition to any of the above to permit +creation in a union directory. +When a new file is created in a union directory, +it is placed in the first element of the union that has been bound or mounted with the +.B -c +flag. +If that directory does not have write permission, the create fails. +.TP +.B -C +(Only in +.IR mount .) +By default, file contents are always retrieved from the server. +With this option, the kernel may instead use a local cache to satisfy +.IR read (5) +requests for files accessible through this mount point. +The currency of cached data for a file is verified at each +.IR open (5) +of the file from this client machine. +.TP +.B -q +Exit silently if the +.B bind +or +.B mount +operation fails. +.PD +.PP +The +.I spec +argument to +.I mount +is passed in the +.IR attach (5) +message to the server, and selects among different +file trees served by the server. +.PP +The +.IR srv (3) +service registry device, normally bound to +.BR /srv , +is a convenient rendezvous point for services that can be mounted. +After bootstrap, the file +.B /srv/boot +contains the communications port to the file system from which +the system was loaded. +.PP +The effects of +.I bind +and +.I mount +can be undone with the +.I unmount +command. +If two arguments are given to +.IR unmount , +the effect is to undo a +.I bind +or +.I mount +with the same arguments. +If only one argument is given, +everything bound to or mounted upon +.I old +is unmounted. +.SH EXAMPLES +To compile a program with the C library from July 16, 1992: +.IP +.EX +mount /srv/boot /n/dump dump +bind /n/dump/1992/0716/mips/lib/libc.a /mips/lib/libc.a +mk +.EE +.SH SOURCE +.B /sys/src/cmd/bind.c +.br +.B /sys/src/cmd/mount.c +.br +.B /sys/src/cmd/unmount.c +.SH SEE ALSO +.IR bind (2), +.IR open (2), +.IR srv (3), +.IR srv (4) diff --git a/static/plan9-4e/man1/bitsyload.1 b/static/plan9-4e/man1/bitsyload.1 new file mode 100644 index 00000000..e9c46461 --- /dev/null +++ b/static/plan9-4e/man1/bitsyload.1 @@ -0,0 +1,146 @@ +.TH BITSYLOAD 1 +.SH NAME +bitsyload, light, pencal, keyboard, params, prompter \- bitsy-specific utilities +.SH SYNOPSIS +.PP +.B bitsy/bitsyload +.B k|r +[ +.I file +] +.PP +.B bitsy/light +[ +.I intensity +] +.PP +.B bitsy/params +[ +.B \-f +] +.PP +.B bitsy/pencal +.PP +.B bitsy/keyboard +[ +.B \-n +] +.PP +.B bitsy/prompter +[ +.B \-n +] +.I file +.SH DESCRIPTION +.PP +.I Bitsyload +erases a section of flash memory on the Bitsy (iPAQ 3650 or 3830) +and copies new +information into it, using the format required by the Compaq +boot loader. The required first argument is the destination, either +.B k +for +.B /dev/flash/kernel +or +.B r +for +.BR /dev/flash/ramdisk . +The optional second argument is the name of the file +to load. The default kernel file is +.B /sys/src/9/bitsy/9bitsy +and the default ramdisk file is +.BR /sys/src/9/bitsy/ramdisk . +.PP +.I Light +sets the intensity of the display backlight. +The +values for +.I intensity +are: +.IP on +set intensity to maximum, the default +.IP off +turn off backlight +.IP \fIn\fP +sets the intensity to +.IR n , +where +.I n +is a value between 0 and 128. Intensity 0 doesn't +turn off the backlight, it just sets it to the dimmest +value. +.PP +.I Pencal +calibrates the display with the touch screen on a Bitsy. +It loops prompting the user with crosses whose center that the user +must touch with the stylus. After a consistent set of touches, +it writes the calibration both to the kernel and to standard out. +It is normally called by the bitsy's +.BR /bin/cpurc . +.PP +.I Params +copies the contents of the file +.BR /dev/tmpparams , +into the flash partition, +.BR /dev/flash/params , +or if the +.B -f +flag it set copies in the opposite direction. +.PP +.I Keyboard +creates a virtual on-screen keyboard and, unless the +.B -n +option is specified, a scribble area. +A user inputs characters by tapping the keys or +by drawing characters in the +scribble area (see +.IR scribble (2)). +It is usually run as the keyboard command for +.IR rio (1) +using +.BR rio 's +.B -k +option. +.PP +.I Prompter +is a small editor used to configure parameters when a Bitsy boots. +It displays the file and starts up a keyboard and scribble pad for +input. +Clicking with the stylus in the text selects where input characters will go. +Pressing Button 5 (top left side of the Bitsy) or typing the +.B Esc +key on the keyboard causes +.I prompter +to write back the updated file and exit; +.B Del +causes +.I prompter +to exit without writing the file. +The +.B -n +flag suppresses the scribble area. +.SH EXAMPLE +.PP +.IR Prompter , +.IR params , +and +.I calibrate +are used in only one place, the Bitsy's +.BR /rc/bin/cpurc : +.sp +.EX +# set variables +ramfs +bitsy/params -f +if(! grep -s '^calibrate=' /tmp/tmpparams) + bitsy/pencal >>/tmp/tmpparams +if not { + eval `{grep '^calibrate=' /tmp/tmpparams} + echo calibrate $calibrate > '#m/mousectl' +} +bitsy/prompter /tmp/tmpparams +bitsy/params +. /tmp/tmpparams +.EE +.SH SOURCE +.B /sys/src/cmd/bitsy diff --git a/static/plan9-4e/man1/bundle.1 b/static/plan9-4e/man1/bundle.1 new file mode 100644 index 00000000..d7b9f9f4 --- /dev/null +++ b/static/plan9-4e/man1/bundle.1 @@ -0,0 +1,53 @@ +.TH BUNDLE 1 +.SH NAME +bundle \- collect files for distribution +.SH SYNOPSIS +.B bundle +.I file ... +.SH DESCRIPTION +.I Bundle +writes on its standard output a shell script for +.IR rc (1) +or a Bourne shell +which, when executed, +will recreate the original +.IR files . +Its main use is for distributing small numbers of text files by +.IR mail (1). +.PP +Although less refined than standard archives from +.IR ar (1) +or +.IR tar (1), +a +.IR bundle +file +is self-documenting and complete; little preparation is required on +the receiving machine. +.SH EXAMPLES +.TP +.L +bundle mkfile *.[ch] | mail kremvax!boris +Send a makefile to Boris together with related +.L .c +and +.L .h +files. +Upon receiving the mail, Boris may save the file sans postmark, +say in +.BR gift/horse , +then do +.TP +.L +cd gift; rc horse; mk +.SH SOURCE +.B /rc/bin/bundle +.SH SEE ALSO +.IR ar (1), +.IR tar (1), +.IR mail (1) +.SH BUGS +.I Bundle +will not create directories and is unsatisfactory for non-text files. +.br +Beware of gift horses. diff --git a/static/plan9-4e/man1/cal.1 b/static/plan9-4e/man1/cal.1 new file mode 100644 index 00000000..7ac5b996 --- /dev/null +++ b/static/plan9-4e/man1/cal.1 @@ -0,0 +1,46 @@ +.TH CAL 1 +.SH NAME +cal \- print calendar +.SH SYNOPSIS +.B cal +[ +.I month +] +[ +.I year +] +.SH DESCRIPTION +.I Cal +prints a calendar. +.I Month +is either a number from 1 to 12, +a lower case month name, +or a lower case three-letter prefix of a month name. +.I Year +can be between 1 +and 9999. +If either +.I month +or +.I year +is omitted, the current month or year is used. +If only one argument is given, and it is a number larger than 12, +a calendar for all twelve months of the given year is produced; +otherwise a calendar for just one month is printed. +The calendar +produced is that for England and her colonies. +.PP +Try +.EX + cal sep 1752 +.EE +.SH SOURCE +.B /sys/src/cmd/cal.c +.SH BUGS +The year is always considered to start in January even though this +is historically naive. +.br +Beware that +.L "cal 90" +refers to the early Christian era, +not the 20th century. diff --git a/static/plan9-4e/man1/calendar.1 b/static/plan9-4e/man1/calendar.1 new file mode 100644 index 00000000..32293752 --- /dev/null +++ b/static/plan9-4e/man1/calendar.1 @@ -0,0 +1,44 @@ +.TH CALENDAR 1 +.SH NAME +calendar \- print upcoming events +.SH SYNOPSIS +.B calendar +[ +.B \-y +] +[ +.I file ... +] +.SH DESCRIPTION +.I Calendar +reads the named files, default +.BR /usr/$user/lib/calendar , +and writes to standard output any lines +containing today's or tomorrow's date. +Examples of recognized date formats are +"4/11", +"April 11", +"Apr 11", +"11 April", +and +"11 Apr". +All comparisons are case insensitive. +.PP +If the +.B \-y +flag is given, an attempt is made to match on year too. In this case, +dates of the forms listed above will be accepted if they are followed +by the current year (or last two digits thereof) or not a year — +digits not followed by white space or non-digits. +.PP +On Friday and Saturday, events through Monday are printed. +.PP +To have your calendar mailed to you every day, use +.IR cron (8). +.SH FILES +.TF /usr/$user/lib/calendar +.TP +.B /usr/$user/lib/calendar +personal calendar +.SH SOURCE +.B /sys/src/cmd/calendar.c diff --git a/static/plan9-4e/man1/cat.1 b/static/plan9-4e/man1/cat.1 new file mode 100644 index 00000000..445844da --- /dev/null +++ b/static/plan9-4e/man1/cat.1 @@ -0,0 +1,82 @@ +.TH CAT 1 +.SH NAME +cat, read \- catenate files +.SH SYNOPSIS +.B cat +[ +.I file ... +] +.br +.B read +[ +.B -m +] [ +.B -n +.I nline +] [ +.I file ... +] +.SH DESCRIPTION +.I Cat +reads each +.I file +in sequence and writes it on the standard output. +Thus +.IP +.L +cat file +.LP +prints a file and +.IP +.L +cat file1 file2 >file3 +.LP +concatenates the first two files and places the result +on the third. +.PP +If no +.I file +is given, +.I cat +reads from the standard input. +Output is buffered in blocks matching the input. +.PP +.I Read +copies to standard output exactly one line from the named +.IR file , +default standard input. +It is useful in interactive +.IR rc (1) +scripts. +.PP +The +.B -m +flag causes it to continue reading and writing multiple lines until end of file; +.B -n +causes it to read no more than +.I nline +lines. +.PP +Read always executes a single +.B write +for each line of input, which can be helpful when +preparing input to programs that expect line-at-a-time data. +It never reads any more data from the input than it prints to the output. +.SH SOURCE +.B /sys/src/cmd/cat.c +.br +.B /sys/src/cmd/read.c +.SH SEE ALSO +.IR cp (1) +.SH DIAGNOSTICS +.I Read +exits with status +.B eof +on end of file. +.SH BUGS +Beware of +.L "cat a b >a" +and +.LR "cat a b >b" , +which +destroy input files before reading them. diff --git a/static/plan9-4e/man1/chgrp.1 b/static/plan9-4e/man1/chgrp.1 new file mode 100644 index 00000000..f1924773 --- /dev/null +++ b/static/plan9-4e/man1/chgrp.1 @@ -0,0 +1,36 @@ +.TH CHGRP 1 +.SH NAME +chgrp \- change file group +.SH SYNOPSIS +.B chgrp +[ +.B -ou +] +.I group file ... +.SH DESCRIPTION +The group of +each named file +is changed to +.IR group , +which should be a name known to the server holding the file. +.PP +A file's group can be changed by the file's owner, if the +owner is a member of the new group, +or by the leader of both +the file's current group and the new group. +.PP +The +.B -o +and +.B -u +option are synonyms; they specify that the +.I owner +is to be set, rather than the group. +They are ineffectual unless the file server is in the bootstrap +state that permits changing file ownership. +.SH SOURCE +.B /sys/src/cmd/chgrp.c +.SH "SEE ALSO" +.IR ls (1), +.IR chmod (1), +.IR stat (2) diff --git a/static/plan9-4e/man1/chmod.1 b/static/plan9-4e/man1/chmod.1 new file mode 100644 index 00000000..8b843005 --- /dev/null +++ b/static/plan9-4e/man1/chmod.1 @@ -0,0 +1,104 @@ +.TH CHMOD 1 +.SH NAME +chmod \- change mode +.SH SYNOPSIS +.B chmod +.I mode file ... +.SH DESCRIPTION +The mode of +each named file +is changed +according to +.IR mode, +which may be an octal number or a symbolic change to the existing mode. +A +.I mode +is an octal +number constructed +from the OR of the +following modes. +.TF 0000 +.TP +0400 +read by owner +.TP +0200 +write by owner +.TP +0100 +execute (search in directory) by owner +.TP +0070 +read, write, execute (search) by group +.TP +0007 +read, write, execute (search) by others +.PD +.PP +A symbolic +.I mode +has the form: +.IP +.RI [who] +.I op permission +.PP +The +.I who +part is a combination +of the letters +.B u +(for user's permissions), +.B g +(group) +and +.B o +(other). +The letter +.B a +stands for +.BR ugo . +If +.I who +is omitted, +the default is +.BR a . +.PP +.I Op +can be +.B + +to add +.I permission +to the file's mode, +.B - +to take away +.IR permission , +and +.B = +to assign +.I permission +absolutely +(all other bits will +be reset). +.PP +.I Permission +is any combination of the letters +.B r +(read), +.B w +(write), +.B x +(execute), +.B a +(append only), +and +.B l +(exclusive access). +.PP +Only the owner of a file or the group leader of its group +may change the file's mode. +.SH SOURCE +.B /sys/src/cmd/chmod.c +.SH "SEE ALSO" +.IR ls (1), +.IR stat (2), +.IR stat (5) diff --git a/static/plan9-4e/man1/cleanname.1 b/static/plan9-4e/man1/cleanname.1 new file mode 100644 index 00000000..41c06c00 --- /dev/null +++ b/static/plan9-4e/man1/cleanname.1 @@ -0,0 +1,32 @@ +.TH CLEANNAME 1 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B cleanname +[ +.B -d +.I pwd +] +.I names ... +.SH DESCRIPTION +For each file name argument, +.IR cleanname , +by lexical processing only, +prints the shortest equivalent string that names the same +(possibly hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically +interprets +.B . +and +.B .. +directory components in the name. +If the +.B -d +option is present, +unrooted names are prefixed with +.IB pwd / +before processing. +.SH SOURCE +.B /sys/src/cmd/cleanname.c +.SH SEE ALSO +.IR cleanname (2). diff --git a/static/plan9-4e/man1/cmp.1 b/static/plan9-4e/man1/cmp.1 new file mode 100644 index 00000000..e48d0766 --- /dev/null +++ b/static/plan9-4e/man1/cmp.1 @@ -0,0 +1,57 @@ +.TH CMP 1 +.SH NAME +cmp \- compare two files +.SH SYNOPSIS +.B cmp +[ +.B -lsL +] +.I file1 file2 +[ +.I offset1 +[ +.I offset2 +] +] +.SH DESCRIPTION +The two files are +compared. +A diagnostic results if the contents differ, otherwise +there is no output. +.PP +The options are: +.TP +.B l +Print the byte number (decimal) and the +differing bytes (hexadecimal) for each difference. +.TP +.B s +Print nothing for differing files, +but set the exit status. +.TP +.B L +Print the line number of the first differing byte. +.PP +If offsets are given, +comparison starts at the designated byte position +of the corresponding file. +Offsets that begin with +.B 0x +are hexadecimal; +with +.BR 0 , +octal; with anything else, decimal. +.SH SOURCE +.B /sys/src/cmd/cmp.c +.SH "SEE ALSO" +.IR diff (1) +.SH DIAGNOSTICS +If a file is inaccessible or missing, the exit status is +.LR open . +If the files are the same, the exit status is empty (true). +If they are the same except that one is longer than the other, the exit status is +.LR EOF . +Otherwise +.I cmp +reports the position of the first disagreeing byte and the exit status is +.LR differ . diff --git a/static/plan9-4e/man1/colors.1 b/static/plan9-4e/man1/colors.1 new file mode 100644 index 00000000..506dd37c --- /dev/null +++ b/static/plan9-4e/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 (6)). +.PP +Clicking mouse button 1 over a color in the grid will display the map index for that color, +its +red, green, and blue components, +and the 32-bit hexadecimal color value as defined in +.IR allocimage (2). +If the +.B -x +option is specified, the components will also be listed in hexadecimal. +.PP +The +.B -r +option instead shows, in the same form, a grey-scale ramp. +.PP +A menu on mouse button 3 contains a single entry, to exit the program. +.PP +On 8-bit color-mapped displays, +.I getmap +loads the display's color map (default +.BR rgbv ). +The named +.I colormap +can be a file in the current directory or in the standard repository +.BR /lib/cmap . +It can also be a string of the form +.B gamma +or +.BI gamma N\f1 , +where +.I N +is a floating point value for the gamma, defining the contrast for a monochrome map. +Similarly, +.B rgamma +and +.BI rgamma N +define a reverse-video monochrome map. +Finally, the names +.B screen +or +.B display +or +.B vga +are taken as synonyms for the current color map stored in the display hardware. +.SH FILES +.B /lib/cmap +directory of color map files +.SH SOURCE +.B /sys/src/cmd/colors.c +.SH SEE ALSO +.IR color (6) diff --git a/static/plan9-4e/man1/comm.1 b/static/plan9-4e/man1/comm.1 new file mode 100644 index 00000000..2fd883c0 --- /dev/null +++ b/static/plan9-4e/man1/comm.1 @@ -0,0 +1,47 @@ +.TH COMM 1 +.CT 1 files +.SH NAME +comm \- select or reject lines common to two sorted files +.SH SYNOPSIS +.B comm +[ +.B -123 +] +.I file1 file2 +.SH DESCRIPTION +.I Comm +reads +.I file1 +and +.IR file2 , +which are in lexicographical order, +and produces a three column output: lines only in +.IR file1 ; +lines only in +.IR file2 ; +and lines in both files. +The file name +.L - +means the standard input. +.PP +Flag +.LR 1 , +.LR 2 , +or +.LR 3 +suppresses printing of the corresponding +column. +.SH EXAMPLE +.TP +.EX +comm -12 file1 file2 +.EE +.IP +Print lines common to two sorted files. +.SH SOURCE +.B /sys/src/cmd/comm.c +.SH "SEE ALSO" +.IR sort (1), +.IR cmp (1), +.IR diff (1), +.IR uniq (1) diff --git a/static/plan9-4e/man1/con.1 b/static/plan9-4e/man1/con.1 new file mode 100644 index 00000000..293b0315 --- /dev/null +++ b/static/plan9-4e/man1/con.1 @@ -0,0 +1,238 @@ +.TH CON 1 +.SH NAME +con, telnet, rx, xms, xmr \- remote login, execution, and XMODEM file transfer +.SH SYNOPSIS +.B con +[ +.B -CdnrRvs +] +[ +.B -b +.I baud +] +[ +.B -l +[ +.I remuser +] +] +[ +.B -c +.I cmd +] +.RI [ net !] machine +.PP +.B telnet +[ +.B -dCrn +] +.RI [ net !] machine +.PP +.B cu +.I number +.PP +.B rx +[ +.B -e +] +[ +.B -l +.I remuser +] +.RI [ net !] machine +[ +.I command-word ... +] +.PP +.B xms +.I file +.PP +.B xmr +.I file +.SH DESCRIPTION +.I Con +connects to the computer whose network address is +.IR net ! machine +and logs in if possible. +With no options, the account name used on the remote system is the same +as that on the local system. +Standard input and output go to the local machine. +.PP +Options are: +.TP +.B -b +sets the baud rate of a dial-up connection to +.IR baud . +.TP +.B -n +if the input is a file or pipe, do not hang up the connection when EOF is received, +but instead wait for the remote end to hang up. +.TP +.B -l +with an argument causes +.I remuser +to be used as the account name on the remote system. +Without an argument this option disables automatic login +and a normal login session ensues. +.TP +.B -C +forces cooked mode, that is, local echo. +.TP +.B -c +runs +.I cmd +as if it had been typed as a command from the escape mode. +This is used by +.IR cu . +.TP +.B -v +(verbose mode) causes information about connection attempts +to be output to standard error. This can be useful when +trying to debug network connectivity. +.TP +.B -d +causes debugging information to be output to standard error. +.TP +.B -r +suppresses printing of any carriage return followed by a new line. +This is useful since carriage return is a printable character in +Plan 9. +.TP +.B -R +translates newlines to carriage returns and +.IR vice versa . +.TP +.B -s +strips received characters to 7 bits to forestall +misinterpretation of +.SM ASCII +with parity as +.SM UTF\c +\&. +.PP +The +.RB control\- \e +character is a local escape. +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B i +Send a quit [sic] signal to the remote machine. +.PD0 +.TP +.B q +Exit. +.TP +.B b +Send a break. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +This is useful for transmitting and receiving files +over the connections using programs such as +.IR xms . +.TP +.B r +Toggle printing of carriage returns. +.PD +.PP +.I Telnet +is similar to con, but uses the +.I telnet +protocol to communicate with the remote machine. +It shares +.I con's +.BR -C , +.BR -d , +.BR -n , +and +.BR -r +options. +.PP +.I Rx +executes one shell command +on the remote machine as if logged in there, +but with local standard input and output. +A rudimentary shell environment is provided. +If the target is a Plan 9 machine, +.B $service +there will be +.BR rx . +The +.B \-e +option causes a zero length message to be written to the +connection when standard input is closed. +The +.B \-l +option causes +.I remuser +to be used on the remote machine if the remote +is a BSD machine. +.PP +Network addresses for both +.I con +and +.I rx +have the form +.IB network ! machine\f1. +Supported networks are those listed in +.BR /net . +.PP +The commands +.I xms +and +.I xmr +respectively send and receive a single file using the +XMODEM protocol. +They use standard input and standard output for communication +and are intended for use with +.IR con . +.SH EXAMPLES +.TP +.L +rx kremvax cat file1 >file2 +Copy remote +.I file1 +to local +.IR file2 . +.TP +.L +rx kremvax cat file1 '>file2' +Copy remote +.I file1 +to remote +.IR file2. +.TP +.L +eqn paper | rx kremvax troff -ms | rx deepthought lp +Parallel processing: +do each stage of a pipeline on a different machine. +.SH SOURCE +.TF /sys/src/cmd/con +.TP +.B /sys/src/cmd/con +for +.IR con , +.IR xms , +and +.IR xmr . +.TP +.B /sys/src/cmd/ip +for +.IR telnet . +.SH BUGS +Under +.IR rx , +a program +that should behave specially towards terminals may not: e.g., +remote shells will not prompt. +Also under +.IR rx , +the remote standard error and standard output are combined +and go inseparably to the local standard output. diff --git a/static/plan9-4e/man1/cp.1 b/static/plan9-4e/man1/cp.1 new file mode 100644 index 00000000..dc1d50ce --- /dev/null +++ b/static/plan9-4e/man1/cp.1 @@ -0,0 +1,92 @@ +.TH CP 1 +.SH NAME +cp, mv \- copy, move files +.SH SYNOPSIS +.B cp +[ +.B -gux +] +.I file1 file2 +.br +.B cp +[ +.B -gux +] +.I file ... directory +.PP +.B mv +.I file1 file2 +.br +.B mv +.I file ... directory +.SH DESCRIPTION +In the first form +.I file1 +is any name and +.I file2 +is any name except an existing directory. +In the second form the commands +copy or move one or more +.I files +into a +.I directory +under their original file names, as if by a sequence of +commands in the first form. +Thus +.L "cp f1 f2 dir +is equivalent to +.LR "cp f1 dir/f1; cp f2 dir/f2" . +.PP +.I Cp +copies the contents of plain +.I file1 +to +.IR file2 . +The mode and owner of +.I file2 +are preserved if it already +exists; the mode of +.I file1 +is used otherwise. +The +.B -x +option sets the mode and modified time of +.I file2 +from +.IR file1 ; +.B -g +sets the group id; and +.B -u +sets the group id and user id (which is usually only possible if the file server is in an administrative mode). +.PP +.I Mv +moves +.I file1 +to +.IR file2 . +If the files are in the same directory, +.I file1 +is just renamed; +otherwise +.I mv +behaves like +.I cp +.B -x +followed by +.B rm +.IR file1 . +.I Mv +will rename directories, +but it refuses to move a directory into another directory. +.SH SOURCE +.B /sys/src/cmd/cp.c +.br +.B /sys/src/cmd/mv.c +.SH "SEE ALSO" +.IR cat (1), +.IR stat (2) +.SH DIAGNOSTICS +.I Cp +and +.I mv +refuse to copy or move files onto themselves. diff --git a/static/plan9-4e/man1/cpp.1 b/static/plan9-4e/man1/cpp.1 new file mode 100644 index 00000000..7ff3a352 --- /dev/null +++ b/static/plan9-4e/man1/cpp.1 @@ -0,0 +1,116 @@ +.TH CPP 1 +.SH NAME +cpp \- C language preprocessor +.SH SYNOPSIS +.B cpp +[ +.I option ... +] +[ +.I ifile +[ +.I ofile +] +] +.SH DESCRIPTION +.I Cpp\^ +interprets ANSI C preprocessor directives +and does macro substitution. +The input +.I ifile +and output +.I ofile +default to standard input and standard output respectively. +.PP +The options are: +.TP +.BI -D name\^ +.PD 0 +.TP +.BI -D name=def\^ +.TP +.BI -I dir\^ +Same as in +.IR 2c "(1): add +.I dir +to the search for +.CW search +directives. +.PD +.TP +.B -M +Generate no output except a list of include files +in a form suitable for specifying dependencies to +.IR mk (1). +Use twice to list files in angle brackets. +.TP +.B -N +Turn off default include directories. All must be +specified with +.BR -I , +or in the environment variable +.BR include . +Without this option, +.B /$objtype/include +and +.B /sys/include +are used as the last two searched directories for include directives, +where +.B $objtype +is read from the environment. +.TP +.B -V +Print extra debugging information. +.TP +.B -P +Do not insert +.RB `` #line '' +directives into the output. +.TP +.B -+ +Understand C++ comments. +.TP +.B -i +Print the list of directories searched when +.I #include +is found. +Last listed are searched first. +.PD +.PP +In the absence of the +.B -P +option, the processed text output is sprinkled +with lines that show the original input line numbering: +.IP +.B #line +.I linenumber +.L +"\fIifile\fP" +.PP +The command reads the environment variable +.IR include +and adds its (blank-separated) list of directories to +the standard search path for +.CW #include +directives. They are looked at before any directories specified with +.BR -I , +which are looked at before the default directories. +.PP +The input language is as described in the ANSI C standard. +The standard Plan 9 C compilers do not use +.IR cpp ; +they contain their own simple but adequate preprocessor, so +.I cpp +is usually superfluous. +.SH FILES +.TF /objtype/include +.TP +.B /sys/include +directory for machine-independent include files +.TP +.B /$objtype/include +directory for machine-dependent include files +.SH SOURCE +.B /sys/src/cmd/cpp +.SH SEE ALSO +.IR 2c (1) diff --git a/static/plan9-4e/man1/cpu.1 b/static/plan9-4e/man1/cpu.1 new file mode 100644 index 00000000..33f321db --- /dev/null +++ b/static/plan9-4e/man1/cpu.1 @@ -0,0 +1,162 @@ +.TH CPU 1 +.SH NAME +cpu \- connection to cpu server +.SH SYNOPSIS +.B cpu +[ +.B -h +.I server +] [ +.B -f +] [ +.B -a +.I auth-method +] [ +.B -e +.I encryption-hash-algs +] [ +.B -c +.I cmd args ... +] +.SH DESCRIPTION +.I Cpu +starts an +.IR rc (1) +running on the +.I server +machine, or the machine named in the +.B $cpu +environment variable if there is no +.B -h +option. +.IR Rc 's +standard input, output, and error files will be +.B /dev/cons +in the name space where the +.I cpu +command was invoked. +Normally, +.I cpu +is run in an +.IR rio (1) +window on a terminal, so +.IR rc +output goes to that window, and input comes from the keyboard +when that window is current. +.IR Rc 's +current directory is +the working directory of the +.I cpu +command itself. +.PP +The name space for the new +.I rc +is an analogue of the name space where the +.I cpu +command was invoked: +it is the same except for architecture-dependent bindings such as +.B /bin +and the use of fast paths to file servers, if available. +.PP +If a +.B -c +argument is present, the remainder of the command line is executed by +.I rc +on the server, and then +.I cpu +exits. +.PP +The +.B -a +command allows the user to specify the authentication mechanism used +when connecting to the remote system. The two possibilities for +.I auth-method +are: +.TF netkey +.TP +.B p9 +This is the default. Authentication is done using the standard Plan 9 +mechanisms, (see +.IR authsrv (6)). +No user interaction is required. +.TP +.B netkey +Authentication is done using challenge/response and a hand held +authenticator or the +.I netkey +program +(see +.IR passwd (1)). +The user must encrypt the challenge and type the encryption +back to +.IR cpu . +This is used if the local host is in a different protection domain than +the server or if the user wants to log into the server as a different +user. +.PD +.PP +The +.B -e +option specifies an encryption and/or hash algorithm to +use for the connection. If both are specified, they must +be space separated and comprise a single argument, so they +must be quoted if in a shell command. The default is +.L rc4_256 +encryption and +.L sha1 +hashing. See +.IR ssl (3) +for details on possible algorithms. The argument +.L clear +specifies no encryption algorithm and can be used to talk +to older versions of the +.B cpu +service. +.PP +The +.B -f +flag inserts a filter in the data stream to coalesce +9P packet fragments into full packets. +It is used on TCP connections, and is set automatically by +the TCP receive script for incoming CPU calls +(see +.IR listen (8)). +.PP +The name space is built by running +.B /usr/$user/lib/profile +with the root of the invoking name space bound to +.BR /mnt/term . +The +.B service +environment variable is set to +.BR cpu ; +the +.B cputype +and +.B objtype +environment variables reflect the server's architecture. +.SH FILES +The name space of the terminal side of the +.B cpu +command is mounted, via +.IR exportfs (4), +on the CPU side on directory +.BR /mnt/term . +The files such as +.B /dev/cons +are bound to their standard locations from there. +.SH SOURCE +.B /sys/src/cmd/cpu.c +.SH SEE ALSO +.IR rc (1) , +.IR rio (1) +.SH BUGS +Binds and mounts done after the terminal +.B lib/profile +is run are not reflected in the new name space. +.PP +When using the +.B -a +option to `log in' as another user, be aware that +resources in the local name space will be made +available to that user. diff --git a/static/plan9-4e/man1/crop.1 b/static/plan9-4e/man1/crop.1 new file mode 100644 index 00000000..ec0e952c --- /dev/null +++ b/static/plan9-4e/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 (6) +file (default standard input), crops it, and writes it as a compressed +.IR image (6) +file to standard output. +There are two ways to specify a crop, by color value or by geometry. +They may be combined in a single run of +.IR crop , +in which case the color value crop will be done first. +.PP +The +.B -c +option takes a red-green-blue triplet as described in +.IR color (2). +(For example, white +is +.B 255 +.B 255 +.BR 255 .) +The corresponding color is used as a value to be cut from the outer +edge of the picture; that is, the image is cropped to remove the maximal +outside rectangular strip in which every pixel has the specified color. +.PP +The +.B -i +option insets the image rectangle by a constant amount, +.IR n , +which may be negative to generate extra space around the image. +The +.B -x +and +.B -y +options are similar, but apply only to the +.I x +or +.I y +coordinates of the image. +.PP +The +.B -r +option specifies an exact rectangle. +.PP +The +.B -t +option specifies that the image's coordinate system should +be translated by +.IR tx , +.IR ty +as the last step of processing. +.PP +The +.B -b +option specifies a background color to be used to fill around the image +if the cropped image is larger than the original, such as if the +.B -i +option is given a negative argument. +This can be used to draw a monochrome frame around the image. +The default color is black. +.PP +.I Iconv +changes the format of pixels in the image +.I file +(default standard input) and writes the resulting image to standard output. +Pixels in the image are converted according to the channel descriptor +.IR chandesc , +(see +.IR image (6)). +For example, to convert a 4-bit-per-pixel grey-scale image to an 8-bit-per-pixel +color-mapped image, +.I chandesc +should be +.BR m8 . +If +.I chandesc +is not given, the format is unchanged. +The output image is by default compressed; the +.B -u +option turns off the compression. +.SH EXAMPLE +To crop white edges off the picture and add a ten-pixel pink border, +.IP +.EX +crop -c 255 255 255 -i -10 -b 255 150 150 imagefile > cropped +.EE +.SH SOURCE +.B /sys/src/cmd/crop.c +.SH SEE ALSO +.IR image (6), +.IR color (2) +.SH BUGS +.I Iconv +should be able to do Floyd-Steinberg error diffusion or dithering +when converting to small image depths. diff --git a/static/plan9-4e/man1/date.1 b/static/plan9-4e/man1/date.1 new file mode 100644 index 00000000..3d232baa --- /dev/null +++ b/static/plan9-4e/man1/date.1 @@ -0,0 +1,58 @@ +.TH DATE 1 +.SH NAME +date, clock \- date and time +.SH SYNOPSIS +.B date +[ +.I option +] [ +.I seconds +] +.br +.B clock +.SH DESCRIPTION +Print the date, in the format +.PP +.B + Tue Aug 16 17:03:52 CDT 1977 +.PP +The options are +.TP +.B -u +Report Greenwich Mean Time (GMT) rather than local time. +.TP +.B -n +Report the date as the number of seconds since the +epoch, 00:00:00 GMT, January 1, 1970. +.PP +The conversion from Greenwich Mean Time to local time depends on the +.B $timezone +environment variable; see +.IR ctime (2). +.PP +If the optional argument +.I seconds +is present, it is used as the time to convert rather than +the real time. +.SH FILES +.TF /adm/timezone/local +.TP +.B /env/timezone +Current timezone name and adjustments. +.TP +.B /adm/timezone +A directory containing timezone tables. +.TP +.B /adm/timezone/local +Default timezone file, copied by +.IR init (8) +into +.BR /env/timezone . +.PD +.PP +.I Clock +draws a simple analog clock in its window. +.SH SOURCE +.B /sys/src/cmd/date.c +.br +.B /sys/src/cmd/clock.c diff --git a/static/plan9-4e/man1/db.1 b/static/plan9-4e/man1/db.1 new file mode 100644 index 00000000..34f1f423 --- /dev/null +++ b/static/plan9-4e/man1/db.1 @@ -0,0 +1,1018 @@ +.TH DB 1 +.SH NAME +db \- debugger +.SH SYNOPSIS +.B db +[ +.I option ... +] +[ +.I textfile +] +[ +.I pid +] +.SH DESCRIPTION +.I Db +is a general purpose debugging program. +It may be used to examine files and to provide +a controlled environment for the execution +of Plan 9 programs. +.PP +A +.I textfile +is a file containing the text and initialized +data of an executable program. +A +.I memfile +is the memory image of an executing process. It is +usually accessed via the process id +.RI ( pid ) +of the process in +.BI /proc/ pid /mem\f1. +A +.I memfile +contains the text, data, and saved registers and +process state. A +.I map +associated with each +.I textfile +or +.I memfile +supports accesses to instructions and data in the file; +see `Addresses'. +.PP +An argument consisting entirely of digits is assumed +to be a process id; otherwise, it is the name of a +.IR textfile . +When a +.I textfile +is given, the textfile map +is associated with it. +If only a +.I pid +is given, the textfile map is +associated with +.BI /proc/ pid /text\f1. +When a +.I pid +is given, the memfile map is associated with +.BI /proc/ pid /mem\f1; +otherwise it is undefined and accesses to the +.I memfile +are not permitted. +.PP +Commands to +.I db +are read from the standard input and +responses are to the standard output. +The options are +.TP +.BI -k +Use the kernel stack of process +.IR pid +to debug the executing kernel process. +If +.I textfile +is not specified, file +.BI / $cputype /9 type +is used, where +.I type +is the second word in +.BR $terminal . +.TP +.B -w +Create +.I textfile +and +.I memfile +if they don't exist; open them for writing +as well as reading. +.TP +.BI -I path +Directory in which to look for relative path names in +.B $< +and +.B $<< +commands. +.TP +.BI -m machine +Assume instructions are for the given CPU type +(any standard architecture name, such as +.B alpha +or +.BR 386 , +plus +.B mipsco +and +.BR sunsparc , +which cause disassembly to the manufacturer's syntax) +instead of using the magic number to select +the CPU type. +.PP +Most +.I db +commands have the following form: +.IP +.RI [ address ] +.RB [ , +.IR count ] +.RI [ command ] +.PP +If +.I address +is present then the current position, called `dot', +is set to +.IR address . +Initially dot +is set to 0. +Most commands are repeated +.I count +times with +dot advancing between repetitions. +The default +.I count +is 1. +.I Address +and +.I count +are expressions. +Multiple commands on one line must be separated by +.LR ; . +.SS Expressions +Expressions are evaluated as long +.IR ints . +.TP 7.2n +.B . +The value of dot. +.TP 7.2n +.B + +The value of dot +incremented by the current increment. +.TP 7.2n +.B ^ +The value of dot +decremented by the current increment. +.TP 7.2n +.B \&" +The last +.I address +typed. +.TP 7.2n +.I integer +A number, in decimal radix by default. +The prefixes +.L 0 +and +.L 0o +and +.L 0O +(zero oh) force interpretation +in octal radix; the prefixes +.L 0t +and +.L 0T +force interpretation in +decimal radix; the prefixes +.LR 0x , +.LR 0X , +and +.L # +force interpretation in +hexadecimal radix. +Thus +.LR 020 , +.LR 0o20 , +.LR 0t16 , +and +.L #10 +all represent sixteen. +.TP 7.2n +.IB integer . fraction +A single-precision floating point number. +.TP 7.2n +.BI \' c\| \' +The +16-bit +value of a character. +.L \e +may be used to escape a +.LR \' . +.TP 7.2n +.BI < name +The value of +.IR name , +which is a register name. +The register names are +those printed by the +.B $r +command. +.TP 7.2n +.I symbol +A +.I symbol +is a sequence +of upper or lower case letters, underscores or +digits, not starting with a digit. +.L \e +may be used to escape other characters. +The location of the +.I symbol +is calculated from the symbol table +in +.IR textfile . +.TP 7.2n +.IB routine . name +The address of the variable +.I name +in the specified +C routine. +Both +.I routine +and +.I name +are +.IR symbols . +If +.I name +is omitted the value is the address of the +most recently activated stack frame +corresponding to +.IR routine ; +if +.I routine +is omitted, +the active procedure +is assumed. +.TP 7.2n +.IB file : integer +The address of the instruction corresponding +to the source statement at the indicated +line number of the file. If the source line contains +no executable statement, the address of the +instruction associated with the nearest +executable source line is returned. Files +begin at line 1. If multiple files of the same +name are loaded, an expression of this form resolves +to the first file encountered in the symbol table. +.TP 7.2n +.BI ( exp ) +The value of the expression +.IR exp . +.LP +.I Monadic operators +.RS +.TP 7.2n +.BI * exp +The contents of the location addressed +by +.I exp +in +.IR memfile . +.TP 7.2n +.BI @ exp +The contents of the location addressed by +.I exp +in +.IR textfile . +.TP 7.2n +.BI - exp +Integer negation. +.TP 7.2n +.BI ~ exp +Bitwise complement. +.TP 7.2n +.BI % exp +When used as an +.IR address , +.I exp +is an offset into the segment named +.IR ublock ; +see `Addresses'. +.RE +.LP +.I "Dyadic\ operators" +are left-associative +and are less binding than monadic operators. +.RS +.TP 7.2n +.IB e1 + e2 +Integer addition. +.TP 7.2n +.IB e1 - e2 +Integer subtraction. +.TP 7.2n +.IB e1 * e2 +Integer multiplication. +.TP 7.2n +.IB e1 % e2 +Integer division. +.TP 7.2n +.IB e1 & e2 +Bitwise conjunction. +.TP 7.2n +.IB e1 | e2 +Bitwise disjunction. +.TP 7.2n +.IB e1 # e2 +.I E1 +rounded up to the next multiple of +.IR e2 . +.RE +.DT +.SS Commands +Most commands have the following syntax: +.TP .5i +.BI ? f +Locations starting at +.I address +in +.I textfile +are printed according to the format +.IR f . +.TP +.BI / f +Locations starting at +.I address +in +.I memfile +are printed according to the format +.IR f . +.TP +.BI = f +The value of +.I address +itself is printed according to the format +.IR f . +.PP +A +.I format +consists of one or more characters that specify a style +of printing. +Each format character may be preceded by a decimal integer +that is a repeat count for the format character. +If no format is given then the last format is used. +.PP +Most format letters fetch some data, +print it, +and advance (a local copy of) dot +by the number of bytes fetched. +The total number of bytes in a format becomes the +.IR current increment . +.ta 2.5n .5i +.RS +.TP +.PD 0 +.B o +Print two-byte integer in octal. +.TP +.B O +Print four-byte integer in octal. +.TP +.B q +Print two-byte integer in signed octal. +.TP +.B Q +Print four-byte integer in signed octal. +.TP +.B d +Print two-byte integer in decimal. +.TP +.B D +Print four-byte integer in decimal. +.TP +.B V +Print eight-byte integer in decimal. +.TP +.B Z +Print eight-byte integer in unsigned decimal. +.TP +.B x +Print two-byte integer in hexadecimal. +.TP +.B X +Print four-byte integer in hexadecimal. +.TP +.B Y +Print eight-byte integer in hexadecimal. +.TP +.B u +Print two-byte integer in unsigned decimal. +.TP +.B U +Print four-byte integer in unsigned decimal. +.TP +.B f +Print +as a single-precision floating point number. +.TP +.B F +Print double-precision floating point. +.TP +.B b +Print the addressed byte in hexadecimal. +.TP +.B c +Print the addressed byte as an +.SM ASCII +character. +.TP +.B C +Print the addressed byte as a character. +Printable +.SM ASCII +characters +are represented normally; others +are printed in the form +.BR \exnn . +.TP +.B s +Print the addressed characters, as a +.SM UTF +string, until a zero byte +is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B S +Print a string using +the escape convention (see +.B C +above). +.TP +.B r +Print as +.SM UTF +the addressed two-byte integer (rune). +.TP +.B R +Print as +.SM UTF +the addressed two-byte integers as runes +until a zero rune is reached. +Advance dot +by the length of the string, +including the zero terminator. +.TP +.B i +Print as machine instructions. Dot is +incremented by the size of the instruction. +.TP +.B I +As +.B i +above, but print the machine instructions in +an alternate form if possible: +.B sunsparc +and +.B mipsco +reproduce the manufacturers' syntax. +.TP +.B M +Print the addressed machine instruction in a +machine-dependent hexadecimal form. +.TP +.B a +Print the value of dot +in symbolic form. +Dot is unaffected. +.TP +.B A +Print the value of dot +in hexadecimal. +Dot is unaffected. +.TP +.B z +Print the function name, source file, and line number +corresponding to dot (textfile only). Dot is unaffected. +.TP +.B p +Print the addressed value in symbolic form. +Dot is advanced by the size of a machine address. +.TP +.B t +When preceded by an integer, tabs to the next +appropriate tab stop. +For example, +.B 8t +moves to the next 8-space tab stop. +Dot is unaffected. +.TP +.B n +Print a newline. +Dot is unaffected. +.tr '" +.TP +.BR ' ... ' +Print the enclosed string. +Dot is unaffected. +.br +.tr '' +.TP +.B ^ +Dot is decremented by the current increment. +Nothing is printed. +.TP +.B + +Dot is incremented by 1. +Nothing is printed. +.TP +.B - +Dot is decremented by 1. +Nothing is printed. +.RE +.PD +.LP +Other commands include: +.TP +newline +Update dot by the current increment. +Repeat the previous command with a +.I count +of 1. +.TP +.RB [ ?/ ] l "\fI value mask\fR" +Words starting at dot +are masked with +.I mask +and compared with +.I value +until +a match is found. +If +.B l +is used, +the match is for a two-byte integer; +.B L +matches four bytes. +If no match is found then dot +is unchanged; otherwise dot +is set to the matched location. +If +.I mask +is omitted then ~0 is used. +.TP +.RB [ ?/ ] w "\fI value ...\fR" +Write the two-byte +.I value +into the addressed +location. +If the command is +.BR W , +write four bytes. +.TP +.RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR] +.br +New values for +.RI ( b,\ e,\ f ) +in the segment named +.I s +are recorded. Valid segment names are +.IR text , +.IR data , +or +.IR ublock . +If less than three address expressions are given, +the remaining parameters are left unchanged. +If the list is terminated by +.L ? +or +.L / +then the file +.RI ( textfile +or +.I memfile +respectively) is used +for subsequent requests. +For example, +.L /m? +causes +.L / +to refer to +.IR textfile . +.TP +.BI > name +Dot is assigned to the variable or register named. +.TP +.B ! +The rest of the line is passed to +.IR rc (1) +for execution. +.TP +.BI $ modifier +Miscellaneous commands. +The available +.I modifiers +are: +.RS +.TP +.PD 0 +.BI < f +Read commands from the file +.IR f . +If this command is executed in a file, further commands +in the file are not seen. +If +.I f +is omitted, the current input stream is terminated. +If a +.I count +is given, and is zero, the command is ignored. +.TP +.BI << f +Similar to +.B < +except it can be used in a file of commands without +causing the file to be closed. +There is a (small) limit to the number of +.B << +files that can be open at once. +.br +.ns +.TP +.BI > f +Append output to the file +.IR f , +which is created if it does not exist. +If +.I f +is omitted, output is returned to the terminal. +.TP +.B ? +Print process id, the condition which caused stopping or termination, +the registers and the instruction addressed by +.BR pc . +This is the default if +.I modifier +is omitted. +.TP +.B r +Print the general registers and +the instruction addressed by +.BR pc . +Dot is set to +.BR pc . +.TP +.B R +Like +.BR $r , +but include miscellaneous processor control registers +and floating point registers. +.TP +.B f +Print floating-point register values as +single-precision floating point numbers. +.TP +.B F +Print floating-point register values as +double-precision floating point numbers. +.TP +.B b +Print all breakpoints +and their associated counts and commands. `B' produces the same results. +.TP +.B c +Stack backtrace. +If +.I address +is given, it specifies the address of a pair of 32-bit +values containing the +.B sp +and +.B pc +of an active process. This allows selecting +among various contexts of a multi-threaded +process. +If +.B C +is used, the names and (long) values of all +parameters, +automatic +and static variables are printed for each active function. +If +.I count +is given, only the first +.I count +frames are printed. +.TP +.B a +Attach to the running process whose pid +is contained in +.IR address . +.TP +.B e +The names and values of all +external variables are printed. +.TP +.B w +Set the page width for output to +.I address +(default 80). +.TP +.B q +Exit from +.IR db . +.TP +.B m +Print the address maps. +.TP +.B k +Simulate kernel memory management. +.TP +.BI M machine +Set the +.I machine +type used for disassembling instructions. +.PD +.RE +.TP +.BI : modifier +Manage a subprocess. +Available modifiers are: +.RS +.TP +.PD 0 +.BI h +Halt +an asynchronously running process to allow breakpointing. +Unnecessary for processes created under +.IR db , +e.g. by +.BR :r . +.TP +.BI b c +Set breakpoint at +.IR address . +The breakpoint is executed +.IR count \-1 +times before +causing a stop. +Also, if a command +.I c +is given it is executed at each +breakpoint and if it sets dot to zero +the breakpoint causes a stop. +.TP +.B d +Delete breakpoint at +.IR address . +.TP +.B r +Run +.I textfile +as a subprocess. +If +.I address +is given the +program is entered at that point; otherwise +the standard entry point is used. +.I Count +specifies how many breakpoints are to be +ignored before stopping. +Arguments to the subprocess may be supplied on the +same line as the command. +An argument starting with < or > causes the standard +input or output to be established for the command. +.TP +.BI c s +The subprocess is continued. +If +.I s +is omitted +or nonzero, +the subprocess +is sent the note that caused it to stop. +If 0 +is specified, +no note is sent. +(If the stop was due to a breakpoint or single-step, +the corresponding note is elided before continuing.) +Breakpoint skipping is the same +as for +.BR r . +.TP +.BI s s +As for +.B c +except that +the subprocess is single stepped for +.I count +machine instructions. +If a note is pending, +it is received +before the first instruction is executed. +If there is no current subprocess then +.I textfile +is run +as a subprocess as for +.BR r . +In this case no note can be sent; the remainder of the line +is treated as arguments to the subprocess. +.TP +.BI S s +Identical to +.B s +except the subprocess is single stepped for +.I count +lines of C source. In optimized code, the correspondence +between C source and the machine instructions is +approximate at best. +.TP +.BI x +The current subprocess, if any, is released by +.I db +and allowed to continue executing normally. +.TP +.B k +The current subprocess, if any, is terminated. +.TP +.BI n c +Display the pending notes for the process. +If +.I c +is specified, first delete +.I c'th +pending note. +.PD +.RE +.SS Addresses +The location in a file or memory image associated with +an address is calculated from a map +associated with the file. +Each map contains one or more quadruples +.RI ( "t, b, e, f" ), +defining a segment named +.I t +(usually, +.IR text , +.IR data , +or +.IR ublock ) +mapping addresses in the range +.I b +through +.I e +to the part of the file +beginning at +offset +.IR f . +The memory model of a Plan 9 process assumes +that segments are disjoint. There +can be more than one segment of a given type (e.g., a process +may have more than one text segment) but segments +may not overlap. +An address +.I a +is translated +to a file address +by finding a segment +for which +.IR b ≤ a < e ; +the location in the file +is then +.IR address + f \- b . +.PP +Usually, +the text and initialized data of a program +are mapped by segments called +.I text +and +.IR data . +Since a program file does not contain bss, stack or ublock data, +these data are +not mapped by the data segment. +The text segment is mapped similarly in +a normal (i.e., non-kernel) +.IR memfile . +However, the segment called +.I data +maps memory from the beginning of the program's data space to +the base of the ublock. +This region contains the program's static data, the bss, the +heap and the stack. A segment +called +.I ublock +maps the page containing its registers and process state. +.PP +Sometimes it is useful to define a map with a single segment +mapping the region from 0 to 0xFFFFFFFF; a map of this type +allows the entire file to be examined +without address translation. +.PP +Registers are saved at a machine-dependent offset in the ublock. +It is usually not necessary to know this offset; the +.BR $r , +.BR $R , +.BR $f , +and +.BR $F +commands calculate it and display the register contents. +.PP +The +.B $m +command dumps the currently active maps. The +.B ?m +and +.B /m +commands modify the segment parameters in the +.I textfile +and +.I memfile +maps, respectively. +.SH EXAMPLES +To set a breakpoint at the beginning of +.B write() +in extant process 27: +.IP +.EX +% db 27 +:h +write:b +:c +.EE +.PP +To examine the Plan 9 kernel stack for process 27: +.IP +.EX +% db -k 27 +$C +.EE +.PP +Similar, but using a kernel named +.BR test : +.IP +.EX +% db -k test 27 +$C +.EE +.PP +To set a breakpoint at the entry of function +.B parse +when the local variable +.B argc +in +.B main +is equal to 1: +.IP +.EX +parse:b *main.argc-1=X +.EE +.PP +This prints the value of +.B argc-1 +which as a side effect sets dot; when +.B argc +is one the breakpoint will fire. +Beware that local variables may be stored in registers; see the +BUGS section. +.PP +Debug process 127 on remote machine +.BR kremvax : +.IP +.EX +% import kremvax /proc +% db 127 +$C +.EE +.SH FILES +.B /proc/*/text +.br +.B /proc/*/mem +.br +.B /proc/*/ctl +.br +.B /proc/*/note +.SH "SEE ALSO" +.IR acid (1), +.IR nm (1), +.IR proc (3) +.SH SOURCE +.B /sys/src/cmd/db +.SH DIAGNOSTICS +Exit status is null, unless the last command failed or +returned non-null status. +.SH BUGS +Examining a local variable with +.I routine.name +returns the contents of the memory allocated for the variable, but +with optimization (suppressed by the +.B -N +compiler flag) variables often reside in registers. +Also, on some architectures, the first argument is always +passed in a register. +.PP +Variables and parameters that have been +optimized away do not appear in the +symbol table, returning the error +.IR "bad local variable" +when accessed by +.IR db . +.PP +Because of alignment incompatibilities, Motorola 68000 +series machines can not be debugged remotely from a +processor of a different type. +.PP +Breakpoints should not be set on instructions scheduled +in delay slots. When a program stops on such a breakpoint, +it is usually impossible to continue its execution. diff --git a/static/plan9-4e/man1/dc.1 b/static/plan9-4e/man1/dc.1 new file mode 100644 index 00000000..0f2c13a5 --- /dev/null +++ b/static/plan9-4e/man1/dc.1 @@ -0,0 +1,257 @@ +.TH DC 1 +.SH NAME +dc \- desk calculator +.SH SYNOPSIS +.B dc +[ +.I file +] +.SH DESCRIPTION +.I Dc +is an arbitrary precision desk calculator. +Ordinarily it operates on decimal integers, +but one may specify an input base, output base, +and a number of fractional digits to be maintained. +The overall structure of +.I dc +is +a stacking (reverse Polish) calculator. +If an argument is given, +input is taken from that file until its end, +then from the standard input. +The following constructions are recognized: +.TP +number +The value of the number is pushed on the stack. +A number is an unbroken string of the digits +.B 0-9A-F +or +.BR 0-9a-f . +A hexadecimal number beginning with a lower case +letter must be preceded by a zero to distinguish it +from the command associated with the letter. +It may be preceded by an underscore +.B _ +to input a +negative number. +Numbers may contain decimal points. +.TP +.L ++ - / * % ^ +Add +.LR + , +subtract +.LR - , +multiply +.LR * , +divide +.LR / , +remainder +.LR % , +or exponentiate +.L ^ +the top two values on the stack. +The two entries are popped off the stack; +the result is pushed on the stack in their place. +Any fractional part of an exponent is ignored. +.TP +.BI s x +.br +.ns +.TP +.BI S x +Pop the top of the stack and store into +a register named +.IR x , +where +.I x +may be any character. +Under operation +.B S +register +.I x +is treated as a stack and the value is pushed on it. +.TP +.BI l x +.br +.ns +.TP +.BI L x +Push the value in register +.I x +onto the stack. +The register +.I x +is not altered. +All registers start with zero value. +Under operation +.B L +register +.I x +is treated as a stack and its top value is popped onto the main stack. +.TP +.B d +Duplicate the +top value on the stack. +.TP +.B p +Print the top value on the stack. +The top value remains unchanged. +.B P +interprets the top of the stack as an +text +string, +removes it, and prints it. +.TP +.B f +Print the values on the stack. +.TP +.B q +.br +.ns +.TP +.B Q +Exit the program. +If executing a string, the recursion level is +popped by two. +Under operation +.B Q +the top value on the stack is popped and the string execution level is popped +by that value. +.TP +.B x +Treat the top element of the stack as a character string +and execute it as a string of +.I dc +commands. +.TP +.B X +Replace the number on the top of the stack with its scale factor. +.TP +.B "[ ... ]" +Put the bracketed +text +string on the top of the stack. +.TP +.PD0 +.BI < x +.TP +.BI > x +.TP +.BI = x +.PD +Pop and compare the +top two elements of the stack. +Register +.I x +is executed if they obey the stated +relation. +.TP +.B v +Replace the top element on the stack by its square root. +Any existing fractional part of the argument is taken +into account, but otherwise the scale factor is ignored. +.TP +.B ! +Interpret the rest of the line as a shell command. +.TP +.B c +Clear the stack. +.TP +.B i +The top value on the stack is popped and used as the +number base for further input. +.TP +.B I +Push the input base on the top of the stack. +.TP +.B o +The top value on the stack is popped and used as the +number base for further output. +In bases larger than 10, each `digit' prints as a group of decimal digits. +.TP +.B O +Push the output base on the top of the stack. +.TP +.B k +Pop the top of the stack, and use that value as +a non-negative scale factor: +the appropriate number of places +are printed on output, +and maintained during multiplication, division, and exponentiation. +The interaction of scale factor, +input base, and output base will be reasonable if all are changed +together. +.TP +.B z +Push the stack level onto the stack. +.TP +.B Z +Replace the number on the top of the stack with its length. +.TP +.B ? +A line of input is taken from the input source (usually the terminal) +and executed. +.TP +.B "; :" +Used by +.I bc +for array operations. +.PP +The scale factor set by +.B k +determines how many digits are kept to the right of +the decimal point. +If +.I s +is the current scale factor, +.I sa +is the scale of the first operand, +.I sb +is the scale of the second, +and +.I b +is the (integer) second operand, +results are truncated to the following scales. +.IP +.nf +\fL+\fR,\fL-\fR max(\fIsa,sb\fR) +\fL*\fR min(\fIsa\fR+\fIsb \fR, max\fR(\fIs,sa,sb\fR)) +\fL/\fI s +\fL%\fR so that dividend = divisor*quotient + remainder; remainder has sign of dividend +\fL^\fR min(\fIsa\fR\(mu|\fIb\fR|, max(\fIs,sa\fR)) +\fLv\fR max(\fIs,sa\fR) +.fi +.SH EXAMPLES +.EX +[la1+dsa*pla10>y]sy +0sa1 +lyx +.EE +.ns +.IP +Print the first ten values of +.IR n ! +.SH SOURCE +.B /sys/src/cmd/dc.c +.SH "SEE ALSO" +.IR bc (1), +.IR hoc (1) +.SH DIAGNOSTICS +.I x +.LR "is unimplemented" , +where +.I x +is an octal number: an internal error. +.br +`Out of headers' +for too many numbers being kept around. +.br +`Nesting depth' +for too many levels of nested execution. +.SH BUGS +When the input base exceeds 16, +there is no notation for digits greater than +.BR F . +.PP +Past its time. diff --git a/static/plan9-4e/man1/dd.1 b/static/plan9-4e/man1/dd.1 new file mode 100644 index 00000000..fbbfe61e --- /dev/null +++ b/static/plan9-4e/man1/dd.1 @@ -0,0 +1,187 @@ +.TH DD 1 +.SH NAME +dd \- convert and copy a file +.SH SYNOPSIS +.B dd +[ +.I option value +] +\&... +.SH DESCRIPTION +.I Dd\^ +copies the specified input file +to the specified output with +possible conversions. +The standard input and output are used by default. +The input and output block size may be +specified to take advantage of raw physical I/O. +The options are +.TP \w'\fLoseek\ \ \fIn'u +.BI -if\ f +Open file +.I f +for input. +.TP +.BI -of\ f +Open file +.I f +for output. +.TP +.BI -ibs\ n\^ +Set input block size to +.I n\^ +bytes (default 512). +.TP +.BI -obs\ n\^ +Set output block size (default 512). +.TP +.BI -bs\ n\^ +Set both input and output block size, +superseding +.I ibs\^ +and +.IR obs . +If no conversion is specified, +preserve the input block size instead of packing short blocks +into the output buffer. +This is particularly efficient since no in-core copy need be done. +.TP +.BI -cbs\ n\^ +Set conversion buffer size. +.TP +.BI -skip\ n\^ +Skip +.I n +input records before copying. +.TP +.BI -iseek\ n\^ +Seek +.I n +records forward on input file +before copying. +.TP +.BI -files\ n\^ +Catenate +.I n +input files (useful only for magnetic tape or similar input device). +.TP +.BI -oseek\ n\^ +Seek +.I n\^ +records from beginning of output file before copying. +.TP +.BI -count\ n\^ +Copy only +.I n +input records. +.TP +.BI -trunc\ n\^ +By default, +.I dd +truncates the output file when it opens it; +.B -trunc +.B 0 +opens it without truncation. +.HP +\fL-conv\ ascii\ \ \ \ \fRConvert +.SM EBCDIC +to +.SM ASCII. +.PD0 +.RS "\w'\fLconv\ \fP'u" +.TP "\w'\fLunblock\ \ \fP'u" +.B ebcdic +Convert +.SM ASCII +to +.SM EBCDIC. +.TP +.B ibm +Like +.B ebcdic +but with a slightly different character map. +.TP +.B block +Convert variable length +.SM ASCII +records to fixed length. +.TP +.B unblock +Convert fixed length +.SM ASCII +records to variable length. +.TP +.B lcase +Map alphabetics to lower case. +.TP +.B ucase +Map alphabetics to upper case. +.TP +.B swab +Swap every pair of bytes. +.TP +.B noerror +Do not stop processing on an error. +.TP +.B sync +Pad every input record to +.I ibs\^ +bytes. +.RE +.PD +.PP +.fi +Where sizes are specified, +a number of bytes is expected. +A number may end with +.L k +or +.LR b +to specify multiplication by +1024 or 512 respectively; +a pair of numbers may be separated by +.L x +to indicate a product. +Multiple conversions may be specified in the style: +.LR "-conv ebcdic,ucase" . +.PP +.L Cbs\^ +is used only if +.LR ascii\^ , +.LR unblock\^ , +.LR ebcdic\^ , +.LR ibm\^ , +or +.L block\^ +conversion is specified. +In the first two cases, +.I n +characters are copied into the conversion buffer, any specified +character mapping is done, +trailing blanks are trimmed and new-line is added +before sending the line to the output. +In the latter three cases, characters are read into the +conversion buffer and blanks are added to make up an +output record of size +.IR n . +If +.L cbs\^ +is unspecified or zero, the +.LR ascii\^ , +.LR ebcdic\^ , +and +.L ibm\^ +options convert the character set without changing the block +structure of the input file; the +.L unblock\^ +and +.L block\^ +options become a simple file copy. +.SH SOURCE +.B /sys/src/cmd/dd.c +.SH "SEE ALSO" +.IR cp (1) +.SH DIAGNOSTICS +.I Dd +reports the number of full + partial input and output +blocks handled. diff --git a/static/plan9-4e/man1/deroff.1 b/static/plan9-4e/man1/deroff.1 new file mode 100644 index 00000000..f62b174d --- /dev/null +++ b/static/plan9-4e/man1/deroff.1 @@ -0,0 +1,117 @@ +.TH DEROFF 1 +.SH NAME +deroff, delatex \- remove formatting requests +.SH SYNOPSIS +.B deroff +[ +.I option ... +] +.I file ... +.PP +.B delatex +.I file +.SH DESCRIPTION +.I Deroff +reads each file in sequence +and removes all +.I nroff +and +.IR troff (1) +requests and non-text arguments, backslash constructions, +and constructs of preprocessors such as +.IR eqn (1), +.IR pic (1), +and +.IR tbl (1). +Remaining text is written on the standard output. +.I Deroff +follows files included by +.L .so +and +.L .nx +commands; +if a file has already been included, a +.L .so +for that file is ignored and a +.L .nx +terminates execution. +If no input file is given, +.I deroff +reads from standard input. +.PP +The options are +.TP +.B -w +Output a word list, one `word' (string of letters, digits, and +properly embedded ampersands and apostrophes, +beginning with a letter) per line. +Other characters are skipped. +Otherwise, the output follows the original, with the deletions mentioned above. +.TP +.B -_ +Like +.BR -w , +but consider underscores to be alphanumeric rather than punctuation. +.TP +.B -i +Ignore +.L .so +and +.L .nx +requests. +.TP +.BR -ms +.PD0 +.TP +.B -mm +Remove titles, attachments, etc., as well as ordinary +.IR troff +constructs, from +.IR ms (6) +or +.I mm +documents. +.PD +.TP +.B -ml +Same as +.BR -mm , +but remove lists as well. +.PP +.I Delatex +does for +.I tex +and +.I latex +(see +.IR tex (1)) +files what +.B deroff -wi +does for +.I troff +files. +.SH SOURCE +.B /sys/src/cmd/deroff.c +.br +.B /sys/src/cmd/tex/local/delatex.c +.SH "SEE ALSO" +.IR troff (1), +.IR tex (1), +.IR spell (1) +.SH BUGS +These filters are not complete interpreters of +.I troff +or +.IR tex . +For example, macro definitions containing +.L \e$ +cause chaos in +.IR deroff +when the popular +.L $$ +delimiters for +.I eqn +are in effect. +.br +Text inside macros is emitted at place of +definition, not place of call. diff --git a/static/plan9-4e/man1/diff.1 b/static/plan9-4e/man1/diff.1 new file mode 100644 index 00000000..404c74f0 --- /dev/null +++ b/static/plan9-4e/man1/diff.1 @@ -0,0 +1,155 @@ +.TH DIFF 1 +.SH NAME +diff \- differential file comparator +.SH SYNOPSIS +.B diff +[ +.B -efmnbwr +] file1 ... file2 +.SH DESCRIPTION +.I Diff +tells what lines must be changed in two files to bring them +into agreement. +If one file +is a directory, +then a file in that directory with basename the same as that of +the other file is used. +If both files are directories, similarly named files in the +two directories are compared by the method of +.I diff +for text +files and +.IR cmp (1) +otherwise. +If more than two file names are given, then each argument is compared +to the last argument as above. +The +.B -r +option causes +.I diff +to process similarly named subdirectories recursively. +When processing more than one file, +.I diff +prefixes file differences with a single line +listing the two differing files, in the form of +a +.I diff +command line. +The +.B -m +flag causes this behavior even when processing single files. +.PP +The normal output contains lines of these forms: +.IP "" 5 +.I n1 +.B a +.I n3,n4 +.br +.I n1,n2 +.B d +.I n3 +.br +.I n1,n2 +.B c +.I n3,n4 +.PP +These lines resemble +.I ed +commands to convert +.I file1 +into +.IR file2 . +The numbers after the letters pertain to +.IR file2 . +In fact, by exchanging `a' for `d' and reading backward +one may ascertain equally how to convert +.I file2 +into +.IR file1 . +As in +.IR ed , +identical pairs where +.I n1 += +.I n2 +or +.I n3 += +.I n4 +are abbreviated as a single number. +.PP +Following each of these lines come all the lines that are +affected in the first file flagged by `<', +then all the lines that are affected in the second file +flagged by `>'. +.PP +The +.B -b +option causes +trailing blanks (spaces and tabs) to be ignored +and other strings of blanks to compare equal. +The +.B -w +option causes all white-space to be removed from input lines +before applying the difference algorithm. +.PP +The +.B -n +option prefixes each range with +.IB file : \fR +and inserts a space around the +.BR a , +.BR c , +and +.B d +verbs. +The +.B -e +option produces a script of +.I "a, c" +and +.I d +commands for the editor +.IR ed , +which will recreate +.I file2 +from +.IR file1 . +The +.B -f +option produces a similar script, +not useful with +.IR ed , +in the opposite order. It may, however, be +useful as input to a stream-oriented post-processor. +.PP +Except in rare circumstances, +.I diff +finds a smallest sufficient set of file +differences. +.SH FILES +.B /tmp/diff[12] +.SH SOURCE +.B /sys/src/cmd/diff +.SH "SEE ALSO" +.IR cmp (1), +.IR comm (1), +.IR ed (1) +.SH DIAGNOSTICS +Exit status is the empty string +for no differences, +.L some +for some, +and +.L error +for trouble. +.SH BUGS +Editing scripts produced under the +.BR -e " or" +.BR -f " option are naive about" +creating lines consisting of a single `\fB.\fR'. +.br +When running +.I diff +on directories, the notion of what is a text +file is open to debate. diff --git a/static/plan9-4e/man1/doc2txt.1 b/static/plan9-4e/man1/doc2txt.1 new file mode 100644 index 00000000..db7beb78 --- /dev/null +++ b/static/plan9-4e/man1/doc2txt.1 @@ -0,0 +1,53 @@ +.TH DOC2TXT 1 +.SH NAME +doc2txt, olefs, mswordstrings \- extract printable strings from Microsoft Word documents +.SH SYNOPSIS +.B doc2txt +[ +.I file.doc +] +.br +.B aux/olefs +[ +.B -m +.I mtpt +] +.I file.doc +.br +.B aux/mswordstrings +.I /mnt/doc/WordDocument +.SH DESCRIPTION +.I Doc2txt +is a shell script that uses +.I olefs +and +.I mswordstrings +to extract the printable text from the body of a Microsoft Word document. +.PP +Microsoft Office documents are stored in OLE (Object Linking and Embedding) +format, which is a scaled down version of Microsoft's FAT file system. +.I Olefs +presents the contents of an Office document as a file system +on +.IR mtpt , +which defaults to +.BR /mnt/doc . +.I Mswordstrings +parses the +.I WordDocument +file inside an Office document, extracting +the text stream. +.SH SOURCE +.B /sys/src/cmd/aux/mswordstrings.c +.br +.B /sys/src/cmd/aux/olefs.c +.br +.B /rc/bin/doc2txt +.SH SEE ALSO +.IR strings (1) +.br +``Microsoft Word 97 Binary File Format'', +available on line at Microsoft's developer home page. +.br +``LAOLA Binary Structures'', +.IR snake.cs.tu-berlin.de:8081/~schwartz/pmh . diff --git a/static/plan9-4e/man1/doctype.1 b/static/plan9-4e/man1/doctype.1 new file mode 100644 index 00000000..14d314d9 --- /dev/null +++ b/static/plan9-4e/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 (6) +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 /rc/bin/doctype +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR ms (6), +.IR man (6) +.SH BUGS +In true A.I. style, its best guesses are inspired rather than accurate. diff --git a/static/plan9-4e/man1/du.1 b/static/plan9-4e/man1/du.1 new file mode 100644 index 00000000..e7dafbbe --- /dev/null +++ b/static/plan9-4e/man1/du.1 @@ -0,0 +1,97 @@ +.TH DU 1 +.SH NAME +du \- disk usage +.SH SYNOPSIS +.B du +[ +.B -a +] +[ +.B -f +] +[ +.B -n +] +[ +.B -q +] +[ +.B -s +] +[ +.B -t +] +[ +.B -u +] +[ +.BI -b size +] +[ +.I file ... +] +.SH DESCRIPTION +.I Du +gives the number of Kbytes allocated to data blocks +of named +.I files +and, recursively, of files in named directories. +It assumes storage is quantized in units of 1024 bytes (Kbytes) by default. +Other values can be set by the +.B -b +option; +.I size +is the number of bytes, optionally suffixed +.B k +to specify multiplication by 1024. +If +.I file +is missing, +the current directory is used. +The count for a directory includes the counts of the +contained files and directories. +.PP +The +.B -a +option prints the number of blocks +for every file in a directory. +Normally counts are printed only for contained directories. +.PP +The +.B -f +option ignores errors, +otherwise it stops on the first error. +.PP +The +.B -n +option prints the size in bytes and the name of each file; it sets +.BR -a . +.PP +The +.B -t +option prints, in the format of +.B du +.BR -n , +the modified time of +each file rather than the size. +If the options +.B -tu +are specified then the accessed time is printed. +.PP +The +.B -q +option prints, in the format of +.B du +.BR -n , +the QID of +each file rather than the size. +.PP +Finally, the +.B -s +option causes +.I du +to descend the hierarchy as always, but to print only a summary line +for each +.IR file . +.SH SOURCE +.B /sys/src/cmd/du.c diff --git a/static/plan9-4e/man1/echo.1 b/static/plan9-4e/man1/echo.1 new file mode 100644 index 00000000..3500b412 --- /dev/null +++ b/static/plan9-4e/man1/echo.1 @@ -0,0 +1,20 @@ +.TH ECHO 1 +.SH NAME +echo \- print arguments +.SH SYNOPSIS +.B echo +[ +.B -n +] +[ +.I arg ... +] +.SH DESCRIPTION +.I Echo +writes its arguments separated by blanks and terminated by +a newline on the standard output. +Option +.B -n +suppresses the newline. +.SH SOURCE +.B /sys/src/cmd/echo.c diff --git a/static/plan9-4e/man1/ed.1 b/static/plan9-4e/man1/ed.1 new file mode 100644 index 00000000..adb79fb7 --- /dev/null +++ b/static/plan9-4e/man1/ed.1 @@ -0,0 +1,683 @@ +.TH ED 1 +.SH NAME +ed \- text editor +.SH SYNOPSIS +.B ed +[ +.B - +] +[ +.B -o +] +[ +.I file +] +.SH DESCRIPTION +.I Ed +is a venerable text editor. +.PP +If a +.I file +argument is given, +.I ed +simulates an +.L e +command (see below) on that file: +it is read into +.I ed's +buffer so that it can be edited. +The options are +.TP +.B - +Suppress the printing +of character counts by +.LR e , +.LR r , +and +.L w +commands and of the confirming +.L ! +by +.L ! +commands. +.TP +.B -o +(for output piping) +Write all output to the standard error file except writing by +.L w +commands. +If no +.I file +is given, make +.B /fd/1 +the remembered file; see the +.L e +command below. +.PP +.I Ed +operates on a `buffer', a copy of the file it is editing; +changes made +in the buffer have no effect on the file until a +.L w +(write) +command is given. +The copy of the text being edited resides +in a temporary file called the +.IR buffer . +.PP +Commands to +.I ed +have a simple and regular structure: zero, one, or +two +.I addresses +followed by a single character +.IR command , +possibly +followed by parameters to the command. +These addresses specify one or more lines in the buffer. +Missing addresses are supplied by default. +.PP +In general, only one command may appear on a line. +Certain commands allow the +addition of text to the buffer. +While +.I ed +is accepting text, it is said +to be in +.I "input mode." +In this mode, no commands are recognized; +all input is merely collected. +Input mode is left by typing a period +.L . +alone at the +beginning of a line. +.PP +.I Ed +supports the +.I "regular expression" +notation described in +.IR regexp (6). +Regular expressions are used in addresses to specify +lines and in one command +(see +.I s +below) +to specify a portion of a line which is to be replaced. +If it is desired to use one of +the regular expression metacharacters as an ordinary +character, that character may be preceded by +.RB ` \e '. +This also applies to the character bounding the regular +expression (often +.LR / ) +and to +.L \e +itself. +.PP +To understand addressing in +.I ed +it is necessary to know that at any time there is a +.I "current line." +Generally, the current line is +the last line affected by a command; however, +the exact effect on the current line +is discussed under the description of +each command. +Addresses are constructed as follows. +.TP +1. +The character +.LR . , +customarily called `dot', +addresses the current line. +.TP +2. +The character +.L $ +addresses the last line of the buffer. +.TP +3. +A decimal number +.I n +addresses the +.IR n -th +line of the buffer. +.TP +4. +.BI \'x +addresses the line marked with the name +.IR x , +which must be a lower-case letter. +Lines are marked with the +.L k +command. +.TP +5. +A regular expression enclosed in slashes ( +.LR / ) +addresses +the line found by searching forward from the current line +and stopping at the first line containing a +string that matches the regular expression. +If necessary the search wraps around to the beginning of the +buffer. +.TP +6. +A regular expression enclosed in queries +.L ? +addresses +the line found by searching backward from the current line +and stopping at the first line containing +a string that matches the regular expression. +If necessary +the search wraps around to the end of the buffer. +.TP +7. +An address followed by a plus sign +.L + +or a minus sign +.L - +followed by a decimal number specifies that address plus +(resp. minus) the indicated number of lines. +The plus sign may be omitted. +.TP +8. +An address followed by +.L + +(or +.LR - ) +followed by a +regular expression enclosed in slashes specifies the first +matching line following (or preceding) that address. +The search wraps around if necessary. +The +.L + +may be omitted, so +.L 0/x/ +addresses the +.I first +line in the buffer with an +.LR x . +Enclosing the regular expression in +.L ? +reverses the search direction. +.TP +9. +If an address begins with +.L + +or +.L - +the addition or subtraction is taken with respect to the current line; +e.g.\& +.L -5 +is understood to mean +.LR .-5 . +.TP +10. +If an address ends with +.L + +or +.LR - , +then 1 is added (resp. subtracted). +As a consequence of this rule and rule 9, +the address +.L - +refers to the line before the current line. +Moreover, +trailing +.L + +and +.L - +characters +have cumulative effect, so +.L -- +refers to the current +line less 2. +.TP +11. +To maintain compatibility with earlier versions of the editor, +the character +.L ^ +in addresses is +equivalent to +.LR - . +.PP +Commands may require zero, one, or two addresses. +Commands which require no addresses regard the presence +of an address as an error. +Commands which accept one or two addresses +assume default addresses when insufficient are given. +If more addresses are given than a command requires, +the last one or two (depending on what is accepted) are used. +.PP +Addresses are separated from each other typically by a comma +.LR , . +They may also be separated by a semicolon +.LR ; . +In this case the current line +is set to +the previous address before the next address is interpreted. +If no address precedes a comma or semicolon, line 1 is assumed; +if no address follows, the last line of the buffer is assumed. +The second address of any two-address sequence +must correspond to a line following the line corresponding to the first address. +.PP +In the following list of +.I ed +commands, the default addresses +are shown in parentheses. +The parentheses are not part of +the address, but are used to show that the given addresses are +the default. +`Dot' means the current line. +.TP +.RB (\|\fL.\fP\|) \|a +.br +.ns +.TP + +.br +.ns +.TP +.B . +Read the given text +and append it after the addressed line. +Dot is left +on the last line input, if there +were any, otherwise at the addressed line. +Address +.L 0 +is legal for this command; text is placed +at the beginning of the buffer. +.TP +.RB (\|\fL.,.\fP\|) \|b [ +- ][\fIpagesize\fP][ pln\fR] +Browse. +Print a `page', normally 20 lines. +The optional +.L + +(default) or +.L - +specifies whether the next or previous +page is to be printed. +The optional +.I pagesize +is the number of lines in a page. +The optional +.LR p , +.LR n , +or +.L l +causes printing in the specified format, initially +.LR p . +Pagesize and format are remembered between +.L b +commands. +Dot is left at the last line displayed. +.TP +.RB (\|\fL.,.\fP\|) \|c +.br +.ns +.TP + +.br +.ns +.TP +.B . +Change. +Delete the addressed lines, then accept input +text to replace these lines. +Dot is left at the last line input; if there were none, +it is left at the line preceding the deleted lines. +.TP +.RB (\|\fL.,.\fP\|) \|d +Delete the addressed lines from the buffer. +Dot is set to the line following the last line deleted, or to +the last line of the buffer if the deleted lines had no successor. +.TP +.BI e " filename" +Edit. +Delete the entire contents of the buffer; +then read the named file into the buffer. +Dot is set to the last line of the buffer. +The number of characters read is typed. +The file name is remembered for possible use in later +.LR e , +.LR r , +or +.L w +commands. +If +.I filename +is missing, the remembered name is used. +.TP +.BI E " filename" +Unconditional +.LR e ; +see +.RL ` q ' +below. +.TP +.BI f " filename" +Print the currently remembered file name. +If +.I filename +is given, +the currently remembered file name is first changed to +.IR filename . +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/\fIcommand\ list\fP +.PD 0 +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP/ +.TP +.RB (\|\fL1,$\fP\|) \|g/\fIregular\ expression\fP +.PD +Global. +First mark every line which matches +the given +.IR regular expression . +Then for every such line, execute the +.I command list +with dot initially set to that line. +A single command or the first of multiple commands +appears on the same line with the global command. +All lines of a multi-line list except the last line must end with +.LR \e . +The +.RB \&` \&. \&' +terminating input mode for an +.LR a , +.LR i , +.L c +command may be omitted if it would be on the +last line of the command list. +The commands +.L g +and +.L v +are not permitted in the command list. +Any character other than space or newline may +be used instead of +.L / +to delimit the regular expression. +The second and third forms mean +.BI g/ regular\ expression /p \f1. +.TP +.RB (\| .\| ) \|i +.PD 0 +.TP + +.TP +.B . +Insert the given text before the addressed line. +Dot is left at the last line input, or, if there were none, +at the line before the addressed line. +This command differs from the +.I a +command only in the placement of the +text. +.PD +.TP +.RB (\| .,.+1 \|) \|j +Join the addressed lines into a single line; +intermediate newlines are deleted. +Dot is left at the resulting line. +.TP +.RB (\|\fL.\fP\|) \|k\fIx\fP +Mark the addressed line with name +.IR x , +which must be a lower-case letter. +The address form +.BI \' x +then addresses this line. +.ne 2.5 +.TP +.RB (\|\fL.,.\fP\|) \|l +List. +Print the addressed lines in an unambiguous way: +a tab is printed as +.LR \et , +a backspace as +.LR \eb , +backslashes as +.LR \e\e , +and non-printing characters as +a backslash, an +.LR x , +and four hexadecimal digits. +Long lines are folded, +with the second and subsequent sub-lines indented one tab stop. +If the last character in the line is a blank, +it is followed by +.LR \en . +An +.L l +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|m\fIa +Move. +Reposition the addressed lines after the line +addressed by +.IR a . +Dot is left at the last moved line. +.TP +.RB (\|\fL.,.\fP\|) \|n +Number. +Perform +.LR p , +prefixing each line with its line number and a tab. +An +.L n +may be appended, like +.LR p , +to any non-I/O command. +.TP +.RB (\|\fL.,.\fP\|) \|p +Print the addressed lines. +Dot is left at the last line printed. +A +.L p +appended to any non-I/O command causes the then current line +to be printed after the command is executed. +.TP +.RB (\|\fL.,.\fP\|) \|P +This command is a synonym for +.LR p . +.TP +.B q +Quit the editor. +No automatic write +of a file is done. +A +.L q +or +.L e +command is considered to be in error if the buffer has +been modified since the last +.LR w , +.LR q , +or +.L e +command. +.TP +.B Q +Quit unconditionally. +.TP +.RB ( $ )\|r\ \fIfilename\fP +Read in the given file after the addressed line. +If no +.I filename +is given, the remembered file name is used. +The file name is remembered if there were no +remembered file name already. +If the read is successful, the number of characters +read is printed. +Dot is left at the last line read from the file. +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/ +.PD 0 +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP/g +.TP +.RB (\|\fL.,.\fP\|) \|s\fIn\fP/\fIregular\ expression\fP/\fIreplacement\fP +.PD +Substitute. +Search each addressed +line for an occurrence of the specified regular expression. +On each line in which +.I n +matches are found +.RI ( n +defaults to 1 if missing), +the +.IR n th +matched string is replaced by the replacement specified. +If the global replacement indicator +.L g +appears after the command, +all subsequent matches on the line are also replaced. +It is an error for the substitution to fail on all addressed lines. +Any character other than space or newline +may be used instead of +.L / +to delimit the regular expression +and the replacement. +Dot is left at the last line substituted. +The third form means +.BI s n / regular\ expression / replacement\fP/p\f1. +The second +.L / +may be omitted if the replacement is +empty. +.IP +An ampersand +.L & +appearing in the replacement +is replaced by the string matching the regular expression. +The characters +.BI \e n\f1, +where +.I n +is a digit, +are replaced by the text matched by the +.IR n -th +regular subexpression +enclosed between +.L ( +and +.LR ) . +When +nested parenthesized subexpressions +are present, +.I n +is determined by counting occurrences of +.L ( +starting from the left. +.IP +A literal +.LR & , +.LR / , +.L \e +or newline may be included in a replacement +by prefixing it with +.LR \e . +.TP +.RB (\|\fL.,.\fP\|) \|t\|\fIa +Transfer. +Copy the addressed lines +after the line addressed by +.IR a . +Dot is left at the last line of the copy. +.TP +.RB (\|\fL.,.\fP\|) \|u +Undo. +Restore the preceding contents +of the first addressed line (sic), which must be the last line +in which a substitution was made (double sic). +.TP +.RB (\|\fL1,$\fP\|) \|v/\fIregular\ expression\fP/\fIcommand\ list\fP +This command is the same as the global command +.L g +except that the command list is executed with +dot initially set to every line +.I except +those +matching the regular expression. +.TP +.RB (\|\fL1,$\fP\|) \|w " \fIfilename\fP" +Write the addressed lines to +the given file. +If the file does not exist, +it is created with mode 666 (readable and writable by everyone). +If no +.I filename +is given, the remembered file name, if any, is used. +The file name is remembered if there were no +remembered file name already. +Dot is unchanged. +If the write is successful, the number of characters written is +printed. +.TP +.RB (\|\fL1,$\fP\|) \|W " \fIfilename\fP" +Perform +.LR w , +but append to, instead of overwriting, any existing file contents. +.TP +.RB ( $ ) \|= +Print the line number of the addressed line. +Dot is unchanged. +.TP +.BI ! shell\ command +Send the remainder of the line after the +.L ! +to +.IR rc (1) +to be interpreted as a command. +Dot is unchanged. +.TP +.RB (\| .+1 )\| +An address without a command is taken as a +.L p +command. +A terminal +.L / +may be omitted from the address. +A blank line alone is equivalent to +.LR .+1p ; +it is useful +for stepping through text. +.PP +If an interrupt signal +.SM (DEL) +is sent, +.I ed +prints a +.L ? +and returns to its command level. +.PP +When reading a file, +.I ed +discards +.SM NUL +characters +and all characters after the last newline. +.SH FILES +.B /tmp/e* +.br +.B ed.hup +\ \ work is saved here if terminal hangs up +.SH SOURCE +.B /sys/src/cmd/ed.c +.SH "SEE ALSO" +.IR sam (1), +.IR sed (1), +.IR regexp (6) +.SH DIAGNOSTICS +.BI ? name +for inaccessible file; +.L ?TMP +for temporary file overflow; +.L ? +for errors in commands or other overflows. diff --git a/static/plan9-4e/man1/emacs.1 b/static/plan9-4e/man1/emacs.1 new file mode 100644 index 00000000..3854c528 --- /dev/null +++ b/static/plan9-4e/man1/emacs.1 @@ -0,0 +1,17 @@ +.TH EMACS 1 +.SH NAME +emacs \- editor macros +.SH SYNOPSIS +.B emacs +[ +.I options +] +.SH DESCRIPTION +This page intentionally left blank. +.SH SOURCE +MIT +.SH SEE ALSO +.IR sam (1), +.IR vi (1) +.SH BUGS +Yes. diff --git a/static/plan9-4e/man1/eqn.1 b/static/plan9-4e/man1/eqn.1 new file mode 100644 index 00000000..7c917cdb --- /dev/null +++ b/static/plan9-4e/man1/eqn.1 @@ -0,0 +1,339 @@ +.TH EQN 1 +.EQ +delim $$ +.EN +.SH NAME +eqn \- typeset mathematics +.SH SYNOPSIS +.B eqn +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Eqn +is a +.IR troff (1) +preprocessor +for typesetting mathematics +on a typesetter. +Usage is almost always +.IP +.L +eqn file ... | troff +.PP +If no files are specified, +.I eqn +reads from the standard input. +.I Eqn +prepares output for the typesetter +named in the +.BI -T dest +option (default +.BR -Tutf ; +see +.IR troff (1)). +When run with other preprocessor filters, +.I eqn +usually comes last. +.PP +A line beginning with +.B .EQ +marks the start of an equation; +the end of an equation +is marked by a line beginning with +.BR .EN . +Neither of these lines is altered, +so they may be defined in macro packages +to get +centering, numbering, etc. +It is also possible to set two characters +as `delimiters'; +text between delimiters is also +.I eqn +input. +Delimiters may be set to characters +.I x +and +.I y +with the option +.BI -d xy +or (more commonly) with +.B delim +.I xy +between +.B .EQ +and +.BR .EN . +Left and right delimiters may be identical. +(They are customarily taken to be +$font L "$$" )$. +Delimiters are turned off by +.LR "delim off" . +All text that is neither between delimiters nor between +.B .EQ +and +.B .EN +is passed through untouched. +.PP +Tokens within +.I eqn +are separated by +spaces, tabs, newlines, braces, double quotes, +tildes or circumflexes. +Braces {} are used for grouping; +generally speaking, +anywhere a single character like +.L x +could appear, a complicated construction +enclosed in braces may be used instead. +Tilde +.L ~ +represents a full space in the output, +circumflex +.L ^ +half as much. +.PP +.vs 13p +Subscripts and superscripts are produced with the keywords +.B sub +and +.BR sup . +Thus +.L "x sub i" +makes +$x sub i$, +.L "a sub i sup 2" +produces +$a sub i sup 2$, +and +.L "e sup {x sup 2 + y sup 2}" +gives +$e sup {x sup 2 + y sup 2}$. +.PP +.B Over +makes fractions: +.L "a over b" +yields $a over b$. +.PP +.B Sqrt +produces square roots: +.L "1 over sqrt {ax sup 2 +bx+c}" +results in +$1 over sqrt {ax sup 2 +bx+c}$ . +.PP +The keywords +.B from +and +.B to +introduce lower and upper +limits on arbitrary things: +$lim from {n -> inf} sum from 0 to n x sub i$ +is made with +.LR "lim from {n -> inf} sum from 0 to n x sub i" . +.PP +Left and right brackets, braces, etc., of the right height are made with +.B left +and +.BR right : +.L "left [ x sup 2 + y sup 2 over alpha right ] ~=~1" +produces +$left [ x sup 2 + y sup 2 over alpha right ] ~=~1$. +The +.B right +clause is optional. +Legal characters after +.B left +and +.B right +are braces, brackets, bars, +.B c +and +.B f +for ceiling and floor, +and +.B +"" +for nothing at all (useful for a right-side-only bracket). +.PP +Vertical piles of things are made with +.BR pile , +.BR lpile , +.BR cpile , +and +.BR rpile : +.L "pile {a above b above c}" +produces +$pile {a above b above c}$. +There can be an arbitrary number of elements in a pile. +.B lpile +left-justifies, +.B pile +and +.B cpile +center, with different vertical spacing, +and +.B rpile +right justifies. +.PP +Matrices are made with +.BR matrix : +.L "matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }" +produces +$matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }$. +In addition, there is +.B rcol +for a right-justified column. +.PP +.vs 12p +Diacritical marks are made with +.BR prime , +.BR dot , +.BR dotdot , +.BR hat , +.BR tilde , +.BR bar , +.BR under , +.BR vec , +.BR dyad , +and +.BR under : +.L "x sub 0 sup prime = f(t) bar + g(t) under" +is +$x sub 0 sup prime = f(t) bar + g(t) under$, +and +.L "x vec = y dyad" +is +$x vec = y dyad$. +.PP +Sizes and fonts can be changed with prefix operators +.B size +.IR n , +.B size +.BI ± n \f1, +.BR fat , +.BR roman , +.BR italic , +.BR bold , +or +.BR font +.IR n . +Size and fonts can be changed globally in a document by +.B gsize +.I n +and +.B gfont +.IR n , +or by the command-line arguments +.BI -s n +and +.BI -f n\f1. +.PP +Normally subscripts and superscripts are reduced by +3 point sizes from the previous size; +this may be changed by the command-line argument +.BI -p n\f1. +.PP +Successive display arguments can be lined up. +Place +.B mark +before the desired lineup point in the first equation; +place +.B lineup +at the place that is to line up vertically in subsequent equations. +.PP +Shorthands may be defined +or existing keywords redefined with +.BR define : +.L define +.I thing +.L % +.I replacement +.L % +defines a new token called +.I thing +which will be replaced by +.I replacement +whenever it appears thereafter. +The +.L % +may be any character that does not occur in +.LR replacement . +.PP +Keywords like +.L sum +.EQ +( sum ), +.EN +.L int +.EQ +( int ), +.EN +.L inf +.EQ +( inf ), +.EN +and shorthands like +.L >= +.EQ +(>=), +.EN +.L -> +.EQ +(->), +.EN +and +.L != +.EQ +( != ) +.EN +are recognized. +Greek letters are spelled out in the desired case, as in +.L alpha +or +.LR GAMMA . +Mathematical words like +.LR sin , +.LR cos , +.L log +are made Roman automatically. +.IR Troff (1) +four-character escapes like +.L \e(lh +(\(lh) can be used anywhere. +Strings enclosed in double quotes " " +are passed through untouched; +this permits keywords to be entered as text, +and can be used to communicate +with +.I troff +when all else fails. +.SH FILES +.TF /sys/lib/troff/font/devutf +.TP +.B /sys/lib/troff/font/devutf +font descriptions for PostScript +.SH SOURCE +.B /sys/src/cmd/eqn +.SH "SEE ALSO" +.IR troff (1), +.IR tbl (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual''. +.br +B. W. Kernighan and L. L. Cherry, +``Typesetting Mathematics\(emUser's Guide'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH BUGS +To embolden digits, parens, etc., +it is necessary to quote them, +as in +.LR bold\ "12.3" . +.EQ +delim off +.EN diff --git a/static/plan9-4e/man1/faces.1 b/static/plan9-4e/man1/faces.1 new file mode 100644 index 00000000..74c693da --- /dev/null +++ b/static/plan9-4e/man1/faces.1 @@ -0,0 +1,93 @@ +.TH FACES 1 +.SH NAME +faces, seemail, vwhois \- mailbox interface +.SH SYNOPSIS +.B faces +[ +.B -ih +] +.br +.B seemail +.br +.B vwhois +.I person +\&... +.SH DESCRIPTION +The +.I faces +command monitors incoming mail and +displays in its window a representation of the user's mail box +using a small image for each message. +The image is typically a portrait of the sender. +.PP +If the user is running +.IR plumber (4), +.I faces +reacts to plumb messages to the +.B seemail +port, +typically from +.BR upas/fs , +and is thus notified of message additions and deletions. +.PP +Right-clicking on a message icon causes that message to be `plumbed' to +.BR showmail . +A typical plumb action will be to display the message, such as by +the rule +.EX + plumb start window mail -s $0 +.EE +The +.IR acme (1) +mail reader listens to the +.B showmail +port automatically. +.PP +If the user is not running +.IR plumber , +.I faces +reads the log file +.F /sys/log/mail +and right-clicking has no effect. +.PP +If arrows are visible, clicking on them will scroll the display. +Middle-clicking on the arrows scrolls to the end. +.PP +Starting +.B faces +with the +.B -i +flag causes +.B faces +to read the messages in +.B /mail/fs/mbox +or in the named mail directory upon startup. +.PP +The +.B -h +flag causes a different, venerable behavior in which +the window displays the history of messages received +rather than the current state of the mail box. +In particular, faces are not removed from the screen when messages are deleted. +Also, in this mode clicking button 1 in the display will clear the window. +.PP +.I Seemail +is an +.IR rc (1) +script that invokes +.B faces +.BR -h . +.PP +.I Vwhois +tells +.I faces +to display the icons of the named +.IR persons , +without sending a message. +.SH FILES +.BR /mail/fs/mbox " mail directory. +.SH "SEE ALSO" +.IR mail (1), +.IR plumber (4), +.IR face (6), +.IR plumb (6) diff --git a/static/plan9-4e/man1/factor.1 b/static/plan9-4e/man1/factor.1 new file mode 100644 index 00000000..2d9b5a09 --- /dev/null +++ b/static/plan9-4e/man1/factor.1 @@ -0,0 +1,66 @@ +.TH FACTOR 1 +.CT 1 numbers +.SH NAME +factor, primes \- factor a number, generate large primes +.SH SYNOPSIS +.B factor +[ +.I number +] +.PP +.B primes +[ +.I start +[ +.I finish +] +] +.SH DESCRIPTION +.I Factor +prints +.I number +and its prime factors, +each repeated the proper number of times. +The number must be positive and less than +.if n 2**54 +.if t 2\u\s754\s0\d +(about +.if n 1.8e16) +.if t 1.8\(mu10\u\s716\s0\d\|). +.PP +If no +.I number +is given, +.I factor +reads a stream of numbers from the standard input and factors them. +It exits on any input not a positive integer. +Maximum running time is proportional to +.if n sqrt(n). +.if t .I \(sr\o'n\(rn'\f1. +.PP +.PP +.I Primes +prints the prime numbers ranging from +.I start +to +.IR finish , +where +.I start +and +.I finish +are positive numbers less than +.if n 2**56. +.if t 2\u\s756\s0\d. +If +.I finish +is missing, +.I primes +prints without end; +if +.I start +is missing, it reads the starting number from the +standard input. +.SH SOURCE +.B /sys/src/cmd/factor.c +.br +.B /sys/src/cmd/primes.c diff --git a/static/plan9-4e/man1/file.1 b/static/plan9-4e/man1/file.1 new file mode 100644 index 00000000..3bf19fc6 --- /dev/null +++ b/static/plan9-4e/man1/file.1 @@ -0,0 +1,117 @@ +.TH FILE 1 +.SH NAME +file \- determine file type +.SH SYNOPSIS +.B file +[ +.B -m +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I File +performs a series of tests on its argument +.I files +in an attempt to classify their contents by language or purpose. +If no arguments are given, the classification is performed +on standard input. +.PP +If the +.B -m +flag is given, +.I file +outputs an +appropriate MIME +.B Content-Type +specification describing the +.B type +and +.B subtype +of each file. +.PP +The file types it looks for include +directory, +device file, +zero-filled file, +empty file, +Plan 9 executable, +PAC audio file, +.B cpio +archive, +.B tex +.B dvi +file, +archive symbol table, +archive, +.B rc +script, +.B sh +script, +PostScript, +.B troff +output file for various devices, +mail box, +GIF, +FAX, +object code, +C and Alef source, +assembler source, +compressed files, +encrypted file, +English text, +compressed image, +image, +subfont, +and +font. +.PP +If a file has no apparent format, +.I file +looks at the character set it uses to classify it according to +.SM ASCII\c +, +extended +.SM ASCII\c +, Latin +.SM ASCII\c +, or +.SM UTF +holding one or more of the following blocks of the Unicode Standard: +Extended Latin, +Greek, +Cyrillic, +Armenian, +Hebrew, +Arabic, +Devanagari, +Bengali, +Gurmukhi, +Gujarati, +Oriya, +Tamil, +Telugu, +Kannada, +Malayalam, +Thai, +Lao, +Tibetan, +Georgian, +Japanese, +Chinese, +or Korean. +.PP +If all else fails, +.I file +decides its input is +binary. +.SH SOURCE +.B /sys/src/cmd/file.c +.SH BUGS +It can make mistakes, for example classifying a file of decimal data, +.LR .01 , +.LR .02 , +etc. as +.IR troff (1) +input. diff --git a/static/plan9-4e/man1/fmt.1 b/static/plan9-4e/man1/fmt.1 new file mode 100644 index 00000000..d71b70d2 --- /dev/null +++ b/static/plan9-4e/man1/fmt.1 @@ -0,0 +1,79 @@ +.TH FMT 1 +.SH NAME +fmt, htmlfmt \- simple text formatters +.SH SYNOPSIS +.B fmt +[ +.I option ... +] +[ +.I file ... +] +.PP +.B htmlfmt +[ +.B -a +] [ +.B -u +.I url +] [ +.I file ... +] +.SH DESCRIPTION +.I Fmt +copies the given +.I files +(standard input by default) +to its standard output, filling and indenting lines. +The options are +.TP +.BI -l " n +Output line length is +.IR n , +including indent (default 70). +.TP +.BI -w " n +A synonym for +.BR -l . +.TP +.BI -i " n +Indent +.I n +spaces (default 0). +.TP +.BI -j +Don't join input lines, simply split them where necessary. +.PP +Empty lines and initial white space in input lines are preserved. +Empty lines are inserted between input files. +.PP +.I Fmt +is idempotent: it leaves already formatted text unchanged. +.PP +.I Htmlfmt +performs a similar service, but accepts as input text formatted with +HTML tags. +It accepts +.IR fmt 's +.B -l +and +.B -w +flags and also: +.TP +.BI -a +Normally +.I htmlfmt +suppresses the contents of form fields and anchors (URLs and image files); this flag +causes it to print them, in square brackets. +.TP +.BI -u " url +Use +.I url +as the base URL for the document when displaying anchors; sets +.BI -a . +.SH SOURCE +.B /sys/src/cmd/fmt.c +.SH BUGS +.I Htmlfmt +makes no attempt to render the two-dimensional geometry of tables; +it just treats the table entries as plain, to-be-formatted text. diff --git a/static/plan9-4e/man1/fortune.1 b/static/plan9-4e/man1/fortune.1 new file mode 100644 index 00000000..dfae7186 --- /dev/null +++ b/static/plan9-4e/man1/fortune.1 @@ -0,0 +1,23 @@ +.TH FORTUNE 1 +.SH NAME +fortune \- sample lines from a file +.SH SYNOPSIS +.B fortune +[ +.I file +] +.SH DESCRIPTION +.I Fortune +prints a one-line aphorism chosen at random. +If a +.I file +is specified, the saying is taken from that file; +otherwise it is selected from +.BR /sys/games/lib/fortunes . +.SH FILES +.B /sys/games/lib/fortunes +.br +.B /sys/games/lib/fortunes.index +\ \ fast lookup table, maintained automatically +.SH SOURCE +.B /sys/src/cmd/fortune.c diff --git a/static/plan9-4e/man1/freq.1 b/static/plan9-4e/man1/freq.1 new file mode 100644 index 00000000..eee4e295 --- /dev/null +++ b/static/plan9-4e/man1/freq.1 @@ -0,0 +1,40 @@ +.TH FREQ 1 +.SH NAME +freq \- print histogram of character frequencies +.SH SYNOPSIS +.B freq +[ +.B -dxocr +] +[ +.I file ... +] +.SH DESCRIPTION +.I Freq +reads the given files (default standard input) +and prints histograms of the character frequencies. +By default, +.I freq +counts each byte as a character; +under the +.B -r +option it instead counts +.SM UTF +sequences, that is, runes. +.PP +Each non-zero entry of the table is printed preceded by the byte value, +in decimal, octal, hex, and +Unicode +character (if printable). +If any options are given, the +.BR -d , +.BR -x , +.BR -o , +.B -c +flags specify a subset of value formats: decimal, hex, octal, and +character, respectively. +.SH SOURCE +.B /sys/src/cmd/freq.c +.SH SEE ALSO +.IR utf (6), +.IR wc (1) diff --git a/static/plan9-4e/man1/grap.1 b/static/plan9-4e/man1/grap.1 new file mode 100644 index 00000000..b098f822 --- /dev/null +++ b/static/plan9-4e/man1/grap.1 @@ -0,0 +1,416 @@ +.TH GRAP 1 +.SH NAME +grap \- pic preprocessor for drawing graphs +.SH SYNOPSIS +.B grap +[ +.I file ... +] +.SH DESCRIPTION +.I Grap +is a +.IR pic (1) +preprocessor for drawing graphs on a typesetter. +Graphs are surrounded by the +.I troff +`commands' +.B \&.G1 +and +.BR \&.G2 . +Data are scaled and plotted, +with tick marks supplied automatically. +Commands exist to modify the frame, +add labels, override the default ticks, +change the plotting style, +define coordinate ranges and transformations, +and include data from files. +In addition, +.I grap +provides the same loops, conditionals, and macro processing that +.I pic +does. +.PP +.BI frame +.B ht +.I e +.B wid +.I e +.B top +.B dotted +.IR ... : +Set the frame around the graph to specified +.B ht +and +.BR wid ; +default is 2 by 3 (inches). +The line +.I styles +.RB ( dotted , +.BR dashed , +.BR invis , +.BR solid +(default)) +of the +.I sides +.RB ( top , +.BR bot , +.BR left , +.BR right ) +of the frame can be set +independently. +.PP +.B label +.I side +.B \&"a label" +.B \&"as a set of strings" +.IR adjust : +Place label on specified side; default side is bottom. +.I adjust +is +.B up +(or +.B down +.B left +.BR right ) +.I expr +to shift default position; +.B width +.I expr +sets the width explicitly. +.PP +.BI ticks +.I side +.B in +.B at +.IR "optname expr, expr, ..." : +Put ticks on +.I side +at +.I "expr, ..., +and label with +.I \&"expr"\f1. +If any +.I expr +is followed by "...", label tick with "...", +and turn off all automatic labels. +If "..." contains +.BR %f 's, +they will be interpreted as +.B printf +formatting instructions for the tick value. +Ticks point +.B in +or +.B out +(default out). +Tick iterator: instead of +.B at +.IR \&... , +use +.BI from +.I expr +.B to +.I expr +.B by +.I "op expr +where +.I op +is optionally +.B +-*/ +for additive or multiplicative steps. +.B by +can be omitted, to give steps of size 1. +If no ticks are requested, they are supplied automatically; +suppress this with +.B ticks +.BR off . +Automatic ticks normally +leave a margin of 7% on each side; set this to anything by +.B margin +.B = +.IR expr . +.PP +.B grid +.I "side linedesc" +.B at +.IR "optname expr, expr, ..." : +Draw grids perpendicular to +.I side +in style +.I linedesc +at +.I "expr, ....\& +Iterators and labels work as with ticks. +.PP +.B coord +.I optname +.B x +.I "min, max" +.B y +.I "min, max" +.B "log x +.BR " log y" : +Set range of coords and optional log scaling on either or both. +This overrides computation of data range. +Default value of +.I optname +is current coordinate system +(each +.B coord +defines a new coordinate system). +.PP +.B plot +.I \&"str" +.B at +.IR point ; +.B +.I \&"str" +.B at +.IR point : +Put +.I str +at +.IR point . +Text position can be qualified with +.BR rjust , +.BR ljust , +.BR above , +.BR below +after "...". +.PP +.B line +.B from +.I point +.B to +.IR "point linedesc" : +Draw line from here to there. +.B arrow +works in place of +.BR line . +.PP +.B next +.I optname +.B at +.IR "point linedesc" : +Continue plot of data in +.I optname to +.IR point ; +default is current. +.PP +.BI draw +.IR "optname linedesc ..." : +Set mode for +.BR next : +use this style from now on, +and plot "..." at each point (if given). +.PP +.BI new +.IR "optname linedesc ..." : +Set mode for +.BR next , +but disconnect from previous. +.PP +A list of numbers +.I "x y1 y2 y3 ... +is treated as +.B plot +.B bullet +.B at +.IR x,y1 ; +.B plot +.B bullet +.B at +.IR x,y2 ; +etc., or as +.B next +.B at +.I x,y1 +etc., if +.B draw +is specified. +Abscissae of 1,2,3,... are provided if there is only one input number per line. +.PP +A +point +.I "optname expr, expr +maps the point to the named coordinate system. +A +.I linedesc +is one of +.B dot +.B dash +.B invis +.B solid +optionally followed by an expression. +.PP +.BI define +.I name +.BI { whatever } \f1: +Define a macro. +There are macros already defined for standard plotting +symbols like +.BR bullet , +.BR circle , +.BR star , +.BR plus , +etc., in +.BR /sys/lib/grap.defines , +which is included if it exists. +.PP +.I var +.B = +.IR expr : +Evaluate an expression. +Operators are +.B= +.B + +.B - +.B * +and +.BR / . +Functions are +.B log +and +.B exp +(both base 10), +.BR sin , +.BR cos , +.BR sqrt ; +.B rand +returns random number on [0,1); +.BI max( e , e )\f1, +.BI min( e , e )\f1, +.BI int( e )\f1. +.PP +.B print +.IR expr ; +.B print +\fL"\f2...\fL"\f1: +As a debugging aid, print +.I expr +or +.I string +on the standard error. +.PP +.B copy +\fL"\fIfile name\fL"\fR: +Include this file right here. +.PP +.B copy +.B thru +.IR macro : +Pass rest of input (until +.BR \&.G2 ) +through +.IR macro , +treating each field (non-blank, or "...") as an argument. +.I macro +can be the name of a macro previously defined, +or the body of one in place, like +.BR "/plot $1 at $2,$3/" . +.PP +.B copy +.B thru +.I macro +.B until +\fL"\fIstring\fL"\fR: +Stop copy when input is +.I string +(left-justified). +.PP +.BI pic +.IR "remainder of line" : +Copy to output with leading blanks removed. +.PP +.BI graph +.IR "Name pic-position" : +Start a new frame, place it at specified position, +e.g., +.B graph +.B Thing2 +.BR "with .sw at Thing1.se + (0.1,0)" . +.I Name +must be capitalized to keep +.I pic +happy. +.PP +.BI \&. "anything at beginning of +.IR line : +Copied verbatim. +.PP +.B sh +.BI % anything +.BR % : +Pass everything between the +.BR % 's +to the shell; +as with macros, +.B % +may be any character and +.I anything +may include newlines. +.PP +.B # +.IR anything : +A comment, which is discarded. +.PP +Order is mostly irrelevant; no category is mandatory. +Any arguments on the +.B \&.G1 +line are placed on the generated +.B \&.PS +line for +.IR pic . +.SH EXAMPLES +.EX +.ps -1 +.vs -1 +\&.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +\&.G2 +.G1 +frame ht 1 top invis right invis +coord x 0, 10 y 1, 3 log y +ticks left in at 1 "bottommost tick", 2,3 "top tick" +ticks bot in from 0 to 10 by 2 +label bot "silly graph" +label left "left side label" "here" +grid left dashed at 2.5 +copy thru / circle at $1,$2 / +1 1 +2 1.5 +3 2 +4 1.5 +10 3 +.G2 +.ps +.vs +.EE +.SH FILES +.TF /sys/lib/grap.defines +.TP +.B /sys/lib/grap.defines +definitions of standard plotting characters, e.g., bullet +.SH SOURCE +.B /sys/src/cmd/grap +.SH "SEE ALSO" +.IR pic (1), +.IR troff (1) +.br +J. L. Bentley and B. W. Kernighan, +``GRAP\(emA Language for Typesetting Graphs'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/static/plan9-4e/man1/graph.1 b/static/plan9-4e/man1/graph.1 new file mode 100644 index 00000000..4cdc6b24 --- /dev/null +++ b/static/plan9-4e/man1/graph.1 @@ -0,0 +1,148 @@ +.TH GRAPH 1 +.CT 1 numbers graphics +.SH NAME +graph \- draw a graph +.SH SYNOPSIS +.B graph +[ +.I option ... +] +.SH DESCRIPTION +.I Graph +with no options takes pairs of numbers from the +standard input as abscissas +.RI ( x -values) +and ordinates +.RI ( y -values) +of a graph. +Successive points are connected by straight lines. +The graph is encoded on the standard output +for display by +.IR plot (1) +filters. +.PP +If an ordinate is followed by +a nonnumeric string, that string is printed as a +label beginning on the point. +Labels may be surrounded with quotes +.L +" " +in which case they may be empty or contain blanks +and numbers; +labels never contain newlines. +.PP +The following options are recognized, +each as a separate argument. +.TP +.B -a +Supply abscissas automatically; no +.IR x -values +appear in the input. +Spacing is given by the next +argument (default 1). +A second optional argument is the starting point for +automatic abscissas (default 0, or 1 +with a log scale in +.IR x , +or the lower limit given by +.BR -x ). +.TP +.B -b +Break (disconnect) the graph after each label in the input. +.TP +.B -c +Character string given by next argument +is default label for each point. +.TP +.B -g +Next argument is grid style, +0 no grid, 1 frame with ticks, 2 full grid (default). +.TP +.B -l +Next argument is a legend to title the graph. +Grid ranges +are automatically printed as part +of the title unless a +.B -s +option is present. +.TP +.B -m +Next argument is mode (style) +of connecting lines: +0 disconnected, 1 connected. +Some devices give distinguishable line styles +for other small integers. +Mode \-1 (default) begins with style 1 and +rotates styles for successive curves under option +.BR -o . +.TP +.B -o +(Overlay.) +The ordinates for +.I n +superposed curves appear in the input +with each abscissa value. +The next argument is +.IR n . +.TP +.B -s +Save screen; no new page for this graph. +.TP +.B -x l +If +.B l +is present, +.IR x -axis +is logarithmic. +Next 1 (or 2) arguments are lower (and upper) +.I x +limits. +Third argument, if present, is grid spacing on +.I x +axis. +Normally these quantities are determined automatically. +.TP +.B -y l +Similarly for +.IR y . +.TP +.B -e +Make automatically determined +.I x +and +.I y +scales equal. +.TP +.B -h +Next argument is fraction of space for height. +.TP +.B -w +Similarly for width. +.TP +.B -r +Next argument is fraction of space to move right before plotting. +.TP +.B -u +Similarly to move up before plotting. +.TP +.B -t +Transpose horizontal and vertical axes. +(Option +.B -a +now applies to the vertical axis.) +.PP +If a specified lower limit exceeds the upper limit, +the axis +is reversed. +.SH SOURCE +.B /sys/src/cmd/graph +.SH "SEE ALSO" +.IR plot (1), +.IR grap (1) +.SH BUGS +Segments that run out of bounds are dropped, not windowed. +Logarithmic axes may not be reversed. +Option +.B -e +actually makes automatic limits, rather than automatic scaling, +equal. diff --git a/static/plan9-4e/man1/grep.1 b/static/plan9-4e/man1/grep.1 new file mode 100644 index 00000000..a266c494 --- /dev/null +++ b/static/plan9-4e/man1/grep.1 @@ -0,0 +1,103 @@ +.TH GREP 1 +.SH NAME +grep \- search a file for a pattern +.SH SYNOPSIS +.B grep +[ +.I option ... +] +.I pattern +[ +.I file ... +] +.SH DESCRIPTION +.I Grep\^ +searches the input +.I files\^ +(standard input default) +for lines that match the +.IR pattern , +a regular expression as defined in +.IR regexp (6) +with the addition of a newline character as an alternative +(substitute for +.BR | ) +with lowest precedence. +Normally, each line matching the pattern is `selected', +and each selected line is copied to the standard output. +The options are +.TP +.B -c +Print only a count of matching lines. +.PD 0 +.TP +.B -h +Do not print file name tags (headers) with output lines. +.TP +.B -e +The following argument is taken as a +.IR pattern . +This option makes it easy to specify patterns that +might confuse argument parsing, such as +.BR -n . +.TP +.B -i +Ignore alphabetic case distinctions. The implementation +folds into lower case all letters in the pattern and input before +interpretation. Matched lines are printed in their original form. +.TP +.B -l +(ell) Print the names of files with selected lines; don't print the lines. +.TP +.B -L +Print the names of files with no selected lines; +the converse of +.BR -l . +.TP +.B -n +Mark each printed line with its line number counted in its file. +.TP +.B -s +Produce no output, but return status. +.TP +.B -v +Reverse: print lines that do not match the pattern. +.TP +.B -f +The pattern argument is the name of a file containing regular +expressions one per line. +.TP +.B -b +Don't buffer the output: write each output line as soon as it is discovered. +.PD +.PP +Output lines are tagged by file name when there is more than one +input file. +(To force this tagging, include +.B /dev/null +as a file name argument.) +.PP +Care should be taken when +using the shell metacharacters +.B $*[^|()=\e +and newline +in +.IR pattern ; +it is safest to enclose the +entire expression +in single quotes +.BR \&\|' \|.\|.\|.\| ' . +An expression starting with '*' +will treat the rest of the expression +as literal characters. +.SH SOURCE +.B /sys/src/cmd/grep +.SH SEE ALSO +.IR ed (1), +.IR awk (1), +.IR sed (1), +.IR sam (1), +.IR regexp (6) +.SH DIAGNOSTICS +Exit status is null if any lines are selected, +or non-null when no lines are selected or an error occurs. diff --git a/static/plan9-4e/man1/gs.1 b/static/plan9-4e/man1/gs.1 new file mode 100644 index 00000000..9350269f --- /dev/null +++ b/static/plan9-4e/man1/gs.1 @@ -0,0 +1,276 @@ +.TH GS 1 +.\" This file is an edited version of /sys/src/cmd/gs/man/gs.1, to +.\" document the local installation and remove needless background. +.de TQ +.br +.ns +.TP \\$1 +.. +.SH NAME +gs \- Aladdin Ghostscript (PostScript and PDF language interpreter) +.SH SYNOPSIS +.B gs +[ +.I options +] [ +.I files +] ... +.br +.SH DESCRIPTION +Ghostscript is a programming language similar to Adobe Systems' +PostScript and PDF languages, which are in turn similar to Forth. +.I Gs +reads +.I files +in sequence and executes them as Ghostscript programs. +After doing this, it reads further input from the standard input. +If the +.I file +.B - +is named, however, it represents the standard input, which is read +in order and not after the files on the command line. +Each line is interpreted separately. +The `quit' command, or end-of-file, exits the interpreter. +.PP +The interpreter recognizes several switches described below, which may appear +anywhere in the command line and apply to all files thereafter. +.PP +The +.B -h +or +.B -? +options give help and list the available devices; the default is +.BR inferno, +which produces compressed image files suitable for viewing with +.IR page (1) +(but note that +.IR page (1) +will invoke +.I gs +automatically; see its manual). +.PP +Ghostscript may be built with multiple output devices. Ghostscript +normally opens the first one and directs output to it. To use device xyz +as the initial output device, include the switch +.EX + -sDEVICE=xyz +.EE +in the command line. This switch must precede the first PostScript +file and only its first invocation has any effect. +Output devices can also be selected by the word +.B selectdevice +in the input language, or by setting the environment variable +.BR GS_DEVICE . +The order of precedence for +these alternatives, highest to lowest, is: +.EX + selectdevice + \f1(command line)\fP + GS_DEVICE + dfaxlow +.EE +.PP +Normally, output goes +directly to a scratch file. +To send the output to a series of files +.BR foo1.xyz , +.BR foo2.xyz , +etc., use the switch +.EX + -sOutputFile=foo%d.xyz +.EE +The %d may be any +.I printf +(see +.IR fprintf (2)) +format specification. Each file will receive one page of output. +If the file name begins with a pipe character, +the output will be sent as standard input to the following pipeline. +For example, +.EX + -sOutputFile=|lp +.EE +Specifying the file +.B - +will send the files to standard output; this also requires enabling the +.B -q +option. +.SS "Initialization files" +When looking for the initialization files +.RB ( gs_*.ps ), +the files related +to fonts, or the file for the +.B run +operator, Ghostscript first looks for the file (if +it doesn't start with a slash) in the current directory, then in these +directories in the following order: +.TP +1. +Any directories specified by +.B -I +switches in the command +line (see below); +.TP +2. +Any directories specified by the +.B GS_LIB +environment variable; +.TP +3. +The directories +.BR /sys/lib/ghostscript , +.BR /sys/lib/ghostscript/font , +and +.BR /sys/lib/postscript/font . +.PP +The +.B GS_LIB +or +.B -I +parameters may be +a single directory or a colon-separated list. +.SS Options +.TP +.BI -- " filename arg1 ..." +Take the next argument as a file name as usual, but take all +remaining arguments (even if they have the syntactic form of switches) +and define the name ARGUMENTS in userdict (not systemdict) as an +array of those strings, +.I before +running the file. When Ghostscript +finishes executing the file, it exits back to the shell. +.TP +.BI -D name = token +.TQ +.BI -d name = token +Define a name in systemdict with the given definition. The token must +be exactly one token (as defined by the `token' operator) and must not +contain any white space. +.TP +.BI -D name +.TQ +.BI -d name +Define a name in systemdict with value=null. +.TP +.BI -S name = string +.TQ +.BI -s name = string +Define a name in systemdict with a given string as value. This is +different from +.BR -d . +For example, +.B -dname=35 +is equivalent to the +program fragment +.EX + /name 35 def +.EE +whereas +.B -sname=35 +is equivalent to +.EX + /name (35) def +.EE +.TP +.B -q +Quiet startup: suppress normal startup messages, and also do the +equivalent of +.BR -dQUIET . +.TP +.BI -g number1 x number2 +Equivalent to +.BI -dDEVICEWIDTH= number1 +and +.BI -dDEVICEHEIGHT= number2\f1. +This is for the benefit of devices, such as windows, +that allow width and height to be specified. +.TP +.BI -r number +.TQ +.BI -r number1 x number2 +Equivalent to +.BI -dDEVICEXRESOLUTION= number1 +and +\fL-dDEVICE\%YRESOLUTION= \f2\%number2\f1. +This is for the benefit of devices, such as printers, +that support multiple X and Y resolutions. +If only one number is given, it is used for both X and Y resolutions. +.TP +.BI -I directories +Adds the designated list of directories at the head of the +search path for library files. +.PP +Note that gs_init.ps makes systemdict read-only, so the values of names +defined with -D/d/S/s cannot be changed (although, of course, they can be +superseded by definitions in userdict or other dictionaries.) +.SS "Special names" +.TP +.B -dBATCH +Exit after the last file has been processed. +This is equivalent to listing +.I quit.ps +at the end of the list of files. +.TP +.B -dDISKFONTS +Causes individual character outlines to be loaded from the disk +the first time they are encountered. (Normally Ghostscript loads all the +character outlines when it loads a font.) This may allow loading more +fonts into RAM, at the expense of slower rendering. +.TP +.B -dNOCACHE +Disables character caching. Only useful for debugging. +.TP +.B -dNOBIND +Disables the `bind' operator. Only useful for debugging. +.TP +.B -dNODISPLAY +Suppresses the normal initialization of the output device. +This may be useful when debugging. +.TP +.B -dNOPAUSE +Disables the prompt and pause at the end of each page. +This may be desirable for applications where another program +(e.g. +.IR page (1)) +is +`driving' Ghostscript. +.TP +.B -dSAFER +Disables the +.B deletefile +and +.B renamefile +operators, and the +ability to open files in any mode other than read-only. This may be +desirable for spoolers or other sensitive environments. +.TP +.B -dWRITESYSTEMDICT +Leaves systemdict writable. This is necessary when running +special utility programs such as font2c and pcharstr, which must bypass +normal PostScript access protection. +.TP +.BI -sDEVICE= device +Selects an alternate initial output device, as described above. +.TP +.BI -sOutputFile= filename +Selects an alternate output file (or pipe) for the initial output +device, as described above. +.SH FILES +.TP +.B /sys/lib/ghostscript/* +Startup-files, utilities, examples, and basic font definitions. +.TP +.B /sys/lib/ghostscript/fonts/* +Additional font definitions. +.SH SOURCE +.B /sys/src/cmd/gs +.SH "SEE ALSO" +.IR page (1) +.br +The Ghostscript document files in +.B doc +and +.B man +subdirectories of the source directory. +.SH BUGS +The treatment of standard input is non-standard. diff --git a/static/plan9-4e/man1/gzip.1 b/static/plan9-4e/man1/gzip.1 new file mode 100644 index 00000000..8863abda --- /dev/null +++ b/static/plan9-4e/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 /sys/src/cmd/gzip +.br +.B /sys/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/static/plan9-4e/man1/hget.1 b/static/plan9-4e/man1/hget.1 new file mode 100644 index 00000000..40ee79eb --- /dev/null +++ b/static/plan9-4e/man1/hget.1 @@ -0,0 +1,68 @@ +.TH HGET 1 +.SH NAME +hget \- retrieve a web page corresponding to a url +.SH SYNOPSIS +.PP +.B hget +[ +.B -dv +][ +.B -o +.I ofile +][ +.B -p +.I body +][ +.B -x +.I netmntpt +] +.I url +.SH DESCRIPTION +.I Hget +retrieves the web page specified by the URL +.I url +and writes it, absent the +.B -o +option, to standard output. +The known URL types are: http and ftp. +.PP +If +.I url +is of type HTTP and the +.B -p +option is specified, then an HTTP POST is performed +with +.I body +as the data to be posted. +.PP +The +.B -o +option is used to keep a local file in sync with a +web page. If the web page has been modified later than the +file, it is copied into the file. If the file is up to date +but incomplete, +.I hget +will fetch the missing bytes. +.PP +Option +.B -d +turns on debugging written to standard error. +.PP +Normally, +.I hget +uses the IP stack mounted under +.BR /net . +The +.B -x +option can be used to specify the mount point of +a different IP stack to use. +.PP +Option +.B -v +writes progress lines to standard output once a second. +Each line contains two numbers, the bytes transferred so +far and the total length to be transferred. +.SH SOURCE +.B /sys/src/cmd/hget.c +.SH "SEE ALSO" +.IR ftpfs (4) diff --git a/static/plan9-4e/man1/history.1 b/static/plan9-4e/man1/history.1 new file mode 100644 index 00000000..7c8d9643 --- /dev/null +++ b/static/plan9-4e/man1/history.1 @@ -0,0 +1,81 @@ +.TH HISTORY 1 +.SH NAME +history \- print file names from the dump +.SH SYNOPSIS +.B history +[ +.B -vDu +] [ +.B -d +.I dumpfilesystem +] [ +.B -s +.I yyyymmdd +] +.I files ... +.SH DESCRIPTION +.I History +prints the names, dates, and sizes, and modifier of all versions of the named +.IR files , +looking backwards in time, +stored in the dump file system. +If the file exists in the main tree, the first line of output will be its current state. +For example, +.IP +.EX +history /adm/users +.EE +.PP +produces +.IP +.EX +May 14 15:29:18 EDT 2001 /adm/users 10083 [adm] +May 14 15:29:18 EDT 2001 /n/dump/2001/0515/adm/users 10083 [adm] +May 11 17:26:24 EDT 2001 /n/dump/2001/0514/adm/users 10481 [adm] +May 10 16:40:51 EDT 2001 /n/dump/2001/0511/adm/users 10476 [adm] + ... +.EE +.PP +The +.B -v +option enables verbose debugging printout. +.PP +The +.B -D +option causes +.IR diff (1) +.B -n +to be run for each adjacent pair of dump files, while +.B -b +runs +.IR diff +.BR -nb . +.PP +The +.B -u +option causes times to be printed in GMT (UT) rather than local time. +.PP +The +.B -d +option selects some other dump filesystem such as +.IR /n/bootesdump . +.PP +Finally, the +.B -s +option +sets the starting (most recent) date for the output. +.SH EXAMPLES +.PP +Check how often a user has been logged in. +.IP +.EX +history /usr/ches/tmp +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /sys/src/cmd/history.c +.SH SEE ALSO +.IR fs (4) +.br +.IR yesterday (1) diff --git a/static/plan9-4e/man1/hoc.1 b/static/plan9-4e/man1/hoc.1 new file mode 100644 index 00000000..68a42a6a --- /dev/null +++ b/static/plan9-4e/man1/hoc.1 @@ -0,0 +1,144 @@ +.TH HOC 1 +.SH NAME +hoc \- interactive floating point language +.SH SYNOPSIS +.B hoc +[ +.I file ... +] +[ +.B -e +.I expression +] +.SH DESCRIPTION +.I Hoc +interprets a simple language for floating point arithmetic, +at about the level of BASIC, with C-like syntax and +functions. +.PP +The named +.I files +are read and interpreted in order. +If no +.I file +is given or if +.I file +is +.L - +.I hoc +interprets the standard input. +The +.B -e +option allows input to +.I hoc +to be specified on the command line, to be treated as if it appeared in a file. +.PP +.I Hoc +input consists of +.I expressions +and +.IR statements . +Expressions are evaluated and their results printed. +Statements, typically assignments and function or procedure +definitions, produce no output unless they explicitly call +.IR print . +.PP +Variable names have the usual syntax, including +.LR _ ; +the name +.L _ +by itself contains the value of the last expression evaluated. +The variables +.BR E , +.BR PI , +.BR PHI , +.BR GAMMA +and +.B DEG +are predefined; the last is 59.25..., degrees per radian. +.PP +Expressions are formed with these C-like operators, listed by +decreasing precedence. +.TP +.B ^ +exponentiation +.TP +.B ! - ++ -- +.TP +.B * / % +.TP +.B + - +.TP +.B > >= < <= == != +.TP +.B && +.TP +.B || +.TP +.B = += -= *= /= %= +.PP +Built in functions are +.BR abs , +.BR acos , +.BR asin , +.B atan +(one argument), +.BR cos , +.BR cosh , +.BR exp , +.BR int , +.BR log , +.BR log10 , +.BR sin , +.BR sinh , +.BR sqrt , +.BR tan , +and +.BR tanh . +The function +.B read(x) +reads a value into the variable +.B x +and returns 0 at EOF; +the statement +.B print +prints a list of expressions that may include +string constants such as +\fL"hello\en"\f1.\fP +.PP +Control flow statements are +.BR if - else , +.BR while , +and +.BR for , +with braces for grouping. +Newline ends a statement. +Backslash-newline is equivalent to a space. +.PP +Functions and procedures are introduced by the words +.B func +and +.BR proc ; +.B return +is used to return with a value from a function. +.SH EXAMPLES +.EX +func gcd(a, b) { + temp = abs(a) % abs(b) + if(temp == 0) return abs(b) + return gcd(b, temp) +} +for(i=1; i<12; i++) print gcd(i,12) +.EE +.SH SOURCE +.B /sys/src/cmd/hoc +.SH "SEE ALSO" +.IR bc (1), +.IR dc (1) +.br +B. W. Kernighan and R. Pike, +.I +The Unix Programming Environment, +Prentice-Hall, 1984 +.SH BUGS +Error recovery is imperfect within function and procedure definitions. diff --git a/static/plan9-4e/man1/idiff.1 b/static/plan9-4e/man1/idiff.1 new file mode 100644 index 00000000..5cb22600 --- /dev/null +++ b/static/plan9-4e/man1/idiff.1 @@ -0,0 +1,72 @@ +.TH IDIFF 1 +.SH NAME +idiff \- interactive diff +.SH SYNOPSIS +.B idiff +[ +.B -bw +] +.I file1 +.I file2 +.SH DESCRIPTION +.I Idiff +interactively +merges +.I file1 +and +.IR file2 . +Wherever +.I file1 +and +.I file2 +differ, +.I idiff +displays the differences in the style of +.RB `` diff +.RB -n '' +and prompts the user to select a chunk. +Valid responses are: +.TP +.B < +Use the chunk from +.IR file1 . +.TP +.B > +Use the chunk from +.IR file2 . +.TP +.B = +Use the diff output itself. +.TP +.BR q< ", " q> ", " q= +Use the given response for all future questions. +.TP +.BI ! cmd +Execute +.I cmd +and prompt again. +.PP +.I Idiff +invokes +.IR diff (1) +to compare the files. +The +.B -b +and +.B -w +flags +are simply +passed through to +.IR diff . +.SH FILES +.B /tmp/idiff.* +.SH SOURCE +.B /sys/src/cmd/idiff.c +.SH "SEE ALSO +.IR diff (1) +.br +Kernighan and Pike, +.IR "The Unix Programming Environment" , +Prentice-Hall, 1984. +.SH BUGS +This is a poorly-written manual page. diff --git a/static/plan9-4e/man1/join.1 b/static/plan9-4e/man1/join.1 new file mode 100644 index 00000000..379eec7f --- /dev/null +++ b/static/plan9-4e/man1/join.1 @@ -0,0 +1,148 @@ +.TH JOIN 1 +.CT 1 files +.SH NAME +join \- relational database operator +.SH SYNOPSIS +.B join +[ +.I options +] +.I file1 file2 +.SH DESCRIPTION +.I Join +forms, on the standard output, +a join +of the two relations specified by the lines of +.I file1 +and +.IR file2 . +If one of the file names is +.LR - , +the standard input is used. +.PP +.I File1 +and +.I file2 +must be sorted in increasing +.SM ASCII +collating +sequence on the fields +on which they are to be joined, +normally the first in each line. +.PP +There is one line in the output +for each pair of lines in +.I file1 +and +.I file2 +that have identical join fields. +The output line normally consists of the common field, +then the rest of the line from +.IR file1 , +then the rest of the line from +.IR file2 . +.PP +Input fields are normally separated spaces or tabs; +output fields by space. +In this case, multiple separators count as one, and +leading separators are discarded. +.PP +The following options are recognized, with POSIX syntax. +.TP +.BI -a " n +In addition to the normal output, +produce a line for each unpairable line in file +.IR n , +where +.I n +is 1 or 2. +.TP +.BI -v " n +Like +.BR -a , +omitting output for paired lines. +.TP +.BI -e " s +Replace empty output fields by string +.IR s . +.TP +.BI -1 " m +.br +.ns +.TP +.BI -2 " m +Join on the +.IR m th +field of +.I file1 +or +.IR file2 . +.TP +.BI -j "n m" +Archaic equivalent for +.BI - n " m"\f1. +.TP +.BI -o fields +Each output line comprises the designated fields. +The comma-separated field designators are either +.BR 0 , +meaning the join field, or have the form +.IR n . m , +where +.I n +is a file number and +.I m +is a field number. +Archaic usage allows separate arguments for field designators. +.PP +.TP +.BI -t c +Use character +.I c +as the only separator (tab character) on input and output. +Every appearance of +.I c +in a line is significant. +.SH EXAMPLES +.TP +.L +sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays +Add birthdays to the +.B /adm/users +file, leaving unknown +birthdays empty. +The layout of +.B /adm/users +is given in +.IR users (6); +.B bdays +contains sorted lines like +.LR "ken:Feb\ 4,\ 1953" . +.TP +.L +tr : ' ' temp +.br +.ns +.TP +.L +join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2' +Print all pairs of users with identical userids. +.SH SOURCE +.B /sys/src/cmd/join.c +.SH "SEE ALSO" +.IR sort (1), +.IR comm (1), +.IR awk (1) +.SH BUGS +With default field separation, +the collating sequence is that of +.BI "sort -b" +.BI -k y , y\f1; +with +.BR -t , +the sequence is that of +.BI "sort -t" x +.BI -k y , y\f1. +.br +One of the files must be randomly accessible. + diff --git a/static/plan9-4e/man1/jpg.1 b/static/plan9-4e/man1/jpg.1 new file mode 100644 index 00000000..b41fb6fb --- /dev/null +++ b/static/plan9-4e/man1/jpg.1 @@ -0,0 +1,204 @@ +.TH JPG 1 +.SH NAME +jpg, gif, png, ppm, togif, toppm, topng \- view and convert pictures +.SH SYNOPSIS +.B jpg +[ +.B -39cdefFkJrtv +] [ +.I file ... +] +.PP +.B gif +[ +.B -39cdektv +] [ +.I file ... +] +.PP +.B png +[ +.B -39cdektv +] [ +.I file ... +] +.B ppm +[ +.B -39cdektv +] [ +.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 ... +] +.PP +.B toppm +[ +.B -c +.I comment +] [ +.I file +] +.PP +.B topng +[ +.B -c +.I comment +] [ +[ +.B -g +.I gamma +] [ +.I file +] +.SH DESCRIPTION +These programs read, display, and write image files in public formats. +.IR Jpg , +.IR gif , +.IR png , +and +.I ppm +read files in the corresponding formats and, by default, display +them in the current window; options cause them instead to convert the images +to Plan 9 image format and write them to standard output. +.IR Togif , +.IR Toppm , +and +.I topng +read Plan 9 images files, convert them to GIF, PPM, or PNG, and write them to standard output. +.PP +The default behavior of +.IR jpg , +.IR gif , +and +.IR ppm +is to display the +.IR file , +or standard input if no file is named. +Once a file is displayed, typing a character causes the program to display the next image. +Typing a +.BR q , +DEL, or control-D exits the program. +For a more user-friendly interface, use +.IR page (1), +which invokes these programs to convert the images to standard format, +displays them, and offers scrolling, panning, and menu-driven navigation among the files. +.PP +These programs share many options: +.TP +.B -e +Disable Floyd-Steinberg error diffusion, which is used to improve the appearance +of images on color-mapped displays, typically with 8 bits per pixel. +Primarily useful for debugging; if the display has true RGB color, the image +will be displayed in full glory. +.TP +.B -k +Convert and display the image as a black and white (really grey-scale) image. +.TP +.B -v +Convert the image to an RGBV color-mapped image, even if the +display has true RGB color. +.TP +.B -d +Suppress display of the image; this is set automatically by +any of the following options: +.TP +.B -c +Convert the image to a Plan 9 representation, as defined by +.IR image (6), +and write it to standard output. +.TP +.B -9 +Like +.BR -c , +but produce an uncompressed image. +This saves processing time, particularly when the output is +being piped to another program such as +.IR page (1), +since it avoids compression and decompression. +.TP +.B -t +Convert the image, if it is in color, to a true color RGB image. +.TP +.B -3 +Like +.BR -t , +but force the image to RGB even if it is originally grey-scale. +.PD +.PP +.I Jpg +has two extra options used to process the output of the LML +video card (see +.IR lml (1)): +.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. +.SH SOURCE +.B /sys/src/cmd/jpg +.SH "SEE ALSO" +.IR lml (1), +.IR page (1), +.IR image (6). +.SH BUGS +Writing an animated GIF using +.I togif +is a clumsy undertaking. diff --git a/static/plan9-4e/man1/kill.1 b/static/plan9-4e/man1/kill.1 new file mode 100644 index 00000000..a4abe8a2 --- /dev/null +++ b/static/plan9-4e/man1/kill.1 @@ -0,0 +1,70 @@ +.TH KILL 1 +.SH NAME +kill, slay, broke \- print commands to kill processes +.SH SYNOPSIS +.B kill +.I name ... +.PP +.B slay +.I name ... +.PP +.B broke +[ +.I user +] +.SH DESCRIPTION +.I Kill +prints commands that will cause all processes called +.I name +and owned by the current user to be terminated. +Use the +.B send +command of +.IR rio (1), +or pipe the output of +.I kill +into +.IR rc (1) +to execute the commands. +.PP +.I Kill +suggests sending a +.B "kill" +note to the process; the same +message delivered to the process's +.B ctl +file (see +.IR proc (3)) +is a surer, if heavy handed, kill, +but is necessary if the offending process is +ignoring notes. +The +.I slay +command prints commands to do this. +.PP +.I Broke +prints commands that will cause all processes +in the +.I Broken +state +and owned by +.I user +(by default, the current user) +to go away. +When a process dies because of an error caught by +the system, it may linger in the +.I Broken +state to allow examination with a debugger. +Executing the commands printed by +.I broke +lets the system reclaim the resources used by +the broken processes. +.SH SOURCE +.B /rc/bin/kill +.br +.B /rc/bin/broke +.SH "SEE ALSO" +.IR ps (1), +.IR stop (1), +.IR notify (2), +.IR proc (3) diff --git a/static/plan9-4e/man1/ktrace.1 b/static/plan9-4e/man1/ktrace.1 new file mode 100644 index 00000000..ef1086f1 --- /dev/null +++ b/static/plan9-4e/man1/ktrace.1 @@ -0,0 +1,62 @@ +.TH KTRACE 1 +.SH NAME +ktrace \- interpret kernel stack dumps +.SH SYNOPSIS +.B ktrace +[ +.B -i +] +.I kernel +.I pc +.I sp +[ +.I link +] +.SH DESCRIPTION +.I Ktrace +translates a hexadecimal kernel stack dump +into a sequence of +.IR acid (1) +commands to show the points in the call trace. +The +.I kernel +argument should be the path of the kernel being debugged, +and +.I pc +and +.I sp +are the PC and SP values given in the stack dump. +For MIPS kernels, the contents of the +.I link +register must also be supplied. +.PP +A stack trace consists of a +.I ktrace +command followed by a series of lines containing +fields of the form +.IB location = contents \fR: +.EX +ktrace /kernel/path 80105bc1 8048e174 +8048e114=80105ac6 8048e120=80140bb4 8048e134=8010031c +8048e16c=80137e45 8048e170=80105bc1 8048e178=80137e62 +\&... +.EE +.PP +The trace can be edited to provide the correct kernel path +and then pasted into a shell window. +If the +.B -i +option is present, +.I ktrace +instead prompts for the contents of the memory locations in which it is interested; +this is useful when the stack trace is on a screen rather than +in a machine readable form. +.SH SOURCE +.B /sys/src/cmd/ktrace.c +.SH SEE ALSO +.IR acid (1), +.IR rdbfs (4) +.SH BUGS +When examining a kernel trace resulting from +an interrupt on top of other interrupts, +only the topmost call trace is printed. diff --git a/static/plan9-4e/man1/leak.1 b/static/plan9-4e/man1/leak.1 new file mode 100644 index 00000000..edcbfbc1 --- /dev/null +++ b/static/plan9-4e/man1/leak.1 @@ -0,0 +1,141 @@ +.TH LEAK 1 +.SH NAME +leak \- examine family of processes for memory leaks +.SH SYNOPSIS +.B leak +[ +.B -bs +] +[ +.B -f +.I binary +] +[ +.B -r +.I res +] +[ +.B -x +.I width +] +.I pid ... +.SH DESCRIPTION +.I Leak +examines the named processes, which +should be sharing their data and bss segments, +for memory leaks. +It uses a mark and sweep-style algorithm to +determine which allocated blocks are no longer +reachable from the set of root pointers. +The set of root pointers is created by looking through +the shared bss segment as well as each process's registers. +.PP +Unless directed otherwise, +.I leak +prints, for each block, a line with five space-separated fields: +the string +.BR block , +the address of the block, +the size of the block, +and the first two words of the block. +Usually, the first two words of the block +contain the malloc and realloc tags +(see +.IR malloc (2)), +useful for finding who allocated the leaked blocks. +.PP +If the +.B -s +option is given, +.I leak +will instead present a sequence of +.IR acid (1) +commands that show each leaky allocation site. +A comment appears next to each command to +indicate how many lost blocks were allocated +at that point in the program. +.PP +If the +.B -b +option is given, leak will print a Plan 9 image file +graphically summarizing the memory arenas. +In the image, each pixel represents +.I res +(default 8) +bytes. +The color code is: +.TP "\w'\fIbright blue\fR 'u +.I "dark blue +Completely allocated. +.TP +.I "bright blue +Contains malloc headers. +.TP +.I "bright red +Contains malloc headers for leaked memory. +.TP +.I "dark red +Contains leaked memory. +.TP +.I "yellow +Completely free +.TP +.I "white +Padding to fill out the image. +.PD +The bright pixels representing headers help in +counting the number of blocks. +Magnifying the images with +.IR lens (1) +is often useful. +.PP +If given a name rather than a list of process ids, +.I leak +echoes back a command-line with process ids of every process +with that name. +.PP +The +.B -f +option specifies a binary to go on the +.IR acid (1) +command-line used to inspect the +processes, and is only necessary +when inspecting processes started +from stripped binaries. +.SH EXAMPLES +List lost blocks in +.IR 8.out . +This depends on the fact that there is only +once instance of +.I 8.out +running; if there were more, the output of +.B "leak -s 8.out +would need editing before sending to the shell. +.IP +.EX +g% leak -s 8.out +leak -s 229 230 +g% leak -s 8.out | rc +src(0x0000bf1b); // 64 +src(0x000016f5); // 7 +src(0x0000a988); // 7 +g% +.EE +.LP +View the memory usage graphic for the window system. +.IP +.EX +g% leak -b rio | rc | page +.EE +.SH SOURCE +.B /sys/lib/acid/leak +.br +.B /sys/src/cmd/aux/acidleak.c +.br +.B /rc/bin/leak +.SH BUGS +Leak depends on the internal structure of the +libc pool memory allocator (see +.IR pool (2)). +Since the ANSI/POSIX environment uses a different +allocator, leak will not work on APE programs. diff --git a/static/plan9-4e/man1/lens.1 b/static/plan9-4e/man1/lens.1 new file mode 100644 index 00000000..58c49dc2 --- /dev/null +++ b/static/plan9-4e/man1/lens.1 @@ -0,0 +1,39 @@ +.TH LENS 1 +.SH NAME +lens \- interactive screen magnifier +.SH SYNOPSIS +.B lens +.SH DESCRIPTION +.I Lens +presents a magnified view in its window of an arbitrary area on the screen. +The default magnification is 4 (showing each pixel as a 4×4 pixel block in +.IR lens 's +window). This may be changed by typing a digit on the keyboard (with +.B 0 +standing for 10), or by using the +.B + +and +.B - +keys to increase or decrease the magnification by one unit. +The lower limit is ×1; the upper ×16. +.PP +The interface to indicate what area to magnify is dictated by the mouse multiplexing rules of +.IR rio (1). +Start by pressing mouse button 1 in the +.I lens +window and dragging, with the button pressed, to the center of the area to magnify. +.I Lens +will update the display as the mouse moves. +Releasing the button freezes the +.I lens +display. +The magnified view is static\(ema snapshot, not a movie\(embut typing a space or +.B . +key in the +.I lens +window will refresh the +display, as will changing the magnification. +.SH SOURCE +.B /sys/src/cmd/lens.c +.SH BUGS +There should be an easier way to indicate what to magnify. diff --git a/static/plan9-4e/man1/lex.1 b/static/plan9-4e/man1/lex.1 new file mode 100644 index 00000000..c4208332 --- /dev/null +++ b/static/plan9-4e/man1/lex.1 @@ -0,0 +1,78 @@ +.TH LEX 1 +.SH NAME +lex \- generator of lexical analysis programs +.SH SYNOPSIS +.B lex +[ +.B -tvn +] +[ +.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. +.SH EXAMPLES +This program converts upper case to lower, +removes blanks at the end of lines, +and replaces multiple blanks by single blanks. +.PP +.EX +%% +[A-Z] putchar(yytext[0]+\'a\'-\'A\'); +[ ]+$ +[ ]+ putchar(\' \'); +.EE +.SH FILES +.TF /sys/lib/lex/ncform +.TP +.B lex.yy.c +output +.TP +.B /sys/lib/lex/ncform +template +.SH "SEE ALSO" +.IR yacc (1), +.IR sed (1) +.br +M. E. Lesk and E. Schmidt, +`LEX\(emLexical Analyzer Generator', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. +.SH SOURCE +.B /sys/src/cmd/lex +.SH BUGS +Cannot handle +.SM UTF. +.br +The asteroid to kill this dinosaur is still in orbit. diff --git a/static/plan9-4e/man1/look.1 b/static/plan9-4e/man1/look.1 new file mode 100644 index 00000000..da4a21ab --- /dev/null +++ b/static/plan9-4e/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 /sys/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/static/plan9-4e/man1/lp.1 b/static/plan9-4e/man1/lp.1 new file mode 100644 index 00000000..0308f9fd --- /dev/null +++ b/static/plan9-4e/man1/lp.1 @@ -0,0 +1,185 @@ +.TH LP 1 +.SH NAME +lp \- printer output +.SH SYNOPSIS +.B lp +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Lp +is a generalized output printing service. +It can be used to queue files for printing, +check a queue, or kill jobs in a queue. +The options are: +.TF -p\ \fIproc\fP +.TP +.BI -d " dest" +Select the destination printer. +If +.I dest +is +.LR ? , +list the currently available printers. +In the absence of +.LR -d , +the destination is taken from the environment variable +.BR LPDEST . +Destination +.L stdout +is the standard output. +Destination +.L safari +is +.L /dev/lpt1data +line printer port on a 386 machine, assumed +to be connected to a PostScript printer. +Destinations +.L hpdeskjet +and +.L bjc240l +are also +.L /dev/lpt1data +but assumed to be connected to an HP Deskjet 670 or +Canon BJC-240. +.I Lp +can print to any printer supported by +Ghostscript using syntax +.BI gs!device +where +.I device +is a Ghostscript output device. +See +.IR gs (1) +and the +.L canonbjc240l +entry in +.LR /sys/lib/lp/devices . +.TP +.B -k +Kill the job(s) given as subsequent arguments instead of file names +for the given destination. +.TP +.BI -p " proc" +The given processor is invoked. +The default processor is +.LR generic , +which tries to do the right thing for regular text, +.IR troff (1) +output, or +.IR tex (1) +output. +If no processing is desired +.L noproc +may be specified. +.TP +.B -q +Print the queue for the given destination. +For some devices, include printer status. +.TP +.B -R +Stops and restarts the printer daemon. +If the printer is wedged, it is often useful to cycle the power on the printer +before running this command. +.PD +.PP +The remaining options may be used to affect the output at a given device. +These options may not be applicable to all devices. +.TF "-p\ \fIproc\fP" +.TP +.BI -c " n" +Print +.I n +copies. +.TP +.BI -f " font" +Set the font (default +.LR CW.11 ). +.TP +.BI -H +Suppress printing of header page. +.TP +.BI -i " n" +Select paper input tray. +.I n +may be a number 0-9, the word +.I man +for the manual feed slot, and/or +.I simplex +or +.I duplex +to get single or double sided output. +Multiple input tray options may be specified if they are +separated by commas. +.TP +.BI -l " n" +Set the number of lines per page to +.IR n . +.TP +.B -L +Print pages in landscape mode (i.e. turned 90 degrees). +.TP +.BI -m " v" +Set magnification to +.IR v . +.TP +.BI -n " n" +Print +.I n +logical pages per physical page. +.TP +.BI -o " list" +Print only pages whose page numbers appear in +the comma-separated +.I list +of numbers and ranges. +A range +.IB n - m +means pages +.I n +through +.IR m ; +a range +.BI - n +means from the beginning to page +.IR n ; +a range +.IB n - +means from page +.I n +to the end. +.TP +.B -r +Reverse the order of page printing. +.TP +.BI -x " v" +Set the horizontal +offset of the print image, measured in inches. +.TP +.BI -y " v" +Set the vertical +offset of the print image, measured in inches. +.SH EXAMPLES +.TP 0 +.L +eqn paper | troff -ms | lp -dsafari +Typeset and print a paper containing equations. +.TP +.L +pr -l100 file | lp -l100 -fCW.8 +Print a file in a small font at 100 lines per page. +.TP +.L +lp -dstdout /dev/windows/3/window > doc.ps +Convert an image to a postscript file. +.SH SEE ALSO +.IR lp (8) +.br +P. Glick, +``A Guide to the Lp Printer Spooler''. +.SH BUGS +Not all options work with all output devices. +Any user can kill any job. diff --git a/static/plan9-4e/man1/ls.1 b/static/plan9-4e/man1/ls.1 new file mode 100644 index 00000000..a938c905 --- /dev/null +++ b/static/plan9-4e/man1/ls.1 @@ -0,0 +1,155 @@ +.TH LS 1 +.SH NAME +ls, lc \- list contents of directory +.SH SYNOPSIS +.B ls +[ +.B -dlmnpqrstuFQ +] +.I name ... +.PP +.B lc +[ +.B -dlmnqrstuFQ +] +.I name ... +.SH DESCRIPTION +For each directory argument, +.I ls +lists the contents of the directory; +for each file argument, +.I ls +repeats its name and any other information requested. +When no argument is given, the current directory is listed. +By default, the output is sorted alphabetically by name. +.PP +.I Lc +is the same as +.IR ls , +but sets the +.B -p +option and pipes the output through +.IR mc (1). +.PP +There are a number of options: +.TP +.B -d +If argument is a directory, list it, not +its contents. +.TP +.B -l +List in long format, giving mode (see below), file system type +(e.g., for devices, the +.B # +code letter that names it; see +.IR Intro (4)), +the instance or subdevice number, owner, group, +size in bytes, and time of last modification +for each file. +.TP +.B -m +List the name of the user who most recently modified the file. +.TP +.B -n +Don't sort the listing. +.TP +.B -p +Print only the final path element of each file name. +.TP +.B -q +List the +.I qid +(see +.IR stat (2)) +of each file; the printed fields are in the order +type, path, and version. +.TP +.B -r +Reverse the order of sort. +.TP +.B -s +Give size in Kbytes for each entry. +.TP +.B -t +Sort by time modified (latest first) instead of +by name. +.TP +.B -u +Under +.B -t +sort by time of last access; +under +.B -l +print time of last access. +.TP +.B -F +Add the character +.B / +after all directory names +and the character +.B * +after all executable files. +.PP +.B -Q +By default, printed file names are quoted if they contain characters special to +.IR rc (1). +The +.B -Q +flag disables this behavior. +.PP +The mode printed under the +.B -l +option contains 11 characters, +interpreted +as follows: +the first character is +.TP +.B d +if the entry is a directory; +.PD 0 +.TP +.B a +if the entry is an append-only file; +.TP +.B - +if the entry is a plain file. +.PD +.PP +The next letter is +.B l +if the file is exclusive access (one writer or reader at a time). +.PP +The last 9 characters are interpreted +as three sets of three bits each. +The first set refers to owner permissions; +the next to permissions to others in the same user-group; +and the last to all others. +Within each set the three characters indicate +permission respectively to read, to write, or to +execute the file as a program. +For a directory, `execute' permission is interpreted +to mean permission to search the directory +for a specified file. +The permissions are indicated as follows: +.TP 3 +.B r +if the file is readable; +.PD 0 +.TP 3 +.B w +if the file is writable; +.TP 3 +.B x +if the file is executable; +.TP 3 +.B - +if none of the above permissions is granted. +.PD +.SH SOURCE +.B /sys/src/cmd/ls.c +.br +.B /rc/bin/lc +.SH SEE ALSO +.IR stat (2) +.IR mc (1) + diff --git a/static/plan9-4e/man1/mail.1 b/static/plan9-4e/man1/mail.1 new file mode 100644 index 00000000..09a8715d --- /dev/null +++ b/static/plan9-4e/man1/mail.1 @@ -0,0 +1,1268 @@ +.TH MAIL 1 +.SH NAME +mail, marshal, nedmail, send, aliasmail, smtp, smtpd, vwhois, filter, fs, biff, pop3, ml, mlmgr, mlowner, list, deliver, token, vf \- mail commands +.SH SYNOPSIS +.B mail +[ +.I arg ... +] +.PP +.B upas/marshal +[ +.B -t +.I mime-type +] +[ +.B -[aA] +.I attachment +] +[ +.B -s +.I subject +] +[ +.B -r +] +[ +.B -x +] +[ +.B -# +] +[ +.B -n +] +[ +.I mailaddr ... +] +.PP +.B upas/send +[ +.B -b +] +[ +.B -i +] +[ +.B -r +] +[ +.B -x +] +[ +.B -# +] +[ +.B -n +] +[ +.I mailaddr ... +] +.PP +.B upas/nedmail +[ +.B -c [dir] +] +[ +.B -r +] +[ +.B -n +] +[ +.B -f +.I mailfile +] +[ +.B -s +.I mailfile +] +.PP +.B upas/fs +[ +.B -f +.I mailbox +] +[ +.B -b +] +[ +.B -n +] +[ +.B -p +] +.PP +.B upas/biff +.PP +.B upas/filter +[ +.B -bh +] +.I rcvr +.I mailbox +.I "regexp file +[ +.I "regexp file +]* +.PP +.B upas/list add|check +.I patterns +.I addrfile ... +.PP +.B upas/deliver +.I recipient +.I fromfile +.I mbox +.PP +.B upas/token +.I key +[ +.I tokenfile +] +.PP +.B upas/pop3 +.PP +.B upas/mlmgr -c +.I listname +.PP +.B upas/mlmgr -ar +.I listname +.I address +.PP +.B upas/ml +.I addressfile +.I listname +.PP +.B upas/mlowner +.I addressfile +.I listname +.PP +upas/vf +.SH DESCRIPTION +.SS Mail +Mail is a shell script that invokes +.I upas/nedmail +when no recipients appear on the command line and +.I upas/marshal +otherwise. +All command line options are passed through. +.SS "Sending mail +.I Marshal +builds a mail message from standard input and passes it +for transmission or delivery to +.B /bin/myupassend +if it exists, otherwise to +.BR /bin/upas/send . +The message format is both RFC 822 and +MIME conformant, so +.I marshal +adds any required headers not already in the message. +Before adding any necessary header lines, it prepends +the contents of +.BI /mail/box/ username /headers\f1. +This allows the addition of personal headers like +.B From: +lines with a full name or a different +return address. +Command line options direct marshal to add a subject line +and append attachments. The arguments to +.I marshal +are the addresses of the recipients. +.PP +When running in a +.IR rio (1) +window, +.I marshal +automatically puts the window into hold mode (see +.IR rio (1)); +this means that the message can be edited freely, +because nothing will be sent to +.I marshal +until the ESC key is hit to exit hold mode. +.PP +The options are: +.TF "-a file" +.TP +.BI -a file +directs +.I marshal +to append +.I file +as a mime attachment. +Unless explicitly specified by the +.B -t +option, the type of the attachment is determined +by running the +.IR file (1) +command. +.TP +.BI -A file +is like +.B -a +but the message disposition is marked as +.I inline +directing any mail reader to display the attachment +(if it can) when the mail message is read. +.TP +.BI -t type +sets the content type for the attachments from +all subsequent +.B -a +and +.B -A +options. +.TP +.BI -s subject +adds a +.B Subject: +header line to the message if one does not +already exist. +.TP +.B -#xnr +are all passed as command line options to the +.I send +that +.I marshal +invokes. +.PD +.PP +.I Send +reads a message from standard input and disposes of it in one +of four ways: +.IP \(bu 3 +If +.I mailaddr +refers to a local mailbox, it appends it to the +recipient's mailbox. +.IP \(bu +If +.I mailaddr +is remote, it queues the mail for remote delivery. +.IP \(bu +If the +.B -r +option is given and the mail is undeliverable, it +returns the mail to the sender. +.IP \(bu +if the +.B -r +option is not given and the mail is undeliverable, it +appends the mail to +.BI /mail/box/ username /dead.letter +and prints a message to standard error. +.PP +The file +.B /mail/lib/rewrite +determines exactly how to deliver or queue the mail. +The decision is based purely on the recipient address. +.PP +The options are: +.TF -b +.TP +.B -b +suppresses the addition of the +.B To: +line. +.TP +.B -i +let the message input be terminated by a line +containing only a period, for +compatibility with +old mailers. +.TP +.B -x +do not send mail, but instead report +the full mail address of the recipient. +.TP +.B -# +do not send mail, but instead report +what command would be used to send the mail. +.TP +.B -r +input is via a pipe from another program. +Expect a From +line at the start of the message to provide the +name of the sender and timestamp. This implies +the +.B -b +option. +.SS "Reading mail" +.I Nedmail +edits a mailbox. +The default mailbox is +.BI /mail/box/ username /mbox\f1. +The +.B -f +command line option specifies an alternate mailbox. +Unrooted path names are interpreted relative to +.BI /mail/box/ username. +If the +.I mailfile +argument is omitted, the name defaults to +.BR stored . +.PP +The options are: +.TF "-f mailfile" +.TP +.BI -c " dir +Create a mailbox. If +.I dir +is specified, the new mailbox is created in +.BI /mail/box/ username / dir /mbox\f1. +Otherwise, the default mailbox is created. +.TP +.B -r +Reverse: show messages in first-in, first-out order; the default is last-in, first-out. +.TP +.B -n +Make the message numbers the same as the file names in the mail +box directory. This implies the +.B -r +option. +.TP +.BI -f " mailfile" +Read messages from the specified file (see above) instead of the default mailbox. +.TP +.BI -s " mailfile" +Read a single message file +.IR mailfile , +as produced by +.IR fs , +and treat it as an entire mailbox. +This is provided for +use in plumbing rules; see +.IR faces (1). +.PD +.PP +.I Nedmail +starts by reading the mail box, printing out the number +of messages, and then prompting for commands from standard input. +Commands, as in +.IR ed (1), +are of the form +.RI `[ range ] +.I command +.RI [ arguments ]'. +The command is applied to each message in the (optional) range. +.PP +The address range can be: +.TP 1.4i +.I address +to indicate a single message header +.PD 0 +.TP +.IB address , address +to indicate a range of contiguous message headers +.TP +.BI g/ expression / +to indicate all messages whose headers match the regular +.IR expression . +.TP +.BI g% expression % +to indicate all messages whose contents match the regular +.IR expression . +.PD +.PP +The addresses can be: +.TP 1.4i +.I number +to indicate a particular message +.PD 0 +.TP +.IB address . number +to indicate a subpart of a particular message +.TP +.BI / expression / +to indicate the next message whose header matches +.I expression +.TP +.BI % expression % +to indicate the next message whose contents match +expression +.TP +.I "empty or . +to indicate the current message +.TP +.BI - address +to indicate backwards search or movement +.PD +.PP +Since messages in MIME are hierarchical +structures, in +.I nedmail +all the subparts are individually addressable. +For example if message 2 contains 3 attachments, +the attachments are numbered 2.1, 2.2, and 2.3. +.PP +The commands are: +.TP 1.1i +.BI a " args +Reply to all addresses in the +.BR To: , +.BR From: , +and +.BR Cc: +header lines. +.I Marshal +is used to format the reply and any arguments the +user specifies are added to the command line to +.I marshal +before the recipient. +The possibility of making a fool of yourself is very +high with this command. +.PD 0 +.TP +.BI A " args +Like +.B a +but with the message +appended to the reply. +.TP +.B b +Print the headers for the next ten messages. +.TP +.B d +Mark message to be deleted upon exiting +.IR nedmail . +.TP +.B f +Append the message to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B h +Print the disposition, size in characters, reception time, sender, +and subject of the message. +.TP +.B H +Print the MIME structure of the message. +.TP +.B help +Print a summary of the commands. +.TP +.BI m " person ... +Forward the message as a mime attachment to the named +.IR persons . +.TP +.BI M " person ... +Like +.B m +but allow the user to type in text to be included +with the forwarded message. +.TP +.B p +Print message. An interrupt stops the printing. +.TP +.BI r " args +Reply to the sender of the message. +.I Marshal +is used to format the reply. +If and optional +.I Args +are specified, they are added to the command line to +.I marshal +before the recipient's address. +.TP +.B R " args +Like +.B r +but with the original message included as an attachment. +.TP +.B rf +Like +.B r +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.B Rf +Like +.B R +but append the message and the reply to the file +.BI /mail/box/ username / sendername +where +.I sendername +is the account name of the sender. +.TP +.BI s " mfile" +Append the message to the specified mailbox. +If +.I mfile +doesn't start with a `/', it is interpreted relative to the directory in which the mailbox resides. +.TP +.B q +Put undeleted mail back in the mailbox and stop. +.TP +EOT (control-D) +Same as +.BR q . +.TP +.BI w " file +Same as +.B s +with the mail header line(s) stripped. This can be used to +save binary mail bodies. +.TP +.B u +Remove mark for deletion. +.TP +.B x +Exit, without changing the mailbox file. +.TP +.BI | command +Run the +.I command +with the message as standard input. +.TP +.BI ! command +Escape to the shell to do +.IR command . +.TP +.B \&= +Print the number of the current message. +.PD +.PP +Here's an example of a mail session that looks at a summary +of the mail messages, saves away an html file added as an +attachment to a message and then deletes the message: +.LP +.EX +% mail +7 messages +: ,h +1 H 2129 07/22 12:30 noone@madeup.net "Add Up To 2000 free miles" +2 504 07/22 11:43 jmk +3 H 784 07/20 09:05 presotto +4 822 07/11 09:23 xxx@yyy.net "You don't call, you don't write..." +5 193 07/06 16:55 presotto +6 529 06/01 19:42 jmk +7 798 09/02 2000 howard +: 1H +1 multipart/mixed 2129 from=noone@madeup.net + 1.1 text/plain 115 + 1.2 text/html 1705 filename=northwest.htm +: 1.2w /tmp/northwest.html +!saved in /tmp/northwest.html +1.2: d +1: q +!1 message deleted +% +.EE +.PP +Notice that the delete of message 1.2 deleted the entire message and +not just the attachment. +.SS "Aliasmail" +.I Aliasmail +expands mail aliases, its arguments, according to alias files. +Each line of an alias file begins with +.B # +(comment) or with a name. +The rest of a name line gives the expansion. +The expansion may contain multiple addresses and may be continued +to another line by appending a backslash. +Items are separated by white space. +.PP +In expanding a name, the sender's personal alias file +.BI /mail/box/ username /names +is checked first. +Then the system alias files, listed one per line in +.BR /mail/lib/namefiles , +are checked in order. +If the name is not found, the expansion is taken to be +.BI local! name\f1. +Under the +.B -f +option, +alias files listed in +.B /mail/lib/fromfiles +are consulted instead, +and the domain part only of the expansion is printed. +.SS Mailboxes +Incoming mail for a user +.I username +is put in the file +.BI /mail/box/ username /mbox +unless either the file +.BI /mail/box/ username /forward +or +.BI /mail/box/ username /pipeto +exists. +The mailbox must have append-only and exclusive-access mode +(see +.IR chmod (1)). +A user must create his or her own mailbox using the +.B -c +option of +.IR nedmail . +Mailboxes are created writable (append-only) but not readable by others. +.SS Forwarding +If the file +.BI /mail/box/ username /forward +exists and is readable by everyone, incoming mail +will be forwarded to the addresses contained in the first line of the file. +The file may contain multiple addresses. +Forwarding loops are caught and resolved by local delivery. +.SS Filtering +If the file +.BI /mail/box/ username /pipeto +exists and is readable and executable by everyone, +it will be run for each incoming message for the user. +The message will be piped to it rather +than appended to his/her mail box. +The file is run as user +.B none +with arguments of the resolved address of +.I username +(e.g., +.BR local!presotto ) +and the user's mail box name. +.PP +.I Filter +provides simple mail filtering. +The first two arguments are the recipient's address and mailbox, that is, +the same arguments provided to +.BR pipeto . +The remaining arguments are all pairs of a regular expression and a file name. +With no flags, the sender's address is matched against each +regular expression starting with the first. If the expression +matches, then the message is delivered to the file whose name +follows the expression. The file must be world writable and should +be append only. +A message that matches none of the expressions is delivered into +the user's standard mail box. +The flags are: +.TP +.B h +the regular expression is matched against the message header +rather than the address. +.TP +.B b +the regular expression is matched against both the header and the body +of the message. +.PP +For example, to delete any messages of precedence bulk, place in +your +.B pipeto +file: +.EX +/bin/upas/filter -h $1 $2 'Precedence: bulk' /dev/null +.EE +.PP +Three other commands exist which, combined by an +.IR rc (1) +script, allow you to build your own filter. +.PP +.I List +takes two verbs; +.B check +and +.BR add . +.B Check +directs +.I list +to check each address contained in the +.IR addressfile s +against a list of patterns in +.IR patternfile . +Patterns come in four forms: +.TP +.B ~\fIregular-expression\fP +If any address matches the regular expression, +.I list +returns successfully. +.TP +.BR =\fIstring\fP . +If any address exactly matches +.IR string , +.I list +returns successfully. +.TP +.B !~\fIregular-expression\fP +If any address matches the regular expression +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.TP +.B !=\fIstring\fP +If any address exactly matches +.I string +and no other address matches a non `!' rule, +.I list +returns error status "!match". +.PP +If no addresses match a pattern, +.I list +returns "no match". +.PP +The pattern file may also contain lines of the form +.EX +#include filename +.EE +This allows pattern files to include other pattern +files. +All pattern matches are case insensitive. +.I List +searches the pattern file (and its includes) in order. +The first matching pattern determines the action. +.PP +.I List +.B add +directs +.I list +to add a pattern to +.I patternfile +for each address in the +.IR addrssfile 's +that doesh't already match a pattern. +.PP +.IR Token , +with only one argument, prints to standard output a unique token +created from the current date and +.IR key . +With two arguments, it checks +.I token +against tokens created over the last 10 days with +.IR key . +If a match is found, it returns successfully. +.PP +.I Deliver +delivers into mail box +.I mbox +the message read from standard input. +It obeys standard mail file locking and logging +conventions. +.PP +A sample +.B pipeto +using the filter kit can be found in +.BR /sys/src/cmd/upas/filterkit/pipeto.sample . +.PP +A sample +.BR myupassend , +.BR /sys/src/cmd/upas/filterkit/myupassend.sample , +is provided which adds all addresses of your outgoing +mail to your pattern file. +You should copy it into a directory that normally gets +bound by your profile onto +.BR /bin . +.SS "Mime File system +.PP +.I Fs +is a user level file system that reads mailboxes and presents them as a file +system. +A user normally starts +.I fs +in his/her profile after starting +.IR plumber (4) +and before starting +a window system, such as +.IR rio (1) +or +.IR acme (1). +The file system is used by +.I nedmail +and +.IR acme (1)'s +mail reader to parse messages. +.I Fs +also generates plumbing messages used by +.IR biff +and +.IR faces (1) +to provide mail announcements. +.PP +The mailbox itself becomes a directory under +.BR /mail/fs . +Each message in the mailbox becomes a numbered directory in the +mailbox directory, and each attachment becomes a numbered directory +in the message directory. Since an attachment may itself be a mail message, +this structure can recurse ad nauseam. +.PP +Each message and attachment directory contains the files: +.TP 1.4i +.B body +.PD 0 +the message minus the RFC822 style headers +.TP +.B cc +the address(es) from the CC: header +.TP +.B date +the date in the message, or if none, the time of delivery +.TP +.B digest +an SHA1 digest of the message contents +.TP +.B disposition +.B inline +or +.B file +.TP +.B filename +a name to use to file an attachment +.TP +.B from +the from address in the From: header, or if none, +the address on the envelope. +.TP +.B header +the RFC822 headers +.TP +.B info +described below, essentially a summary of the header info +.TP +.B inreplyto +contents of the +.B in-reply-to: +header +.TP +.B mimeheader +the mime headers +.TP +.B raw +the undecoded MIME message +.TP +.B rawbody +the undecoded message body +.TP +.B rawheader +the undecoded message header +.TP +.B replyto +the address to send any replies to. +.TP +.B subject +the contents of the subject line +.TP +.B to +the address(es) from the To: line. +.TP +.B type +the MIME content type +.TP +.B unixheader +the envelope header from the mailbox +.PD +.PP +The +.B info +file contains the following information, one item per line. Lists +of addresses are single space separated. +.IP +.TP 2i +.I "sender address +.PD 0 +.TP +.I "recipient addresses +.TP +.I "cc addresses +.TP +.I "reply address +.TP +.I "envelope date +.TP +.I "subject +.TP +.I "MIME content type +.TP +.I "MIME disposition +.TP +.I filename +.TP +.I "SHA1 digest +.TP +.I "bcc addresses +.TP +.I "in-reply-to: contents +.TP +.I "RFC822 date +.TP +.I "message senders +.TP +.I "message id +.TP +.I "number of lines in body +.PD +.PP +Deleting message directories causes the message to be removed from +the mailbox. +.PP +The mailbox is reread and the structure updated +whenever the mailbox changes. Message directories are +not renumbered. +.PP +The file +.B /mail/fs/ctl +is used to direct +.I fs +to open/close new mailboxes or to delete groups of messages atomically. +The messages that can be written to this file are: +.TP 2i +.PD 0 +.B "open \fIpath mboxname\fP +opens a new mailbox. +.I path +is the file to open, and +.I mboxname +is the name that appears under +.BR /mail/fs . +.TP +.B "close \fImboxname\fP +close +.IR mboxname . +The close takes affect only after all files open under +.BI /mail/fs/ mboxname +have been closed. +.TP +.B "delete \fImboxname number ...\fP +Delete the messages with the given numbers from +.IR mboxname. +.PD +.PP +The options are: +.TF "-f file +.TP +.BI -f file +use +.I file +as the mailbox instead of the default, +.BI /mail/box/ username /mbox. +.PD 0 +.TP +.B -b +stands for biffing. Each time new mail +is received, a message is printed to standard +output containing the sender address, subject, +and number of bytes. It is intended for +people telnetting in who want mail announcements. +.TP +.B -n +Don't open a mailbox initially. Overridden by -f. +.TP +.B -p +turn off plumbing. Unless this is specified, +.I fs +sends a message to the plumb port, +.BR seemail , +from source +.B mailfs +for each message received or deleted. +The message contains the attributes +.IR sender = "" , +.IR filetype =mail, +.IR mailtype = "deleted or new" , +and +.IR length = "" . +The contents of the message is the full path +name of the directory representing the message. +.TP +.B -s +causes +.I fs +to put itself in +.B /srv +with a name of the form +.BR /srv/upasfs.\fIuser\fP . +.TP +.B -m +specifies a mount point other than +.BR /mail/fs . +.PD +.PP +.I Fs +will exit once all references to its directory +have disappeared. +.SS "Mail Announcements +.PP +.I Biff +is the textual equivalent of +.IR faces (1). +It listens to plumbing messages from +.I fs +and for each new message prints to standard output a line +containing the sender address, subject, +and number of bytes. +It exists for people without graphics capability or with screens too small to +dedicate the space +.IR faces (1) +requires. It forks to place itself in the background. +.SS "Remote delivery +.PP +.I Smtp +sends the mail message from standard input +to the users +.I rcpt-list +on the host at network address +.I address +using the Simple Mail Transfer Protocol. +The return address of the mail will contain the local +system name from the environment variable +.I sysname +and the user +.IR sender . +The +.B -h +option uses +.I host +as the local system name; +it may be fully-qualified or not. +If +.I .domain +is given, it is appended to the end of the system name. +The +.B -f +option just prints out the converted message rather than +sending it to the destination. +The +.B -g +option specifies a gateway system to pass the message to if smtp can't +find an address or MX entry for the destination system. +The +.B -d +option turns on debugging output to standard error. +.PP +.I Smtpd +receives a message using the Simple Mail Transfer Protocol. +Standard input and output are the protocol connection. +.PP +The options are: +.TP 1.1i +.B -d +turns on debugging output to standard error. +.TP +.B -r +turns on forward DNS validation of non-trusted sender address. +.TP +.B -f +prevents relaying from non-trusted networks. +.TP +.B "-n \fItcp-directory\fP" +specifies the name of the network directory assigned to the incoming connection. +This is used to determine the peer IP address. If this flag is not +specified, the peer address is determined using standard input. +.TP +.B "-h \fIdomain\fP" +specifies the receiving domain. If this flag is not specified, the +receiving domain is inferred from the host name. +.TP +.B -s +causes copies of blocked messages to be saved in a sub-directory of +.BR /mail/queue.dump . +.TP +.B "-k \fIIP address\fP" +causes connections from the host at +.I "IP address" +to be dropped at program startup. Multiple addresses +can be specified with several +.B -k +options. This option should be used carefully; +it is intended to lessen the effects of denial of +service attacks or broken mailers which continually +connect. The connections are not logged and the +remote system is not notified via the protocol. +.PP +.I Smtpd +is normally run by a network listener such as +.IR listen (8). +Most of the command line options are more conveniently +specified in the smtpd configuration file stored in +.BR /mail/lib/smtpd.conf . +.SS "Mailing lists +.I Mlmgr +creates and updates unmoderated mailing lists. +The +.B \-c +option creates mail directories for both +.I listname +and +.IB listname -owner\f1,\fP +each containing a +.B pipeto +file. +Messages mailed to +.I listname +are sent to all members of the mailing list. +Any +.B Reply-to: +and +.B Precedence: +fields are +removed from the messages and new ones are added +directing replies to +.I listname +and specifying bulk precedence. The envelope address for +error replies is set to +.BR /dev/null . +.PP +The mailing list membership is the file +.BR /mail/box/\fIlistname\fP/address-list . +This file is an add/remove log. Each line +represents a single address. Lines beginning +with a hash +.RB ( # ) +are comments. +Lines beginning with an exclamation point +.RB ( ! ) +are removals. +All other lines are additions. +.PP +Addition and removal entries can be appended using the +.B -a +and +.B -r +options to +.IR mlmgr . +However, they are normally appended as a consequence or +user requests. +.PP +To be added or removed from the list, a user +may send a message to +.IB listname -owner\f1.\fP +containing a key word in +the header or body. The key words are: +.IP +subscribe - add my +.B From: +address to the list +.IP +remove - remove my +.B From: +address from the list +.IP +unsubscribe - remove my +.B From: +address from the list +.PP +Addition and removal events cause notification messages to +be sent to the added/removed address. In the case of +addition, the message describes how to be removed. +.PP +.I Ml +and +.I mlowner +are the programs that receive messages for +.I listname +and +.IB listname -owner +respectively. +Appropriate calls to them are inserted in the +.B pipeto +files created by +.IR mlmgr . +.SS "Virus Wrapper +.I Vf +takes a mail message as standard input, searches for executable +MIME attachments, wraps them in a warning message, and appends +.B .suspect +to any related filenames. +.B /sys/lib/mimetype +contains the list of known MIME content types and file extensions. +.I Vf +wraps all those for which the fifth field of +.B mimetype +is +.BR n . +.SS "Mail server +.I Pop3 +is a rudimentary POP3 server that uses APOP for authentication. +It predates +.I upas/fs +and does not use it. It will soon be replaced by one that uses +.IR upas/fs . +See also the IMAP4 server described in +.IR ipserv (8). +.SH FILES +.TF /mail/box/*/dead.letter +.TP +.B /sys/log/mail +mail log file +.TP +.B /mail/box/* +mail directories +.TP +.B /mail/box/*/mbox +mailbox files +.TP +.B /mail/box/*/forward +forwarding address(es) +.TP +.B /mail/box/*/pipeto +mail filter +.TP +.B /mail/box/*/L.reading +mutual exclusion lock for multiple mbox readers +.TP +.B /mail/box/*/L.mbox +mutual exclusion lock for altering mbox +.TP +.B /mail/box/*/dead.letter +unmailable text +.TP +.B /mail/box/*/names +personal alias files +.TP +.B /mail/lib/rewrite +rules for handling addresses +.TP +.B /mail/lib/namefiles +lists files to search for aliases in +.TP +.B /lib/face/48x48x? +directories of icons for +.I seemail +.SH SOURCE +.TF /sys/src/cmd/upas +.TP +.B /rc/bin/mail +.TP +.B /sys/src/cmd/upas +source for commands in +.B /bin/upas +.TP +.B /sys/src/cmd/faces +.TP +.B /rc/bin/vwhois +.SH "SEE ALSO" +.IR face (6), +.IR rewrite (6) +.IR ipserv (8) +.SH BUGS +.I Nedmail +truncates +long headers for searching. +.sp +.br +.I Biff +and +the +.B \-b +option of +.I fs +perform the same function but in slightly +different environments. +The duality is confusing. +The +.B \-b +option exists because starting both +.I fs +and +.I biff +in a Telnet session results in a number +of processes that don't die when the +session is terminated; the +.IR plumber (4) +is held open by +.I fs +and +.I biff +still having it mounted, while +.I fs +is held open by +.I biff +which is blocked waiting for plumbing +input. diff --git a/static/plan9-4e/man1/man.1 b/static/plan9-4e/man1/man.1 new file mode 100644 index 00000000..c7273051 --- /dev/null +++ b/static/plan9-4e/man1/man.1 @@ -0,0 +1,97 @@ +.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 ... +.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. +.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 /rc/bin/man +.br +.B /rc/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/static/plan9-4e/man1/mc.1 b/static/plan9-4e/man1/mc.1 new file mode 100644 index 00000000..672bc967 --- /dev/null +++ b/static/plan9-4e/man1/mc.1 @@ -0,0 +1,40 @@ +.TH MC 1 +.SH NAME +mc \- multicolumn print +.SH SYNOPSIS +.B mc +[ +.B - +] +[ +.BI - N +] +[ +.I file ... +] +.SH DESCRIPTION +.I Mc +splits the input into as many columns as will fit in +.I N +print positions. +If run in an +.IR rio (1) +window, the default +.I N +is the number of blanks that will fit across the window; +otherwise the default +.I N +is 80. +Under option +.B - +each input line ending in a colon +.L : +is printed separately. +.SH SOURCE +.B /sys/src/cmd/mc.c +.SH "SEE ALSO" +.IR rio (1), +.IR pr (1), +.I lc +in +.IR ls (1) diff --git a/static/plan9-4e/man1/mk.1 b/static/plan9-4e/man1/mk.1 new file mode 100644 index 00000000..32485e5e --- /dev/null +++ b/static/plan9-4e/man1/mk.1 @@ -0,0 +1,654 @@ +.TH MK 1 +.SH NAME +mk, membername \- maintain (make) related files +.SH SYNOPSIS +.B mk +[ +.B -f +.I mkfile +] ... +[ +.I option ... +] +[ +.I target ... +] +.PP +.B membername +.I aggregate ... +.SH DESCRIPTION +.I Mk +uses the dependency rules specified in +.I mkfile +to control the update (usually by compilation) of +.I targets +(usually files) +from the source files upon which they depend. +The +.I mkfile +(default +.LR mkfile ) +contains a +.I rule +for each target that identifies the files and other +targets upon which it depends and an +.IR rc (1) +script, a +.IR recipe , +to update the target. +The script is run if the target does not exist +or if it is older than any of the files it depends on. +.I Mkfile +may also contain +.I meta-rules +that define actions for updating implicit targets. +If no +.I target +is specified, the target of the first rule (not meta-rule) in +.I mkfile +is updated. +.PP +The environment variable +.B $NPROC +determines how many targets may be updated simultaneously; +Plan 9 sets +.B $NPROC +automatically to the number of CPUs on the current machine. +.PP +Options are: +.TP \w'\fL-d[egp]\ 'u +.B -a +Assume all targets to be out of date. +Thus, everything is updated. +.PD 0 +.TP +.BR -d [ egp ] +Produce debugging output +.RB ( p +is for parsing, +.B g +for graph building, +.B e +for execution). +.TP +.B -e +Explain why each target is made. +.TP +.B -i +Force any missing intermediate targets to be made. +.TP +.B -k +Do as much work as possible in the face of errors. +.TP +.B -n +Print, but do not execute, the commands +needed to update the targets. +.TP +.B -s +Make the command line arguments sequentially rather than in parallel. +.TP +.B -t +Touch (update the modified date of) file targets, without +executing any recipes. +.TP +.BI -w target1 , target2,... +Pretend the modify time for each +.I target +is the current time; useful in conjunction with +.B -n +to learn what updates would be triggered by +modifying the +.IR targets . +.PD +.PP +The +.IR rc (1) +script +.I membername +extracts member names +(see `Aggregates' below) +from its arguments. +.SS The \fLmkfile\fP +A +.I mkfile +consists of +.I assignments +(described under `Environment') and +.IR rules . +A rule contains +.I targets +and a +.IR tail . +A target is a literal string +and is normally a file name. +The tail contains zero or more +.I prerequisites +and an optional +.IR recipe , +which is an +.B rc +script. +Each line of the recipe must begin with white space. +A rule takes the form +.IP +.EX +target: prereq1 prereq2 + rc \f2recipe using\fP prereq1, prereq2 \f2to build\fP target +.EE +.PP +When the recipe is executed, +the first character on every line is elided. +.PP +After the colon on the target line, a rule may specify +.IR attributes , +described below. +.PP +A +.I meta-rule +has a target of the form +.IB A % B +where +.I A +and +.I B +are (possibly empty) strings. +A meta-rule acts as a rule for any potential target whose +name matches +.IB A % B +with +.B % +replaced by an arbitrary string, called the +.IR stem . +In interpreting a meta-rule, +the stem is substituted for all occurrences of +.B % +in the prerequisite names. +In the recipe of a meta-rule, the environment variable +.B $stem +contains the string matched by the +.BR % . +For example, a meta-rule to compile a C program using +.IR 2c (1) +might be: +.IP +.EX +%: %.c + 2c $stem.c + 2l -o $stem $stem.2 +.EE +.PP +Meta-rules may contain an ampersand +.B & +rather than a percent sign +.BR % . +A +.B % +matches a maximal length string of any characters; +an +.B & +matches a maximal length string of any characters except period +or slash. +.PP +The text of the +.I mkfile +is processed as follows. +Lines beginning with +.B < +followed by a file name are replaced by the contents of the named +file. +Lines beginning with +.B "<|" +followed by a file name are replaced by the output +of the execution of the named +file. +Blank lines and comments, which run from unquoted +.B # +characters to the following newline, are deleted. +The character sequence backslash-newline is deleted, +so long lines in +.I mkfile +may be folded. +Non-recipe lines are processed by substituting for +.BI `{ command } +the output of the +.I command +when run by +.IR rc . +References to variables are replaced by the variables' values. +Special characters may be quoted using single quotes +.BR \&'' +as in +.IR rc (1). +.PP +Assignments and rules are distinguished by +the first unquoted occurrence of +.B : +(rule) +or +.B = +(assignment). +.PP +A later rule may modify or override an existing rule under the +following conditions: +.TP +\- +If the targets of the rules exactly match and one rule +contains only a prerequisite clause and no recipe, the +clause is added to the prerequisites of the other rule. +If either or both targets are virtual, the recipe is +always executed. +.TP +\- +If the targets of the rules match exactly and the +prerequisites do not match and both rules +contain recipes, +.I mk +reports an ``ambiguous recipe'' error. +.TP +\- +If the target and prerequisites of both rules match exactly, +the second rule overrides the first. +.SS Environment +Rules may make use of +.B rc +environment variables. +A legal reference of the form +.B $OBJ +is expanded as in +.IR rc (1). +A reference of the form +.BI ${name: A % B = C\fL%\fID\fL}\fR, +where +.I A, B, C, D +are (possibly empty) strings, +has the value formed by expanding +.B $name +and substituting +.I C +for +.I A +and +.I D +for +.I B +in each word in +.B $name +that matches pattern +.IB A % B\f1. +.PP +Variables can be set by +assignments of the form +.I + var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR +.br +Blanks in the +.I value +break it into words, as in +.I rc +but without the surrounding parentheses. +Such variables are exported +to the environment of +recipes as they are executed, unless +.BR U , +the only legal attribute +.IR attr , +is present. +The initial value of a variable is +taken from (in increasing order of precedence) +the default values below, +.I mk's +environment, the +.IR mkfiles , +and any command line assignment as an argument to +.IR mk . +A variable assignment argument overrides the first (but not any subsequent) +assignment to that variable. +The variable +.B MKFLAGS +contains all the option arguments (arguments starting with +.L - +or containing +.LR = ) +and +.B MKARGS +contains all the targets in the call to +.IR mk . +.PP +It is recommended that mkfiles start with +.IP +.EX + output +.br +.B html2ms < input > output +.SH DESCRIPTION +.I Ms2html +converts the +.IR ms (6) +source on standard input into HTML and prints it to +standard output. +If the source contains +.IR tbl (1) +or +.IR eqn +input, you must first pipe the text through those +preprocessors. +Postscript images, equations, and tables will be +converted to gif files. +If the document has a +.B .TL +entry, its contents will be used as the title; otherwise +.I ms2html +will look for a +.B ._T +macro, unknown to +.IR ms (6), +and take its value. +.SH SOURCE +.B /sys/src/cmd/ms2html.c +.br +.B /sys/src/cmd/html2ms.c +.SH BUGS +.PP +Ms2html doesn't understand a number of troff +commands. It does handle macros and defined +strings. +.PP +Html2ms doesn't understand html tables. diff --git a/static/plan9-4e/man1/netstat.1 b/static/plan9-4e/man1/netstat.1 new file mode 100644 index 00000000..6c16484b --- /dev/null +++ b/static/plan9-4e/man1/netstat.1 @@ -0,0 +1,39 @@ +.TH NETSTAT 1 +.SH NAME +netstat \- summarize network connections +.SH SYNOPSIS +.B netstat +[ +.B -in +] [ +.I netmtpt +] +.SH DESCRIPTION +.I Netstat +prints information about network mounted at +.IR netmtpt , +default +.BR /net . +With the +.B \-i +option, it reports one line per network interface listing the +device, MTU, local address, masl, remote address, packets in, +packets out, errors in, and errors out for this interface. +For +.I IP +connections +.I netstat +reports the connection number, user, +connection state, local port, remote port and +remote address. +.I Netstat +looks up port numbers and addresses in the network databases +to print symbolic names if possible, but if the +.B -n +option is specified, it does not translate to symbolic form. +.SH FILES +.B /net/*/* +.SH SOURCE +.B /sys/src/cmd/netstat.c +.SH "SEE ALSO" +.IR ipconfig (8) diff --git a/static/plan9-4e/man1/news.1 b/static/plan9-4e/man1/news.1 new file mode 100644 index 00000000..0a33502a --- /dev/null +++ b/static/plan9-4e/man1/news.1 @@ -0,0 +1,63 @@ +.TH NEWS 1 +.SH NAME +news \- print news items +.SH SYNOPSIS +.B news +[ +.B -a +] +[ +.B -n +] +[ +.I item ... +] +.SH DESCRIPTION +When invoked without options, +this simple local news service +prints files that have appeared in +.BR /lib/news +since last reading, most recent first, +with each preceded by an appropriate header. +The time of reading is recorded. +The options are +.TP +.B -a +Print all items, regardless of currency. +The recorded time is not changed. +.TP +.B -n +Report the names of the current items without +printing their contents, and without changing +the recorded time. +.PP +Other arguments +select particular news items. +.PP +To post a news item, create a file in +.BR /lib/news . +.PP +You may arrange to receive news automatically by +registering your mail address in +.BR /sys/lib/subscribers . +A daemon mails recent news +to all addresses on the list. +.PP +Empty news items, and news items named +.B core +or +.B dead.letter +are ignored. +.SH FILES +.TF /sys/lib/subscribers +.TP +.B /lib/news/* +articles +.TP +.B $HOME/lib/newstime +modify time is time news was last read +.TP +.B /sys/lib/subscribers +who gets news mailed to them +.SH SOURCE +.B /sys/src/cmd/news.c diff --git a/static/plan9-4e/man1/nm.1 b/static/plan9-4e/man1/nm.1 new file mode 100644 index 00000000..f9faad54 --- /dev/null +++ b/static/plan9-4e/man1/nm.1 @@ -0,0 +1,104 @@ +.TH NM 1 +.SH NAME +nm \- name list (symbol table) +.SH SYNOPSIS +.B nm +[ +.B -aghnsu +] +.I file ... +.SH DESCRIPTION +.I Nm +prints the name list of each executable or object +.I file +in the argument list. +If the +.I file +is an archive +(see +.IR ar (1)), +the name list of each file in the archive is printed. +If more than one file is given in the argument list, +the name of each file is printed at the beginning of each line. +.PP +Each symbol name is preceded by its hexadecimal +value (blanks if undefined) +and one of the letters +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.TP +.B z +source file name +.TP +.B Z +source file line offset +.TP +.B f +source file name components +.PD +.PP +The output is sorted alphabetically. +.PP +Options are: +.TP +.B -a +Print all symbols; normally only user-defined text, data, +and bss segment symbols are printed. +.TP +.B -g +Print only global +.RB ( T , +.BR L , +.BR D , +.BR B ) +symbols. +.TP +.B -h +Do not print file name headers with output lines. +.TP +.B -n +Sort according to the address of the symbols. +.TP +.B -s +Don't sort; print in symbol-table order. +.TP +.B -u +Print only undefined symbols. +.SH SOURCE +.B /sys/src/cmd/nm.c +.SH SEE ALSO +.IR ar (1), +.IR 2l (1), +.IR db (1), +.IR acid (1), +.IR a.out (6) + diff --git a/static/plan9-4e/man1/ns.1 b/static/plan9-4e/man1/ns.1 new file mode 100644 index 00000000..ab980345 --- /dev/null +++ b/static/plan9-4e/man1/ns.1 @@ -0,0 +1,44 @@ +.TH NS 1 +.SH NAME +ns \- display name space +.SH SYNOPSIS +.B ns +[ +.B -r +] [ +.I pid +] +.SH DESCRIPTION +.I Ns +prints a representation of the file name space of the process with the named +.IR pid , +or by default itself. +The output is in the form of an +.IR rc (1) +script that could, in principle, recreate the name space. +The output is produced by reading and reformatting the contents of +.BI /proc/ pid /ns . +.PP +By default, +.I ns +rewrites the names of network data files to represent the network +address that data file is connected to, for example replacing +.B /net/il/82/data +with +.BR il!123.122.121.9 . +The +.B -r +flag suppresses this rewriting. +.SH FILES +.B /proc/*/ns +.SH SOURCE +.B /sys/src/cmd/ns.c +.SH "SEE ALSO" +.IR ps (1), +.IR proc (3), +.IR namespace (4), +.IR namespace (6) +.SH BUGS +The names of files printed by +.I ns +will be inaccurate if a file or directory it includes has been renamed. diff --git a/static/plan9-4e/man1/p.1 b/static/plan9-4e/man1/p.1 new file mode 100644 index 00000000..d3287599 --- /dev/null +++ b/static/plan9-4e/man1/p.1 @@ -0,0 +1,33 @@ +.TH P 1 +.SH NAME +p \- paginate +.SH SYNOPSIS +.B p +[ +.BI - number +] +[ +.I file ... +] +.SH DESCRIPTION +.I P +copies its standard input, or the named files if given, +to its standard output, +stopping at the end of every 22nd line, and between files, +to wait for a newline from the user. +The option sets the +.I number +of lines on a page. +.PP +While waiting for a newline, +.I p +interprets the commands: +.TP +.B ! +Pass the rest of the line to the shell as a command. +.TP +.B q +Quit. +.PP +.SH SOURCE +.B /sys/src/cmd/p.c diff --git a/static/plan9-4e/man1/page.1 b/static/plan9-4e/man1/page.1 new file mode 100644 index 00000000..ffa7f8b7 --- /dev/null +++ b/static/plan9-4e/man1/page.1 @@ -0,0 +1,229 @@ +.TH PAGE 1 +.SH NAME +page \- view +FAX, +image, graphic, PostScript, PDF, +and typesetter output +files +.SH SYNOPSIS +.B page +[ +.B -abirPRvVw +] +[ +.B -p +.I ppi +] +[ +.IR file ... +] +.SH DESCRIPTION +.I Page +is a general purpose document viewer. +It can be used to display the individual pages +of a +PostScript, +PDF, +or +.IR tex (1) +or +.IR troff (1) +device independent output +file. +.I Tex +or +.I troff +output is simply converted to PostScript in order to be viewed. +It can also be used to view any number of +graphics files +(such as a +FAX +page, +a Plan 9 +.IR image (6) +file, an Inferno bitmap file, or other common format). +.I Page +displays these +in sequence. +In the absence of named files, +.I page +reads one from standard input. +.PP +By default, +.I page +runs in the window in which it is started +and leaves the window unchanged. +The +.B -R +option causes +.I page +to grow the window if necessary +to display the page being viewed. +The +.B -w +option causes +.I page +to create a new window for itself. +The newly created window will grow as under the +.B -R +option. +If being used to display +multipage documents, +only one file may be specified on the command line. +.PP +The +.B -p +option sets the resolution for PostScript and PDF +files, in pixels per inch. +The default is 100 ppi. +The +.B -r +option reverses the order in which pages are displayed. +.PP +When viewing a document, +.I page +will try to guess the true bounding box, usually rounding up from +the file's bounding box to +8½×11 or A4 size. +The +.B -b +option causes it to respect the bounding box given in the file. +As a more general problem, +some PostScript files claim to conform to Adobe's +Document Structuring Conventions but do not. +The +.B -P +option enables a slightly slower and slightly more +skeptical version of the PostScript processing code. +Unfortunately, there are PostScript documents +that can only be viewed with the +.B -P +option, and there are PostScript documents that +can only be viewed without it. +.PP +When viewing images with +.IR page , +it listens to the +.B image +plumbing channel +(see +.IR plumber (4)) +for more images to display. +The +.B -i +option causes +.I page +to not load any graphics files nor to read +from standard input but rather to listen +for ones to load from the plumbing channel. +.PP +The +.B -v +option turns on extra debugging output, and +the +.B -V +option turns on even more debugging output. +The +.B -a +option causes +.I page +to call +.IR abort (2) +rather than exit cleanly on errors, +to facilitate debugging. +.PP +Pressing and holding button 1 permits panning about the page. +Typing a +.B q +or +control-D exits the program. +Typing a +.B u +toggles whether images are displayed upside-down. +(This is useful in the common case of mistransmitted upside-down faxes). +Typing a +.B r +reverses the order in which pages are displayed. +Typing a +.B w +will write the currently viewed page to a new file as a compressed +.IR image (6) +file. +When possible, the filename is of the form +.IR basename . pagenum . bit . +Typing a +.B d +removes an image from the working set. +.PP +To go to a specific page, one can type its number followed by enter. +Typing left arrow, backspace, or minus displays the previous page. +Clicking button 2 or typing right arrow, space, or enter displays the next page. +The up and down arrow pan up and down one half screen height, +changing pages when panning off the top or bottom of the page. +Button 3 raises a menu of the +pages +to be selected for viewing in any order. +.PP +.I Page +calls +.IR gs (1) +to draw each page of PostScript +and +PDF +.IR files . +It also calls a variety of conversion programs, such as those described in +.IR jpg (1), +to convert the various raster graphics formats +into Inferno bitmap files. +Pages are converted ``on the fly,'' as needed. +.SH EXAMPLES +.TP +.L +page /sys/src/cmd/gs/examples/tiger.ps +Display a color PostScript file. +.TP +.L +page /usr/inferno/icons/*.bit +Browse the Inferno bitmap library. +.TP +.L +man -t page | page -w +Preview this manual in a new window. +.SH "SEE ALSO +.IR gs (1), +.IR jpg (1), +.IR tex (1), +.IR troff (1) +.SH SOURCE +.B /sys/src/cmd/page +.SH DIAGNOSTICS +The mouse cursor changes to an arrow and ellipsis +when +.I page +is reading or writing a file. +.SH BUGS +.I Page +supports reading of only one document +file at a time, and +the user interface is clumsy when viewing very large documents. +.PP +When viewing multipage PostScript files that do not contain +.RB `` %%Page '' +comments, the button 3 menu only contains +``this page'' and ``next page'': +correctly determining +page boundaries in Postscript code is not computable +in the general case. +.PP +If +.I page +has trouble viewing a Postscript file, +it might not be exactly conforming: try viewing it with the +.B -P +option. +.PP +The interface to the plumber is unsatisfactory. In particular, +document references cannot be sent +via plumbing messages. +.PP +There are too many keyboard commands. diff --git a/static/plan9-4e/man1/passwd.1 b/static/plan9-4e/man1/passwd.1 new file mode 100644 index 00000000..4c5b6705 --- /dev/null +++ b/static/plan9-4e/man1/passwd.1 @@ -0,0 +1,74 @@ +.TH PASSWD 1 +.SH NAME +passwd, netkey, iam \- change user password +.SH SYNOPSIS +.B passwd +[ +.I authdom +] +.PP +.B netkey +.PP +.B auth/iam +[ +.I username +] +.SH DESCRIPTION +.I Passwd +changes the invoker's Plan 9 password and/or APOP secret. +The Plan 9 password is used to login to a terminal while +the APOP secret is used for a number of external services: +POP3, IMAP, and VPN access. The optional argument specifies +the authentication domain to use if different than the one +associated with the machine +.I passwd +is run on. +.PP +The program first prompts for the old Plan 9 password in the specified +domain to establish +identity. +It then prompts for changes to the password and the +secret. +New passwords and secrets must be typed twice, to forestall mistakes. +New passwords must be sufficiently hard to guess. +They may be of any length greater than seven characters. +.PP +.I Netkey +uses the password to encrypt network challenges. +It is a substitute for a SecureNet box. +.PP +These commands may be run only on a terminal, to avoid +transmitting clear text passwords over the network. +.PP +.I Auth/iam +can be run only by the the host owner (the user specified as the contents of +.BR /dev/hostower ). +With it both the identity and password of the host owner may +be changed. For example, if start a terminal and log in as +.LR tor , +you may later change identity to +.LR supertor . +If the host owner changes, all processes running as the host owner +also change their identity to the new user id. +.PP +Without an argument, +.I Auth/iam +just sets the password of the host owner. +This can be used on machines like the Bitsy which have no +possibility of user input until the bootstrap procedure has already +started a number of processes. +.SH FILES +.B /dev/key +.SH SOURCE +.B /sys/src/cmd/auth/passwd.c +.br +.B /sys/src/cmd/auth/netkey.c +.SH "SEE ALSO" +.IR encrypt (2), +.IR cons (3), +.IR securenet (8) +.PP +Robert Morris and Ken Thompson, +``UNIX Password Security,'' +.I AT&T Bell Laboratories Technical Journal +Vol 63 (1984), pp. 1649-1672 diff --git a/static/plan9-4e/man1/pcc.1 b/static/plan9-4e/man1/pcc.1 new file mode 100644 index 00000000..fd7acd91 --- /dev/null +++ b/static/plan9-4e/man1/pcc.1 @@ -0,0 +1,185 @@ +.TH PCC 1 +.SH NAME +pcc \- APE C compiler driver +.SH SYNOPSIS +.B pcc +[ +.I option ... +] +[ +.I name ... +] +.SH DESCRIPTION +.I Pcc +compiles and loads C programs, +using APE (ANSI C/POSIX) include files and libraries. +Named files ending with +.B .c +are preprocessed with +.IR cpp (1), +then compiled with one of the compilers described in +.IR 2c (1), +as specified by the environment variable +.BR $objtype . +The object files are then loaded using one of the loaders described in +.IR 2l (1). +The options are: +.TP \w'\fL-D\ \fIname=def\ 'u +.B "-+ +Accept C++ +.B // +comments. +.TP +.BI -o " out" +Place loader output in file +.I out +instead of the default +.BR 2.out , +.BR v.out , +etc. +.TP +.B -P +Omit the compilation and loading phases; +leave the result of preprocessing +.IB name .c +in +.IB name .i\f1. +.TP +.B -E +Like +.BR -P , +but send the result to standard output. +.TP +.B -c +Omit the loading phase. +.TP +.B -p +Insert profiling code into the executable output. +.TP +.B -w +Print compiler warning messages. +.TP +.BI -l lib +Include +.BI / $objtype /lib/ape/lib lib .a +as a library during the linking phase. +.TP +.B -B +Don't complain about functions used without +ANSI function prototypes. +.TP +.B -V +Enable +.B void* +conversion warnings, as in +.IR 2c (1). +.TP +.B -v +Echo the preprocessing, compiling, and loading commands +before they are executed. +.TP +.BI -D name=def +.br +.ns +.TP +.BI -D name +Define the +.I name +to the preprocessor, +as if by +.LR #define . +If no definition is given, the name is defined as +.LR 1 . +.TP +.BI -U name +Undefine the +.I name +to the preprocessor, +as if by +.LR #undef . +.TP +.BI -I dir +.L #include +files whose names do not begin with +.L / +are always +sought first in the directory +of the +.I file +argument, +then in directories named in +.B -I +options, +then in +.BR /$objtype/include/ape . +.TP +.B -N +Don't optimize compiled code. +.TP +.B -S +Print an assembly language version of the object code +on standard output. +.TP +.B -a +Instead of compiling, print on standard output acid functions (see +.IR acid (1)) +for examining structures declared in the source files. +.TP +.B -aa +Like +.B -a +except that functions for structures declared in included header files +are omitted. +.TP +.B -F +Enable vararg type checking as described in +.IR 2c (1). +This is of limited use without the appropriate +.B #pragma +definitions. +.PP +The APE environment contains all of the include +files and library routines specified in the ANSI C standard +(X3.159-1989), as well as those specified in the IEEE Portable +Operating System Interface standard (POSIX, 1003.1-1990, ISO 9945-1). +In order to access the POSIX routines, source programs should +define the preprocessor constant +.BR _POSIX_SOURCE . +.SH FILES +.TF /$objtype/lib/ape/libap.a +.TP +.B /sys/include/ape +directory for machine-independent +.B #include +files. +.TP +.B /$objtype/include/ape +directory for machine-dependent +.B #include +files. +.TP +.B /$objtype/lib/ape/libap.a +ANSI C/POSIX library. +.SH "SEE ALSO" +.IR cpp (1), +.IR 2c (1), +.IR 2a (1), +.IR 2l (1), +.IR mk (1), +.IR nm (1), +.IR acid (1), +.IR db (1), +.IR prof (1) +.PP +Howard Trickey, +``APE \(em The ANSI/POSIX Environment'' +.SH SOURCE +.B /sys/src/cmd/pcc.c +.SH BUGS +The locale manipulation functions are minimal. +Signal functions and terminal characteristic +handlers are only minimally implemented. +.IR Link +always fails, because Plan 9 doesn't support multiple links to a file. +The functions related to setting effective user and group ids +cannot be implemented because the concept doesn't exist in Plan 9. diff --git a/static/plan9-4e/man1/pic.1 b/static/plan9-4e/man1/pic.1 new file mode 100644 index 00000000..9737b83b --- /dev/null +++ b/static/plan9-4e/man1/pic.1 @@ -0,0 +1,344 @@ +.TH PIC 1 +.de PS \" start picture +. \" $1 is height, $2 is width, both in inches +.if \\$1>0 .sp .35 +.ie \\$1>0 .nr $1 \\$1 +.el .nr $1 0 +.in (\\n(.lu-\\$2)/2u +.ne \\$1 +.. +.de PE \" end of picture +.in +.if \\n($1>0 .sp .65 +.. +.SH NAME +pic, tpic \- troff and tex preprocessors for drawing pictures +.SH SYNOPSIS +.B pic +[ +.I files +] +.PP +.B tpic +[ +.I files +] +.SH DESCRIPTION +.I Pic +is a +.IR troff (1) +preprocessor for drawing figures on a typesetter. +.I Pic +code is contained between +.B .PS +and +.B .PE +lines: +.IP +.EX +\&.PS \f2optional-width\fP \f2optional-height\fP +\f2element-list\fP +\&.PE +.EE +.LP +or in a file mentioned in a +.B .PS +line: +.IP +.BI .PS " optional-width optional-height " < file +.LP +If +.IR optional-width +is present, the picture is made that many inches wide, +regardless of any dimensions used internally. +The height is scaled in the same proportion unless +.IR optional-height +is present. +If +.B .PF +is used instead of +.BR .PE , +the typesetting position after printing is restored to what it was +upon entry. +.PP +An +.IR element-list +is a list of elements: +.EX + \f2primitive attribute-list\fP + \f2placename\fP : \f2element\fP + \f2placename\fP : \f2position\fP + \f2var\fP = \f2expr\fP + \f2direction\fP + { \f2element-list\fP } + [ \f2element-list\fP ] + for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP } + if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP } + copy \f2file,\fP copy thru \f2macro,\fP copy \f2file\fP thru \fPmacro\fP + sh { \f2commandline\fP } + print \f2expr\fP + reset \f2optional var-list\fP + \f2troff-command\fP +.EE +.PP +Elements are separated by newlines or semicolons; +a long element may be continued by ending the line with a backslash. +Comments are introduced by a +.BI # +and terminated by a newline. +Variable names begin with a lower case letter; +place names begin with upper case. +Place and variable names retain their values +from one picture to the next. +.PP +After each primitive +the current position moves in the current direction +.RB ( up , down , +.BR left , right +(default)) by the size of the primitive. +The current position and direction are saved upon entry +to a +.BR { ... } +block and restored upon exit. +Elements within a block enclosed in +.BR [ ... ] +are treated as a unit; +the dimensions are determined by the extreme points +of the contained objects. +Names, variables, and direction of motion within a block are local to that block. +.PP +.IR Troff-command +is any line that begins with a period. +Such a line is assumed to make sense in the context where it appears; +generally, this means only size and font changes. +.PP +The +.I primitive +objects are: +.br +.EX + box circle ellipse arc line arrow spline move \f2text-list\fP +.EE +.L arrow +is a synonym for +.LR "line ->" . +.PP +An +.IR attribute-list +is a sequence of zero or more attributes; +each attribute consists of a keyword, perhaps followed by a value. +.EX +.ta .5i 2.5i + h(eigh)t \f2expr\fP wid(th) \f2expr\fP + rad(ius) \f2expr\fP diam(eter) \f2expr\fP + up \f2opt-expr\fP down \f2opt-expr\fP + right \f2opt-expr\fP left \f2opt-expr\fP + from \f2position\fP to \f2position\fP + at \f2position\fP with \f2corner\fP + by \f2expr, expr\fP then + dotted \f2opt-expr\fP dashed \f2opt-expr\fP + chop \f2opt-expr\fP -> <- <-> + invis same + fill \f2opt-expr\fP + \f2text-list\fP \f2expr\fP +.EE +Missing attributes and values are filled in from defaults. +Not all attributes make sense for all primitives; +irrelevant ones are silently ignored. +The attribute +.L at +causes the geometrical center to be put at the specified place; +.L with +causes the position on the object to be put at the specified place. +For lines, splines and arcs, +.L height +and +.L width +refer to arrowhead size. +A bare +.I expr +implies motion in the current direction. +.PP +Text is normally an attribute of some primitive; +by default it is placed at the geometrical center of the object. +Stand-alone text is also permitted. +A text list +is a list of text items: +.EX +\f2 text-item\fP: + "..." \f2positioning ...\fP + sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP +\f2 positioning\fP: + center ljust rjust above below +.EE +If there are multiple text items for some primitive, +they are arranged vertically and centered except as qualified. +Positioning requests apply to each item independently. +Text items may contain +.I troff +commands for size and font changes, local motions, etc., +but make sure that these are balanced +so that the entering state is restored before exiting. +.PP +A position is ultimately an +.I x,y +coordinate pair, but it may be specified in other ways. +.EX +\f2 position\fP: + \f2expr, expr\fP + \f2place\fP ± \f2expr, expr\fP + \f2place\fP ± ( \f2expr, expr\fP ) + ( \f2position\fP,\f2 position\fP ) \f2x\fP\fR from one, \f2y\fP\fR the other\fP + \f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP + \f2expr\fP < \f2position\fP , \f2position\fP > + ( \f2position\fP ) +.EE +.PP +.EX +\f2 place\fP: + \f2placename\fP \f2optional-corner\fP + \f2corner\fP of \f2placename\fP + \f2nth\fP \f2primitive\fP \f2optional-corner\fP + \f2corner\fP of \f2nth\fP \f2primitive\fP + Here +.EE +An +.IR optional-corner +is one of the eight compass points +or the center or the start or end of a primitive. +.EX +\f2 optional-corner\fP: + .n .e .w .s .ne .se .nw .sw .c .start .end +\f2 corner\fP: + top bot left right start end +.EE +Each object in a picture has an ordinal number; +.IR nth +refers to this. +.EX +\f2 nth\fP: + \f2n\fPth\f2, n\fPth last +.EE +.PP +The built-in variables and their default values are: +.EX +.ta .5i 2.5i + boxwid 0.75 boxht 0.5 + circlerad 0.25 arcrad 0.25 + ellipsewid 0.75 ellipseht 0.5 + linewid 0.5 lineht 0.5 + movewid 0.5 moveht 0.5 + textwid 0 textht 0 + arrowwid 0.05 arrowht 0.1 + dashwid 0.1 arrowhead 2 + scale 1 +.EE +These may be changed at any time, +and the new values remain in force from picture to picture until changed again +or reset by a +.L reset +statement. +Variables changed within +.B [ +and +.B ] +revert to their previous value upon exit from the block. +Dimensions are divided by +.B scale +during output. +.PP +Expressions in +.I pic +are evaluated in floating point. +All numbers representing dimensions are taken to be in inches. +.EX +\f2 expr\fP: + \f2expr\fP \f2op\fP \f2expr\fP + - \f2expr\fP + ! \f2expr\fP + ( \f2expr\fP ) + variable + number + \f2place\fP .x \f2place\fP .y \f2place\fP .ht \f2place\fP .wid \f2place\fP .rad + sin(\f2expr\fP) cos(\f2expr\fP) atan2(\f2expr,expr\fP) log(\f2expr\fP) exp(\f2expr\fP) + sqrt(\f2expr\fP) max(\f2expr,expr\fP) min(\f2expr,expr\fP) int(\f2expr\fP) rand() +\f2 op\fP: + + - * / % < <= > >= == != && || +.EE +.PP +The +.B define +and +.B undef +statements are not part of the grammar. +.EX + define \f2name\fP { \f2replacement text\fP } + undef \f2name\fP +.EE +Occurrences of +.BR $1 , +.BR $2 , +etc., +in the replacement text +will be replaced by the corresponding arguments if +.I name +is invoked as +.EX + \f2name\fP(\f2arg1\fP, \f2arg2\fP, ...) +.EE +Non-existent arguments are replaced by null strings. +Replacement text +may contain newlines. +The +.B undef +statement removes the definition of a macro. +.PP +.I Tpic +is a +.IR tex (1) +preprocessor that accepts +.IR pic +language. +It produces Tex commands that define a box called +.BR \egraph , +which contains the picture. +The box may be output this way: +.IP +.L +\ecenterline{\ebox\egraph} +.SH EXAMPLES +.EX +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.EE +.PP +.PS +arrow "input" above; box "process"; arrow "output" above +move +A: ellipse + circle rad .1 with .w at A.e + circle rad .05 at 0.5 + circle rad .065 at 0.5 + spline from last circle.nw left .25 then left .05 down .05 + arc from A.c to A.se rad 0.5 + for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 } +.PE +.SH SOURCE +.B /sys/src/cmd/pic +.SH "SEE ALSO" +.IR grap (1), +.IR doctype (1), +.IR troff (1) +.br +B. W. Kernighan, +``PIC\(ema Graphics Language for Typesetting'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 diff --git a/static/plan9-4e/man1/pipefile.1 b/static/plan9-4e/man1/pipefile.1 new file mode 100644 index 00000000..19f207f3 --- /dev/null +++ b/static/plan9-4e/man1/pipefile.1 @@ -0,0 +1,101 @@ +.TH PIPEFILE 1 +.SH NAME +pipefile \- attach filter to file in name space +.SH SYNOPSIS +.B pipefile +[ +.B -d +] [ +.B -r +.I command +] [ +.B -w +.I command +] +.I file +.SH DESCRIPTION +.I Pipefile +uses +.IR bind (2) +to attach a pair of pipes to +.IR file , +using them to +interpose filter +.I commands +between the true file and the simulated file that subsequently +appears in the name space. +Option +.B -r +interposes a filter that will affect the data delivered to programs that read from +.IR file ; +.B -w +interposes a filter that will affect the data written by programs to +.IR file . +At least one +.I command +must be specified; +.I pipefile +will insert a +.IR cat (1) +process in the other direction. +.PP +After +.I pipefile +has been run, the filters are established for programs that subsequently +open the +.IR file ; +programs already using the +.I file +are unaffected. +.PP +.I Pipefile +opens the +.I file +twice, once for each direction. If the +.I file +is a single-use device, such as +.BR /dev/mouse , +use the +.B -d +flag to specify that the file is to be opened once, in +.B ORDWR +mode. +.SH EXAMPLES +Simulate an old terminal: +.EX +.IP +% pipefile -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% echo hello +HELLO +% +.EE +.PP +Really simulate an old terminal: +.EX +.IP +% pipefile -r 'tr A-Z a-z' -w 'tr a-z A-Z' /dev/cons +% rc -i /dev/cons >[2=1] +% DATE +THU OCT 12 10:13:45 EDT 2000 +% +.EE +.SH SOURCE +.B /sys/src/cmd/pipefile.c +.SH SEE ALSO +.IR mouse (8) +.SH BUGS +The I/O model of +.I pipefile +is peculiar; it doesn't work well on plain files. +It is really intended for use with continuous devices such as +.I /dev/cons +and +.IR /dev/mouse . +.I Pipefile +should be rewritten to be a user-level file system. +.PP +If the program using the file managed by +.I pipefile +exits, the filter will see EOF and exit, and the file will be unusable +until the name space is repaired. diff --git a/static/plan9-4e/man1/plot.1 b/static/plan9-4e/man1/plot.1 new file mode 100644 index 00000000..cd1a1b81 --- /dev/null +++ b/static/plan9-4e/man1/plot.1 @@ -0,0 +1,61 @@ +.TH PLOT 1 +.SH NAME +plot \- graphics filter +.SH SYNOPSIS +.B plot +[ +.I file ... +] +.SH DESCRIPTION +.I Plot +interprets plotting instructions (see +.IR plot (6)) +from the +.I files +or standard input, +drawing the results in a newly created +.IR rio (1) +window. +Plot persists until a newline is typed in the window. +Various options may be interspersed with the +.I file +arguments; they take effect at the given point in processing. +Options are: +.TP "\w'\fL-g \fIgrade\fLXX'u" +.B -d +Double buffer: accumulate the plot off-screen and write to the screen all at once +when an erase command is encountered or at end of file. +.TP +.B -e +Erase the screen. +.TP +.BI -c " col" +Set the foreground color (see +.IR plot (6) +for color names). +.TP +.BI -f " fill" +Set the background color. +.TP +.BI -g " grade" +Set the quality factor for arcs. +Higher grades give better quality. +.TP +.BI -p " col" +Set the pen color. +.TP +.BI -w +Pause until a newline is typed on standard input. +.TP +.B -C +Close the current plot. +.TP +.B -W " x0,y0,x1,y1" +Specify the bounding rectangle of plot's window. +By default it uses a 512×512 window in the +middle of the screen. +.SH SOURCE +.B /sys/src/cmd/plot +.SH "SEE ALSO" +.IR rio (1), +.IR plot (6) diff --git a/static/plan9-4e/man1/plumb.1 b/static/plan9-4e/man1/plumb.1 new file mode 100644 index 00000000..6c51d68b --- /dev/null +++ b/static/plan9-4e/man1/plumb.1 @@ -0,0 +1,92 @@ +.TH PLUMB 1 +.SH NAME +plumb \- send message to plumber +.SH SYNOPSIS +.B plumb +[ +.B -p +.I plumbfile +] [ +.B -a +.I attributes +] [ +.B -s +.I source +] [ +.B -d +.I destination +] [ +.B -t +.I type +] [ +.B -w +.I directory +] +.B -i +| +.I data... +.SH DESCRIPTION +The +.I plumb +command formats and sends a plumbing message whose data +is, by default, the concatenation of the argument strings separated by blanks. +The options are: +.TP +.B -p +write the message to +.I plumbfile +(default +.BR /mnt/plumb/send ). +.TP +.B -a +set the +.B attr +field of the message (default is empty). +.TP +.B -s +set the +.B src +field of the message (default is +.BR plumb ). +.TP +.B -d +set the +.B dst +field of the message (default is empty). +.TP +.B -t +set the +.B type +field of the message (default is +.BR text ). +.TP +.B -w +set the +.B wdir +field of the message (default is the current working directory of +.IR plumb ). +.TP +.B -i +take the data from standard input rather than the argument strings. +If an +.B action= +attribute is not otherwise specified, +.I plumb +will add an +.B action=showdata +attribute to the message. +.SH FILES +.TF /usr/$user/lib/plumbing +.TP +.B /usr/$user/lib/plumbing +default rules file +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.SH SOURCE +.B /sys/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (2), +.IR plumber (4), +.IR plumb (6) diff --git a/static/plan9-4e/man1/pr.1 b/static/plan9-4e/man1/pr.1 new file mode 100644 index 00000000..3aaac9f2 --- /dev/null +++ b/static/plan9-4e/man1/pr.1 @@ -0,0 +1,110 @@ +.TH PR 1 +.SH NAME +pr \- print file +.SH SYNOPSIS +.B pr +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Pr +produces a printed listing of one or more +.I files +on its standard output. +The output is separated into pages headed by a date, +the name of the file or a specified header, and the page number. +With no file arguments, +.I pr +prints its standard input. +.PP +Options apply to all following files but may be reset +between files: +.TP +.BI - n +Produce +.IR n -column +output. +.TP +.BI + n +Begin printing with page +.IR n . +.TP +.B -b +Balance columns on last page, in case of multi-column output. +.TP +.B -d +Double space. +.TP +.BI -e n +Set the tab stops for input text every +.I n +spaces. +.TP +.B -h +Take the next argument as a page header +.RI ( file +by default). +.TP +.BI -i n +Replace sequences of blanks in the output +by tabs, using tab stops set every +.I n +spaces. +.TP +.BI -f +Use form feeds to separate pages. +.TP +.BI -l n +Take the length of the page to be +.I n +lines instead of the default 66. +.TP +.B -m +Print all +.I files +simultaneously, +each in one column. +.TP +.BI -n m +Number the lines of each +.IR file . +The numeric argument +.IR m , +default 5, +sets the width of the line-number field. +.TP +.BI -o n +Offset the left margin +.I n +character positions. +.TP +.BI -p +Pad each file printed to an odd number of pages. +For two-sided printers, +this will ensure each file will start a new page. +.TP +.BI -s c +Separate columns by the single character +.I c +instead of aligning them with white space. +A missing +.I c +is taken to be a tab. +.TP +.B -t +Do not print the 5-line header or the +5-line trailer normally supplied for each page. +.TP +.BI -w n +For multi-column output, +take the width of the page to be +.I n +characters instead of the default 72. +.SH SOURCE +.B /sys/src/cmd/pr.c +.SH "SEE ALSO" +.IR cat (1), +.IR lp (1) diff --git a/static/plan9-4e/man1/prof.1 b/static/plan9-4e/man1/prof.1 new file mode 100644 index 00000000..6dedeb21 --- /dev/null +++ b/static/plan9-4e/man1/prof.1 @@ -0,0 +1,132 @@ +.TH PROF 1 +.SH NAME +prof, tprof, kprof \- display profiling data +.SH SYNOPSIS +.B prof +[ +.B -dr +] +[ +.I program +] +[ +.I profile +] +.PP +.B tprof +.I pid +.PP +.B kprof +.I kernel +.I kpdata +.SH DESCRIPTION +.I Prof +interprets files produced automatically by programs loaded using the +.B -p +option of +.IR 2l (1) +or other loader. +The symbol table in the +named program file +.RL ( 2.out +etc., according to +.BR $objtype , +by default) +is read and correlated with the +profile file +.RL ( prof.out +by default). +For each symbol, the percentage +of time (in seconds) spent executing between that symbol +and the next +is printed (in decreasing order), +together with the time spent there and +the number of times that routine was called. +.PP +Under option +.BR -d , +.I prof +prints the dynamic call graph of the target program, +annotating the calls with the time spent in each routine +and those it calls, recursively. The output is indented +two spaces for each call, and is formatted as +.EX + symbol:time/ncall +.EE +where +.I symbol +is the entry point of the call, +.I time +is in milliseconds, +and +.I ncall +is the number of times that entry point was called at that +point in the call graph. If +.I ncall +is one, the +.B /ncall +is elided. +Normally recursive calls are compressed to keep the output brief; +option +.B -r +prints the full call graph. +.PP +The size of the buffer +in +.I program +used to hold the profiling +data, by default 2000 entries, +may be controlled by setting the environment variable +.B profsize +before running +.IR program . +If the buffer fills, subsequent function calls may not be recorded. +.PP +.I Tprof +is similar to +.IR prof , +but is intended for profiling multiprocess programs. +It uses the +.BI /proc/ pid /profile +file to collect instruction frequency counts for the text image associated with the process, +for all processes that share that text. +It must be run while the program is still active, since the data is stored with the running program. +To enable +.I tprof +profiling for a given process, +.EX + echo profile > /proc/\f2pid\f1/ctl +.EE +and then, after the program has run for a while, execute +.EX + tprof \f2pid\f1 +.EE +Since the data collected for +.I tprof +is based on interrupt-time sampling of the program counter, +.I tprof +has no +.B -d +or +.B -r +options. +.PP +.I Kprof +is similar to +.IR prof , +but presents the data accumulated by the kernel +profiling device, +.IR kprof (3) . +The symbol table file, that of the operating system kernel, +and the data file, typically +.BR /dev/kpdata , +must be provided. +.I Kprof +has no options and cannot present dynamic data. +.SH SOURCE +.B /sys/src/cmd/prof.c +.br +.B /sys/src/cmd/kprof.c +.SH SEE ALSO +.IR 2l (1), +.IR kprof (3) diff --git a/static/plan9-4e/man1/proof.1 b/static/plan9-4e/man1/proof.1 new file mode 100644 index 00000000..260ad5ff --- /dev/null +++ b/static/plan9-4e/man1/proof.1 @@ -0,0 +1,134 @@ +.TH PROOF 1 +.SH NAME +proof \- troff output interpreter +.SH SYNOPSIS +.B proof +[ +.BI -m mag +] +[ +.BI -/ nview +] +[ +.B -F +.I dir +] +[ +.B -d +] +[ +.I file +] +.SH DESCRIPTION +.I Proof +reads +.IR troff (1) +intermediate language from +.I file +or standard input +and simulates the resulting pages on the screen. +.PP +After a page of text is displayed, +.I proof +pauses for a command from the keyboard. +The typed commands are: +.TP \w'newline\ \ \ 'u +newline +Go on to next page of text. +.TP +.B - +Go back to the previous page. +.TP +.B q +Quit. +.TP +.BI p n +Print page +.IR n . +An out-of-bounds page number means the end nearer to that number; +a missing number means the current page; +a signed number means an offset to the current page. +.TP +.I n +Same as +.BI p n\f1. +.TP +.B c +Clear the screen, then wait for another command. +.TP +.BI m mag +Change the magnification at which the output is printed. +Normally it is printed with magnification .9; +.IR mag "=.5" +shrinks it to half size; +.IR mag "=2" +doubles the size. +.TP +.BI x val +Move everything +.I val +screen pixels to the right (left, if +.I val +is negative). +.TP +.BI y val +Move everything +.I val +screen pixels down (up, if +.I val +is negative). +.TP +.BI / nview +Split the window into +.I nview +pieces. The current page goes into the rightmost, bottommost piece, +and previous pages are shown in the other pieces. +.TP +.BI "-F " dir +Use +.I dir +for fonts instead of +.BR /lib/font/bit . +.TP +.B d +Toggle the debug flag. +.PD +.PP +These commands are also available, under slightly different form, +from a menu on button 3. The +.B pan +menu item allows arbitrary positioning of the page: +after selecting +.BR pan , +press the mouse button again and hold it down while moving +the page to the desired location. The page will be redisplayed +in its entirety when the button is released. +Mouse button 1 also pans, without the need for selecting from a menu. +.PP +The +.BR m , +.BR x , +.BR y , +.BR F , +.BR / , +and +.B d +commands are also available as command line options. +.SH FILES +.TF /lib/font/bit/MAP +.TP +.B /lib/font/bit/* +fonts +.TP +.B /lib/font/bit/MAP +how to convert troff output fonts and character names +into screen fonts and character numbers +.SH SOURCE +.B /sys/src/cmd/proof +.SH SEE ALSO +.IR lp (1), +.IR gs (1), +.IR page (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' diff --git a/static/plan9-4e/man1/ps.1 b/static/plan9-4e/man1/ps.1 new file mode 100644 index 00000000..f51e09b5 --- /dev/null +++ b/static/plan9-4e/man1/ps.1 @@ -0,0 +1,109 @@ +.TH PS 1 +.SH NAME +ps, psu \- process status +.SH SYNOPSIS +.B ps +[ +.B -pa +] +.PP +.B psu +[ +.B -pa +] +[ +.I user +] +.SH DESCRIPTION +.I Ps +prints information about processes. +.I Psu +prints only information about processes started by +.I user +(default +.BR $user ). +.PP +For each process reported, +the user, +process id, +user time, +system time, +size, +state, +and command name are printed. +State is one of the following: +.TP \w'\fLno\ \fIresource\ \ \ 'u +.B Moribund +Process has exited and is about to have its +resources reclaimed. +.TP +.B Ready +on the queue of processes ready to be run. +.TP +.B Scheding +about to be run. +.TP +.B Running +running. +.TP +.B Queueing +waiting on a queue for a resource. +.TP +.B Wakeme +waiting for I/O or some other kernel event to wake it up. +.TP +.B Broken +dead of unnatural causes; lingering +so that it can be examined. +.TP +.B Stopped +stopped. +.TP +.B Stopwait +waiting for another process to stop. +.TP +.B Fault +servicing a page fault. +.TP +.B Idle +waiting for something to do (kernel processes only). +.TP +.B New +being created. +.TP +.B Pageout +paging out some other process. +.TP +.I Syscall +performing the named system call. +.TP +.BI no " resource +waiting for more of a critical +.IR resource . +.PD +.PP +With the +.B -p +flag, +.I ps +also prints, after the system time, the baseline and current priorities of each process. +.PP +The +.B -a +flag causes +.I ps +to print the arguments for the process. Newlines in arguments will be translated to spaces for display. +.SH FILES +.TF /proc/*/status +.TP +.B /proc/*/status +.SH SOURCE +.B /sys/src/cmd/ps.c +.br +.B /rc/bin/psu +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR kill (1), +.IR ns (1), +.IR proc (3) diff --git a/static/plan9-4e/man1/pwd.1 b/static/plan9-4e/man1/pwd.1 new file mode 100644 index 00000000..78fedb19 --- /dev/null +++ b/static/plan9-4e/man1/pwd.1 @@ -0,0 +1,46 @@ +.TH PWD 1 +.SH NAME +pwd, pbd \- working directory +.SH SYNOPSIS +.B pwd +.br +.B pbd +.SH DESCRIPTION +.I Pwd +prints the path name of the working (current) directory. +.I Pwd +is guaranteed to return the same path that was used to +enter the directory. +If, however, the name space has changed, or directory names +have been changed, this path name may no longer be valid. +(See +.IR fd2path (2) +for a description of +.BR pwd 's +mechanism.) +.PP +.I Pbd +prints the base name of the working (current) directory. +It prints no final newline and is intended for applications +such as constructing shell prompts. +Since it uses +.IR stat (2) +to discover the name of +.B \&. +(dot), +if the directory has been bound to another name, it will show +the underlying name rather than that reported by +.IR pwd . +.SH SOURCE +.B /sys/src/cmd/pwd.c +.br +.B /sys/src/cmd/pbd.c +.SH SEE ALSO +.I cd +in +.IR rc (1), +.IR bind (1), +.IR intro (2), +.IR getwd (2), +.IR fd2path (2) + diff --git a/static/plan9-4e/man1/rc.1 b/static/plan9-4e/man1/rc.1 new file mode 100644 index 00000000..b296a48a --- /dev/null +++ b/static/plan9-4e/man1/rc.1 @@ -0,0 +1,959 @@ +.TH RC 1 +.SH NAME +rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language +.SH SYNOPSIS +.B rc +[ +.B -srdiIlxepvV +] +[ +.B -c command +] +[ +.I file +[ +.I arg ... +]] +.SH DESCRIPTION +.I Rc +is the Plan 9 shell. +It executes command lines read from a terminal or a file or, with the +.B -c +flag, from +.I rc's +argument list. +.SS Command Lines +A command line is a sequence of commands, separated by ampersands or semicolons +.RB ( & +or +.BR ; ), +terminated by a newline. +The commands are executed in sequence +from left to right. +.I Rc +does not wait for a command followed by +.B & +to finish executing before starting +the following command. +Whenever a command followed by +.B & +is executed, its process id is assigned to the +.I rc +variable +.BR $apid . +Whenever a command +.I not +followed by +.B & +exits or is terminated, the +.I rc +variable +.B $status +gets the process's wait message (see +.IR wait (2)); +it will be the null string if the command was successful. +.PP +A long command line may be continued on subsequent lines by typing +a backslash +.RB ( \e ) +followed by a newline. +This sequence is treated as though it were a blank. +Backslash is not otherwise a special character. +.PP +A number-sign +.RB ( # ) +and any following characters up to (but not including) the next newline +are ignored, except in quotation marks. +.SS Simple Commands +A simple command is a sequence of arguments interspersed with I/O redirections. +If the first argument is the name of an +.I rc +function or of one of +.I rc's +built-in commands, it is executed by +.IR rc . +Otherwise if the name starts with a slash +.RB ( / ), +it must be the path name of the program to be executed. +Names containing no initial slash are searched for in +a list of directory names stored in +.BR $path . +The first executable file of the given name found +in a directory in +.B $path +is the program to be executed. +To be executable, the user must have execute permission (see +.IR stat (2)) +and the file must be either an executable binary +for the current machine's CPU type, or a shell script. +Shell scripts begin with a line containing the full path name of a shell +(usually +.BR /bin/rc ), +prefixed by +.LR #! . +.PP +The first word of a simple command cannot be a keyword unless it is +quoted or otherwise disguised. +The keywords are +.EX + for in while if not switch fn ~ ! @ +.EE +.SS Arguments and Variables +A number of constructions may be used where +.I rc's +syntax requires an argument to appear. +In many cases a construction's +value will be a list of arguments rather than a single string. +.PP +The simplest kind of argument is the unquoted word: +a sequence of one or more characters none of which is a blank, tab, +newline, or any of the following: +.EX + # ; & | ^ $ = ` ' { } ( ) < > +.EE +An unquoted word that contains any of the characters +.B * +.B ? +.B [ +is a pattern for matching against file names. +The character +.B * +matches any sequence of characters, +.B ? +matches any single character, and +.BI [ class ] +matches any character in the +.IR class . +If the first character of +.I class +is +.BR ~ , +the class is complemented. +The +.I class +may also contain pairs of characters separated by +.BR - , +standing for all characters lexically between the two. +The character +.B / +must appear explicitly in a pattern, as must the +first character of the path name components +.B . +and +.BR .. . +A pattern is replaced by a list of arguments, one for each path name matched, +except that a pattern matching no names is not replaced by the empty list, +but rather stands for itself. +Pattern matching is done after all other +operations. +Thus, +.EX + x=/tmp echo $x^/*.c +.EE +matches +.BR /tmp/*.c , +rather than matching +.B "/*.c +and then prefixing +.BR /tmp . +.PP +A quoted word is a sequence of characters surrounded by single quotes +.RB ( ' ). +A single quote is represented in a quoted word by a pair of quotes +.RB ( '' ). +.PP +Each of the following is an argument. +.PD 0 +.HP +.BI ( arguments ) +.br +The value of a sequence of arguments enclosed in parentheses is +a list comprising the members of each element of the sequence. +Argument lists have no recursive structure, although their syntax may +suggest it. +The following are entirely equivalent: +.EX + echo hi there everybody + ((echo) (hi there) everybody) +.EE +.HP +.BI $ argument +.HP +.BI $ argument ( subscript ) +.br +The +.I argument +after the +.B $ +is the name of a variable whose value is substituted. +Multiple levels +of indirection are possible, but of questionable utility. +Variable values +are lists of strings. +If +.I argument +is a number +.IR n , +the value is the +.IR n th +element of +.BR $* , +unless +.B $* +doesn't have +.I n +elements, in which case the value is empty. +If +.I argument +is followed by a parenthesized list of subscripts, the +value substituted is a list composed of the requested elements (origin 1). +The parenthesis must follow the variable name with no spaces. +Assignments to variables are described below. +.HP +.BI $# argument +.br +The value is the number of elements in the named variable. +A variable +never assigned a value has zero elements. +.HP +$"\c +.I argument +.br +The value is a single string containing the components of the named variable +separated by spaces. A variable with zero elements yields the empty string. +.HP +.BI `{ command } +.br +.I rc +executes the +.I command +and reads its standard output, splitting it into a list of arguments, +using characters in +.B $ifs +as separators. +If +.B $ifs +is not otherwise set, its value is +.BR "'\ \et\en'" . +.HP +.BI <{ command } +.HP +.BI >{ command } +.br +The +.I command +is executed asynchronously with its standard output or standard input +connected to a pipe. +The value of the argument is the name of a file +referring to the other end of the pipe. +This allows the construction of +non-linear pipelines. +For example, the following runs two commands +.B old +and +.B new +and uses +.B cmp +to compare their outputs +.EX + cmp <{old} <{new} +.EE +.HP +.IB argument ^ argument +.br +The +.B ^ +operator concatenates its two operands. +If the two operands +have the same number of components, they are concatenated pairwise. +If not, +then one operand must have one component, and the other must be non-empty, +and concatenation is distributive. +.PD +.SS Free Carets +In most circumstances, +.I rc +will insert the +.B ^ +operator automatically between words that are not separated by white space. +Whenever one of +.B $ +.B ' +.B ` +follows a quoted or unquoted word or an unquoted word follows a quoted word +with no intervening blanks or tabs, +a +.B ^ +is inserted between the two. +If an unquoted word immediately follows a +.BR $ +and contains a character other than an alphanumeric, underscore, +or +.BR * , +a +.B ^ +is inserted before the first such character. +Thus +.IP +.B cc -$flags $stem.c +.LP +is equivalent to +.IP +.B cc -^$flags $stem^.c +.SS I/O Redirections +The sequence +.BI > file +redirects the standard output file (file descriptor 1, normally the +terminal) to the named +.IR file ; +.BI >> file +appends standard output to the file. +The standard input file (file descriptor 0, also normally the terminal) +may be redirected from a file by the sequence +.BI < file \f1, +or from an inline `here document' +by the sequence +.BI << eof-marker\f1. +The contents of a here document are lines of text taken from the command +input stream up to a line containing nothing but the +.IR eof-marker , +which may be either a quoted or unquoted word. +If +.I eof-marker +is unquoted, variable names of the form +.BI $ word +have their values substituted from +.I rc's +environment. +If +.BI $ word +is followed by a caret +.RB ( ^ ), +the caret is deleted. +If +.I eof-marker +is quoted, no substitution occurs. +.PP +Redirections may be applied to a file-descriptor other than standard input +or output by qualifying the redirection operator +with a number in square brackets. +For example, the diagnostic output (file descriptor 2) +may be redirected by writing +.BR "cc junk.c >[2]junk" . +.PP +A file descriptor may be redirected to an already open descriptor by writing +.BI >[ fd0 = fd1 ] +or +.BI <[ fd0 = fd1 ]\f1. +.I Fd1 +is a previously opened file descriptor and +.I fd0 +becomes a new copy (in the sense of +.IR dup (2)) +of it. +A file descriptor may be closed by writing +.BI >[ fd0 =] +or +.BI <[ fd0 =]\f1. +.PP +Redirections are executed from left to right. +Therefore, +.B cc junk.c >/dev/null >[2=1] +and +.B cc junk.c >[2=1] >/dev/null +have different effects: the first puts standard output in +.BR /dev/null +and then puts diagnostic output in the same place, where the second +directs diagnostic output to the terminal and sends standard output to +.BR /dev/null . +.SS Compound Commands +A pair of commands separated by a pipe operator +.RB ( | ) +is a command. +The standard output of the left command is sent through a pipe +to the standard input of the right command. +The pipe operator may be decorated +to use different file descriptors. +.BI |[ fd ] +connects the output end of the pipe to file descriptor +.I fd +rather than 1. +.BI |[ fd0 = fd1 ] +connects output to +.I fd1 +of the left command and input to +.I fd0 +of the right command. +.PP +A pair of commands separated by +.B && +or +.B || +is a command. +In either case, the left command is executed and its exit status examined. +If the operator is +.B && +the right command is executed if the left command's status is null. +.B || +causes the right command to be executed if the left command's status is non-null. +.PP +The exit status of a command may be inverted (non-null is changed to null, null +is changed to non-null) by preceding it with a +.BR ! . +.PP +The +.B | +operator has highest precedence, and is left-associative (i.e. binds tighter +to the left than the right). +.B ! +has intermediate precedence, and +.B && +and +.B || +have the lowest precedence. +.PP +The unary +.B @ +operator, with precedence equal to +.BR ! , +causes its operand to be executed in a subshell. +.PP +Each of the following is a command. +.PD 0 +.HP +.B if ( +.I list +.B ) +.I command +.br +A +.I list +is a sequence of commands, separated by +.BR & , +.BR ; , +or newline. +It is executed and +if its exit status is null, the +.I command +is executed. +.HP +.B if not +.I command +.br +The immediately preceding command must have been +.BI if( list ) +.IR command . +If its condition was non-zero, the +.I command +is executed. +.HP +.BI for( name +.B in +.IB arguments ) +.I command +.HP +.BI for( name ) +.I command +.br +The +.I command +is executed once for each +.IR argument +with that argument assigned to +.IR name . +If the argument list is omitted, +.B $* +is used. +.HP +.BI while( list ) +.I command +.br +The +.I list +is executed repeatedly until its exit status is non-null. +Each time it returns null status, the +.I command +is executed. +An empty +.I list +is taken to give null status. +.HP +.BI "switch(" argument "){" list } +.br +The +.IR list +is searched for simple commands beginning with the word +.BR case . +(The search is only at the `top level' of the +.IR list . +That is, +.B cases +in nested constructs are not found.) +.I Argument +is matched against each word following +.B case +using the pattern-matching algorithm described above, except that +.B / +and the first characters of +.B . +and +.B .. +need not be matched explicitly. +When a match is found, commands in the list are executed up to the next +following +.B case +command (at the top level) or the closing brace. +.HP +.BI { list } +.br +Braces serve to alter the grouping of commands implied by operator +priorities. +The +.I body +is a sequence of commands separated by +.BR & , +.BR ; , +or newline. +.HP +.BI "fn " name { list } +.HP +.BI "fn " name +.br +The first form defines a function with the given +.IR name . +Subsequently, whenever a command whose first argument is +.I name +is encountered, the current value of +the remainder of the command's argument list will be assigned to +.BR $* , +after saving its current value, and +.I rc +will execute the +.IR list . +The second form removes +.IR name 's +function definition. +.HP +.BI "fn " note { list } +.br +.HP +.BI "fn " note +.br +A function with a special name will be called when +.I rc +receives a corresponding note; see +.IR notify (2). +The valid note names (and corresponding notes) are +.B sighup +.RB ( hangup ), +.B sigint +.RB ( interrupt ), +.BR sigalrm +.RB ( alarm ), +and +.B sigfpe +(floating point trap). +By default +.I rc +exits on receiving any signal, except when run interactively, +in which case interrupts and quits normally cause +.I rc +to stop whatever it's doing and start reading a new command. +The second form causes +.I rc +to handle a signal in the default manner. +.I Rc +recognizes an artificial note, +.BR sigexit , +which occurs when +.I rc +is about to finish executing. +.HP +.IB name = "argument command" +.br +Any command may be preceded by a sequence of assignments +interspersed with redirections. +The assignments remain in effect until the end of the command, unless +the command is empty (i.e. the assignments stand alone), in which case +they are effective until rescinded by later assignments. +.PD +.SS Built-in Commands +These commands are executed internally by +.IR rc , +usually because their execution changes or depends on +.IR rc 's +internal state. +.PD 0 +.HP +.BI . " file ..." +.br +Execute commands from +.IR file . +.B $* +is set for the duration to the remainder of the argument list following +.IR file . +.I File +is searched for using +.BR $path . +.HP +.BI builtin " command ..." +.br +Execute +.I command +as usual except that any function named +.I command +is ignored in favor of the built-in meaning. +.HP +.BI "cd [" dir "]" +.br +Change the current directory to +.IR dir . +The default argument is +.BR $home . +.I dir +is searched for in each of the directories mentioned in +.BR $cdpath . +.HP +.BI "eval [" "arg ..." "]" +.br +The arguments are concatenated separated by spaces into a single string, +read as input to +.IR rc , +and executed. +.HP +.BI "exec [" "command ..." "]" +.br +This instance of +.I rc +replaces itself with the given (non-built-in) +.IR command . +.HP +.BI "flag " f " [+-]" +.br +Either set +.RB ( + ), +clear +.RB ( - ), +or test (neither +.B + +nor +.BR - ) +the flag +.IR f , +where +.I f +is a single character, one of the command line flags (see Invocation, below). +.HP +.BI "exit [" status "]" +.br +Exit with the given exit status. +If none is given, the current value of +.B $status +is used. +.HP +.BR "rfork " [ nNeEsfFm ] +.br +Become a new process group using +.BI rfork( flags ) +where +.I flags +is composed of the bitwise OR of the +.B rfork +flags specified by the option letters +(see +.IR fork (2)). +If no +.I flags +are given, they default to +.BR ens . +The +.I flags +and their meanings are: +.B n +is +.BR RFNAMEG ; +.B N +is +.BR RFCNAMEG ; +.B e +is +.BR RFENVG ; +.B E +is +.BR RFCENVG ; +.B s +is +.BR RFNOTEG ; +.B f +is +.BR RFFDG ; +.B F +is +.BR RFCFDG ; +and +.B m +is +.BR RFNOMNT . +.HP +.BI "shift [" n "]" +.br +Delete the first +.IR n +(default 1) +elements of +.BR $* . +.HP +.BI "wait [" pid "]" +.br +Wait for the process with the given +.I pid +to exit. +If no +.I pid +is given, all outstanding processes are waited for. +.HP +.BI whatis " name ..." +.br +Print the value of each +.I name +in a form suitable for input to +.IR rc . +The output is +an assignment to any variable, +the definition of any function, +a call to +.B builtin +for any built-in command, or +the completed pathname of any executable file. +.HP +.BI ~ " subject pattern ..." +.br +The +.I subject +is matched against each +.I pattern +in sequence. +If it matches any pattern, +.B $status +is set to zero. +Otherwise, +.B $status +is set to one. +Patterns are the same as for file name matching, except that +.B / +and the first character of +.B . +and +.B .. +need not be matched explicitly. +The +.I patterns +are not subjected to +file name matching before the +.B ~ +command is executed, so they need not be enclosed in quotation marks. +.PD +.SS Environment +The +.I environment +is a list of strings made available to executing binaries by the +.B env +device +(see +.IR env (3)). +.I Rc +creates an environment entry for each variable whose value is non-empty, +and for each function. +The string for a variable entry has the variable's name followed by +.B = +and its value. +If the value has more than one component, these +are separated by ctrl-a +.RB ( '\e001' ) +characters. +The string for a function is just the +.I rc +input that defines the function. +The name of a function in the environment is the function name +preceded by +.LR fn# . +.PP +When +.I rc +starts executing it reads variable and function definitions from its +environment. +.SS Special Variables +The following variables are set or used by +.IR rc . +.PD 0 +.TP \w'\fL$promptXX'u +.B $* +Set to +.IR rc 's +argument list during initialization. +Whenever a +.B . +command or a function is executed, the current value is saved and +.B $* +receives the new argument list. +The saved value is restored on completion of the +.B . +or function. +.TP +.B $apid +Whenever a process is started asynchronously with +.BR & , +.B $apid +is set to its process id. +.TP +.B $home +The default directory for +.BR cd . +.TP +.B $ifs +The input field separators used in backquote substitutions. +If +.B $ifs +is not set in +.IR rc 's +environment, it is initialized to blank, tab and newline. +.TP +.B $path +The search path used to find commands and input files +for the +.B . +command. +If not set in the environment, it is initialized by +.BR "path=(.\ /bin)" . +Its use is discouraged; instead use +.IR bind (1) +to build a +.B /bin +containing what's needed. +.TP +.B $pid +Set during initialization to +.IR rc 's +process id. +.TP +.B $prompt +When +.I rc +is run interactively, the first component of +.B $prompt +is printed before reading each command. +The second component is printed whenever a newline is typed and more lines +are required to complete the command. +If not set in the environment, it is initialized by +.BR "prompt=('%\ '\ '\ ')" . +.TP +.B $status +Set to the wait message of the last-executed program. +(unless started with +.BR &). +.B ! +and +.B ~ +also change +.BR $status . +Its value is used to control execution in +.BR && , +.BR || , +.B if +and +.B while +commands. +When +.I rc +exits at end-of-file of its input or on executing an +.B exit +command with no argument, +.B $status +is its exit status. +.PD +.SS Invocation +If +.I rc +is started with no arguments it reads commands from standard input. +Otherwise its first non-flag argument is the name of a file from which +to read commands (but see +.B -c +below). +Subsequent arguments become the initial value of +.BR $* . +.I Rc +accepts the following command-line flags. +.PD 0 +.TP \w'\fL-c\ \fIstring\fLXX'u +.BI -c " string" +Commands are read from +.IR string . +.TP +.B -s +Print out exit status after any command where the status is non-null. +.TP +.B -e +Exit if +.B $status +is non-null after executing a simple command. +.TP +.B -i +If +.B -i +is present, or +.I rc +is given no arguments and its standard input is a terminal, +it runs interactively. +Commands are prompted for using +.BR $prompt . +.TP +.B -I +Makes sure +.I rc +is not run interactively. +.TP +.B -l +If +.B -l +is given or the first character of argument zero is +.BR - , +.I rc +reads commands from +.BR $home/lib/profile , +if it exists, before reading its normal input. +.TP +.B -p +A no-op. +.TP +.B -d +A no-op. +.TP +.B -v +Echo input on file descriptor 2 as it is read. +.TP +.B -x +Print each simple command before executing it. +.TP +.B -r +Print debugging information (internal form of commands +as they are executed). +.PD +.SH SOURCE +.B /sys/src/cmd/rc +.SH "SEE ALSO" +Tom Duff, +``Rc \- The Plan 9 Shell''. +.SH BUGS +There should be a way to match patterns against whole lists rather than +just single strings. +.br +Using +.B ~ +to check the value of +.B $status +changes +.BR $status . +.br +Functions that use here documents don't work. +.br +Free carets don't get inserted next to keywords. diff --git a/static/plan9-4e/man1/replica.1 b/static/plan9-4e/man1/replica.1 new file mode 100644 index 00000000..0279cc14 --- /dev/null +++ b/static/plan9-4e/man1/replica.1 @@ -0,0 +1,304 @@ +.TH REPLICA 1 +.SH NAME +changes, pull, push, scan \- client-server replica management +.SH SYNOPSIS +.B replica/pull +[ +.B -cnsv +] +.I name +[ +.I path +... +] +.br +.B replica/push +[ +.B -nv +] +.I name +[ +.I path +... +] +.br +.B replica/changes +.I name +[ +.I path +... +] +.br +.B replica/scan +.I name +[ +.I path +... +] +.SH DESCRIPTION +These shell scripts provide a simple log-based client-server replica management. +The server keeps a log of changes made to its file system, +and clients synchronize by reading the log and applying these changes locally. +.PP +These scripts are a polished interface to the low-level tools described in +.IR replica (8). +See +.IR replica (8) +for details on the inner workings of replica management. +These tools were written primarily as the fourth +edition Plan 9 distribution mechanism, but they +have wider applicability. +For example, they could be used to synchronize one's +home directory between a laptop and a central file server. +.PP +Replicas are described by configuration files. +The +.I name +in all the replica commands is a configuration +file. Paths that do not begin with +.BR / , +.BR ./ , +or +.B ../ +are assumed to be relative to +.BR $home/lib/replica . +Configuration files are described below. +.PP +.I Replica/scan +is the only one of these programs that does not +need to be run on the client. +It scans the server file system for changes +and appends entries for those changes into the server log. +Typically it is run on a machine with a fast network +connection to the server file system. +.PP +.I Replica/pull +copies changes from the server to the client, +while +.I replica/push +copies changes from the client to the server. +(Both run on the client.) +If a list of +.I paths +is given, only changes to those paths or their children are copied. +The +.B -v +flag causes +.I pull +or +.I push +to print a summary of what it is doing. +Each status line is of the form +.sp 0.5 +\h'0.25i' +.I verb +.I path +.I serverpath +.I mode +.I uid +.I gid +.I mtime +.I length +.sp 0.5 +.I Verb +describes the event: +addition of a file +.RB ( a ), +deletion of a file +.RB ( d ), +a change to a file's contents +.RB ( c ), +or a change to a file's metadata +.RB ( m ). +.I Path +is the file path on the client; +.I serverpath +is the file path on the server. +.IR Mode , +.IR uid , +.IR gid , +and +.I mtime +are the file's metadata as in the +.B Dir +structure (see +.IR stat (5)). +For deletion events, the metadata is that of the deleted file. +For other events, the metadata is that after the event. +The +.B -n +flag causes +.I pull +or +.I push +to print the summary but not actually carry out the actions. +.PP +.I Push +and +.I pull +are careful to notice simultaneous changes to a file or +its metadata on both client and server. +Such simultaneous changes are called +.IR conflicts . +Here, simultaneous does not mean at the same instant +but merely that both changes were carried out without knowledge +of the other. +For example, if a client and server both make changes to a file +without an intervening +.I push +or +.IR pull , +the next +.I push +or +.I pull +will report an update/update conflict. +If a conflict is detected, both files are left the same. +The +.B -c +flag to +.I pull +causes updates to be resolved using the client's copy, +while +.B -s +specifies the server's copy. +Typically these flags are only used when +invoking +.I pull +with a specific list of files that are known +to be conflicting. +.PP +.I Replica/changes +prints a list of local changes made on the client +that have not yet been pushed to the server. +It is like +.I push +with the +.B -n +flag, except that it does not check for conflicts +and thus does not require the server to be available. +.PP +The replica configuration file is an +.IR rc (1) +script that must define the following functions and variables: +.TP +.B servermount +A function that mounts the server; run on both client and server. +.TP +.B serverupdate +A function that rescans the server for changes. +Typically this command dials a CPU server known +to be close to the file server and runs +.I replica/scan +on that well-connected machine. +.TP +.B serverroot +The path to the root of the replicated file +system on the server, as it will be in the name space +after running +.BR servermount . +.TP +.B serverlog +The path to the server's change log, after running +.BR servermount . +.TP +.B serverproto +The path to the proto file describing the server's files, +after running +.BR servermount . +Only used by +.IR scan . +.TP +.B serverdb +The path to the server's file database, after running +.BR servermount . +Only used by +.IR scan . +.TP +.B clientmount +A function to mount the client file system; run only on the client. +.TP +.B clientroot +The path to the root of the replicated file system on the client, +after running +.BR clientmount . +.TP +.B clientlog +The path to the client's copy of the server log file. +The client log is maintained by +.IR pull . +.TP +.B clientproto +The path to the proto file describing the client's files. +Only used by +.IR changes . +Often just a copy of +.BR $serverproto . +.TP +.B clientdb +The path to the client's file database, after running +.BR clientmount . +.TP +.B clientexclude +A (potentially empty) list of paths to exclude from +synchronization. A typical use of this is to exclude +the client database and log files. +These paths are relative to the root of the replicated file system. +.PD +.PP +As an example, the Plan 9 distribution replica configuration looks like: +.EX + fn servermount { 9fs outside; bind /n/outside/plan9 /n/dist } + fn serverupdate { status='' } + serverroot=/n/dist + s=/n/dist/dist/replica + serverlog=$s/plan9.log + serverproto=$s/plan9.proto + + fn clientmount { 9fs kfs } + clientroot=/n/kfs + c=/n/kfs/dist/replica + clientlog=$c/client/plan9.log + clientproto=$c/plan9.proto + clientdb=$c/client/plan9.db + clientexclude=(dist/replica/client) +.EE +.PP +(Since the Plan 9 developers run +.I scan +manually to update the log, the clients need not do anything +to rescan the file system. +Thus +.B serverupdate +simply returns successfully.) +.PP +The fourth edition Plan 9 distribution uses these +tools to synchronize installations with the central +server at Bell Labs. +The replica configuration files and metadata are kept +in +.BR /dist/replica . +To update your system, make sure you are connected +to the internet and run +.EX + disk/kfscmd allow + replica/pull /dist/replica/network + disk/kfscmd disallow +.EE +(We have not yet set up the outside file server at Bell Labs +to make this work; once we do, we will announce instructions +on the Plan 9 web page and in the Usenet group +.BR comp.os.plan9 ). +.PP +To see a list of changes made to the local file system +since installation, run +.EX + replica/changes /dist/replica/network +.EE +(Although the script is called +.IR network , +since +.I changes +is a local-only operation, the network need not be configured.) +.SH SEE ALSO +.IR replica (8) diff --git a/static/plan9-4e/man1/resample.1 b/static/plan9-4e/man1/resample.1 new file mode 100644 index 00000000..35968d05 --- /dev/null +++ b/static/plan9-4e/man1/resample.1 @@ -0,0 +1,58 @@ +.TH RESAMPLE 1 +.SH NAME +resample \- resample a picture +.SH SYNOPSIS +.B resample +[ +.B -x +.I size +] [ +.B -y +.I size +] [ +.I file +] +.SH DESCRIPTION +.I Resample +resamples its input image (default standard input) to a new size. +The image is decimated or interpolated using +a Kaiser window. +.PP +The size of the resampled image can be specified +with the +.B -x +and +.B -y +options. +An unadorned value sets the number of pixels of that dimension; a suffixed percent sign specifies a percentage. +If only one of +.B -x +or +.B -y +is given, the other dimension is scaled to preserve +the aspect ratio of the original image. +Thus, +.B -x50% +will reduce the image to half its original dimension in both +.B x +and +.BR y . +.PP +The input should be a Plan 9 image +as described in +.IR image (6), +and the output will be a compressed 24-bit +.B r8g8b8 +image. +To uncompress the image or change the pixel format, use +.I iconv +(see +.IR crop (1)). +.PP +.SH SOURCE +.B /sys/src/cmd/resample.c +.SH "SEE ALSO +.IR crop (1), +.IR image (6) +.SH BUGS +Faster algorithms exist, but this implementation produces correct pictures. diff --git a/static/plan9-4e/man1/rio.1 b/static/plan9-4e/man1/rio.1 new file mode 100644 index 00000000..6438c29f --- /dev/null +++ b/static/plan9-4e/man1/rio.1 @@ -0,0 +1,513 @@ +.TH RIO 1 +.SH NAME +rio, label, window, wloc \- window system +.SH SYNOPSIS +.B rio +[ +.BI "-i '"cmd ' +] +[ +.BI "-k '"kbdcmd ' +] +[ +.B -s +] +[ +.B -f +.I font +] +.PP +.B label +.I name +.PP +.B window +[ +.B -m +] [ +.B -r +.I minx miny maxx maxy +] [ +.B -dx +.I n +] [ +.B -dy +.I n +] [ +.B -minx +.I n +] [ +.B -miny +.I n +] [ +.B -maxx +.I n +] [ +.B -maxy +.I n +] [ +.B -cd +.I dir +] [ +.B -hide +] [ +.I cmd +.I arg ... +] +.PP +.B wloc +.SH DESCRIPTION +.I Rio +manages asynchronous layers of text, or windows, on a raster display. +It also serves a variety of files for communicating with +and controlling windows; these are discussed in section +.IR rio (4). +.SS Commands +The +.I rio +command starts a new instance of the window system. +Its +.B -i +option names a startup script, which typically contains several +.I window +commands generated by +.IR wloc . +The +.B -k +option causes +.I rio +to run the command +.I kbdcmd +at startup and allow it to provide characters as keyboard input; the +.B keyboard +program described in +.IR bitsyload (1) +is the usual choice. +.PP +The +.B -s +option initializes windows so that text scrolls; +the default is not to scroll. +The +.I font +argument names a font used to display text, both in +.IR rio 's +menus +and as a default for any programs running in its windows; it also +establishes the +environment variable +.BR $font . +If +.B -f +is not given, +.I rio +uses the imported value of +.BR $font +if set; otherwise it imports the default font from the underlying graphics +server, usually the terminal's operating system. +.PP +The +.I label +command changes a window's identifying name. +.PP +The +.I window +command creates a window. +By default, it creates a shell window and sizes and places it automatically. +The geometry arguments control the size +.IB ( dx , +.BR dy ) +and placement +.RB ( minx , +.BR miny , +.BR maxx , +.BR maxy ; +.BR hide +causes the window to be created off-screen); and working directory +.RB ( cd ). +the units are pixels with the +upper left corner of the screen at (0, 0). +The optional command and arguments define which program to run in the window. +.PP +By default, +.I window +uses +.B /dev/wctl +(see +.IR rio (4)) +to create the window and run the command. Therefore, the window and command +will be created by +.I rio +and run in a new file name space, just as if the window had been created using the interactive menu. +However, the +.B -m +option uses the file server properties of +.I rio +to +.B mount +(see +.IR bind (1)) +the new window's name space within the name space of the program calling +.IR window . +This means, for example, that running +.B window +in a CPU window will create another window whose command runs on the terminal, where +.I rio +is running; while +.B window +.B -m +will create another window whose command runs on the CPU server. +.PP +The +.I wloc +command prints the coordinates and label of each window in its instance of +.I rio +and is used to construct arguments for +.IR window . +.SS Window control +Each window behaves as a separate terminal with at least one process +associated with it. +When a window is created, a new process (usually a shell; see +.IR rc (1)) +is established and bound to the window as a new process group. +Initially, each window acts as a simple terminal that displays character text; +the standard input and output of its processes +are attached to +.BR /dev/cons . +Other special files, accessible to the processes running in a window, +may be used to make the window a more general display. +Some of these are mentioned here; the complete set is +discussed in +.IR rio (4). +.PP +One window is +.IR current , +and is indicated with a dark border and text; +characters typed on the keyboard are available in the +.B /dev/cons +file of the process in the current window. +Characters written on +.B /dev/cons +appear asynchronously in the associated window whether or not the window +is current. +.PP +Windows are created, deleted and rearranged using the mouse. +Clicking (pressing and releasing) mouse button 1 in a non-current +window makes that window current and brings it in front of +any windows that happen to be overlapping it. +When the mouse cursor points to the background area or is in +a window that has not claimed the mouse for its own use, +pressing mouse button 3 activates a +menu of window operations provided by +.IR rio . +Releasing button 3 then selects an operation. +At this point, a gunsight or cross cursor indicates that +an operation is pending. +The button 3 menu operations are: +.TF Resize +.TP +.B New +Create a window. +Press button 3 where one corner of the new rectangle should +appear (cross cursor), and move the mouse, while holding down button 3, to the +diagonally opposite corner. +Releasing button 3 creates the window, and makes it current. +Very small windows may not be created. +.TP +.B Resize +Change the size and location of a window. +First click button 3 in the window to be changed +(gunsight cursor). +Then sweep out a window as for the +.B New +operation. +The window is made current. +.TP +.B Move +Move a window to another location. +After pressing and holding button 3 over the window to be moved (gunsight cursor), +indicate the new position by dragging the rectangle to the new location. +The window is made current. +Windows may be moved partially off-screen. +.TP +.B Delete +Delete a window. Click in the window to be deleted (gunsight cursor). +Deleting a window causes a +.L hangup +note to be sent to all processes in the window's process group +(see +.IR notify (2)). +.TP +.B Hide +Hide a window. Click in the window to be hidden (gunsight cursor); +it will be moved off-screen. +Each hidden window is given a menu entry in the button 3 menu according to the +value of the file +.BR /dev/label , +which +.I rio +maintains +(see +.IR rio (4)). +.TP +.I label +Restore a hidden window. +.PD +.PP +Windows may also be arranged by dragging their borders. +Pressing button 1 or 2 over a window's border allows one to +move the corresponding edge or corner, while button 3 +moves the whole window. +.PD +.SS Text windows +Characters typed on the keyboard or written to +.B /dev/cons +collect in the window to form +a long, continuous document. +.PP +There is always some +.I selected +.IR text , +a contiguous string marked on the screen by reversing its color. +If the selected text is a null string, it is indicated by a hairline cursor +between two characters. +The selected text +may be edited by mousing and typing. +Text is selected by pointing and clicking button 1 +to make a null-string selection, or by pointing, +then sweeping with button 1 pressed. +Text may also be selected by double-clicking: +just inside a matched delimiter-pair +with one of +.B {[(<«`'" +on the left and +.B }])>»`'" +on the right, it selects all text within +the pair; at the beginning +or end of a line, it selects the line; within or at the edge of an alphanumeric word, +it selects the word. +.PP +Characters typed on the keyboard replace the selected text; +if this text is not empty, it is placed in a +.I snarf buffer +common to all windows but distinct from that of +.IR sam (1). +.PP +Programs access the text in the window at a single point +maintained automatically by +.IR rio . +The +.I output point +is the location in the text where the next character written by +a program to +.B /dev/cons +will appear; afterwards, the output point is the null string +beyond the new character. +The output point is also the location in the text of the next character +that will be read (directly from the text in the window, +not from an intervening buffer) +by a program from +.BR /dev/cons . +When such a read will occur is, however, under control of +.I rio +and the user. +.PP +In general there is text in the window after the output point, +usually placed there by typing but occasionally by the editing +operations described below. +A pending read of +.B /dev/cons +will block until the text after the output point contains +a newline, whereupon the read may +acquire the text, up to and including the newline. +After the read, as described above, the output point will be at +the beginning of the next line of text. +In normal circumstances, therefore, typed text is delivered +to programs a line at a time. +Changes made by typing or editing before the text is read will not +be seen by the program reading it. +If the program in the window does not read the terminal, +for example if it is a long-running computation, there may +accumulate multiple lines of text after the output point; +changes made to all this text will be seen when the text +is eventually read. +This means, for example, that one may edit out newlines in +unread text to forestall the associated text being read when +the program finishes computing. +This behavior is very different from most systems. +.PP +Even when there are newlines in the output text, +.I rio +will not honor reads if the window is in +.I hold +.IR mode , +which is indicated by a white cursor and blue text and border. +The ESC character toggles hold mode. +Some programs, such as +.IR mail (1), +automatically turn on hold mode to simplify the editing of multi-line text; +type ESC when done to allow +.I mail +to read the text. +.PP +An EOT character (control-D) behaves exactly like newline except +that it is not delivered to a program when read. +Thus on an empty line an EOT serves to deliver an end-of-file indication: +the read will return zero characters. +Like newlines, unread EOTs may be successfully edited out of the text. +The BS character (control-H) erases the character before the selected text. +The ETB character (control-W) erases any nonalphanumeric characters, then +the alphanumeric word just before the selected text. +`Alphanumeric' here means non-blanks and non-punctuation. +The NAK character (control-U) erases the text after the output point, +and not yet read by a program, but not more than one line. +All these characters are typed on the keyboard and hence replace +the selected text; for example, typing a BS with a word selected +places the word in the snarf buffer, removes it from the screen, +and erases the character before the word. +.PP +Text may be moved vertically within the window. +A scroll bar on the left of the window shows in its clear portion what fragment of the +total output text is visible on the screen, and in its gray part what +is above or below view; +it measures characters, not lines. +Mousing inside the scroll bar moves text: +clicking button 1 with the mouse pointing inside the scroll bar +brings the line at the top of the +window to the cursor's vertical location; +button 3 takes the line at the cursor to the top of the window; +button 2, treating the scroll bar as a ruler, jumps to the indicated portion +of the stored text. +Holding a button pressed in the scroll bar will cause the text +to scroll continuously until the button is released. +Also, a VIEW key (possibly with a different label; see +.IR keyboard (6)) +or down-arrow +scrolls forward +half a window, and up-arrow scrolls back. +.PP +The DEL character sends an +.L interrupt +note to all processes in the window's process group. +Unlike the other characters, the DEL, VIEW, and up- and down-arrow +keys do not affect the selected text. +.PP +Normally, written output to a window blocks when +the text reaches the end of the screen; +a button 2 menu item toggles scrolling. +.PP +Other editing operations are selected from a menu on button 2. +The +.B cut +operation deletes the selected text +from the screen and puts it in the snarf buffer; +.B snarf +copies the selected text to the buffer without deleting it; +.B paste +replaces the selected text with the contents of the buffer; +and +.B send +copies the snarf buffer to just after the output point, adding a final newline +if missing. +.B Paste +will sometimes and +.B send +will always place text after the output point; the text so placed +will behave exactly as described above. Therefore when pasting +text containing newlines after the output point, it may be prudent +to turn on hold mode first. +.PP +The +.B plumb +menu item sends the contents of the selection (not the snarf buffer) to the +.IR plumber (4). +If the selection is empty, it sends the white-space-delimited text +containing the selection (typing cursor). +A typical use of this feature is to tell the editor to find the source of an error +by plumbing the file and line information in a compiler's diagnostic. +.SS Raw text windows +Opening or manipulating certain files served by +.IR rio +suppresses some of the services supplied to ordinary text windows. +While the file +.B /dev/mouse +is open, any mouse operations are the responsibility of another program +running in the window. Thus, +.I rio +refrains from maintaining +the scroll bar, +supplying text editing or menus, interpreting the +VIEW key as a request to scroll, and also turns scrolling on. +.PP +The file +.B /dev/consctl +controls interpretation of keyboard input. +In particular, a raw mode may be set: +in a raw-input window, no typed keyboard characters are special, +they are not echoed to the screen, and all are passed +to a program immediately upon reading, instead of being gathered into +lines. +.SS Graphics windows +A program that holds +.B /dev/mouse +and +.B /dev/consctl +open after putting the console in raw mode +has complete control of the window: +it interprets all mouse events, gets all keyboard characters, +and determines what appears on the screen. +.SH FILES +.TF /srv/riowctl.\fIuser\fP.\fIpid\fP +.TP +.B /lib/font/bit/* +font directories +.TP +.B /mnt/wsys +Files served by +.I rio +(also unioned in +.B /dev +in a window's name space, before the terminal's real +.B /dev +files) +.TP +.B /srv/rio.\fIuser\fP.\fIpid\fP +Server end of +.IR rio . +.TP +.B /srv/riowctl.\fIuser\fP.\fIpid\fP +Named pipe for +.I wctl +messages. +.SH SOURCE +.TF /sys/src/cmd/rio +.TP +.B /sys/src/cmd/rio +.TP +.B /rc/bin/label +.TP +.B /rc/bin/window +.TP +.B /rc/bin/wloc +.SH "SEE ALSO" +.IR rio (4), +.IR rc (1), +.IR cpu (1), +.IR sam (1), +.IR mail (1), +.IR proof (1), +.IR graphics (2), +.IR frame (2), +.IR window (2), +.IR notify (2), +.IR cons (3), +.IR draw (3), +.IR mouse (3), +.IR keyboard (6) +.SH BUGS +The standard input of +.I window +is redirected to the newly created window, so there is no way to pipe the output +of a program to the standard input of the new window. +In some cases, +.IR plumb (1) +can be used to work around this limitation. diff --git a/static/plan9-4e/man1/rm.1 b/static/plan9-4e/man1/rm.1 new file mode 100644 index 00000000..c5786f92 --- /dev/null +++ b/static/plan9-4e/man1/rm.1 @@ -0,0 +1,28 @@ +.TH RM 1 +.SH NAME +rm \- remove files +.SH SYNOPSIS +.B rm +[ +.B -fr +] +.I file ... +.SH DESCRIPTION +.I Rm +removes files or directories. +A directory is removed only if it is empty. +Removal of a file requires write permission in its directory, +but neither read nor write permission on the file itself. +The options are +.TP +.B -f +Don't report files that can't be removed. +.TP +.B -r +Recursively delete the +entire contents of a directory +and the directory itself. +.SH SOURCE +.B /sys/src/cmd/rm.c +.SH "SEE ALSO" +.IR remove (2) diff --git a/static/plan9-4e/man1/rtstats.1 b/static/plan9-4e/man1/rtstats.1 new file mode 100644 index 00000000..a01bffc4 --- /dev/null +++ b/static/plan9-4e/man1/rtstats.1 @@ -0,0 +1,117 @@ +.TH RTSTATS 1 +.SH NAME +rtstats \- show real-time process behavior +.SH SYNOPSIS +.B rtstats +[ +.B \-T +.I period +] +[ +.B \-D +.I deadline +] +[ +.B \-C +.I cost +] +[ +.B \-d +.I dir +] +[ +.B \-t +.I timedev +] +[ +.B \-b +] +[ +.B \-v +] +[ +.B \-w +] +.SH DESCRIPTION +.I Rtstats +displays the behavor of the real-time tasks running on a machine. +In its window it shows a time line for each real-time task with +black up arrows to indicate releases, black down arrows to indicate +deadlines, red down arrows to indicate early deadline as a consequence +of reaching cost, and green down arrows to indicate early deadline as +a consequence of yielding. Running tasks are shown as colored blocks, +while pre-empted ones are shown as very thin colored blocks. +.PP +Normally, +.B rtstats +itself runs in real time so that one of the bars in the display represents +.B rtstats +itself. The +.B \-b +flag makes it run as a best-effort process instead. +.PP +The +.BR \-T , +.BR \-D , +and +.BR \-C , +flags, respectively, specification a period, deadline or cost other than the +defaults of 200ms, 80ms and 40ms. +Times can be specified as a fixed-point decimal number, optionally followed +by one of the units +.BR s , +.BR ms , +.BR µs ,(or +.BR us ), +or +.BR ns . +Choosing periods, deadlines or costs less than 1ms or so will probably not produce very +desirable results. +.PP +The +.B \-d +flag can be used to specify a real-time event file other than the default, +.BR #R/realtime/nblog +and the +.B \-t +flag can be used to specify another time source than +.BR #R/realtime/time . +.PP +The +.B \-v +flag prints out the events as they are received from the event file. +.PP +The \-w +flag makes +.B rtstats +open a new window for its display. +.PP +The following one-character commands are recognized by +.BR rtstats : +.TP +.B + +Zoom in by a factor of two, +.TP +.B - +Zoom out by a factor of two, +.TP +.B p +Pause or resume, +.TP +.B q +Quit. +.SH "SEE ALSO +.IR realtime (3) +.SH FILES +.TF #R/realtime/nblog +.TP +.B #R/realtime/task +Task directory +.TP +.B #R/realtime/nblog +Real-time event log (non-blocking version) +.TP +.B #R/realtime/time +Current real time. +.SH SOURCE +.B /sys/src/cmd/rtstats diff --git a/static/plan9-4e/man1/sam.1 b/static/plan9-4e/man1/sam.1 new file mode 100644 index 00000000..55294447 --- /dev/null +++ b/static/plan9-4e/man1/sam.1 @@ -0,0 +1,885 @@ +.TH SAM 1 +.ds a \fR*\ \fP +.SH NAME +sam, B, sam.save \- screen editor with structural regular expressions +.SH SYNOPSIS +.B sam +[ +.I option ... +] [ +.I files +] +.PP +.B sam +.B -r +.I machine +.PP +.B sam.save +.PP +.B B +[ +.BI -nnnn +] +.I file ... +.SH DESCRIPTION +.I Sam +is a multi-file editor. +It modifies a local copy of an external file. +The copy is here called a +.IR file . +The files are listed in a menu available through mouse button 3 +or the +.B n +command. +Each file has an associated name, usually the name of the +external file from which it was read, and a `modified' bit that indicates whether +the editor's file agrees with the external file. +The external file is not read into +the editor's file until it first becomes the current file\(emthat to +which editing commands apply\(emwhereupon its menu entry is printed. +The options are +.TF -rmachine +.TP +.B -d +Do not `download' the terminal part of +.IR sam . +Editing will be done with the command language only, as in +.IR ed (1). +.TP +.BI -r " machine +Run the host part remotely +on the specified machine, the terminal part locally. +.TP +.BI -s " path +Start the host part from the specified file on the remote host. +Only meaningful with the +.BI -r +option. +.TP +.BI -t " path +Start the terminal part from the specified file. Useful +for debugging. +.PD +.SS Regular expressions +Regular expressions are as in +.IR regexp (6) +with the addition of +.BR \en +to represent newlines. +A regular expression may never contain a literal newline character. +The empty +regular expression stands for the last complete expression encountered. +A regular expression in +.I sam +matches the longest leftmost substring formally +matched by the expression. +Searching in the reverse direction is equivalent +to searching backwards with the catenation operations reversed in +the expression. +.SS Addresses +An address identifies a substring in a file. +In the following, `character +.IR n ' +means the null string +after the +.IR n -th +character in the file, with 1 the +first character in the file. +`Line +.IR n ' +means the +.IR n -th +match, +starting at the beginning of the file, of the regular expression +.LR .*\en? . +All files always have a current substring, called dot, +that is the default address. +.SS Simple Addresses +.PD0 +.TP +.BI # n +The empty string after character +.IR n ; +.B #0 +is the beginning of the file. +.TP +.I n +Line +.IR n ; +.B 0 +is the beginning of the file. +.TP +.BI / regexp / +.PD0 +.TP +.BI ? regexp ? +The substring that matches the regular expression, +found by looking toward the end +.RB ( / ) +or beginning +.RB ( ? ) +of the file, +and if necessary continuing the search from the other end to the +starting point of the search. +The matched substring may straddle +the starting point. +When entering a pattern containing a literal question mark +for a backward search, the question mark should be +specified as a member of a class. +.PD +.TP +.B 0 +The string before the first full line. +This is not necessarily +the null string; see +.B + +and +.B - +below. +.TP +.B $ +The null string at the end of the file. +.TP +.B . +Dot. +.TP +.B \&' +The mark in the file (see the +.B k +command below). +.TP +\fL"\f2regexp\fL"\f1\f1 +Preceding a simple address (default +.BR . ), +refers to the address evaluated in the unique file whose menu line +matches the regular expression. +.PD +.SS Compound Addresses +In the following, +.I a1 +and +.I a2 +are addresses. +.TF a1+a2 +.TP +.IB a1 + a2 +The address +.I a2 +evaluated starting at the end of +.IR a1 . +.TP +.IB a1 - a2 +The address +.I a2 +evaluated looking in the reverse direction +starting at the beginning of +.IR a1 . +.TP +.IB a1 , a2 +The substring from the beginning of +.I a1 +to the end of +.IR a2 . +If +.I a1 +is missing, +.B 0 +is substituted. +If +.I a2 +is missing, +.B $ +is substituted. +.TP +.IB a1 ; a2 +Like +.IB a1 , a2\f1, +but with +.I a2 +evaluated at the end of, and dot set to, +.IR a1 . +.PD +.PP +The operators +.B + +and +.B - +are high precedence, while +.B , +and +.B ; +are low precedence. +.PP +In both +.B + +and +.B - +forms, if +.I a2 +is a line or character address with a missing +number, the number defaults to 1. +If +.I a1 +is missing, +.L . +is substituted. +If both +.I a1 +and +.I a2 +are present and distinguishable, +.B + +may be elided. +.I a2 +may be a regular +expression; if it is delimited by +.LR ? 's, +the effect of the +.B + +or +.B - +is reversed. +.PP +It is an error for a compound address to represent a malformed substring. +Some useful idioms: +.IB a1 +- +\%(\f2a1\fL-+\f1) +selects the line containing +the end (beginning) of a1. +.BI 0/ regexp / +locates the first match of the expression in the file. +(The form +.B 0;// +sets dot unnecessarily.) +.BI ./ regexp /// +finds the second following occurrence of the expression, +and +.BI .,/ regexp / +extends dot. +.SS Commands +In the following, text demarcated by slashes represents text delimited +by any printable +character except alphanumerics. +Any number of +trailing delimiters may be elided, with multiple elisions then representing +null strings, but the first delimiter must always +be present. +In any delimited text, +newline may not appear literally; +.B \en +may be typed for newline; and +.B \e/ +quotes the delimiter, here +.LR / . +Backslash is otherwise interpreted literally, except in +.B s +commands. +.PP +Most commands may be prefixed by an address to indicate their range +of operation. +Those that may not are marked with a +.L * +below. +If a command takes +an address and none is supplied, dot is used. +The sole exception is +the +.B w +command, which defaults to +.BR 0,$ . +In the description, `range' is used +to represent whatever address is supplied. +Many commands set the +value of dot as a side effect. +If so, it is always set to the `result' +of the change: the empty string for a deletion, the new text for an +insertion, etc. (but see the +.B s +and +.B e +commands). +.br +.ne 1.2i +.SS Text commands +.PD0 +.TP +.BI a/ text / +.TP +or +.TP +.B a +.TP +.I lines of text +.TP +.B . +Insert the text into the file after the range. +Set dot. +.PD +.TP +.B c\fP +.br +.ns +.TP +.B i\fP +Same as +.BR a , +but +.B c +replaces the text, while +.B i +inserts +.I before +the range. +.TP +.B d +Delete the text in the range. +Set dot. +.TP +.BI s/ regexp / text / +Substitute +.I text +for the first match to the regular expression in the range. +Set dot to the modified range. +In +.I text +the character +.B & +stands for the string +that matched the expression. +Backslash behaves as usual unless followed by +a digit: +.BI \e d +stands for the string that matched the +subexpression begun by the +.IR d -th +left parenthesis. +If +.I s +is followed immediately by a +number +.IR n , +as in +.BR s2/x/y/ , +the +.IR n -th +match in the range is substituted. +If the +command is followed by a +.BR g , +as in +.BR s/x/y/g , +all matches in the range +are substituted. +.TP +.BI m " a1 +.br +.ns +.TP +.BI t " a1 +Move +.RB ( m ) +or copy +.RB ( t ) +the range to after +.IR a1 . +Set dot. +.SS Display commands +.PD 0 +.TP +.B p +Print the text in the range. +Set dot. +.TP +.B = +Print the line address and character address of the range. +.TP +.B =# +Print just the character address of the range. +.PD +.SS File commands +.PD0 +.TP +.BI \*ab " file-list +Set the current file to the first file named in the list +that +.I sam +also has in its menu. +The list may be expressed +.BI < "Plan 9 command" +in which case the file names are taken as words (in the shell sense) +generated by the Plan 9 command. +.TP +.BI \*aB " file-list +Same as +.BR b , +except that file names not in the menu are entered there, +and all file names in the list are examined. +.TP +.B \*an +Print a menu of files. +The format is: +.RS +.TP 11 +.BR ' " or blank +indicating the file is modified or clean, +.TP 11 +.BR - " or \&" + +indicating the file is unread or has been read +(in the terminal, +.B * +means more than one window is open), +.TP 11 +.BR . " or blank +indicating the current file, +.TP 11 +a blank, +.TP 11 +and the file name. +.RE +.TP 0 +.BI \*aD " file-list +Delete the named files from the menu. +If no files are named, the current file is deleted. +It is an error to +.B D +a modified file, but a subsequent +.B D +will delete such a file. +.PD +.SS I/O Commands +.PD0 +.TP +.BI \*ae " filename +Replace the file by the contents of the named external file. +Set dot to the beginning of the file. +.TP +.BI r " filename +Replace the text in the range by the contents of the named external file. +Set dot. +.TP +.BI w " filename +Write the range (default +.BR 0,$ ) +to the named external file. +.TP +.BI \*af " filename +Set the file name and print the resulting menu entry. +.PP +If the file name is absent from any of these, the current file name is used. +.B e +always sets the file name; +.B r +and +.B w +do so if the file has no name. +.TP +.BI < " Plan 9-command +Replace the range by the standard output of the +Plan 9 command. +.TP +.BI > " Plan 9-command +Send the range to the standard input of the +Plan 9 command. +.TP +.BI | " Plan 9-command +Send the range to the standard input, and replace it by +the standard output, of the +Plan 9 command. +.TP +.BI \*a! " Plan 9-command +Run the +Plan 9 command. +.TP +.BI \*acd " directory +Change working directory. +If no directory is specified, +.B $home +is used. +.PD +.PP +In any of +.BR < , +.BR > , +.B | +or +.BR ! , +if the +.I Plan 9 command +is omitted the last +.I Plan 9 command +(of any type) is substituted. +If +.I sam +is +.I downloaded +(using the mouse and raster display, i.e. not using option +.BR -d ), +.B ! +sets standard input to +.BR /dev/null , +and otherwise +unassigned output +.RB ( stdout +for +.B ! +and +.BR > , +.B stderr +for all) is placed in +.B /tmp/sam.err +and the first few lines are printed. +.SS Loops and Conditionals +.PD0 +.TP +.BI x/ regexp / " command +For each match of the regular expression in the range, run the command +with dot set to the match. +Set dot to the last match. +If the regular +expression and its slashes are omitted, +.L /.*\en/ +is assumed. +Null string matches potentially occur before every character +of the range and at the end of the range. +.TP +.BI y/ regexp / " command +Like +.BR x , +but run the command for each substring that lies before, between, +or after +the matches that would be generated by +.BR x . +There is no default regular expression. +Null substrings potentially occur before every character +in the range. +.TP +.BI \*aX/ regexp / " command +For each file whose menu entry matches the regular expression, +make that the current file and +run the command. +If the expression is omitted, the command is run +in every file. +.TP +.BI \*aY/ regexp / " command +Same as +.BR X , +but for files that do not match the regular expression, +and the expression is required. +.TP +.BI g/ regexp / " command +.br +.ns +.TP +.BI v/ regexp / " command +If the range contains +.RB ( g ) +or does not contain +.RB ( v ) +a match for the expression, +set dot to the range and run the command. +.PP +These may be nested arbitrarily deeply, but only one instance of either +.B X +or +.B Y +may appear in a \%single command. +An empty command in an +.B x +or +.B y +defaults to +.BR p ; +an empty command in +.B X +or +.B Y +defaults to +.BR f . +.B g +and +.B v +do not have defaults. +.PD +.SS Miscellany +.TF (empty) +.TP +.B k +Set the current file's mark to the range. Does not set dot. +.TP +.B \*aq +Quit. +It is an error to quit with modified files, but a second +.B q +will succeed. +.TP +.BI \*au " n +Undo the last +.I n +(default 1) +top-level commands that changed the contents or name of the +current file, and any other file whose most recent change was simultaneous +with the current file's change. +Successive +.BR u 's +move further back in time. +The only commands for which u is ineffective are +.BR cd , +.BR u , +.BR q , +.B w +and +.BR D . +If +.I n +is negative, +.B u +`redoes,' undoing the undo, going forwards in time again. +.TP +(empty) +If the range is explicit, set dot to the range. +If +.I sam +is downloaded, the resulting dot is selected on the screen; +otherwise it is printed. +If no address is specified (the +command is a newline) dot is extended in either direction to +line boundaries and printed. +If dot is thereby unchanged, it is set to +.B .+1 +and printed. +.PD +.SS Grouping and multiple changes +Commands may be grouped by enclosing them in braces +.BR {} . +Commands within the braces must appear on separate lines (no backslashes are +required between commands). +Semantically, an opening brace is like a command: +it takes an (optional) address and sets dot for each sub-command. +Commands within the braces are executed sequentially, but changes made +by one command are not visible to other commands (see the next +paragraph). +Braces may be nested arbitrarily. +.PP +When a command makes a number of changes to a file, as in +.BR x/re/c/text/ , +the addresses of all changes to the file are computed in the original file. +If the changes are in sequence, +they are applied to the file. +Successive insertions at the same address are catenated into a single +insertion composed of the several insertions in the order applied. +.SS The terminal +What follows refers to behavior of +.I sam +when downloaded, that is, when +operating as a display editor on a raster display. +This is the default +behavior; invoking +.I sam +with the +.B -d +(no download) option provides access +to the command language only. +.PP +Each file may have zero or more windows open. +Each window is equivalent +and is updated simultaneously with changes in other windows on the same file. +Each window has an independent value of dot, indicated by a highlighted +substring on the display. +Dot may be in a region not within +the window. +There is usually a `current window', +marked with a dark border, to which typed text and editing +commands apply. +Text may be typed and edited as in +.IR rio (1); +also the escape key (ESC) selects (sets dot to) text typed +since the last mouse button hit. +.PP +The button 3 menu controls window operations. +The top of the menu +provides the following operators, each of which uses one or +more +.IR rio -like +cursors to prompt for selection of a window or sweeping +of a rectangle. +`Sweeping' a null rectangle gets a large window, disjoint +from the command window or the whole screen, depending on +where the null rectangle is. +.TF resize +.TP +.B new +Create a new, empty file. +.TP +.B zerox +Create a copy of an existing window. +.TP +.B resize +As in +.IR rio . +.TP +.B close +Delete the window. +In the last window of a file, +.B close +is equivalent to a +.B D +for the file. +.TP +.B write +Equivalent to a +.B w +for the file. +.PD +.PP +Below these operators is a list of available files, starting with +.BR ~~sam~~ , +the command window. +Selecting a file from the list makes the most recently +used window on that file current, unless it is already current, in which +case selections cycle through the open windows. +If no windows are open +on the file, the user is prompted to open one. +Files other than +.B ~~sam~~ +are marked with one of the characters +.B -+* +according as zero, one, or more windows +are open on the file. +A further mark +.L . +appears on the file in the current window and +a single quote, +.BR ' , +on a file modified since last write. +.PP +The command window, created automatically when +.B sam +starts, is an ordinary window except that text typed to it +is interpreted as commands for the editor rather than passive text, +and text printed by editor commands appears in it. +The behavior is like +.IR rio , +with an `output point' that separates commands being typed from +previous output. +Commands typed in the command window apply to the +current open file\(emthe file in the most recently +current window. +.SS Manipulating text +Button 1 changes selection, much like +.IR rio . +Pointing to a non-current window with button 1 makes it current; +within the current window, button 1 selects text, thus setting dot. +Double-clicking selects text to the boundaries of words, lines, +quoted strings or bracketed strings, depending on the text at the click. +.PP +Button 2 provides a menu of editing commands: +.TF /regexp +.TP +.B cut +Delete dot and save the deleted text in the snarf buffer. +.TP +.B paste +Replace the text in dot by the contents of the snarf buffer. +.TP +.B snarf +Save the text in dot in the snarf buffer. +.TP +.B plumb +Send the text in the selection as a plumb +message. If the selection is empty, +the white-space-delimited block of text is sent as a plumb message +with a +.B click +attribute defining where the selection lies (see +.IR plumb (6)). +.TP +.B look +Search forward for the next occurrence of the literal text in dot. +If dot is the null string, the text in the snarf buffer is +used. +The snarf buffer is unaffected. +.TP +.B +Exchange snarf buffers with +.IR rio . +.TP +.BI / regexp +Search forward for the next match of the last regular expression +typed in a command. +(Not in command window.) +.TP +.B send +Send the text in dot, or the snarf buffer if +dot is the null string, as if it were typed to the command window. +Saves the sent text in the snarf buffer. +(Command window only.) +.PD +.SS External communication +.I Sam +listens to the +.B edit +plumb port. +If plumbing is not active, +on invocation +.I sam +creates a named pipe +.BI /srv/sam. user +which acts as an additional source of commands. Characters written to +the named pipe are treated as if they had been typed in the command window. +.PP +.I B +is a shell-level command that causes an instance of +.I sam +running on the same terminal to load the named +.IR files . +.I B +uses either plumbing or the named pipe, whichever service is available. +If plumbing is not enabled, +the option allows a line number to be specified for +the initial position to display in the last named file +(plumbing provides a more general mechanism for this ability). +.SS Abnormal termination +If +.I sam +terminates other than by a +.B q +command (by hangup, deleting its window, etc.), modified +files are saved in an +executable file, +.BR $home/sam.save . +This program, when executed, asks whether to write +each file back to a external file. +The answer +.L y +causes writing; anything else skips the file. +.SH FILES +.TF /sys/src/cmd/samterm +.TP +.B $home/sam.save +.TP +.B $home/sam.err +.TP +.B /sys/lib/samsave +the program called to unpack +.BR $home/sam.save . +.SH SOURCE +.TF /sys/src/cmd/samterm +.TP +.B /sys/src/cmd/sam +source for +.I sam +itself +.TP +.B /sys/src/cmd/samterm +source for the separate terminal part +.TP +.B /rc/bin/B +.SH SEE ALSO +.IR ed (1), +.IR sed (1), +.IR grep (1), +.IR rio (1), +.IR regexp (6). +.PP +Rob Pike, +``The text editor sam''. diff --git a/static/plan9-4e/man1/secstore.1 b/static/plan9-4e/man1/secstore.1 new file mode 100644 index 00000000..97c5b231 --- /dev/null +++ b/static/plan9-4e/man1/secstore.1 @@ -0,0 +1,107 @@ +.TH SECSTORE 1 +.SH NAME +aescbc, secstore \- secstore commands +.SH SYNOPSIS +.B auth/secstore +[-c] [-s +.I server +] [ -(g|G) +.I getfile +] [ -p +.I putfile +] [ -r +.I rmfile +] [ -u +.I user +] +.br +.B auth/aescbc +-e +.I password +.I cleartext +.I cryptext +.br +.B auth/aescbc +-d +.I password +.I cryptext +.I cleartext +.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 -v +produces more verbose output, in particular providing a few +bits of feedback to help the user detect mistyping. +.PP +Option +.B -c +prompts for a password change. +.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 default file read by +.IR factotum (4) +at startup, open a new window and +.sp +.EX + % ramfs -p; cd /tmp + % auth/secstore -g factotum + secstore password: + % echo 'proto=apop dom=x.com user=ehg !password=y~1' >> factotum + % auth/secstore -p factotum + secstore password: + % read -m factotum > /mnt/factotum/ctl +.EE +and delete the window. +The first line 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 +.I Aescbc +encrypts and decrypts using AES (Rijndael) in cipher +block chaining (CBC) mode. This is the file encryption +used internally by +.IR secstore . +.SH SOURCE +.B /sys/src/cmd/auth/secstore +.SH SEE ALSO +.IR factotum (4), +.IR secstore (8) +.SH BUGS +There is deliberately no backup of files on the secstore, so +.B -r +(or a disk crash) is irrevocable. You are advised to store +important secrets in a second location. diff --git a/static/plan9-4e/man1/sed.1 b/static/plan9-4e/man1/sed.1 new file mode 100644 index 00000000..3b5ac181 --- /dev/null +++ b/static/plan9-4e/man1/sed.1 @@ -0,0 +1,385 @@ +.TH SED 1 +.SH NAME +sed \- stream editor +.SH SYNOPSIS +.B sed +[ +.B -n +] +[ +.B -g +] +[ +.B -e +.I script +] +[ +.B -f +.I sfile +] +[ +.I file ... +] +.SH DESCRIPTION +.I Sed +copies the named +.I files +(standard input default) to the standard output, +edited according to a script of commands. +The +.B -f +option causes the script to be taken from file +.IR sfile ; +these options accumulate. +If there is just one +.B -e +option and no +.BR -f 's, +the flag +.B -e +may be omitted. +The +.B -n +option suppresses the default output; +.B -g +causes all substitutions to be global, as if suffixed +.BR g . +.PP +A script consists of editing commands, one per line, +of the following form: +.IP +[\fIaddress\fR [\fL,\fI address\fR] ] \fIfunction\fR [\fIargument\fR ...] +.PP +In normal operation +.I sed +cyclically copies a line of input into a +.I pattern space +(unless there is something left after +a +.L D +command), +applies in sequence +all commands whose +.I addresses +select that pattern space, +and at the end of the script copies the pattern space +to the standard output (except under +.BR -n ) +and deletes the pattern space. +.PP +An +.I address +is either a decimal number that counts +input lines cumulatively across files, a +.L $ +that +addresses the last line of input, or a context address, +.BI / regular-expression / \f1, +in the style of +.IR regexp (6), +with the added convention that +.L \en +matches a +newline embedded in the pattern space. +.PP +A command line with no addresses selects every pattern space. +.PP +A command line with +one address selects each pattern space that matches the address. +.PP +A command line with +two addresses selects the inclusive range from the first +pattern space that matches the first address through +the next pattern space that matches +the second. +(If the second address is a number less than or equal +to the line number first selected, only one +line is selected.) +Thereafter the process is repeated, looking again for the +first address. +.PP +Editing commands can be applied to non-selected pattern +spaces by use of the negation function +.L ! +(below). +.PP +An argument denoted +.I text +consists of one or more lines, +all but the last of which end with +.L \e +to hide the +newline. +Backslashes in text are treated like backslashes +in the replacement string of an +.L s +command, +and may be used to protect initial blanks and tabs +against the stripping that is done on +every script line. +.PP +An argument denoted +.I rfile +or +.I wfile +must terminate the command +line and must be preceded by exactly one blank. +Each +.I wfile +is created before processing begins. +There can be at most 120 distinct +.I wfile +arguments. +.TP \w'\fL!\ \fIfunction\fLXXX'u +.B a\e +.br +.ns +.TP +.I text +Append. +Place +.I text +on the output before +reading the next input line. +.TP +.BI b " label" +Branch to the +.B : +command bearing the +.IR label . +If +.I label +is empty, branch to the end of the script. +.TP +.B c\e +.br +.ns +.TP +.I text +Change. +Delete the pattern space. +With 0 or 1 address or at the end of a 2-address range, place +.I text +on the output. +Start the next cycle. +.TP +.B d +Delete the pattern space. +Start the next cycle. +.TP +.B D +Delete the initial segment of the +pattern space through the first newline. +Start the next cycle. +.TP +.B g +Replace the contents of the pattern space +by the contents of the hold space. +.TP +.B G +Append the contents of the hold space to the pattern space. +.TP +.B h +Replace the contents of the hold space by the contents of the pattern space. +.TP +.B H +Append the contents of the pattern space to the hold space. +.ne 3 +.TP +.B i\e +.br +.ns +.TP +.I text +Insert. +Place +.I text +on the standard output. +.TP +.B n +Copy the pattern space to the standard output. +Replace the pattern space with the next line of input. +.TP +.B N +Append the next line of input to the pattern space +with an embedded newline. +(The current line number changes.) +.TP +.B p +Print. +Copy the pattern space to the standard output. +.TP +.B P +Copy the initial segment of the pattern space through +the first newline to the standard output. +.TP +.B q +Quit. +Branch to the end of the script. +Do not start a new cycle. +.TP +.BI r " rfile" +Read the contents of +.IR rfile . +Place them on the output before reading +the next input line. +.TP +.B s/\fIregular-expression\fP/\fIreplacement\fP/\fIflags +Substitute the +.I replacement +string for instances of the +.I regular-expression +in the pattern space. +Any character may be used instead of +.LR / . +For a fuller description see +.IR regexp (6). +.I Flags +is zero or more of +.RS +.TP +.B g +Global. +Substitute for all non-overlapping instances of the +.I regular expression +rather than just the +first one. +.TP +.B p +Print the pattern space if a replacement was made. +.TP +.BI w " wfile" +Write. +Append the pattern space to +.I wfile +if a replacement +was made. +.RE +.TP +.BI t " label" +Test. +Branch to the +.L : +command bearing the +.I label +if any +substitutions have been made since the most recent +reading of an input line or execution of a +.LR t . +If +.I label +is empty, branch to the end of the script. +.TP +.B w +.I wfile +.br +Write. +Append the pattern space to +.IR wfile . +.TP +.B x +Exchange the contents of the pattern and hold spaces. +.TP +.B y/\fIstring1\fP/\fIstring2\fP/ +Transform. +Replace all occurrences of characters in +.I string1 +with the corresponding character in +.IR string2 . +The lengths of +.I +string1 +and +.I string2 +must be equal. +.TP +.BI ! "function" +Don't. +Apply the +.I function +(or group, if +.I function +is +.LR { ) +only to lines +.I not +selected by the address(es). +.TP +.BI : " label" +This command does nothing; it bears a +.I label +for +.B b +and +.B t +commands to branch to. +.TP +.B = +Place the current line number on the standard output as a line. +.TP +.B { +Execute the following commands through a matching +.L } +only when the pattern space is selected. +.TP +.B " " +An empty command is ignored. +.ne 4 +.SH EXAMPLES +.TP +.B sed 10q file +Print the first 10 lines of the file. +.TP +.B sed '/^$/d' +Delete empty lines from standard input. +.TP +.B sed 's/UNIX/& system/g' +Replace every instance of +.L UNIX +by +.LR "UNIX system" . +.PP +.EX +sed 's/ *$// \fRdrop trailing blanks\fP +/^$/d \fRdrop empty lines\fP +s/ */\e \fRreplace blanks by newlines\fP +/g +/^$/d' chapter* +.EE +.ns +.IP +Print the files +.BR chapter1 , +.BR chapter2 , +etc. one word to a line. +.PP +.EX +nroff -ms manuscript | sed ' +${ + /^$/p \fRif last line of file is empty, print it\fP +} +//N \fRif current line is empty, append next line\fP +/^\en$/D' \fRif two lines are empty, delete the first\fP +.EE +.ns +.IP +Delete all but one of each group of empty lines from a +formatted manuscript. +.SH SOURCE +.B /sys/src/cmd/sed.c +.SH SEE ALSO +.IR ed (1), +.IR grep (1), +.IR awk (1), +.IR lex (1), +.IR sam (1), +.IR regexp (6) +.br +L. E. McMahon, +`SED \(em A Non-interactive Text Editor', +Unix Research System Programmer's Manual, Volume 2. +.SH BUGS +If input is from a pipe, buffering may consume +characters beyond a line on which a +.L q +command is executed. diff --git a/static/plan9-4e/man1/seq.1 b/static/plan9-4e/man1/seq.1 new file mode 100644 index 00000000..97b68da0 --- /dev/null +++ b/static/plan9-4e/man1/seq.1 @@ -0,0 +1,69 @@ +.TH SEQ 1 +.SH NAME +seq \- print sequences of numbers +.SH SYNOPSIS +.B seq +[ +.B -w +] +[ +.BI -f format +] +[ +.I first +[ +.I incr +] +] +.I last +.SH DESCRIPTION +.I Seq +prints a sequence of numbers, one per line, from +.I first +(default 1) to as near +.I last +as possible, in increments of +.I incr +(default 1). +The numbers are interpreted as floating point. +.PP +Normally integer values are printed as decimal integers. +The options are +.TP "\w'\fL-f \fIformat\fLXX'u" +.BI -f format +Use the +.IR print (2)-style +.I format +.IR print +for printing each (floating point) number. +The default is +.LR %g . +.TP +.B -w +Equalize the widths of all numbers by padding with +leading zeros as necessary. +Not effective with option +.BR -f , +nor with numbers in exponential notation. +.SH EXAMPLES +.TP +.L +seq 0 .05 .1 +Print +.BR "0 0.05 0.1" +(on separate lines). +.TP +.L +seq -w 0 .05 .1 +Print +.BR "0.00 0.05 0.10" . +.SH SOURCE +.B /sys/src/cmd/seq.c +.SH BUGS +Option +.B -w +always surveys every value in advance. +Thus +.L +seq -w 1000000000 +is a painful way to get an `infinite' sequence. diff --git a/static/plan9-4e/man1/size.1 b/static/plan9-4e/man1/size.1 new file mode 100644 index 00000000..cd7ba9b8 --- /dev/null +++ b/static/plan9-4e/man1/size.1 @@ -0,0 +1,28 @@ +.TH SIZE 1 +.SH NAME +size \- print size of executable files +.SH SYNOPSIS +.B size +[ +.I file ... +] +.SH DESCRIPTION +.I Size +prints the size of the segments for each of the argument executable files +(default +.BR v.out ). +The format is +.IP +.IB textsize t ++ +.IB datasize d ++ +.IB bsssize b += +.I total +.PP +where the numbers are in bytes. +.SH SOURCE +.B /sys/src/cmd/size.c +.SH "SEE ALSO +.IR a.out (6) diff --git a/static/plan9-4e/man1/sleep.1 b/static/plan9-4e/man1/sleep.1 new file mode 100644 index 00000000..61169e96 --- /dev/null +++ b/static/plan9-4e/man1/sleep.1 @@ -0,0 +1,31 @@ +.TH SLEEP 1 +.SH NAME +sleep \- suspend execution for an interval +.SH SYNOPSIS +.B sleep +.I time +.SH DESCRIPTION +.I Sleep +suspends execution for +.I time +seconds. +.SH EXAMPLES +Execute a command +100 seconds hence. +.IP +.EX +{sleep 100; command}& +.EE +.PP +Repeat a command every 30 seconds. +.IP +.EX +while (){ + command + sleep 30 +} +.EE +.SH SOURCE +.B /sys/src/cmd/sleep.c +.SH "SEE ALSO" +.IR sleep (2) diff --git a/static/plan9-4e/man1/sort.1 b/static/plan9-4e/man1/sort.1 new file mode 100644 index 00000000..6dded61a --- /dev/null +++ b/static/plan9-4e/man1/sort.1 @@ -0,0 +1,260 @@ +.TH SORT 1 +.SH NAME +sort \- sort and/or merge files +.SH SYNOPSIS +.B sort +[ +.BI -cmuMbdf\&inrwt x +] +[ +.BI + pos1 +[ +.BI - pos2 +] ... +] ... +[ +.B -k +.I pos1 +[ +.I ,pos2 +] +] ... +[ +.B -o +.I output +] +[ +.B -T +.I dir +\&... +] +[ +.I option +\&... +] +[ +.I file +\&... +] +.SH DESCRIPTION +.I Sort\^ +sorts +lines of all the +.I files +together and writes the result on +the standard output. +If no input files are named, the standard input is sorted. +.PP +The default sort key is an entire line. +Default ordering is +lexicographic by runes. +The ordering is affected globally by the following options, +one or more of which may appear. +.TP +.B -M +Compare as months. +The first three +non-white space characters +of the field +are folded +to upper case +and compared +so that +.L JAN +precedes +.LR FEB , +etc. +Invalid fields +compare low to +.LR JAN . +.TP +.B -b +Ignore leading white space (spaces and tabs) in field comparisons. +.TP +.B -d +`Phone directory' order: +only letters, +accented letters, +digits and white space +are significant in comparisons. +.TP +.B -f +Fold lower case +letters onto upper case. +Accented characters are folded to their +non-accented upper case form. +.TP +.B -i +Ignore characters outside the +.SM ASCII +range 040-0176 +in non-numeric comparisons. +.TP +.B -w +Like +.BR -i , +but ignore only tabs and spaces. +.TP +.B -n +An initial numeric string, +consisting of optional white space, +optional plus or minus sign, +and zero or more digits with optional decimal point, +is sorted by arithmetic value. +.TP +.B -g +Numbers, like +.B -n +but with optional +.BR e -style +exponents, are sorted by value. +.TP +.B -r +Reverse the sense of comparisons. +.TP +.BI -t x\^ +`Tab character' separating fields is +.IR x . +.PP +The notation +.BI + "pos1\| " - pos2\^ +restricts a sort key to a field beginning at +.I pos1\^ +and ending just before +.IR pos2 . +.I Pos1\^ +and +.I pos2\^ +each have the form +.IB m . n\f1, +optionally followed by one or more of the flags +.BR Mbdfginr , +where +.I m\^ +tells a number of fields to skip from the beginning of the line and +.I n\^ +tells a number of characters to skip further. +If any flags are present they override all the global +ordering options for this key. +A missing +.BI \&. n\^ +means +.BR \&.0 ; +a missing +.BI - pos2\^ +means the end of the line. +Under the +.BI -t x\^ +option, fields are strings separated by +.IR x ; +otherwise fields are +non-empty strings separated by white space. +White space before a field +is part of the field, except under option +.BR -b . +A +.B b +flag may be attached independently to +.IR pos1 +and +.IR pos2. +.PP +The notation +.B -k +.IR pos1 [, pos2 ] +is how POSIX +.I sort +defines fields: +.I pos1 +and +.I pos2 +have the same format but different meanings. +The value of +.I m\^ +is origin 1 instead of origin 0 +and a missing +.BI \&. n\^ +in +.I pos2 +is the end of the field. +.PP +When there are multiple sort keys, later keys +are compared only after all earlier keys +compare equal. +Lines that otherwise compare equal are ordered +with all bytes significant. +.PP +These option arguments are also understood: +.TP \w'\fL-z\fIrecsize\fLXX'u +.B -c +Check that the single input file is sorted according to the ordering rules; +give no output unless the file is out of sort. +.TP +.B -m +Merge; assume the input files are already sorted. +.TP +.B -u +Suppress all but one in each +set of equal lines. +Ignored bytes +and bytes outside keys +do not participate in +this comparison. +.TP +.B -o +The next argument is the name of an output file +to use instead of the standard output. +This file may be the same as one of the inputs. +.TP +.BI -T dir +Put temporary files in +.I dir +rather than in +.BR /tmp . +.ne 4 +.SH EXAMPLES +.TP +.L sort -u +0f +0 list +Print in alphabetical order all the unique spellings +in a list of words +where capitalized words differ from uncapitalized. +.TP +.L sort -t: +1 /adm/users +Print the users file +sorted by user name +(the second colon-separated field). +.TP +.L sort -umM dates +Print the first instance of each month in an already sorted file. +Options +.B -um +with just one input file make the choice of a +unique representative from a set of equal lines predictable. +.TP +.L +grep -n '^' input | sort -t: +1f +0n | sed 's/[0-9]*://' +A stable sort: input lines that compare equal will +come out in their original order. +.SH FILES +.BI /tmp/sort. . +.SH SOURCE +.B /sys/src/cmd/sort.c +.SH SEE ALSO +.IR uniq (1), +.IR look (1) +.SH DIAGNOSTICS +.I Sort +comments and exits with non-null status for various trouble +conditions and for disorder discovered under option +.BR -c . +.SH BUGS +An external null character can be confused +with an internally generated end-of-field character. +The result can make a sub-field not sort +less than a longer field. +.PP +Some of the options, e.g. +.B -i +and +.BR -M , +are hopelessly provincial. diff --git a/static/plan9-4e/man1/spell.1 b/static/plan9-4e/man1/spell.1 new file mode 100644 index 00000000..8298452c --- /dev/null +++ b/static/plan9-4e/man1/spell.1 @@ -0,0 +1,96 @@ +.TH SPELL 1 +.SH NAME +spell, sprog \- find spelling errors +.SH SYNOPSIS +.B spell +[ +.I options +] +\&... +[ +.I file +] +\&... +.PP +.B sprog +[ +.I options +] +[ +.B -f +.I file +] +.SH DESCRIPTION +.I Spell +looks up words from the named +.I files +(standard input default) +in a spelling list and places +possible misspellings\(emwords +not sanctioned there\(emon the standard output. +.PP +.I Spell +ignores constructs of +.IR troff (1) +and its standard preprocessors. +It understands these options: +.TP +.B -b +Check British spelling. +.TP +.B -v +Print all words not literally in the spelling list, with +derivations. +.TP +.B -x +Print, marked with +.LR = , +every stem as it is looked up in the spelling list, +along with its affix classes. +.PP +As a matter of policy, +.I spell +does not admit multiple spellings of the same word. +Variants that follow general rules are preferred +over those that don't, even when the unruly spelling is +more common. +Thus, in American usage, `modelled', `sizeable', and `judgment' are +rejected in favor of `modeled', `sizable', and `judgement'. +Agglutinated variants are shunned: `crewmember' and `backyard' +cede to `crew member' and `back yard' (noun) or `back-yard' +(adjective). +.SH FILES +.TF /sys/lib/brspell +.TP +.B /sys/lib/amspell +American spelling list +.TP +.B /sys/lib/brspell +British spelling list +.TP +.B /bin/aux/sprog +The actual spelling checker. +It expects one word per line on standard input, +and takes the same arguments as +.IR spell . +.SH SOURCE +.TF /sys/src/cmd/spell +.TP +.B /rc/bin/spell +the script +.TP +.B /sys/src/cmd/spell +source for +.I sprog +.SH SEE ALSO +.IR deroff (1) +.SH BUGS +The heuristics of +.IR deroff (1) +used to excise formatting information are imperfect. +.br +The spelling list's coverage is uneven; +in particular biology, medicine, and chemistry, and +perforce proper names, +not to mention languages other than English, +are covered very lightly. diff --git a/static/plan9-4e/man1/spin.1 b/static/plan9-4e/man1/spin.1 new file mode 100644 index 00000000..99f99925 --- /dev/null +++ b/static/plan9-4e/man1/spin.1 @@ -0,0 +1,149 @@ +.TH SPIN 1 +.SH NAME +spin \- verification tool for concurrent systems +.SH SYNOPSIS +.B spin +[ +.BI -n N +] +[ +.B -cplgrsmv +] +[ +.B -iat +] +[ +.B -V +] +[ +.I file +] +.SH DESCRIPTION +.I Spin +is a tool for analyzing the logical consistency of +concurrent systems, specifically communication protocols. +The system is specified in a guarded command language called +.SM PROMELA\c +\&. +The language, described in the references, +allows for the dynamic creation of processes, +nondeterministic case selection, loops, gotos, +variables, and the specification of correctness requirements. +The tool has fast algorithms for analyzing arbitrary +liveness and safety conditions. +.PP +Given a model system specified in +.SM PROMELA\c +, +.I spin +can perform interactive, guided, or random simulations +of the system's execution +or it can generate a C program that performs an exhaustive +or approximate verification of the system. +The verifier can check, for instance, if user specified system +invariants are violated during a protocol's execution, or +if non-progress execution cycles exist. +.PP +Without any options the program performs a random simulation of the system +defined in the input +.IR file , +default standard input. +The option +.BI -n N +sets the random seed to the integer value +.IR N . +.PP +The group of options +.B -pglmrsv +is used to set the level of information reported +about the simulation run. +Every line of output normally contains a reference to the source +line in the specification that caused it. +.TP +.B c +Show message send and receive operations in tabular form, but +no other information about the execution. +.TP +.B p +Show at each time step which process changed state and what source +statement was executed. +.TP +.B l +In combination with option +.BR p , +show the current value of local variables of the process. +.TP +.B g +Show the value of global variables at each time step. +.TP +.B r +Show all message-receive events, giving +the name and number of the receiving process +and the corresponding source line number. +For each message parameter, show +the message type and the message channel number and name. +.TP +.B s +Show all message-send events. +.TP +.B m +Ordinarily, a send action will be delayed if the +target message buffer if full. +With this option a message sent to a full buffer is lost. +The option can be combined with +.B -a +(see below). +.TP +.B v +Verbose mode: add extra detail and include more warnings. +.TP +.BI i +Perform an interactive simulation. +.TP +.B a +Generate a protocol-specific verifier. +The output is written into a set of C files, named +.BR pan. [ cbhmt ], +that can be compiled +.RB ( "cc pan.c" ) +to produce an executable verifier. +Systems that require more memory than available +on the target machine can still be analyzed by compiling +the verifier with a bit state space: +.IP +.B " cc -DBITSTATE pan.c +.IP +This collapses the state space to 1 bit per system state, +with minimal side-effects. +Partial order reduction rules normally take effect during the +verification unless the compiler directive +.B -DNOREDUCE +is used. +.IP +The compiled verifiers have their own sets of options, +which can be seen by running them with option +.BR -? . +.TP +.B t +If the verifier finds a violation of a correctness property, +it writes an error trail. +The trail can be inspected in detail by invoking +.I spin +with the +.B -t +option. +In combination with the options +.BR pglrsv , +different views of the error sequence are then be obtained. +.TP +.B V +Print the version number and exit. +.SH SEE ALSO +G.J. Holzmann, +.I +Design and Validation of Computer Protocols, +Prentice Hall, 1991. +.br +\(em, ``Using +.SM SPIN\c +\&''. diff --git a/static/plan9-4e/man1/split.1 b/static/plan9-4e/man1/split.1 new file mode 100644 index 00000000..0f169bc7 --- /dev/null +++ b/static/plan9-4e/man1/split.1 @@ -0,0 +1,76 @@ +.TH SPLIT 1 +.CT 1 files +.SH NAME +split \- split a file into pieces +.SH SYNOPSIS +.B split +[ +.I option ... +] +[ +.I file +] +.SH DESCRIPTION +.I Split +reads +.I file +(standard input by default) +and writes it in pieces of 1000 +lines per output file. +The names of the +output files are +.BR xaa , +.BR xab , +and so on to +.BR xzz . +The options are +.TP +.BI - n +Split into +.IR n -line +pieces. +.TP +.BI -e " expression" +File divisions occur at each line +that matches a regular +.IR expression ; +see +.IR regexp (6). +Multiple +.B -e +options may appear. +If a subexpression of +.I expression +is contained in parentheses +.BR ( ... ) , +the output file name is the portion of the +line which matches the subexpression. +.TP +.BI -f " stem +Use +.I stem +instead of +.B x +in output file names. +.TP +.BI -s " suffix +Append +.I suffix +to names identified under +.BR -e . +.TP +.B -x +Exclude the matched input line from the output file. +.TP +.B -i +Ignore case in option +.BR -e ; +force output file names (excluding the suffix) +to lower case. +.SH SOURCE +.B /sys/src/cmd/split.c +.SH SEE ALSO +.IR sed (1), +.IR awk (1), +.IR grep (1), +.IR regexp (6) diff --git a/static/plan9-4e/man1/src.1 b/static/plan9-4e/man1/src.1 new file mode 100644 index 00000000..f6e22ce9 --- /dev/null +++ b/static/plan9-4e/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 /rc/bin/src +.SH "SEE ALSO" +.IR db (1), +.IR plumb (1), +.IR sam (1). diff --git a/static/plan9-4e/man1/ssh.1 b/static/plan9-4e/man1/ssh.1 new file mode 100644 index 00000000..f2dc79ec --- /dev/null +++ b/static/plan9-4e/man1/ssh.1 @@ -0,0 +1,338 @@ +.TH SSH 1 +.SH NAME +ssh, sshnet, scp, sshserve, ssh_genkey \- secure login and file copy from/to Unix or Plan 9 +.SH SYNOPSIS +.B ssh +[ +.B -CiImPprvw +] +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -[lu] +.I user +] +.RI [ user\fB@ ] host +[ +.I cmd +[ +.I args +\&... ]] +.PP +.B sshnet +[ +.B -A +.I authlist +] +[ +.B -c +.I cipherlist +] +[ +.B -m +.I mtpt +] +.RI [ user\fB@ ] host +.PP +.B scp +[host:]file [host:]file +.br +.B scp +[host:]file ... [host:]dir +.PP +.B aux/sshserve +[ +.B -p +] +.I address +.PP +.B aux/ssh_genkey +[ +.I basename +] +.SH DESCRIPTION +.I Ssh +allows authenticated login over an encrypted channel to hosts that +support the ssh protocol (see the RFC listed below for encryption and +authentication details). +.LP +.I Ssh +takes the host name of the machine to connect to as its mandatory argument. +It may be specified as a domain name or an IP address. +Normally, login is attempted using the user name from /dev/user. +.PP +Command-line options are: +.TP +.B -C +force input to be read in cooked mode: +``line at a time'' with local echo. +.TP +.B -i +force interactive mode. +In interactive mode, +.I ssh +prompts for passwords and confirmations of +new host keys when necessary. +(In non-interactive mode, password requests +are rejected and unrecognized host keys are +cause for disconnecting.) +By default, +.I ssh +runs in interactive mode only when its +input file descriptor is +.BR /dev/cons . +.TP +.B -I +force non-interactive mode. +.TP +.B -m +disable the +.RB control- \e +menu, described below. +.TP +.B -p +force pseudoterminal request. +The +.I ssh +protocol, grounded in Unix tradition, +differentiates between connections +that request controlling pseudoterminals +and those that do not. +By default, +.I ssh +requests a pseudoterminal only when no +.I command +is given. +.TP +.B -P +force no pseudoterminal request. +.TP +.B -r +strip carriage returns. +.TP +.B -v +enable verbose feedback during the connection and authentication process. +.TP +.B -w +notify the remote side whenever the window changes size. +.TP +.BR - [ lu ] "\fI user +specify user name. +This option is deprecated in favor of the +.IB user @ hostname +syntax. +.TP +.B "-A\fI authlist +specify an ordered space-separated list of authentication protocols to try. +The full set of authentication protocols is +.B rsa +(RSA using +.IR factotum (4) +to moderate key usage), +.B password +(use a password gathered from factotum), +and +.B tis +(challenge-response). +The default list is all three in that order. +.TP +.B "-c\fI cipherlist +specify an ordered space-separated list of allowed ciphers to use when encrypting the channel. +The full set of ciphers is +.B des +(standard DES), +.B 3des +(a somewhat doubtful variation on triple DES), +.B blowfish +(Bruce Schneier's Blowfish), +.B rc4 +(RC4), +and +.B none +(no encryption). +The default cipher list is +.B blowfish +.B rc4 +.BR 3des . +.PD +.PP +The +.RB control\- \e +character is a local escape, as in +.IR con (1). +It prompts with +.BR >>> . +Legitimate responses to the prompt are +.TP +.B q +Exit. +.TP +.B . +Return from the escape. +.TP +.B !cmd +Run the command with the network connection as its +standard input and standard output. +Standard error will go to the screen. +.TP +.B r +Toggle printing of carriage returns. +.PD +.LP +If no command is specified, +a login session is started on the remote +host. +Otherwise, the command is executed with its arguments. +.LP +.I Ssh +establishes a connection with an ssh daemon on the remote host. +The daemon sends to +.I ssh +its RSA public host key and session key. +Using these, +.I ssh +sends a session key which, presumably, only the +daemon can decipher. After this, both sides start encrypting their +data with this session key. +.LP +When the daemon's host key has been received, +.I ssh +looks it up in +.B $home/lib/keyring +and in +.BR /sys/lib/ssh/keyring . +If +the key is found there, and it matches the received key, +.I ssh +is satisfied. If not, +.I ssh +reports this and offers to add the key to +.BR $home/lib/keyring . +.LP +Over the encrypted channel, +.I ssh +attempts to convince the daemon to accept the call +using the listed authentication protocols +(see the +.B -A +option above). +.LP +The preferred way to authenticate is a +.IR netkey -style +challenge/response or via a SecurID token. +.I Ssh +users on other systems than Plan 9 should enable \s-2TIS_A\s0uthentication. +.LP +When the connection is authenticated, the given command line, +(by default, a login shell) is executed on the remote host. +.sp 1 +The SSH protocol allows clients to make outgoing TCP calls via the server. +.I Sshnet +establishes an SSH connection and, rather than execute a remote command, +presents the remote server's TCP stack as a network stack +(see the discussion of TCP in +.IR ip (3)) +mounted at +.I mtpt +(default +.BR /net ). +The +.B -A +and +.B -c +arguments are as in +.IR ssh . +.sp 1 +.I Scp +uses +.I ssh +to copy files from one host to another. A remote file is identified by +a host name, a colon and a file name (no spaces). +.I Scp +can copy files from remote hosts and to remote hosts. +.sp 1 +.I Sshserve +is the server that services +.I ssh +calls from remote hosts. +The +.B -A +and +.B -c +options set valid authentication methods and ciphers +as in +.IR ssh , +except that there is no +.B rsa +authentication method. +Unlike in +.IR ssh , +the list is not ordered: the server presents a set and the client makes the choice. +The default sets are +.B tis +and +.B blowfish +.B rc4 +.BR 3des . +By default, users start with the namespace defined in +.BR /lib/namespace . +Users in group +.B noworld +in +.B /adm/users +start with the namespace defined in +.BR /lib/namespace.noworld . +.I Sshserve +does not provide the TCP forwarding functionality used +by +.IR sshnet , +because many Unix clients present +this capability in an insecure manner. +.PP +.I Ssh_genkey +generates an RSA key set, writing the +private key to +.IB basename .secret +and the public key to +.IB basename .public\fR. +.I Ssh_genkey +also writes +a secret key in the style expected by factotum +to +.IB basename .secret.factotum\fR. +The default +.B basename +is +.BR /sys/lib/ssh/hostkey , +so running it with no arguments +will generate an RSA key set +for the file server in use. +.SH FILES +.TF /sys/lib/ssh/hostkey.public +.TP +.B /sys/lib/ssh/hostkey.public +Public key for the host on which the program runs. +.TP +.B /sys/lib/ssh/hostkey.secret +Secret key for the host on which the program runs. This file must +be owned and be readable by bootes only. +.TP +.B /sys/lib/ssh/keyring +System keyring file containing public keys for remote ssh clients and servers. +.TP +.B /usr/\fIuser\fP/lib/keyring +Personal keyring file containing public keys for remote ssh clients and +servers. +.SH SOURCE +.B /sys/src/cmd/ssh +.SH "SEE ALSO" +.IR /sys/src/cmd/ssh/RFC* +.br +.IR factotum (4), +.IR authsrv (6) diff --git a/static/plan9-4e/man1/stop.1 b/static/plan9-4e/man1/stop.1 new file mode 100644 index 00000000..46e88772 --- /dev/null +++ b/static/plan9-4e/man1/stop.1 @@ -0,0 +1,36 @@ +.TH STOP 1 +.SH NAME +stop, start \- print commands to stop and start processes +.SH SYNOPSIS +.B stop +.I name +.PP +.B start +.I name +.SH DESCRIPTION +.I Stop +prints commands that will cause all processes called +.I name +and owned by the current user to be stopped. +The processes can then be debugged when they are in a consistent state. +.PP +.I Start +prints commands that will cause all stopped processes called +.I name +and owned by the current user to be started again. +.PP +Use the +.B send +command of +.IR rio (1), +or pipe into +.IR rc (1) +to execute the commands. +.SH SOURCE +.B /rc/bin/stop +.br +.B /rc/bin/start +.SH "SEE ALSO" +.IR ps (1), +.IR kill (1), +.IR proc (3) diff --git a/static/plan9-4e/man1/strings.1 b/static/plan9-4e/man1/strings.1 new file mode 100644 index 00000000..d72ffbb1 --- /dev/null +++ b/static/plan9-4e/man1/strings.1 @@ -0,0 +1,28 @@ +.TH STRINGS 1 +.SH NAME +strings \- extract printable strings +.SH SYNOPSIS +.B strings +[ +.I file ... +] +.SH DESCRIPTION +.I Strings +finds and prints strings containing 6 or more +consecutive printable UTF-encoded characters +in a (typically) binary file, default +standard input. +Printable characters are taken to be +.SM ASCII +characters from blank through tilde (hexadecimal 20 through 7E), inclusive, +and +all other characters from value 00A0 to FFFF. +Strings reports +the decimal offset within the file at which the string starts and the text +of the string. If the string is longer than 70 runes the line is +terminated by three dots and the printing is resumed on the next +line with the offset of the continuation line. +.SH SOURCE +.B /sys/src/cmd/strings.c +.SH SEE ALSO +.IR nm (1) diff --git a/static/plan9-4e/man1/strip.1 b/static/plan9-4e/man1/strip.1 new file mode 100644 index 00000000..bed917b1 --- /dev/null +++ b/static/plan9-4e/man1/strip.1 @@ -0,0 +1,19 @@ +.TH STRIP 1 +.SH NAME +strip \- remove symbols from binary files +.SH SYNOPSIS +.B strip +[ +.I file ... +] +.SH DESCRIPTION +.I Strip +removes symbol table segments from executable files, rewriting the files in place. +Stripping a file requires write permission of the file +and the directory it is in. +If no file is given, +standard input is stripped and the result written to standard output. +.SH SOURCE +.B /sys/src/cmd/strip.c +.SH "SEE ALSO" +.IR a.out (6) diff --git a/static/plan9-4e/man1/sum.1 b/static/plan9-4e/man1/sum.1 new file mode 100644 index 00000000..d981c8c7 --- /dev/null +++ b/static/plan9-4e/man1/sum.1 @@ -0,0 +1,77 @@ +.TH SUM 1 +.SH NAME +sum, md5sum, sha1sum \- sum and count blocks in a file +.SH SYNOPSIS +.B sum +[ +.B -5r +] +[ +.I file ... +] +.PP +.B md5sum +[ +.I file ... +] +.PP +.B sha1sum +[ +.I file ... +] +.SH DESCRIPTION +By default, +.I sum +calculates and prints a 32-bit hexadecimal checksum, +a byte count, +and the name of +each +.IR file . +The checksum is also a function of the input length. +If no files are given, +the standard input is +summed. +Other summing algorithms are available. +The options are +.TP +.B -r +Sum with the algorithm of System V's +.B "sum -r" +and print the length (in 1K blocks) of the input. +.TP +.B -5 +Sum with System V's default algorithm +and print the length (in 512-byte blocks) of the input. +.PP +.I Sum +is typically used to look for bad spots, +to validate a file communicated over +some transmission line or +as a quick way to determine if two files on different machines might be the same. +.PP +.B Md5sum +computes the 32 hex digit RSA Data Security, Inc. MD5 Message-Digest Algorithm +described in RFC1321. +If no +.I files +are given, +the standard input is +summed. +.PP +.B Sha1sum +computes the 40 hex digit National Institute of Standards and Technology SHA1 secure hash algorithm +described in FIPS PUB 180-1. +If no +.I files +are given, +the standard input is +summed. +.SH SOURCE +.B /sys/src/cmd/sum.c +.br +.B /sys/src/cmd/md5sum.c +.br +.B /sys/src/cmd/sha1sum.c +.SH "SEE ALSO" +.IR cmp (1), +.IR wc (1) diff --git a/static/plan9-4e/man1/syscall.1 b/static/plan9-4e/man1/syscall.1 new file mode 100644 index 00000000..18746c67 --- /dev/null +++ b/static/plan9-4e/man1/syscall.1 @@ -0,0 +1,77 @@ +.TH SYSCALL 1 +.SH NAME +syscall \- test a system call +.SH SYNOPSIS +.B syscall +[ +.B -osx +] +.I entry +[ +.I arg ... +] +.SH DESCRIPTION +.I Syscall +invokes the system call +.I entry +with the given arguments. +(Some functions, such as +.I write +and +.IR read (2), +although not strictly system calls, are valid +.IR entries .) +It prints the return value and the error string, if there was an error. +An argument is either an integer constant as in C (its value is passed), +a string (its address is passed), +or the literal +.B buf +(a pointer to a 1 Kbyte buffer is passed). +.PP +If +.B -o +is given, the contents of the 1 Kbyte buffer are printed as a zero-terminated string +after the system call is done. +The +.B -x +and +.B -s +options are similar, but +.B -x +formats the data as hexadecimal bytes, while +.B -s +interprets the data as a +.IR stat (5) +message and formats it similar to the style of +.B ls +.B -lqm +(see +.IR ls (1)), +with extra detail about the modify and access times. +.SH EXAMPLES +Write a string to standard output: +.IP +.EX +syscall write 1 hello 5 +.EE +.PP +Print information about the file connected to standard input: +.IP +.EX +syscall -s fstat 0 buf 1024 +.EE +.SH SOURCE +.B /sys/src/cmd/syscall +.SH "SEE ALSO" +Section 2 of this manual. +.SH DIAGNOSTICS +If +.I entry +is not known to +.IR syscall , +the exit status is +.LR unknown . +If the system call succeeds, the exit status is null; +otherwise the exit status is the string that +.IR errstr (2) +returns. diff --git a/static/plan9-4e/man1/tail.1 b/static/plan9-4e/man1/tail.1 new file mode 100644 index 00000000..b2d880b6 --- /dev/null +++ b/static/plan9-4e/man1/tail.1 @@ -0,0 +1,87 @@ +.TH TAIL 1 +.SH NAME +tail \- deliver the last part of a file +.SH SYNOPSIS +.B tail +[ +.BR +- \fInumber\fP[ lbc ][ rf ] +] +[ +.I file +] +.PP +.B tail +[ +.B -fr +] +[ +.B -n +.I nlines +] +[ +.B -c +.I nbytes +] +[ +.I file +] +.SH DESCRIPTION +.I Tail +copies the named file to the standard output beginning +at a designated place. +If no file is named, the standard input is copied. +.PP +Copying begins at position +.BI + number +measured from the beginning, or +.BI - number +from the end of the input. +.I Number +is counted in lines, 1K blocks or bytes, +according to the appended flag +.LR l , +.LR b , +or +.LR c . +Default is +.B -10l +(ten ell). +.PP +The further flag +.L r +causes tail to print lines from the end of the file in reverse order; +.L f +(follow) causes +.IR tail , +after printing to the end, to keep watch and +print further data as it appears. +.PP +The second syntax is that promulgated by POSIX, where +the +.I numbers +rather than the options are signed. +.SH EXAMPLES +.TP +.B tail file +Print the last 10 lines of a file. +.TP +.B tail +0f file +Print a file, and continue to watch +data accumulate as it grows. +.TP +.B sed 10q file +Print the first 10 lines of a file. +.SH SOURCE +.B /sys/src/cmd/tail.c +.SH BUGS +Tails relative to the end of the file +are treasured up in a buffer, and thus +are limited in length. +.br +According to custom, option +.BI + number +counts lines from 1, and counts +blocks and bytes from 0. +.br +.I Tail +is ignorant of UTF. diff --git a/static/plan9-4e/man1/tapefs.1 b/static/plan9-4e/man1/tapefs.1 new file mode 100644 index 00000000..7e3cc630 --- /dev/null +++ b/static/plan9-4e/man1/tapefs.1 @@ -0,0 +1,100 @@ +.TH TAPEFS 1 +.SH NAME +32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs \- mount archival file systems +.SH SYNOPSIS +.B fs/32vfs +[ +.B -m +.I mountpoint +] +[ +.B -p +.I passwd +] +[ +.B -g +.I group +] +.I file +.br +.B fs/cpiofs +.br +.B fs/tapfs +.br +.B fs/tarfs +.br +.B fs/tpfs +.br +.B fs/v6fs +.br +.B fs/v10fs +.br +.SH DESCRIPTION +These commands interpret data from traditional tape or file system formats +stored in +.IR file , +and mount their contents (read-only) into a Plan 9 file system. +The optional +.B -p +and +.B -g +flags specify Unix-format password (respectively group) files +that give the mapping between the numeric user- and group-ID +numbers on the media and the strings reported by Plan 9 status +inquiries. +The +.B -m +flag introduces the name at which the new file system should be +attached; the default is +.BR /n/tapefs . +.PP +.I 32vfs +interprets raw disk images of 32V systems, which are ca. 1978 research Unix systems for +the VAX, and also pre-FFS Berkeley VAX systems (1KB block size). +.PP +.I Cpiofs +interprets +.B cpio +tape images (constructed with +.BI cpio 's +.B c +flag). +.PP +.I Tarfs +interprets +.I tar +tape images. +.PP +.I Tpfs +interprets +.I tp +tapes from the Fifth through Seventh Edition research Unix systems. +.PP +.I Tapfs +interprets +.I tap +tapes from the pre-Fifth Edition era. +.PP +.I V6fs +interprets disk images from the +Fifth and Sixth edition research Unix systems (512B block size). +.PP +.I V10fs +interprets disk images from the +Tenth Edition research Unix systems (4KB block size). +.SH SOURCE +.PP +These commands are constructed in a highly stereotyped +way using the files +.I fs.c +and +.I util.c +in +.BR /sys/src/cmd/tapefs , +which in +turn derive substantially from +.IR ramfs (4). +.SH "SEE ALSO +Section 5 +.IR passim , +.IR ramfs (4). diff --git a/static/plan9-4e/man1/tar.1 b/static/plan9-4e/man1/tar.1 new file mode 100644 index 00000000..c0e25ba5 --- /dev/null +++ b/static/plan9-4e/man1/tar.1 @@ -0,0 +1,110 @@ +.TH TAR 1 +.SH NAME +tar \- archiver +.SH SYNOPSIS +.B tar +.I key +[ +.I file ... +] +.SH DESCRIPTION +.PP +.I Tar +saves and restores file trees. +It is most often used to transport a tree of files from one +system to another. +The +.I key +is a string that contains +at most one function letter plus optional modifiers. +Other arguments to the command are names of +files or directories to be dumped or restored. +A directory name implies all the contained +files and subdirectories (recursively). +.PP +The function is one of the following letters: +.TP +.B c +Create a new archive with the given files as contents. +.TP +.B x +Extract the named files from the archive. +If a file is a directory, the directory is extracted recursively. +Modes are restored if possible. +If no file argument is given, extract the entire archive. +If the archive contains multiple entries for a file, +the latest one wins. +.TP +.B t +List all occurrences of each +.I file +in the archive, or of all files if there are no +.I file +arguments. +.TP +.B r +The named files +are appended to the archive. +.PP +The modifiers are: +.TP +.B v +(verbose) +Print the name of each file treated +preceded by the function letter. +With +.BR t , +give more details about the +archive entries. +.TP +.B f +Use the next argument as the name of the archive instead of +the default standard input (for keys +.B x +and +.BR t ) +or standard output (for keys +.B c +and +.BR r ). +.TP +.B u +Use the next (numeric) argument as the user id for files in +the output archive. This is only useful when moving files to +a non-Plan 9 system. +.TP +.B g +Use the next (numeric) argument as the group id for files in +the output archive. +.TP +.B R +When extracting, ignore leading slash on file names, +i.e., extract all files relative to the current directory. +.TP +.B T +Modifies the behavior of +.B x +to set the mode and modified time +of each file to that specified in the archive. +.SH EXAMPLES +.I Tar +can be used to copy hierarchies thus: +.IP +.EX +{cd fromdir && tar c .} | {cd todir && tar xT} +.EE +.SH SOURCE +.B /sys/src/cmd/tar.c +.SH SEE ALSO +.IR ar (1), +.IR bundle (1), +.IR tapefs (1) +.SH BUGS +There is no way to ask for any but the last +occurrence of a file. +.br +File path names are limited to +100 characters. +.br +The tar format allows specification of links and symbolic links, +concepts foreign to Plan 9: they are ignored. diff --git a/static/plan9-4e/man1/tbl.1 b/static/plan9-4e/man1/tbl.1 new file mode 100644 index 00000000..921e9e85 --- /dev/null +++ b/static/plan9-4e/man1/tbl.1 @@ -0,0 +1,285 @@ +.TH TBL 1 +.SH NAME +tbl \- format tables for nroff or troff +.SH SYNOPSIS +.B tbl +[ +.I file ... +] +.SH DESCRIPTION +.I Tbl +is a preprocessor for formatting tables for +.I nroff +or +.IR troff (1). +The input +.I files +are copied to the standard output, +except for segments of the form +.IP +.nf +.B .TS +.IB options " ; +.IB format " . +.I data +.B .T& +.IB format " . +.I data +\&. . . +.B .TE +.fi +.LP +which describe tables +and are replaced by +.I troff +requests to lay out the tables. +If no arguments are given, +.I tbl +reads the standard input. +.PP +The (optional) +.I options +line is terminated by a semicolon and contains one or more +of +.RS +.TF linesize(n) +.TP +.B center +center the table; default is left-adjust +.TP +.B expand +make table as wide as current line length +.TP +.B box +.TP +.B doublebox +enclose the table in a box or double box +.TP +.B allbox +enclose every item in a box +.TP +.BI tab( x ) +use +.I x +to separate input items; default is tab +.TP +.BI linesize( n ) +set rules in +.IR n -point +type +.TP +.BI delim( xy ) +recognize +.I x +and +.I y +as +.IR eqn (1) +delimiters +.PD +.RE +.PP +Each line, except the last, of the obligatory +.I format +describes one row of the table. +The last line describes all rows until the next +.BR .T& , +where the format changes, +or the end of the table at +.BR .TE . +A format is specified by key letters, one per column, either upper or lower case: +.RS +.TP 0 +.B L +Left justify: the default for +columns without format keys. +.PD0 +.TP +.B R +Right justify. +.TP +.B C +Center. +.TP +.B N +Numeric: align at decimal point (inferred for integers) or at +.LR \e& . +.TP +.B S +Span: extend previous column across this one. +.TP +.B A +Alphabetic: left-aligned within column, widest item centered, indented relative to +.B L +rows. +.TP +.B ^ +Vertical span: continue item from previous row into this row. +.TP +.B - +Draw a horizontal rule in this column. +.TP +.B = +Draw a double horizontal rule in this column. +.PD +.RE +.PP +Key letters may be followed by modifiers, also either case: +.RS +.TP \w'\fLF\fIfont\fLXX'u +.B | +Draw vertical rule between columns. +.PD0 +.TP +.B || +Draw a double vertical rule between columns. +.TP +.I n +Gap between column is +.I n +ens wide. +Default is 3. +.TP +.BI F font +Use specified +.IR font . +.B B +and +.B I +mean +.B FB +and +.BR FI . +.TP +.B T +Begin vertically-spanned item at top row of range; default is +vertical centering (with +.LR ^ ). +.TP +.BI P n +Use point size +.IR n . +.TP +.BI V n +Use +.IR n -point +vertical spacing in text block; signed +.I n +means relative change. +.TP +.BI W( n ) +Column width as a +.I troff +width specification. +Parens are optional if +.I n +is a simple integer. +.TP +.B E +Equalize the widths of all columns marked +.BR E . +.PD +.RE +.PP +Each line of +.I data +becomes one row of the table; tabs separate items. +Lines beginning with +.L . +are +.I troff +requests. +Certain special data items are recognized: +.RS +.TP 0 +.B _ +Draw a horizontal rule in this column. +.PD0 +.TP +.B = +Draw a double horizontal rule in this column. +A data line consisting of a single +.L _ +or +.L = +draws the rule across the whole table. +.TP +.B \e_ +Draw a rule only as wide as the contents of the column. +.TP +.BI \eR x +Repeat character +.I x +across the column. +.TP +.B \e^ +Span the previous item in this column down into this row. +.TP +.B T{ +The item is a text block to be separately formatted +by +.I troff +and placed in the table. +The block continues to the next line beginning with +.BR T} . +The remainder of the data line follows at that point. +.PD +.RE +.PP +When it is used in a pipeline with +.IR eqn , +the +.I tbl +command should be first, to minimize the volume +of data passed through +pipes. +.SH EXAMPLES +.ds tb \fR\fP +Let \*(tb +represent a tab (which should +be typed as a genuine tab). +.if t .2C +.EX +\&.TS +c s s +c c s +c c c +l n n. +Household Population +Town\*(tbHouseholds +\*(tbNumber\*(tbSize +Bedminster\*(tb789\*(tb3.26 +Bernards Twp.\*(tb3087\*(tb3.74 +Bernardsville\*(tb2018\*(tb3.30 +\&.TE +.if t \{\0 +\0 +\0\} +.if n .PP +.TS +c s s +c c s +c c c +l n n. +Household Population +Town Households + Number Size +Bedminster 789 3.26 +Bernards Twp. 3087 3.74 +Bernardsville 2018 3.30 +.TE +.EE +.if t \{.sp3 +.1C\} +.SH SOURCE +.B /sys/src/cmd/tbl +.SH SEE ALSO +.IR troff (1), +.IR eqn (1), +.IR doctype (1) +.br +M. E. Lesk and L. L. Cherry, +``TBL\(ema Program to Format Tables'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/static/plan9-4e/man1/tcs.1 b/static/plan9-4e/man1/tcs.1 new file mode 100644 index 00000000..51b76a7d --- /dev/null +++ b/static/plan9-4e/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 (6). +The +.B -l +option lists the character sets known to +.IR tcs . +Processing continues in the face of conversion errors (the +.B -s +option prevents reporting of these errors). +The +.B -c +option forces the output to contain only correctly converted characters; +otherwise, +.B 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 /sys/src/cmd/tcs +.SH SEE ALSO +.IR ascii (1), +.IR rune (2), +.IR utf (6). diff --git a/static/plan9-4e/man1/tee.1 b/static/plan9-4e/man1/tee.1 new file mode 100644 index 00000000..d237fb7f --- /dev/null +++ b/static/plan9-4e/man1/tee.1 @@ -0,0 +1,28 @@ +.TH TEE 1 +.SH NAME +tee \- pipe fitting +.SH SYNOPSIS +.B tee +[ +.B -i +] +[ +.B -a +] +.I files +.SH DESCRIPTION +.I Tee +transcribes the standard input to the standard +output and makes copies in the +.IR files . +The options are +.TP +.B -i +Ignore interrupts. +.TP +.B -a +Append the output to the +.I files +rather than rewriting them. +.SH SOURCE +.B /sys/src/cmd/tee.c diff --git a/static/plan9-4e/man1/tel.1 b/static/plan9-4e/man1/tel.1 new file mode 100644 index 00000000..5774255d --- /dev/null +++ b/static/plan9-4e/man1/tel.1 @@ -0,0 +1,110 @@ +.TH TEL 1 +.SH NAME +tel, ppq, iwhois \- look in phone book +.SH SYNOPSIS +.B tel +.I key ... +.PP +.B p +.RB [ -f ] +.I value +.PP +.B ppq +.RB [ -f ] +.IR attribute = value +.PP +.B iwhois +.IR name [ \fL@\f2domain ] +.SH DESCRIPTION +.I Tel +looks up +.I key +in a private telephone book, +.BR $home/lib/tel , +and in the public telephone book, +.BR /lib/tel . +It uses +.IR grep +(with the +.B -i +option to ignore case differences), so the key may be any part of a +name or number. Customarily, the telephone book contains names, +userids, home numbers, and office numbers of users. It also contains +a directory of area codes and miscellaneous people of general +interest. +.PP +.I Ppq +looks up entries in the Lucent personnel database. +Each search is against a single attribute. The +possible search attributes are: +.IP tel +a telephone number. +An entry matches if its telephone number ends in the +digits given in +.IR value . +.IP name +a proper name. +.I Value +must contain a family name, optionally prefixed +with first and middle names or initials separated by '.'s. +For example, emlin, grace.emlin, g.r.emlin can +can be used to look up Grace Roosevelt Emlin. +.IP org +an organization name. +.I Value +can be any prefix string of an organization number. +For example, +.B bl011 +looks up everyone in research while +.B bl011273 +looks up everyone in a single department. +.IP id +a post id. +.I Value +must exactly match the post id. +.PP +The attribute can be explicitly declared, e.g. +.BR tel=5551212 , +or can be inferred from the form of the value using the following criteria: +.IP 1) +A +.I value +containing a '.' implies a name. +.IP 2) +Nothing but digits, '+', and '-' implies a telephone number. +.IP 3) +A mix of digits and letters implies an organization. +.IP 4) +Anything else implies two searches, first with the attribute +.B id +and if that fails, with attribute +.BR name . +.PP +With no flags, +.I ppq +returns for each match a single line containing +the employee's name, title, organization, location, room, telephone number, +and email address. +With +.BR \-f , +.I ppq +returns a fuller multiline entry for each match. +.PP +.I Iwhois +looks up names in the Internet NIC's personnel database. +.I Name +should be a surname optionally followed by a comma and given name. +A different server can be chosen by appending to the name an +.B @ +followed by the server's domain name. +.SH FILES +.TF /lib/tel +.TP +.B /lib/tel +Public telephone number database. +.SH SOURCE +.B /rc/bin/tel +.br +.B /rc/bin/iwhois +.br +.B /sys/src/cmd/ppq.c diff --git a/static/plan9-4e/man1/test.1 b/static/plan9-4e/man1/test.1 new file mode 100644 index 00000000..7de80217 --- /dev/null +++ b/static/plan9-4e/man1/test.1 @@ -0,0 +1,174 @@ +.TH TEST 1 +.SH NAME +test \- set status according to condition +.SH SYNOPSIS +.B test +.I expr +.SH DESCRIPTION +.I Test +evaluates the expression +.IR expr . +If the value is true the exit status is null; otherwise the +exit status is non-null. +If there are no arguments the exit status is non-null. +.PP +The following primitives are used to construct +.IR expr . +.TP "\w'\fIn1 \fL-eq \fIn2\fLXX'u" +.BI -r " file" +True if the file exists (is accessible) and is readable. +.PD0 +.TP +.BI -w " file" +True if the file exists and is writable. +.TP +.BI -x " file" +True if the file exists and has execute permission. +.TP +.BI -e " file +True if the file exists. +.TP +.BI -f " file" +True if the file exists and is a plain file. +.TP +.BI -d " file" +True if the file exists and is a directory. +.TP +.BI -s " file" +True if the file exists and has a size greater than zero. +.TP +.BI -t " fildes +True if the open file whose file descriptor number is +.I fildes +(1 by default) +is the same file as +.BR /dev/cons . +.TP +.BI -A " file" +True if the file exists and is append-only. +.TP +.BI -L " file" +True if the file exists and is exclusive-use. +.TP +.IB s1 " = " s2 +True +if the strings +.I s1 +and +.I s2 +are identical. +.TP +.IB s1 " != " s2 +True +if the strings +.I s1 +and +.I s2 +are not identical. +.TP +s1 +True if +.I s1 +is not the null string. +(Deprecated.) +.TP +.BI -n " s1" +True if the length of string +.I s1 +is non-zero. +.TP +.BI -z " s1" +True if the length of string +.I s1 +is zero. +.TP +.IB n1 " -eq " n2 +True if the integers +.I n1 +and +.I n2 +are arithmetically equal. +Any of the comparisons +.BR -ne , +.BR -gt , +.BR -ge , +.BR -lt , +or +.BR -le +may be used in place of +.BR -eq . +The (nonstandard) construct +.BI -l " string\f1, +meaning the length of +.IR string , +may be used in place of an integer. +.PD +.PP +These primaries may be combined with the +following operators: +.TP "\w'\fL( \fIexpr\fL )XX'u" +.B ! +unary negation operator +.PD0 +.TP +.B -o +binary +.I or +operator +.TP +.B -a +binary +.I and +operator; higher precedence than +.BR -o +.TP +.BI "( " expr " )" +parentheses for grouping. +.PD +.PP +The primitives +.BR -b , +.BR -u , +.BR -g , +and +.BR -s +return false; they are recognized for compatibility with POSIX. +.PP +Notice that all the operators and flags are separate +arguments to +.IR test . +Notice also that parentheses and equal signs are meaningful +to +.I rc +and must be enclosed in quotes. +.SH EXAMPLES +.I Test +is a dubious way to check for specific character strings: +it uses a process to do what an +.IR rc (1) +match or switch statement can do. +The first example is not only inefficient but wrong, because +.I test +understands the purported string +.B \&"-c" +as an option. +.IP +.EX +if (test $1 '=' "-c") echo OK # wrong! +.EE +.LP +A better way is +.IP +.EX +if (~ $1 -c) echo OK +.EE +.PP +Test whether +.L abc +is in the current directory. +.IP +.B test -f abc -o -d abc +.SH SOURCE +.B /sys/src/cmd/test.c +.SH "SEE ALSO" +.IR rc (1) diff --git a/static/plan9-4e/man1/time.1 b/static/plan9-4e/man1/time.1 new file mode 100644 index 00000000..2c6b834b --- /dev/null +++ b/static/plan9-4e/man1/time.1 @@ -0,0 +1,21 @@ +.TH TIME 1 +.SH NAME +time \- time a command +.SH SYNOPSIS +.B time +.I command +[ +.I arg ... +] +.SH DESCRIPTION +The +.I command +is executed with the given arguments; after it is complete, +.I time +reports on standard error the program's elapsed user time, +system time, and real time, in seconds, +followed by the command line. +.SH SOURCE +.B /sys/src/cmd/time.c +.SH "SEE ALSO" +.IR prof (1) diff --git a/static/plan9-4e/man1/touch.1 b/static/plan9-4e/man1/touch.1 new file mode 100644 index 00000000..ac5937ec --- /dev/null +++ b/static/plan9-4e/man1/touch.1 @@ -0,0 +1,35 @@ +.TH TOUCH 1 +.SH NAME +touch \- set modification date of a file +.SH SYNOPSIS +.B touch +[ +.B -c +] +[ +.B -t +.I time +] +.I file ... +.SH DESCRIPTION +.I Touch +attempts to set the modification time of the +.I files +to +.I time +(by default, the current time). +If a +.I file +does not exist, +it will be created unless option +.B -c +is present. +.SH SOURCE +.B /sys/src/cmd/touch.c +.SH SEE ALSO +.IR ls (1), +.IR stat (2), +.IR chmod (1) +.SH BUGS +.I Touch +will not touch directories. diff --git a/static/plan9-4e/man1/tr.1 b/static/plan9-4e/man1/tr.1 new file mode 100644 index 00000000..0e11f5b9 --- /dev/null +++ b/static/plan9-4e/man1/tr.1 @@ -0,0 +1,97 @@ +.TH TR 1 +.SH NAME +tr \- translate characters +.SH SYNOPSIS +.B tr +[ +.B -cds +] +[ +.I string1 +[ +.I string2 +] +] +.SH DESCRIPTION +.I Tr +copies the standard input to the standard output with +substitution or deletion of selected characters (runes). +Input characters found in +.I string1 +are mapped into the corresponding characters of +.IR string2 . +When +.I string2 +is short it is padded to the length of +.I string1 +by duplicating its last character. +Any combination of the options +.B -cds +may be used: +.TP +.B -c +Complement +.IR string1 : +replace it with a lexicographically ordered +list of all other characters. +.TP +.B -d +Delete from input all characters in +.IR string1 . +.TP +.B -s +Squeeze repeated output characters that occur in +.I string2 +to single characters. +.PP +In either string a noninitial sequence +.BI - x\f1, +where +.I x +is any character (possibly quoted), stands for +a range of characters: +a possibly empty sequence of codes running from +the successor of the previous code up through +the code for +.IR x . +The character +.L \e +followed by 1, 2 or 3 octal digits stands for the +character whose +16-bit +value is given by those digits. +The character sequence +.L \ex +followed by 1, 2, 3, or 4 hexadecimal digits stands +for the character whose +16-bit value is given by those digits. +A +.L \e +followed by any other character stands +for that character. +.SH EXAMPLES +Replace all upper-case +.SM ASCII +letters by lower-case. +.IP +.EX +tr A-Z a-z lower +.EE +.PP +Create a list of all +the words in +.L file1 +one per line in +.LR file2 , +where a word is taken to be a maximal string of alphabetics. +.I String2 +is given as a quoted newline. +.IP +.EX +tr -cs A-Za-z ' +\&' file2 +.EE +.SH SOURCE +.B /sys/src/cmd/tr.c +.SH "SEE ALSO" +.IR sed (1) diff --git a/static/plan9-4e/man1/troff.1 b/static/plan9-4e/man1/troff.1 new file mode 100644 index 00000000..db5b9e6f --- /dev/null +++ b/static/plan9-4e/man1/troff.1 @@ -0,0 +1,198 @@ +.TH TROFF 1 +.SH NAME +troff, nroff \- text formatting and typesetting +.SH SYNOPSIS +.B troff +[ +.I option ... +] +[ +.I file ... +] +.PP +.B nroff +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I Troff +formats text in the named +.I files +for +printing on a typesetter. +.I Nroff +does the same, but produces output suitable +for typewriter-like devices. +.PP +If no +.I file +argument is present, the standard input is read. +An argument consisting of a single minus +.RB ( - ) +is taken to be +a file name corresponding to the standard input. +The options are: +.nr xx \w'\fL-m\f2name\ \ ' +.TP \n(xxu +.BI -o list +Print pages in the comma-separated +.I list +of numbers and ranges. +A range +.IB N - M +means +.I N +through +.IR M ; +initial +.BI - M +means up to +.IR M ; +final +.IB N - +means from +.I N +to the end. +.TP +.BI -n N +Number first generated page +.IR N . +.TP +.BI -m name +Process the macro file +.BI /sys/lib/tmac/tmac. name +before the input +.IR files . +.TP +.BI -r aN +Set register +.I a +(one character name) to +.IR N . +.TP +.B -i +Read standard input after the input files are exhausted. +.TP +.B -q +Invoke the simultaneous input-output mode of the +.B rd +request. +.TP +.B -N +Produce output suitable for typewriter-like devices. +.SS Typesetter devices (not \fL-N\fP) only +.TP \n(xxu +.B -a +Send a printable +textual +approximation +of the results to the standard output. +.TP +.BI -T dest +Prepare output for typesetter +.IR dest : +.br +.ns +.RS +.TP \w'\fL-TLatin1\ 'u +.B -Tutf +(The default.) PostScript printers with +preprocessing to handle Unicode +characters encoded in +.SM UTF +.PD0 +.TP +.B -Tpost +Regular PostScript printers +.PD0 +.TP +.B -T202 +Mergenthaler Linotron 202 +.RE +.PD +.TP "\w'\fL-m\f2name 'u" +.BI -F dir +Take font information from directory +.IR dir . +.SS Typewriter (\fL-N\fP) output only +.TP \n(xxu +.BI -s N +Halt prior to every +.I N +pages (default +.IR N =1) +to allow paper loading or changing. +.TP +.BI -T name +Prepare output for specified terminal. +Known +.I names +include +.B utf +for the normal Plan 9 +.SM UTF +encoding of the Unicode Standard character set (default), +.B 37 +for the +Teletype model 37, +.B lp +(`line-printer') +for any terminal without half-line capability, +.B 450 +for the \s-1DASI\s+1-450 +(Diablo Hyterm), +and +.B think +(HP ThinkJet). +.TP +.B -e +Produce equally-spaced words in adjusted +lines, using full terminal resolution. +.TP +.B -h +Use output tabs during horizontal spacing +to speed output and reduce output character count. +Tab settings are assumed to be every +8 nominal character widths. +.SH FILES +.TF /sys/lib/troff/term/* +.TP +.B /tmp/trtmp* +temporary file +.TP +.B /sys/lib/tmac/tmac.* +standard macro files +.TP +.B /sys/lib/troff/term/* +terminal driving tables for +.I nroff +.TP +.B /sys/lib/troff/font/* +font width tables for +.I troff +.SH SOURCE +.B /sys/src/cmd/troff +.SH "SEE ALSO" +.IR lp (1), +.IR proof (1), +.IR eqn (1), +.IR tbl (1), +.IR pic (1), +.IR grap (1), +.IR doctype (1), +.IR ms (6), +.IR image (6), +.IR tex (1), +.IR deroff (1) +.br +J. F. Ossanna and B. W. Kernighan, +``Troff User's Manual'' +.br +B. W. Kernighan, +``A TROFF Tutorial'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2. diff --git a/static/plan9-4e/man1/troff2html.1 b/static/plan9-4e/man1/troff2html.1 new file mode 100644 index 00000000..36b47c31 --- /dev/null +++ b/static/plan9-4e/man1/troff2html.1 @@ -0,0 +1,97 @@ +.TH TROFF2HTML 1 +.SH NAME +troff2html \- convert troff output into HTML +.SH SYNOPSIS +.B troff2html +[ +.B -t +.I title +] [ +.I file +\ ... +] +.SH DESCRIPTION +.I Troff2html +reads the +.IR troff (1) +output in the named +.IR files , +default standard input, +and converts them into HTML. +.PP +.I Troff2html +does a tolerable job with straight +.B troff +output, but it is helped by annotations, described below. +Its main use is for +.B man2html +(see +.IR httpd (8)), +which converts +.IR man (1) +pages into HTML +and depends on a specially annotated set of +.IR man (6) +macros, invoked by +.B troff +.BR -manhtml . +.PP +.B Troff +output lines beginning +.IP +.EX +x X html \f1... +.EE +.LP +which are introduced by placing +.B \eX'html\ \f1...\fP' +in the +.IR input , +cause the rest of the line to be interpolated into the HTML produced. +Several such lines are recognized specially by +.IR troff2html . +The most important are the pair +.IP +.EX +x X html manref start cp 1 +x X html manref end cp 1 +.EE +.PP +which are used to create HTML anchors of the form +.IR cp (1) +pointing to +.BR /magic/man2html/1/cp . +.PP +.I Troff2html +is new and experimental; in time, it may improve and subsume +.IR ms2html (1). +On the one hand, because it uses the input, +.B ms2html +can handle +.IR pic (1), +.IR eqn (1), +etc., which +.I troff2html +does not handle at all; on the other hand, +.B ms2html +understands only +.IR ms (6) +documents and is easily confused by complex +.B troff +constructions. +.I Troff2html +has the reverse properties: it does not handle the preprocessors but its output +is reliable and (modulo helper annotations) is independent of macro package. +.SH SEE ALSO +.IR troff (1), +.IR ms2html (1), +.B man2html +in +.IR httpd (8). +.SH BUGS +.B Troff +and HTML have different models, and they don't mesh well in all cases. +.BR Troff 's +indented paragraphs are not well served in HTML, and the output of +.I troff2html +shows this. diff --git a/static/plan9-4e/man1/tweak.1 b/static/plan9-4e/man1/tweak.1 new file mode 100644 index 00000000..e3f19503 --- /dev/null +++ b/static/plan9-4e/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 (6)); +and the subfont's +.BR n , +.BR height , +and +.B ascent +as defined in +.IR cachechars (2). +.PP +By means described below, magnified views of portions of the images +may be displayed. +The text associated with such a view includes +.BR mag , +the magnification. +If the view is of a single character from a subfont, the second +line of text shows the character's value (including the subfont's offset) +in hexadecimal and as a character in +.I tweak's +default font; the character's +.BR x , +.BR top , +.BR bottom , +.BR left , +and +.BR width +as defined in +.IR cachechars (2); +and +.BR iwidth , +the physical width of the image in the subfont's image. +.PP +There are two methods to obtain a magnified view of a character from a +subfont. +The first is to click mouse button 1 over the image of the character in +the subfont. The second is to select the +.B char +entry on the button 3 menu, +point the resulting gunsight cursor at the desired subfont and click button 3, +and then type at the text prompt at the bottom of the screen the +character value, either as a multi-digit hexadecimal number or as a single +rune representing the character. +.PP +To magnify a portion of other types of image files, +click button 1 over the unmagnified file. +The cursor will switch to a cross. +Still with button 1, sweep a rectangle, as in +.BR rio , +that encloses the portion of the image to be magnified. +(If the file is 16×16 or smaller, +.I tweak +will just magnify the entire file; no sweeping is necessary.) +.PP +Pressing buttons 1 and 2 within magnified images changes pixel values. +By default, button 1 sets the pixel to all zeros and button 2 sets the pixel +to all ones. +.PP +Across the top of the screen is a textual display of global parameters. +These values, as well as many of the textual values associated with +the images, may be edited by clicking button 1 on the displayed +value and typing a new value. +The values along the top of the screen are: +.TP +.B mag +Default magnification. +.TP +.B val(hex) +The value used to modify pixels within magnified images. +The value must be in hexadecimal, optionally preceded by a +tilde for bitwise negation. +.TP +.B but1 +.TP +.B but2 +The pixel value written when the corresponding button is pressed over a pixel. +.TP +.B invert-on-copy +Whether the pixel values are inverted when a +.B copy +operation is performed. +.PP +Under button 3 is a menu holding a variety of functions. +Many of these functions prompt for the image upon which to act +by switching to a gunsight cursor; click button 3 over the +selection, or click a different button to cancel the action. +.TP +.B open +Read and display a file. The name of the file is typed to the prompt +on the bottom line. +.TP +.B read +Reread a file. +.TP +.B write +Write a file. +.TP +.B copy +Use the copy function, default +.BR S , +to transfer a rectangle of pixels from one image to another. +The program prompts with a cross cursor; sweep out a rectangle in +one image or just click button 3 to select the whole image. +The program will leave that rectangle in place and +attach another one to the cursor. Move that rectangle to the desired +place in any image and click button 3, or another button to cancel the action. +.TP +.B char +As described above, open a magnified view of a character image in a subfont. +.TP +.B pixels +Report the coordinate and value of individual pixels indicated by pressing button 3. +This is a mode of operation canceled by pressing button 1 or 2. +.TP +.B close +Close the specified image. +If the image is the unmagnified file, also close any magnified views of that file. +.TP +.B exit +Quit +.IR tweak . +The program will complain once about modified but unwritten files. +.SH SOURCE +.B /sys/src/cmd/tweak.c +.SH "SEE ALSO" +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH BUGS +For a program written to adjust width tables in fonts, +.I tweak +has been pushed unreasonably far. diff --git a/static/plan9-4e/man1/uniq.1 b/static/plan9-4e/man1/uniq.1 new file mode 100644 index 00000000..65fcd49f --- /dev/null +++ b/static/plan9-4e/man1/uniq.1 @@ -0,0 +1,59 @@ +.TH UNIQ 1 +.SH NAME +uniq \- report repeated lines in a file +.SH SYNOPSIS +.B uniq +[ +.B -udc +[ +.BI +- num +] +] +[ +.I file +] +.SH DESCRIPTION +.I Uniq +copies the input +.IR file , +or the standard input, to the +standard output, comparing adjacent lines. +In the normal case, the second and succeeding copies +of repeated lines are +removed. +Repeated lines must be adjacent +in order to be found. +.TP +.B -u +Print unique lines. +.TP +.B -d +Print (one copy of) duplicated lines. +.TP +.B -c +Prefix a repetition count and a tab to each output line. +Implies +.B -u +and +.BR -d . +.TP +.BI - num +The first +.IR num +fields +together with any blanks before each are ignored. +A field is defined as a string of non-space, non-tab characters +separated by tabs and spaces from its neighbors. +.TP +.BI + num +The first +.IR num +characters are ignored. +Fields are skipped before characters. +.SH SOURCE +.B /sys/src/cmd/uniq.c +.SH "SEE ALSO" +.IR sort (1) +.SH BUGS +Field selection and comparison should be compatible with +.IR sort (1). diff --git a/static/plan9-4e/man1/units.1 b/static/plan9-4e/man1/units.1 new file mode 100644 index 00000000..799b3114 --- /dev/null +++ b/static/plan9-4e/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 /sys/src/cmd/units.y +.SH BUGS +Since +.I units +does only multiplicative scale changes, +it can convert Kelvin to Rankine but not Centigrade to +Fahrenheit. +.br +Currency conversions are only as accurate as the last time someone +updated +.BR /lib/units . diff --git a/static/plan9-4e/man1/vac.1 b/static/plan9-4e/man1/vac.1 new file mode 100644 index 00000000..2af05984 --- /dev/null +++ b/static/plan9-4e/man1/vac.1 @@ -0,0 +1,122 @@ +.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 -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 -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 /sys/src/cmd/vac +.SH "SEE ALSO" +.IR vacfs (4), +.IR venti (8) diff --git a/static/plan9-4e/man1/vi.1 b/static/plan9-4e/man1/vi.1 new file mode 100644 index 00000000..e97aa80e --- /dev/null +++ b/static/plan9-4e/man1/vi.1 @@ -0,0 +1,170 @@ +.TH VI 1 +.SH NAME +0i, 5i, ki, vi \- instruction simulators +.SH SYNOPSIS +.B vi +[ +.I textfile +] +.br +.B vi +.I pid +.br +.B 0i +[ +.I textfile +] +.br +.B 0i +.I pid +.br +.B 5i +[ +.I textfile +] +.br +.B 5i +.I pid +.br +.B ki +[ +.I textfile +] +.br +.B ki +.I pid +.SH DESCRIPTION +.I Vi +simulates the execution of a MIPS binary in +a Plan 9 environment. +It has two main uses: as +a debugger and as a statistics gatherer. +Programs running under +.I vi +execute about two hundred times +slower than normal\(embut faster than +single stepping under +.IR db . +.IR 0i , +.IR 5i , +and +.IR ki +are similar to +.I vi +but interpret little-endian MIPS, ARM 7500, and SPARC binaries. +The following discussion refers to +.I vi +but applies to the others +as well. +.PP +.I Vi +will simulate the execution of a named +.IR textfile . +It will also make a copy of an existing process with process id +.I pid +and simulate its continuation. +.PP +As a debugger +.I vi +offers more complete information +than +.IR db (1). +Tracing can be performed at the level of instructions, +system calls, or function calls. +.I Vi +allows breakpoints to be triggered when specified addresses +in memory are accessed. +A report of instruction counts, +load delay fills and distribution is produced for +each run. +.I Vi +simulates the CPU's caches and MMU +to assist the optimization of compilers and programs. +.PP +The command interface mirrors the interface to +.IR db ; +see +.IR db (1) +for a detailed description. +Data formats and addressing are compatible with +.I db +except +for disassembly: +.I vi +offers only MIPS +.RB ( db +.BR -mmipsco ) +mnemonics for +machine instructions. +.I Ki +offers both Plan 9 and Sun SPARC formats. +.PP +Several extra commands allow +extended tracing and printing of statistics: +.TP +.BR $t [ 0ics ] +The +.I t +command controls tracing. Zero cancels all tracing +options. +.RS +.TP +.B i +Enable instruction tracing +.TP +.B c +Enable call tracing +.TP +.B s +Enable system call tracing +.RE +.TP +.BR $i [ itsp ] +The +.B i +command prints statistics accumulated by +all code run in this session. +.RS +.TP +.B i +Print instruction counts and frequency. +.TP +.B p +Print cycle profile. +.TP +.B t +.RI ( Vi +only) Print TLB and cache statistics. +.TP +.B s +Print memory reference, working set and size statistics. +.RE +.TP +.BR :b [ arwe ] +.I Vi +allows breakpoints to be set on any memory location. +These breakpoints monitor when a location is +accessed, read, written, or equals a certain value. +For equality the compared value is the +.I count +(see +.IR db (1)) +supplied to the command. +.SH SOURCE +.B /sys/src/cmd/vi +etc. +.SH "SEE ALSO" +.IR nm (1), +.IR db (1) +.SH BUGS +The code generated by +the compilers +is well supported, but some unusual instructions are unimplemented. +Some Plan 9 system calls such as +.I rfork +cause simulated traps. +The floating point simulation makes assumptions about the interpreting +machine's floating point support. The floating point conversions performed +by +.I vi +may cause a loss of precision. diff --git a/static/plan9-4e/man1/vnc.1 b/static/plan9-4e/man1/vnc.1 new file mode 100644 index 00000000..a94de71d --- /dev/null +++ b/static/plan9-4e/man1/vnc.1 @@ -0,0 +1,153 @@ +.TH VNC 1 +.SH NAME +vncs, vncv \- remote frame buffer server and viewer for Virtual Network Computing (VNC) +.SH SYNOPSIS +.B vncs +[ +.B -v ] [ -g +.I width +.B X +.I height +.B ] +.B [ -d +.I :display +.B ] +.B [command [args ...]] +.PP +.B vncs -k +.I :display +.PP +.B vncv +[ +.B -e +.I encodings +] +[ +.B -csv +] +.IR host [\fL: n ] +.SH DESCRIPTION +.I vncs +starts a new virtual frame buffer in memory and waits for connections from remote viewers. +Each viewer is authenticated using challenge and response. APOP password is used as the +private key. A display number +.I :n +in the global name space is printed to stderr. A viewer must use the same display number +in order to contact the desired server. Multiple VNC servers can co-exist on the same host, +each with a unique display number. +.PP +One frame buffer can have simultaneous viewers if the viewers are started with the -s option, +see below. Otherwise, starting a new viewer would cause the server to disconnect from all +existing viewers. Killing the viewers will not affect the remote server. Therefore, the same desktop +can migrate from one location to another without restarting the window system. +.PP +The server options are: +.TP +.B -v +causes verbose output to stderr. +.TP +.B -g " widthXheight +specifies the frame buffer geometry. Default is 1024x768. The depth is fixed +at 16 bits per pixel (r5g6b5). +.TP +.B -d +chooses a display number +.RI : n . +The server aborts if the display is not available. If not specified, the server hunts for +the first available on that host interface. +.TP +.I command [args ...] +By default, the server starts with a terminal similar to that of drawterm. RC is +executed on behalf of the owner of the vncs process. The user can specify any program +to start the VNC server, e.g. rio. +.TP +.B -k " :display +shutdown the VNC server and all of its connected clients on +.RI : display . +Note, kill vncs | rc will kill ALL servers running on that host. +.PP +.I Vncv +provides access to remote frame buffer +.I n +on +.I host +using the VNC (Virtual Network Computing) +protocol. +It resizes its window to be the smaller of the +remote frame buffer size and the local screen. +.PP +The +.B -e +option specifies an ordered list of rectangle +encodings to allow in the protocol. +The default (and full set) is +.IP +.EX +copyrect corre hextile rre raw +.EE +.PP +By default, connecting to a display closes +any other connections to that display. +The +.B -s +option allows the other connections to share the display. +.PP +The +.B -v +option causes verbose output. +.PP +.I Vncv +negotiates with the VNC server to settle on a true-color pixel format. +For true-color displays, this is the native display pixel format. +On eight bit color-mapped displays, +.I vncv +requests +.B r3g3b2 +pixels and upon receipt translates them to the nearest +color in the map. +This does not cover the color map particularly well. +When invoked with the +.B -c +option, +.I vncv +requests +.B r4g4b4 +pixels instead. This consumes more bandwidth +but results in better matching to the available colors. +.PP +.I Vncv +correctly handles the typing of control characters +and shifted keystrokes. +To support systems that require the use +of modifiers like Alt, Ctl, and Shift on +things like mouse events, +typing the sequences +.B Alt +.B Z +.B A +(for Alt), +.B Alt +.B Z +.B C +(for Ctrl), +and +.B Alt +.B Z +.B S +(for Shift) +will send a ``key down'' message for +the given key (see +.IR keyboard (6)). +A corresponding ``key up'' message +will be sent after the next key is pressed, +or when the sequence is retyped, +whichever happens first. +.SH SOURCE +.B /sys/src/cmd/vnc +.SH "SEE ALSO +.IR drawterm (8) +.br +.B http://www.uk.research.att.com/vnc +.SH BUGS +If the remote frame buffer is larger than the local screen, +only the upper left corner can be accessed. diff --git a/static/plan9-4e/man1/vt.1 b/static/plan9-4e/man1/vt.1 new file mode 100644 index 00000000..2addce85 --- /dev/null +++ b/static/plan9-4e/man1/vt.1 @@ -0,0 +1,109 @@ +.TH VT 1 +.SH NAME +vt \- emulate a VT-100 or VT-220 terminal +.SH SYNOPSIS +.B vt +[ +.B -2sa +] +.SH DESCRIPTION +.I Vt +replaces a rio window with a fresh instance of the shell +.IR rc (1) +running within an emulation of a DEC VT-100 terminal. +The +.B -2 +and +.B -a +options configure +.I vt +to emulate a VT-220 and Ansi terminal respectively. +The +.B -s +options forces a saner color scheme, i.e, black text on white +background. +.PP +The right button has a menu with the following entries to provide +the sort of character processing expected by non-Plan 9 systems: +.TF cooked +.TP +.B 24x80 +Resize the +.I vt +window to hold 24 rows of 80 columns. +.TP +.B crnl +Print a newline (linefeed) character after receiving a carriage return from the host. +.TP +.B cr +Do not print a newline after carriage return. +.TP +.B nlcr +Print a carriage return after receiving a newline from the host. +.TP +.B nl +Do not print a carriage return after newline. +.TP +.B raw +Enter raw (no echo, no interpretation) character mode for input. +.TP +.B cooked +Leave raw mode. +.TP +.B exit +Exits +.IR vt . +.PD +.PP +The middle button has a menu with the following entries: +.TF right_key +.TP +.B backup +Move the display back one screenful. +.TP +.B forward +Move the display forward one screenful. +(These are a poor substitute for a scroll bar.) +.TP +.B reset +Display the last screenful; the same as going +.B forward +to the end. +.TP +.B clear +Clear the screen. Previous contents can be recovered using +.BR backup . +.TP +.B send +Send the contents of the +.B rio +snarf buffer, just as +.B send +in the +.B rio +menu. +.TP +.B scroll +Make new lines visible as they appear at the bottom. +.TP +.B page +When the page fills, pause and wait for a character to be typed before proceeding. +The down arrow key advances a page without sending the character to the host. +.PD +.PP +To exit +.IR vt , +exit its +.B rc +session by, for example, typing EOT (control-D). +.SH SOURCE +.B /sys/src/cmd/vt +.SH BUGS +.PP +This program is used only for communicating with foreign systems, so it is not +as rich an emulation as its equivalent in other environments. +.PP +Use care in setting raw and newline modes when connecting to Unix systems +via +.IR con . +It may also be necessary to set the emulator into raw mode. diff --git a/static/plan9-4e/man1/wc.1 b/static/plan9-4e/man1/wc.1 new file mode 100644 index 00000000..1c9768fc --- /dev/null +++ b/static/plan9-4e/man1/wc.1 @@ -0,0 +1,53 @@ +.TH WC 1 +.SH NAME +wc \- word count +.SH SYNOPSIS +.B wc +[ +.B -lwrbc +] +[ +.I file ... +] +.SH DESCRIPTION +.I Wc +counts lines, words, runes, syntactically-invalid +.SM UTF +codes and bytes in the named +.IR files , +or in the standard input if no file is named. +A word is a maximal string of characters +delimited by spaces, tabs or newlines. +The count of runes includes invalid codes. +.PP +If the optional argument is present, +just the specified counts (lines, words, runes, broken +.SM UTF +codes or bytes) +are selected by the letters +.BR l , +.BR w , +.BR r , +.BR b , +or +.BR c . +Otherwise, lines, words and bytes +.RB ( -lwc ) +are reported. +.SH SOURCE +.B /sys/src/cmd/wc.c +.SH BUGS +The Unicode Standard has many blank characters scattered through it, +but +.I wc +looks for only +.SM ASCII +space, tab and newline. +.br +.I Wc +should have options to count suboptimal +.SM UTF +codes +and bytes that cannot occur in any +.SM UTF +code. diff --git a/static/plan9-4e/man1/who.1 b/static/plan9-4e/man1/who.1 new file mode 100644 index 00000000..1a13c3af --- /dev/null +++ b/static/plan9-4e/man1/who.1 @@ -0,0 +1,22 @@ +.TH WHO 1 +.SH NAME +who, whois \- who is using the machine +.SH SYNOPSIS +.B who +.PP +.B whois +.I person +.SH DESCRIPTION +.I Who +prints the name of everyone with a non-Exiting process +on the current machine. +.PP +.I Whois +looks in +.B /adm/whois +and +.B /adm/users +to find out more information about +.IR person . +.SH SOURCE +.B /rc/bin/who diff --git a/static/plan9-4e/man1/xd.1 b/static/plan9-4e/man1/xd.1 new file mode 100644 index 00000000..cc2d394f --- /dev/null +++ b/static/plan9-4e/man1/xd.1 @@ -0,0 +1,87 @@ +.TH XD 1 +.SH NAME +xd \- hex, octal, decimal, or ASCII dump +.SH SYNOPSIS +.B xd +[ +.I option ... +] +[ +.BI - "format ... +] [ +.I file ... +] +.SH DESCRIPTION +.I Xd +concatenates and dumps the +.I files +(standard input by default) +in one or more formats. +Groups of 16 bytes are printed in each of the named formats, one +format per line. +Each line of output is prefixed by its address (byte offset) +in the input file. +The first line of output for each group is zero-padded; subsequent are blank-padded. +.PP +Formats other than +.B -c +are specified by pairs of characters telling size and style, +.L 4x +by default. +The sizes are +.TP \w'2\ or\ w\ \ \ 'u +.BR 1 " or " b +1-byte units. +.PD0 +.TP +.BR 2 " or " w +2-byte big-endian units. +.TP +.BR 4 " or " l +4-byte big-endian units. +.TP +.BR 8 " or " v +8-byte big-endian units. +.PD +.PP +The styles are +.TP 0 +.B o +Octal. +.PD0 +.TP +.B x +Hexadecimal. +.TP +.B d +Decimal. +.PD +.PP +Other options are +.TP \w'\fL-a\fIstyle\fLXX'u +.B -c +Format as +.B 1x +but print +.SM ASCII +representations or C escape sequences where possible. +.TP +.BI -a style +Print file addresses in the given style (and size 4). +.TP +.B -u +(Unbuffered) Flush the output buffer after each 16-byte sequence. +.TP +.B -s +Reverse (swab) the order of bytes in each group of 4 before printing. +.TP +.B -r +Print repeating groups of identical 16-byte sequences as the first group +followed by an asterisk. +.SH SOURCE +.B /sys/src/cmd/xd.c +.SH "SEE ALSO" +.IR db (1) +.SH BUGS +The various output formats don't line up properly in the output of +.IR xd . diff --git a/static/plan9-4e/man1/yacc.1 b/static/plan9-4e/man1/yacc.1 new file mode 100644 index 00000000..a965f953 --- /dev/null +++ b/static/plan9-4e/man1/yacc.1 @@ -0,0 +1,167 @@ +.TH YACC 1 +.SH NAME +yacc \- yet another compiler-compiler +.SH SYNOPSIS +.B yacc +[ +.I option ... +] +.I grammar +.SH DESCRIPTION +.I Yacc +converts a context-free grammar and translation code +into a set of +tables for an LR(1) parser and translator. +The grammar may be ambiguous; +specified precedence rules are used to break ambiguities. +.PP +The output file, +.BR y.tab.c , +must be compiled by the C compiler +to produce a program +.LR yyparse . +This program must be loaded with a lexical analyzer function, +.B yylex(void) +(often generated by +.IR lex (1)), +with a +.B main(int argc, char *argv[]) +program, and with an error handling routine, +.BR yyerror(char*) . +.PP +The options are +.TP "\w'\fL-o \fIoutput\fLXX'u" +.BI -o " output +Direct output to the specified file instead of +.BR y.tab.c . +.TP +.BI -D n +Create file +.BR y.debug , +containing diagnostic messages. +To incorporate them in the parser, compile it with preprocessor symbol +.B yydebug +defined. +The amount of +diagnostic output from the parser is regulated by +value +.IR n . +The value 0 reports errors; 1 reports reductions; +higher values (up to 4) include more information about +state transitions. +.TP +.B -v +Create file +.BR y.output , +containing a description of the parsing tables and of +conflicts arising from ambiguities in the grammar. +.TP +.B -d +Create file +.BR y.tab.h , +containing +.B #define +statements that associate +.IR yacc -assigned +`token codes' with user-declared `token names'. +Include it in source files other than +.B y.tab.c +to give access to the token codes. +.TP +.BI -s " stem +Change the prefix +.L y +of the file names +.BR y.tab.c , +.BR y.tab.h , +.BR y.debug , +and +.B y.output +to +.IR stem . +.TP +.B -S +Write a parser that uses +Stdio +instead of the +.B print +routines in libc. +.PP +The specification of +.I yacc +itself is essentially the same as the UNIX version +described in the references mentioned below. +Besides the +.B -D +option, the main relevant differences are: +.IP +The interface to the C environment is by default through +.B +rather than +.BR ; +the +.B -S +option reverses this. +.IP +The parser accepts +.SM UTF +input text (see +.IR utf (6)), +which has a couple of effects. +First, the return value of +.B yylex() +no longer fits in a +.BR short ; +second, the starting value for non-terminals is now 0xE000 rather than 257. +.IP +The generated parser can be recursive: actions can call +.IR yyparse , +for example to implement a sort of +.B #include +statement in an interpreter. +.IP +Finally, some undocumented inner workings of the parser have been +changed, which may affect programs that know too much about its structure. +.SH FILES +.TF /sys/lib/yaccpars +.TP +.B y.output +.TP +.B y.tab.c +.TP +.B y.tab.h +.TP +.B y.debug +.TP +.B y.tmp.* +temporary file +.TP +.B y.acts.* +temporary file +.TP +.B /sys/lib/yaccpar +parser prototype +.TP +.B /sys/lib/yaccpars +parser prototype using stdio +.SH SOURCE +.B /sys/src/cmd/yacc.c +.SH "SEE ALSO" +.IR lex (1) +.br +S. C. Johnson and R. Sethi, +``Yacc: A parser generator'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 +.br +B. W. Kernighan and Rob Pike, +.I +The UNIX Programming Environment, +Prentice Hall, 1984 +.SH BUGS +The parser may not have full information when it writes to +.B y.debug +so that the names of the tokens returned by +.L yylex +may be missing. diff --git a/static/plan9-4e/man1/yesterday.1 b/static/plan9-4e/man1/yesterday.1 new file mode 100644 index 00000000..123366b7 --- /dev/null +++ b/static/plan9-4e/man1/yesterday.1 @@ -0,0 +1,122 @@ +.TH YESTERDAY 1 +.SH NAME +yesterday \- print file names from the dump +.SH SYNOPSIS +.B yesterday +[ +.B -abcCdD +] [ +.B -n +.I daysago +] [ +.I \-date +] +.I files ... +.SH DESCRIPTION +.I Yesterday +prints the names of the +.I files +from the most recent dump. +Since dumps are done early in the morning, +yesterday's files are really in today's dump. +For example, if today is March 17, 1992, +.IP +.EX +yesterday /adm/users +.EE +.PP +prints +.IP +.EX +/n/dump/1992/0317/adm/users +.EE +.PP +In fact, the implementation is to select the most recent dump in +the current year, so the dump selected may not be from today. +.PP +By default, +.I yesterday +prints the names of the dump files corresponding to the named files. +The first set of options changes this behavior. +.TP +.B -a +Run +.IR acme (1)'s +.I adiff +to compare the dump files with the named files. +.TP +.B -b +Bind the dump files over the named files. +.TP +.B -c +Copy the dump files over the named files. +.TP +.B -C +Copy the dump files over the named files only when +they differ. +.TP +.B -d +Run +.B diff +to compare the dump files with the named files. +.TP +.B -D +Run +.B diff +.B -n +to compare the dump files with the named files. +.PP +The +.I date +option selects other day's dumps, with a format of +1, 2, 4, 6, or 8 digits of the form +.IR d, +.IR dd , +.IR mmdd , +.IR yymmdd , +or +.IR yyyymmdd . +.PP +The +.B -n +option selects the dump +.I daysago +prior to the current day. +.PP +.I Yesterday +does not guarantee that the string it prints represents an existing file. +.SH EXAMPLES +.PP +Back up to yesterday's MIPS binary of +.BR vc : +.IP +.EX +yesterday -c /mips/bin/vc +.EE +.PP +Temporarily back up to March 1's MIPS C library to see if a program +runs correctly when loaded with it: +.IP +.EX +yesterday -b -0301 /mips/lib/libc.a +rm v.out +mk +v.out +.EE +.PP +Find what has changed in the C library since March 1: +.IP +.EX +yesterday -d -0301 /sys/src/libc/port/*.c +.EE +.SH FILES +.B /n/dump +.SH SOURCE +.B /rc/bin/yesterday +.SH SEE ALSO +.IR history (1), +.IR bind (1), +.IR diff (1), +.IR fs (4). +.SH BUGS +It's hard to use this command without singing. diff --git a/static/plan9-4e/man2/0intro.2 b/static/plan9-4e/man2/0intro.2 new file mode 100644 index 00000000..5ed0b30a --- /dev/null +++ b/static/plan9-4e/man2/0intro.2 @@ -0,0 +1,465 @@ +.TH INTRO 2 +.SH NAME +intro \- introduction to library functions +.SH SYNOPSIS +.nf +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B #include +.fi +.SH DESCRIPTION +This section describes functions +in various libraries. +For the most part, each library is defined by a single C include +file, such as those listed above, and a single archive file containing +the library proper. The name of the archive is +.BI /$objtype/lib/lib x .a \f1, +where +.I x +is the base of the include file name, stripped of a leading +.B lib +if present. +For example, +.B +defines the contents of library +.BR /$objtype/lib/libdraw.a , +which may be abbreviated when named to the loader as +.BR -ldraw . +In practice, each include file contains a +.B #pragma +that directs the loader to pick up the associated archive +automatically, so it is rarely necessary to tell the loader +which +libraries a program needs. +.PP +The library to which a function belongs is defined by the +header file that defines its interface. +The `C library', +.IR libc , +contains most of the basic subroutines such +as +.IR strlen . +Declarations for all of these functions are +in +.BR , +which must be preceded by +.RI ( needs ) +an include of +.BR . +The graphics library, +.IR draw , +is defined by +.BR , +which needs +.B +and +.BR . +The Buffered I/O library, +.IR libbio , +is defined by +.BR , +which needs +.B +and +.BR . +The ANSI C Standard I/O library, +.IR libstdio , +is defined by +.BR , +which has no prerequisites. +There are a few other, less commonly used libraries defined on +individual pages of this section. +.PP +The include file +.BR , +a prerequisite of several other include files, +declares the architecture-dependent and -independent types, including: +.IR ushort , +.IR uchar , +and +.IR ulong , +the unsigned integer types; +.IR schar , +the signed char type; +.IR vlong , +a very long integral type; +.IR jmp_buf , +the type of the argument to +.I setjmp +and +.IR longjmp , +plus macros that define the layout of +.IR jmp_buf +(see +.IR setjmp (2)); +definitions of the bits in the floating-point control register +as used by +.IR getfcr (2); +the macros +.B va_arg +and friends for accessing arguments of variadic functions (identical to the +macros defined in +.B +in ANSI C); +and +.IR Length , +for historical reasons a union, +representing the 64-bit length of a file, declared something like +.IP +.EX +.ta 6n +6n +6n +typedef union +{ + vlong length; +} Length; +.EE +.SS "Name space +Files are collected into a hierarchical organization called a +.I "file tree +starting in a +.I directory +called the +.IR root . +File names, also called +.IR paths , +consist of a number of +.BR / -separated +.IR "path elements" +with the slashes corresponding to directories. +A path element must contain only printable +characters (those outside +.SM ASCII +and Latin-1 control space) +that occupy no more than +.B NAMELEN-1 +bytes. +A path element cannot contain a space or slash. +.PP +When a process presents a file name to Plan 9, it is +.I evaluated +by the following algorithm. +Start with a directory that depends on the first +character of the path: +.L / +means the root of the main hierarchy, +.L # +means the separate root of a kernel device's file tree (see Section 3), +and anything else means the process's current working directory. +Then for each path element, look up the element +in the directory, advance to that directory, +do a possible translation (see below), and repeat. +The last step may yield a directory or regular file. +The collection of files reachable from the root is called the +.I "name space +of a process. +.PP +A program can use +.I bind +or +.I mount +(see +.IR bind (2)) +to say that whenever a specified file is reached during evaluation, +evaluation instead continues from a second specified file. +Also, the same system calls create +.IR "union directories" , +which are concatenations of ordinary directories +that are searched sequentially until the desired element is found. +Using +.I bind +and +.I mount +to do name space adjustment affects only +the current process group (see below). +Certain conventions about the layout of the name space should +be preserved; see +.IR namespace (4). +.SS "File I/O" +Files are opened for input or output +by +.I open +or +.I create +(see +.IR open (2)). +These calls return an integer called a +.IR "file descriptor" +which identifies the file +to subsequent I/O calls, +notably +.IR read (2) +and +.IR write . +The system allocates the numbers by selecting the lowest unused descriptor. +They are allocated dynamically; there is no visible limit to the number of file +descriptors a process may have open. +They may be reassigned using +.IR dup (2). +File descriptors are indices into a +kernel resident +.IR "file descriptor table" . +Each process has an associated file descriptor table. +In some cases (see +.I rfork +in +.IR fork (2)) +a file descriptor table may be shared by several processes. +.PP +By convention, +file descriptor 0 is the standard input, +1 is the standard output, +and 2 is the standard error output. +With one exception, the operating system is unaware of these conventions; +it is permissible to close file 0, +or even to replace it by a file open only for writing, +but many programs will be confused by such chicanery. +The exception is that the system prints messages about broken processes +to file descriptor 2. +.PP +Files are normally read or written in sequential order. +The I/O position in the file is called the +.IR "file offset" +and may be set arbitrarily using the +.IR seek (2) +system call. +.PP +Directories may be opened and read much like regular files. +They contain an integral number of records, called +.IR "directory entries" , +of length +.B DIRLEN +(defined in +.BR ). +Each entry is a machine-independent representation of +the information about an existing file in the directory, +including the name, ownership, +permission, +access dates, +and so on. +The entry +corresponding to an arbitrary file can be retrieved by +.IR stat (2) +or +.IR fstat ; +.I wstat +and +.I fwstat +write back entries, thus changing the properties of a file. +An entry may be translated into a more convenient, addressable +form called a +.B Dir +structure; +.IR dirstat , +.IR dirfstat, +.IR dirwstat , +and +.I dirfwstat +execute the appropriate translations (see +.IR stat (2)). +.PP +New files are made with +.I create +(in +.IR open (2)) +and deleted with +.IR remove (2). +Directories may not directly be written; +.IR create , +.IR remove , +.IR wstat , +and +.I fwstat +alter them. +.PP +The operating system kernel records the file name used to access each open file or directory. +If the file is opened by a local name (one that does not begin +.B / +or +.BR # ), +the system makes the stored name absolute by prefixing +the string associated with the current directory. +Similar lexical adjustments are made for path names containing +.B . +(dot) or +.B .. +(dot-dot). +By this process, the system maintains a record of the route by which each file was accessed. +Although there is a possibility for error\(emthe name is not maintained after the file is opened, +so removals and renamings can confound it\(emthis simple method usually +permits the system to return, via the +.IR fd2path (2) +system call and related calls such as +.IR getwd (2), +a valid name that may be used to find a file again. +This is also the source of the names reported in the name space listing of +.IR ns (1) +or +.B /dev/ns +(see +.IR proc (3)). +.PP +.IR Pipe (2) +creates a connected pair of file descriptors, +useful for bidirectional local communication. +.SS "Process execution and control" +A new process is created +when an existing one calls +.I rfork +with the +.B RFPROC +bit set, usually just by calling +.IR fork (2). +The new (child) process starts out with +copies of the address space and most other attributes +of the old (parent) process. +In particular, +the child starts out running +the same program as the parent; +.IR exec (2) +will bring in a different one. +.PP +Each process has a unique integer process id; +a set of open files, indexed by file descriptor; +and a current working directory +(changed by +.IR chdir (2)). +.PP +Each process has a set of attributes \(em memory, open files, +name space, etc. \(em that may be shared or unique. +Flags to +.IR rfork +control the sharing of these attributes. +.PP +The memory of a process is divided into +.IR segments . +Every program has at least a +.I text +(instruction) and +.I stack +segment. +Most also have an initialized +.I data +segment and a segment of zero-filled data called +.IR bss . +Processes may +.IR segattach (2) +other segments for special purposes. +.PP +A process terminates by calling +.IR exits (2). +A parent process may call +.I wait +(in +.IR exits (2)) +to wait for some child to terminate. +A string of status information +may be passed from +.I exits +to +.IR wait . +A process can go to sleep for a specified time by calling +.IR sleep (2). +.PP +There is a +.I notification +mechanism for telling a process about events such as address faults, +floating point faults, and messages from other processes. +A process uses +.IR notify (2) +to register the function to be called (the +.IR "notification handler" ) +when such events occur. +.SS Multithreading +By calling +.I rfork +with the +.B RFMEM +bit set, a program may create several independently executing processes sharing the same +memory (except for the stack segment, which is unique to each process). +Where possible according to the ANSI C standard, +the main C library works properly in multiprocess programs; +.IR malloc , +.IR print , +and the other routines use locks (see +.IR lock (2)) +to synchronize access to their data structures. +The graphics library defined in +.B +is also multi-process capable; details are in +.IR graphics (2). +In general, though, multiprocess programs should use some form of synchronization +to protect shared data. +.PP +The thread library, defined in +.BR , +provides support for multiprocess programs. +It includes a data structure called a +.B Channel +that can be used to send messages between processes, +and coroutine-like +.IR threads , +which enable multiple threads of control within a single process. +The threads within a process are scheduled by the library, but there is +no pre-emptive scheduling within a process; thread switching occurs +only at communication or synchronization points. +.PP +Most programs using the thread library +comprise multiple processes +communicating over channels, and within some processes, +multiple threads. Since Plan 9 I/O calls may block, a system +call may block all the threads in a process. +Therefore, a program that shouldn't block unexpectedly will use a process +to serve the I/O request, passing the result to the main processes +over a channel when the request completes. +For an example of this design, see +.IR mouse (2). +.SH SEE ALSO +.IR nm (1), +.IR 2l (1), +.IR 2c (1) +.SH DIAGNOSTICS +Math functions in +.I libc +return +special values when the function is undefined for the +given arguments or when the value is not representable +(see +.IR nan (2)). +.PP +Some of the functions in +.I libc +are system calls and many others employ system calls in their implementation. +All system calls return integers, +with \-1 indicating that an error occurred; +.IR errstr (2) +recovers a string describing the error. +Some user-level library functions also use the +.I errstr +mechanism to report errors. +Functions that may affect the value of the error string are said to ``set +.IR errstr ''; +it is understood that the error string is altered only if an error occurs. +.SH BUGS +The limitation of path elements to 27 bytes +.RB ( NAMELEN-1 ) +is a liability in the networked world. diff --git a/static/plan9-4e/man2/9p.2 b/static/plan9-4e/man2/9p.2 new file mode 100644 index 00000000..f1191bb5 --- /dev/null +++ b/static/plan9-4e/man2/9p.2 @@ -0,0 +1,678 @@ +.TH 9P 2 +.SH NAME +Srv, +dirread9p, +emalloc9p, +erealloc9p, +estrdup9p, +postfd, +postmountsrv, +readbuf, +readstr, +respond, +threadpostmountsrv, +srv \- 9P file service +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fLTree* 'u +typedef struct Srv { + Tree* tree; + + void (*attach)(Req*); + void (*auth)(Req*); + void (*open)(Req*); + void (*create)(Req*); + void (*read)(Req*); + void (*write)(Req*); + void (*remove)(Req*); + void (*flush)(Req*); + void (*stat)(Req*); + void (*wstat)(Req*); + void (*walk)(Req*); + + char* (*walk1)(Fid *fid, char *name, Qid *qid); + char* (*clone)(Fid *oldfid, Fid *newfid); + + void (*destroyfid)(Fid*); + void (*destroyreq)(Req*); + void (*end)(Srv*); + void* aux; +} Srv; +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +int srv(Srv *s, int fd) +int postmountsrv(Srv *s, char *srvname, char *mtpt, int flag) +int threadpostmountsrv(Srv *s, char *srvname, char *mtpt, int flag) +int postfd(char *srvname, int fd) +void respond(Req *r, char *error) +ulong readstr(Req *r, char *src) +ulong readbuf(Req *r, void *src, ulong nsrc) +typedef int Dirgen(int n, Dir *dir, void *aux) +void dirread9p(Req *r, Dirgen *gen, void *aux) +.fi +.PP +.nf +.ft L +.ta \w'\fLvoid* 'u +void* emalloc9p(ulong n) +void* erealloc9p(void *v, ulong n) +char* estrdup9p(char *s) +.fi +.PP +.nf +.ft L +extern int chatty9p; +.fi +.SH DESCRIPTION +The function +.I srv +uses serves a 9P session by dispatching requests +to the function pointers kept in +.BR Srv . +.PP +.B Req +and +.B Fid +structures are allocated one-to-one with uncompleted +requests and active fids, and are described in +.IR 9pfid (2). +.PP +The behavior of +.I srv +depends on whether there is a file tree +(see +.IR 9pfile (2)) +associated with the server, that is, +whether the +.B tree +element is nonzero. +The differences are made explicit in the +discussion of the service loop below. +The +.B aux +element is the client's, to do with as it pleases. +At the end of its service loop, +.I srv +calls the +.I endsrv +function (if not zero) +on the +.I Srv +structure itself. +.I Endsrv +should perform any necessary cleanup, +which may include freeing the data associated +with +.IR aux , +or freeing the +.B Srv +structure itself. +.PP +.I Srv +does not return until the 9P conversation is finished. +.I Postmountsrv +and +.I threadpostmountsrv +are wrappers that create a separate process in which to run +.IR srv , +optionally posting the remote end of the service pipe in +.BI /srv/ srvname +or mounting it at +.IR mtpt . +They both return +the file descriptor corresponding to the +.I local +end of the service pipe on success, or \-1 on failure. +.I Threadpostmountsrv +is intended for use in programs that utilize the +.IR thread (2) +library. +.I Postfd +posts the given file descriptor as +.BI /srv/ srvname \fR, +but does not mount and does not start the service loop. +.PP +Since it is usually run in a separate process so that +the caller can exit, the service loop has little chance +to return gracefully on out of memory errors. +It calls +.IR emalloc9p , +.IR erealloc9p , +and +.I estrdup 9p +to obtain its memory. +The default implementations of these functions +act as +.IR malloc , +.IR realloc , +and +.I strdup +but abort the program if they run out of memory. +If alternate behavior is desired, clients can link against +alternate implementations of these functions. +.SS Service functions +The functions in a +.B Srv +structure named after 9P transactions +are called to satisfy requests as they arrive. +If a function is provided, it +.I must +arrange for +.I respond +to be called when the request is satisfied. +The only parameter of each service function +is a +.B Req* +parameter (say +.BR r ). +The incoming request parameters are stored in +.IB r -> ifcall \fR; +.IB r -> fid +and +.IB r -> newfid +are pointers to +.B Fid +structures corresponding to the +numeric fids in +.IB r -> ifcall \fR; +similarly, +.IB r -> oldreq +is the +.B Req +structure corresponding to +.IB r -> ifcall.oldreq \fR. +The outgoing response data should be stored in +.IB r -> ofcall \fR. +The one exception to this rule is that +.B stat +should fill in +.IB r -> d +rather than +.IB r -> ofcall.stat \fR: +the library will convert the structure into the machine-independent +wire representation. +Similarly, +.B wstat +may consult +.IB r -> d +rather than decoding +.IB r -> ifcall . stat +itself. +When a request has been handled, +.I respond +should be called with +.B r +and an error string. +If the request was satisfied successfully, the error +string should be a nil pointer. +Note that it is permissible for a function to return +without itself calling +.IR respond , +as long as it has arranged for +.I respond +to be called at some point in the future +by another proc sharing its address space, +but see the discussion of +.B flush +below. +Once +.I respond +has been called, the +.B Req* +as well as any pointers it once contained must +be considered freed and not referenced. +.PP +If the service loop detects an error in a request +(e.g., an attempt to reuse an extant fid, an open of +an already open fid, a read from a fid opened for write, etc.) +it will reply with an error without consulting +the service functions. +.PP +The service loop provided by +.I srv +(and indirectly by +.I postmountsrv +and +.IR threadpostmountsrv ) +is single-threaded. +If it is expected that some requests might +block, arranging for alternate processes +to handle them is suggested. +.PP +The constraints on the service functions are as follows. +These constraints are checked while the server executes. +If a service function fails to do something it ought to have, +.I srv +will call +.I endsrv +and then abort. +.TP +.I Auth +If authentication is desired, +the +.I auth +function should record that +.B afid +is the new authentication fid and +set +.I afid->qid +and +.IR ofcall.qid . +.I Auth +may be nil, in which case it will be treated as having +responded with the error +.RI `` "argv0: authentication not required" ,'' +where +.I argv0 +is the program name variable as set by +.I ARGBEGIN +(see +.IR arg (2)). +.TP +.I Attach +The +.I attach +function should check the authentication state of +.B afid +if desired, +and set +.IB r -> fid -> qid +and +.I ofcall.qid +to the qid of the file system root. +.I Attach +may be nil only if file trees are in use; +in this case, the qid will be filled from the root +of the tree, and no authentication will be done. +.TP +.B Walk +If file trees are in use, +.I walk +is handled internally, and +.IB srv -> walk +is never called. +.IP +If file trees are not in use, +.I walk +should consult +.B ifcall.wname +and +.BR ifcall.nwname , +filling in +.B ofcall.qid +and +.BR ofcall.nqid , +and also copying any necessary +.B aux +state from +.IB r -> fid +to +.IB r -> newfid +when the two are different. +As long as +.I walk +sets +.B ofcall.nqid +appropriately, it can +.I respond +with a nil error string even when 9P +demands an error +.RI ( e.g. , +in the case of a short walk); +the library detects error conditions and handles them appropriately. +.TP +.B Walk1\fR, \fPClone +Because implementing the full walk message is +intricate and prone to error, the client may instead provide functions +.IB srv -> walk1 +and (optionally) +.IB srv -> clone \fR. +.IR Clone , +if non-nil, is called to signal the creation of +.I newfid +from +.IR oldfid . +Typically a +.I clone +routine will copy or increment a reference count in +.IR oldfid 's +.I aux +element. +.I Walk1 +should walk +.I fid +to +.IR name , +initializing both +.IB fid -> qid +and +.BI * qid +to the new path's qid. +Rather than calling +.IR respond , +both should return nil +on success or an error message on error. +.TP +.B Open +If file trees are in use, the file +metadata will be consulted on open, create, remove, and wstat +to see if the requester has the appropriate permissions. +If not, an error will be sent back without consulting a service function. +.PP +If not using file trees or the user has the appropriate permissions, +.I open +is called with +.IB r -> ofcall . qid +already initialized to the one stored in the +.B Fid +structure (that is, the one returned in the previous walk). +If the qid changes, both should be updated. +.TP +.B Create +The +.I create +function must fill in +both +.IB r -> fid -> qid +and +.IB r -> ofcall . qid +on success. +When using file trees, +.I create +should allocate a new +.B File +with +.IR createfile ; +note that +.I createfile +may return nil (because, say, the file already exists). +If the +.I create +function is nil, +.I srv +behaves as though it were a function that always responded +with the error ``create prohibited''. +.TP +.B Remove +.I Remove +should mark the file as removed, whether +by calling +.I removefile +when using file trees, or by updating an internal data structure. +In general it is not a good idea to clean up the +.I aux +information associated with the corresponding +.B File +at this time, to avoid memory errors if other +fids have references to that file. +Instead, it is suggested that +.I remove +simply mark the file as removed (so that further +operations on it know to fail) and wait until the +file tree's destroy function is called to reclaim the +.I aux +pointer. +If not using file trees, it is prudent to take the +analogous measures. +If +.I remove +is not provided, all remove requests will draw +``remove prohibited'' errors. +.TP +.B Read +The +.I read +function must be provided; it fills +.IB r -> ofcall . data +with at most +.IB r -> ifcall . count +bytes of data from offset +.IB r -> ofcall . offset +of the file. +It also sets +.IB r -> ofcall . count +to the number of bytes being returned. +If using file trees, +.I srv +will handle reads of directories internally, only +calling +.I read +for requests on files. +.I Readstr +and +.I readbuf +are useful for satisfying read requests on a string or buffer. +Consulting the request in +.BR r->ifcall , +they fill +.B r->ofcall.data +and set +.BR r->ofcall.count ; +they do not call +.BR respond . +Similarly, +.I dirread9p +can be used to handle directory reads in servers +not using file trees. +The passed +.I gen +function will be called as necessary to +fill +.I dir +with information for the +.I n th +entry in the directory. +The string pointers placed in +.I dir +should be fresh copies +made with +.IR estrdup9p ; +they will be freed by +.I dirread9p +after each successful call to +.IR gen . +.I Gen +should return zero if it successfully filled +.IR dir , +minus one on end of directory. +.TP +.B Write +The +.I write +function is similar but need not be provided. +If it is not, all writes will draw +``write prohibited'' errors. +Otherwise, +.I write +should attempt to write the +.IB r -> ifcall . n +bytes of +.IB r -> ifcall . data +to offset +.IB r -> ifcall . offset +of the file, setting +.IB r -> ofcall . offset +to the number of bytes actually written. +Most programs consider it an error to +write less than the requested amount. +.TP +.B Stat +.I Stat +should fill +.IB r -> d +with the stat information for +.IB r -> fid \fR. +If using file trees, +.IB r -> d +will have been initialized with the stat info from +the tree, and +.I stat +itself may be nil. +.TP +.I Wstat +The +.I wstat +consults +.IB r -> d +in changing the metadata for +.IB r -> fid +as described in +.IR stat (5). +When using file trees, +.I srv +will take care to check that the request satisfies +the permissions outlined in +.IR stat (5). +Otherwise +.I wstat +should take care to enforce permissions +where appropriate. +.TP +.B Flush +Single-threaded servers, which always call +.I respond +before returning from the service functions, +need not provide a +.I flush +implementation: +.I flush +is only necessary in multithreaded programs, +which arrange for +.I respond +to be called asynchronously. +.I Flush +must ensure that once +.I respond +has been called on +.BR r , +.I respond +will +.I never +be called on +.IB r -> oldreq \fR, +and in fact that +.IB r -> oldreq +and the pointers it contains +will never be accessed again (consider them freed). +.I Flush +must +.I not +call respond with a non-nil error string. +.PD +.PP +.IR Destroyfid , +.IR destroyreq , +and +.I end +are auxiliary functions, not called in direct response to 9P requests. +.TP +.B Destroyfid +When a +.BR Fid 's +reference count drops to zero +.RI ( i.e., +it has been clunked and there are no outstanding +requests referring to it), +.I destroyfid +is called to allow the program to dispose +of the +.B Fid.aux +pointer. +.TP +.B Destroyreq +Similarly, when a +.BR Req 's +reference count drops to zero +.RI ( i.e. , +it has been handled via +.I respond +or has been successfully flushed), +.I destroyreq +is called to allow the program to dispose of the +.B Req.aux +pointer. +.TP +.B End +Once the 9P service loop has finished +(end of file been reached on the service pipe +or a bad message has been read), +.I end +is called (if provided) to allow any final cleanup. +For example, it is used by the Palm Pilot synchronization +file system to gracefully close the serial connection once +the file system has been unmounted. +After calling +.IR end , +the service loop (which runs in a separate process +from its caller) terminates using +.I _exits +(see +.IR exits (2)). +.PD +.PP +If the +.B chatty9p +flag is at least one, +a transcript of the 9P session is printed +on standard error. +If the +.B chatty9p +flag is greater than one, +additional unspecified debugging output is generated. +By convention, servers written using this library +accept the +.B -D +option to increment +.BR chatty9p . +.SH EXAMPLES +.IR Archfs (4), +.IR cdfs (4), +.IR nntpfs (4), +.IR snap (4), +and +.B /sys/src/lib9p/ramfs.c +are good examples of simple single-threaded file servers. +.IR Webfs (4) +and +.I sshnet +(see +.IR ssh (1)) +are good examples of multithreaded file servers. +.PP +In general, the +.B File +interface is appropriate for maintaining arbitrary file trees (as in +.IR ramfs ). +The +.B File +interface is best avoided when the +tree structure is easily generated as necessary; +this is true when the tree is highly structured (as in +.I cdfs +and +.IR nntpfs ) +or is maintained elsewhere. +.SH SOURCE +.B /sys/src/lib9p +.SH SEE ALSO +.IR 9pfid (2), +.IR 9pfile (2), +.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. diff --git a/static/plan9-4e/man2/9pfid.2 b/static/plan9-4e/man2/9pfid.2 new file mode 100644 index 00000000..33c05761 --- /dev/null +++ b/static/plan9-4e/man2/9pfid.2 @@ -0,0 +1,204 @@ +.TH 9PFID 2 +.SH NAME +Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid, +Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq \- 9P fid, request tracking +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Fid +{ + ulong fid; + char omode; /* -1 if not open */ + char *uid; + Qid qid; + File *file; + void *aux; + \fI...\fP +} Fid; +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Req +{ + ulong tag; + Fcall fcall; + Req *oldreq; + void *aux; + \fI...\fP +} Req; +.fi +.PP +.ft L +.nf +.ta \w'\fLFidpool* 'u +Fidpool* allocfidpool(void (*destroy)(Fid*)) +void freefidpool(Fidpool *p) +Fid* allocfid(Fidpool *p, ulong fid) +Fid* lookupfid(Fidpool *p, ulong fid) +void closefid(Fid *f) +void removefid(Fid *f) +.fi +.PP +.ft L +.nf +.ta \w'\fLReqpool* 'u +Reqpool* allocreqpool(void (*destroy)(Req*)) +void freereqpool(Reqpool *p) +Req* allocreq(Reqpool *p, ulong tag) +Req* lookupreq(Reqpool *p, ulong tag) +void closereq(Req *f) +void removereq(Req *r) +.fi +.SH DESCRIPTION +These routines provide management of +.B Fid +and +.B Req +structures from +.BR Fidpool s +and +.BR Reqpool s. +They are primarily used by the 9P server loop +described in +.IR 9p (2). +.PP +.B Fid +structures are intended to represent +active fids in a 9P connection, as +.B Chan +structures do in the Plan 9 kernel. +The +.B fid +element is the integer fid used in the 9P +connection. +.B Omode +is the mode under which the fid was opened, or +.B -1 +if this fid has not been opened yet. +Note that in addition to the values +.BR OREAD , +.BR OWRITE , +and +.BR ORDWR , +.B omode +can contain the various flags permissible in +an open call. +To ignore the flags, use +.BR omode&OMASK . +.B Omode +should not be changed by the client. +The fid derives from a successful authentication by +.BR uid . +.B Qid +contains the qid returned in the last successful +.B walk +or +.B create +transaction involving the fid. +In a file tree-based server, the +.BR Fid 's +.B file +element points at a +.B File +structure +(see +.IR 9pfile (2)) +corresponding to the fid. +The +.B aux +member is intended for use by the +client to hold information specific to a particular +.BR Fid . +With the exception of +.BR aux , +these elements should be treated +as read-only by the client. +.PP +.I Allocfidpool +creates a new +.BR Fidpool . +.I Freefidpool +destroys such a pool. +.I Allocfid +returns a new +.B Fid +whose fid number is +.IR fid . +There must not already be an extant +.B Fid +with that number in the pool. +Once a +.B Fid +has been allocated, it can be looked up by +fid number using +.IR lookupfid . +.BR Fid s +are reference counted: both +.I allocfid +and +.I lookupfid +increment the reference count on the +.B Fid +structure before +returning. +When a reference to a +.B Fid +is no longer needed, +.I closefid +should be called to note the destruction of the reference. +When the last reference to a +.B Fid +is removed, if +.I destroy +(supplied when creating the fid pool) +is not zero, it is called with the +.B Fid +as a parameter. +It should perform whatever cleanup is necessary +regarding the +.B aux +element. +.I Removefid +is equivalent to +.I closefid +but also removes the +.B Fid +from the pool. +Note that due to lingering references, +the return of +.I removefid +may not mean that +.I destroy +has been called. +.PP +.IR Allocreqpool , +.IR freereqpool , +.IR allocreq , +.IR lookupreq , +.IR closereq , +and +.I removereq +are analogous but +operate on +.BR Reqpool s +and +.B Req +structures. +.SH SOURCE +.B /sys/src/lib9p +.SH SEE ALSO +.IR 9p (2), +.IR 9pfile (2) diff --git a/static/plan9-4e/man2/9pfile.2 b/static/plan9-4e/man2/9pfile.2 new file mode 100644 index 00000000..10949a26 --- /dev/null +++ b/static/plan9-4e/man2/9pfile.2 @@ -0,0 +1,224 @@ +.TH 9PFILE 2 +.SH NAME +Tree, alloctree, freetree, +File, createfile, closefile, removefile, walkfile, +opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLFile 'u +typedef struct File +{ + Ref; + Dir; + void *aux; + \fI...\fP +} File; +.fi +.PP +.ft L +.nf +.ta \w'\fLTree 'u +typedef struct Tree +{ + File *root; + \fI...\fP +} Tree; +.fi +.PP +.ft L +.nf +.ta \w'\fLReaddir* 'u +4n +4n +Tree* alloctree(char *uid, char *gid, ulong mode, + void (*destroy)(File*)) +void freetree(Tree *tree) +File* createfile(File *dir, char *name, char *uid, + ulong mode, void *aux) +int removefile(File *file) +void closefile(File *file) +File* walkfile(File *dir, char *path) +Readdir* opendirfile(File *dir) +long readdirfile(Readdir *rdir, char *buf, long n) +void closedirfile(Readdir *rdir) +int hasperm(File *file, char *uid, int p) +.fi +.SH DESCRIPTION +.BR File s +and +.BR Tree s +provide an in-memory file hierarchy +intended for use in 9P file servers. +.PP +.I Alloctree +creates a new tree of files, and +.I freetree +destroys it. +The root of the tree +(also the +.B root +element in the structure) +will have mode +.I mode +and be owned by user +.I uid +and group +.IR gid . +.I Destroy +is used when freeing +.B File +structures and is described later. +.PP +.BR File s +(including directories) +other than the root are created using +.IR createfile , +which attempts to create a file named +.I name +in the directory +.IR dir . +If created, the file will have owner +.I uid +and have a group inherited from +the directory. +.I Mode +and the permissions of +.I dir +are used to calculate the permission bits for +the file as described in +.IR open (5). +It is permissible for +.I name +to be a slash-separated path rather than a single element. +.PP +.I Removefile +removes a file from the file tree. +The file will not be freed until the last +reference to it has been removed. +Directories may only be removed when empty. +.I Removefile +returns zero on success, \-1 on error. +It is correct to consider +.I removefile +to be +.I closefile +with the side effect of removing the file +when possible. +.PP +.I Walkfile +evaluates +.I path +relative to the directory +.IR dir , +returning the resulting file, +or zero if the named file or any intermediate element +does not exist. +.PP +The +.B File +structure's +.B aux +pointer may be used by the client +for +.RB per- File +storage. +.BR File s +are reference-counted: if not zero, +.I destroy +(specified in the call to +.IR alloctree ) +will be called for each file when its +last reference is removed or when the tree is freed. +.I Destroy +should take care of any necessary cleanup related to +.BR aux . +When creating new file references by copying pointers, +call +.I incref +(see +.IR lock (2)) +to update the reference count. +To note the removal of a reference to a file, call +.IR closefile . +.I Createfile +and +.I walkfile +return new references. +.IR Removefile , +.IR closefile , +and +.I walkfile +(but not +.IR createfile ) +consume the passed reference. +.PP +Directories may be read, yielding a directory entry structure +(see +.IR stat (5)) +for each file in the directory. +In order to allow concurrent reading of directories, +clients must obtain a +.B Readdir +structure by calling +.I opendirfile +on a directory. +Subsequent calls to +.I readdirfile +will each yield an integral number of machine-independent +stat buffers, until end of directory. +When finished, call +.I closedirfile +to free the +.BR Readdir . +.PP +.I Hasperm +does simplistic permission checking; it assumes only +one-user groups named by uid and returns non-zero if +.I uid +has permission +.I p +(a bitwise-or of +.BR AREAD , +.BR AWRITE +and +.BR AEXEC ) +according to +.IB file ->mode \fR. +9P servers written using +.B File +trees will do standard permission checks automatically; +.I hasperm +may be called explicitly to do additional checks. +A 9P server may link against a different +.I hasperm +implementation to provide more complex groups. +.SH EXAMPLE +The following code correctly handles references +when elementwise walking a path and creating a file. +.IP +.EX +f = tree->root; +incref(f); +for(i=0; i +plan 9 man section 2 + + +[manual index] +

Plan 9 from Bell Labs - Section 2 - System and Library Calls

+
+
+
0intro +- introduction to library functions +
intro + +
9p +- 9P file service +
Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, postmountsrv, readbuf, readstr, respond, threadpostmountsrv, srv + +
9pfid +- 9P fid, request tracking +
Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid, Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq + +
9pfile +- in-memory file hierarchy +
Tree, alloctree, freetree, File, createfile, closefile, removefile, walkfile, opendirfile, readdirfile, closedirfile, hasperm + +
abort +- generate a fault +
abort + +
abs +- integer absolute values +
abs, labs + +
access +- determine accessibility of file +
access + +
addpt +- arithmetic on points and rectangles +
addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, Dx, Dy, Pt, Rect, Rpt + +
aes +- advanced encryption standard (rijndael) +
setupAESstate, aesCBCencrypt, aesCBCdecrypt + +
allocimage +- allocating, freeing, reading, writing images +
allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline + +
arg +- process option letters from argv +
ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt + +
arith3 +- operations on 3-d points and planes +
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 + +
assert +- check program invariants +
assert + +
atof +- convert text to numbers +
atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull + +
auth +- +
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 + +
authsrv +- routines for communicating with authentication servers +
authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp + +
bin +- grouped memory allocation +
binalloc, bingrow, binfree + +
bind +- change name space +
bind, mount, unmount + +
bio +- buffered input/output +
Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered + +
blowfish +- blowfish encryption +
setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt + +
brk +- change memory allocation +
brk, sbrk + +
cachechars +- font utilities +
cachechars, agefont, loadchar, Subfont, Fontchar, Font + +
chdir +- change working directory +
chdir + +
cleanname +- clean a path name +
cleanname + +
color +- colors and color maps +
cmap2rgb, cmap2rgba, rgb2cmap + +
control +- interactive graphical controls +
Control, Controlset, activate, closecontrol, closecontrolset, controlcalled, controlwire, createbox, createboxbox, createbutton, createcolumn, createentry, createkeyboard, createlabel, createmenu, createradiobutton, createrow, createscribble, createslider, createstack, createtab, createtext, createtextbutton, ctlerror, ctlmalloc, ctlrealloc, ctlstrdup, ctlprint, deactivate, freectlfont, freectlimage, initcontrols, namectlfont, namectlimage, newcontrolset, resizecontrolset + +
cputime +- cpu time in this process and children +
cputime, times + +
ctime +- convert date and time +
ctime, localtime, gmtime, asctime, tm2sec, timezone + +
ctype +- ASCII character classification +
isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toascii, _toupper, _tolower, toupper, tolower + +
debugger +- machine-independent debugger functions +
cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff, fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos, leieeesftos, leieeedftos, ieeesftos, ieeedftos + +
des +- single and triple digital encryption standard +
setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, setupDES3state, triple_block_cipher, + +
dial +- make and break network connections +
dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo + +
dirread +- read directory +
dirread, dirreadall + +
disk +- generic disk device interface +
opendisk, Disk + +
draw +- graphics functions +
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 + +
dup +- duplicate an open file descriptor +
dup + +
elgamal +- elgamal encryption +
eggen, egencrypt, egdecrypt, egsign, egverify, egalloc, egfree, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub + +
encode +- encoding byte arrays as strings +
dec64, enc64, dec32, enc32, dec16, enc16, encodefmt + +
encrypt +- DES encryption +
encrypt, decrypt, netcrypt + +
errstr +- description of last system call error +
errstr, rerrstr, werrstr + +
event +- graphics events +
event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu + +
exec +- execute a file +
exec, execl, _clock, _privates, _nprivates + +
exits +- terminate process, process cleanup +
exits, _exits, atexit, atexitdont, terminate + +
exp +- exponential, logarithm, power, square root +
exp, log, log10, pow, pow10, sqrt + +
fauth +- set up authentication on a file descriptor to a file server +
fauth + +
fcall +- interface to Plan 9 File protocol +
Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeD2M + +
fd2path +- return file name associated with file descriptor +
fd2path + +
fgetc +- Stdio input and output +
fgetc, getc, getchar, fputc, putc, putchar, ungetc, fgets, gets, fputs, puts, fread, fwrite + +
flate +- deflate compression +
deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 + +
floor +- absolute value, remainder, floor, ceiling functions +
fabs, fmod, floor, ceil + +
fmtinstall +- support for user-defined print formats and output routines +
fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt + +
fopen +- standard buffered input/output package +
fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror, clearerr + +
fork +- manipulate process resources +
fork, rfork + +
fprintf +- print formatted output +
fprintf, printf, sprintf, snprintf, vfprintf, vprintf, vsprintf, vsnprintf + +
frame +- frames of text +
frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse + +
frexp +- split into mantissa and exponent +
frexp, ldexp, modf + +
fscanf +- scan formatted input +
fscanf, scanf, sscanf, vfscanf + +
fversion +- initialize 9P connection and negotiate version +
fversion + +
genrandom +- random number generation +
genrandom, prng + +
getcallerpc +- fetch return PC of current function +
getcallerpc + +
getenv +- access environment variables +
getenv, putenv + +
getfcr +- control floating point +
getfcr, setfcr, getfsr, setfsr + +
getfields +- break a string into fields +
getfields, gettokens, tokenize + +
getpid +- get process ids +
getpid, getppid + +
getuser +- get user or system name +
getuser, sysname + +
getwd +- get current directory +
getwd + +
graphics +- interactive graphics +
Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth + +
html +- HTML parser +
parsehtml, printitems, validitems, freeitems, freedocinfo, dimenkind, dimenspec, targetid, targetname, fromStr, toStr + +
httpd +- routines for creating an http server +
HConnect, HContent, HContents, HETag, HFields, Hio, Htmlesc, HttpHead, HttpReq, HRange, HSPairs, hmydomain, hversion, htmlesc, halloc, hbodypush, hbuflen, hcheckcontent, hclose, hdate2sec, hdatefmt, hfail, hflush, hgetc, hgethead, hinit, hiserror, hload, hlower, hmkcontent, hmkhfields, hmkmimeboundary, hmkspairs, hmoved, hokheaders, hparseheaders, hparsequery, hparsereq, hprint, hputc, hreadbuf, hredirected, hreqcleanup, hrevhfields, hrevspairs, hstrdup, http11, httpfmt, httpunesc, hunallowed, hungetc, hunload, hurlfmt, hurlunesc, hwrite, hxferenc, + +
hypot +- Euclidean distance +
hypot + +
intmap +- integer to data structure maps +
Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, deletekey + +
iounit +- return size of atomic I/O unit for file descriptor +
iounit + +
ip +- Internet protocol +
eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc + +
isalpharune +- Unicode character classes and cases +
isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, tolowerrune, totitlerune, toupperrune + +
keyboard +- keyboard control +
initkeyboard, ctlkeyboard, closekeyboard + +
lock +- shared memory spin locks, rendez-vous locks, reader-writer locks, and atomic increment and decrement +
lock, canlock, unlock, qlock, canqlock, qunlock, rlock, runlock, canrlock, wlock, wunlock, canwlock, incref, decref + +
mach +- machine-independent access to executable files +
crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap, loadmap, attachproc, get1, get2, get4, get8, put1, put2, put4, put8, beswab, beswal, beswav, leswab, leswal, leswav + +
malloc +- memory allocator +
malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock + +
matrix +- Geometric transformations +
ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport + +
memdraw +- drawing routines for memory-resident images +
Memimage, Memdata, Memdrawparam, memimageinit, wordaddr, byteaddr, memimagemove, allocmemimage, allocmemimaged, readmemimage, creadmemimage, writememimage, freememimage, memsetchan, loadmemimage, cloadmemimage, unloadmemimage, memfillcolor, memarc, mempoly, memellipse, memfillpoly, memimageline, memimagedraw, drawclip, memlinebbox, memlineendsize, allocmemsubfont, openmemsubfont, freememsubfont, memsubfontwidth, getmemdefont, memimagestring, iprint, hwdraw + +
memlayer +- windows of memory-resident images +
memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn + +
memory +- memory operations +
memccpy, memchr, memcmp, memcpy, memmove, memset + +
mktemp +- make a unique file name +
mktemp + +
mouse +- mouse control +
initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor + +
mp +- 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 + +
muldiv +- high-precision multiplication and division +
muldiv, umuldiv + +
nan +- not-a-number and infinity functions +
NaN, Inf, isNaN, isInf + +
ndb +- network database +
ndbopen, ndbcat, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetval, ndbfree, ipattr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetval, ndblookval, dnsquery + +
notify +- handle asynchronous process notification +
notify, noted, atnotify + +
object +- object file interpretation functions +
objtype, readobj, objtraverse, isar, nextar, readar + +
open +- open a file for reading or writing, create file +
open, create, close + +
perror +- system error messages +
perror, syslog, sysfatal + +
pipe +- create an interprocess channel +
pipe + +
plumb +- plumb messages +
eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg + +
pool +- general memory management routines +
poolalloc, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck, pooldump + +
postnote +- send a note to a process or process group +
postnote + +
prime +- prime number generation +
genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, smallprimetest + +
print +- print formatted output +
print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint + +
privalloc +- per-process private storage management +
privalloc, privfree + +
proto +- parse and process a proto file listing +
rdproto + +
pushssl +- attach SSL version 2 encryption to a communication channel +
pushssl + +
pushtls +- attach TLS1 or SSL3 encryption to a communication channel +
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert + +
qball +- 3-d rotation controller +
qball + +
qsort +- quicker sort +
qsort + +
quaternion +- Quaternion arithmetic +
qtom, mtoq, qadd, qsub, qneg, qmul, qdiv, qunit, qinv, qlen, slerp, qmid, qsqrt + +
quote +- quoted character strings +
quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote + +
rand +- random number generator +
rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand + +
rc4 +- alleged rc4 encryption +
setupRC4state, rc4, rc4skip, rc4back + +
read +- read or write file +
read, readn, write, pread, pwrite + +
readcolmap +- access display color map +
RGB, readcolmap, writecolmap + +
readv +- scatter/gather read and write +
readv, writev, preadv, pwritev + +
regexp +- regular expression +
regcomp, regcomplit, regcompnl, regexec, regsub, rregexec, rregsub, regerror + +
remove +- remove a file +
remove + +
rendezvous +- user level process synchronization +
rendezvous + +
rsa +- +
+ +
rune +- rune/UTF conversion +
runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf + +
runestrcat +- rune string operations +
runestrcat, runestrncat, runestrcmp, runestrncmp, runestrcpy, runestrncpy, runestrecpy, runestrlen, runestrchr, runestrrchr, runestrdup, runestrstr + +
scribble +- character recognition +
scribblealloc, recognize + +
scsi +- SCSI device operations +
openscsi, scsiready, scsi, scsicmd, scsierror + +
sechash +- cryptographically secure hashes +
md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle + +
seek +- change file offset +
seek + +
segattach +- map/unmap a segment in virtual memory +
segattach, segdetach, segfree + +
segbrk +- change memory allocation +
segbrk + +
segflush +- flush instruction and data caches +
segflush + +
setjmp +- non-local goto +
setjmp, longjmp, notejmp + +
sin +- trigonometric functions +
sin, cos, tan, asin, acos, atan, atan2 + +
sinh +- hyperbolic functions +
sinh, cosh, tanh + +
sleep +- delay, ask for delayed note +
sleep, alarm + +
stat +- get and put file status +
stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir + +
strcat +- string operations +
strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr + +
string +- 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 + +
stringsize +- graphical size of strings +
stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, runestringnwidth + +
subfont +- subfont manipulation +
allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont + +
symbol +- symbol table access functions +
syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal, getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym, fileline, fnbound + +
thread +- thread and proc management +
alt, chancreate, chanfree, chaninit, chanprint, mainstacksize, proccreate, procdata, procexec, procexecl, procrfork, recv, recvp, recvul, send, sendp, sendul, nbrecv, nbrecvp, nbrecvul, nbsend, nbsendp, nbsendul, threadcreate, threaddata, threadexits, threadexitsall, threadgetgrp, threadgetname, threadint, threadintgrp, threadkill, threadkillgrp, threadmain, threadnotify, threadid, threadpid, threadprint, threadsetgrp, threadsetname, threadwaitchan, yield + +
time +- time in seconds and nanoseconds since epoch +
time, nsec + +
tmpfile +- Stdio temporary files +
tmpfile, tmpnam + +
wait +- wait for a process to exit +
await, wait, waitpid + +
window +- window management +
Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow + +
diff --git a/static/plan9-4e/man2/Makefile b/static/plan9-4e/man2/Makefile new file mode 100644 index 00000000..b938fb36 --- /dev/null +++ b/static/plan9-4e/man2/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.2) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man2/abort.2 b/static/plan9-4e/man2/abort.2 new file mode 100644 index 00000000..feec9d85 --- /dev/null +++ b/static/plan9-4e/man2/abort.2 @@ -0,0 +1,18 @@ +.TH ABORT 2 +.SH NAME +abort \- generate a fault +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +void abort(void) +.fi +.SH DESCRIPTION +.I Abort +causes an access fault, causing the current process to enter the `Broken' state. +The process can then be inspected by a debugger. +.SH SOURCE +.B /sys/src/libc/9sys/abort.c diff --git a/static/plan9-4e/man2/abs.2 b/static/plan9-4e/man2/abs.2 new file mode 100644 index 00000000..b2df7fba --- /dev/null +++ b/static/plan9-4e/man2/abs.2 @@ -0,0 +1,33 @@ +.TH ABS 2 +.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 /sys/src/libc/port/abs.c +.SH SEE ALSO +.IR floor (2) +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/static/plan9-4e/man2/access.2 b/static/plan9-4e/man2/access.2 new file mode 100644 index 00000000..f21eda24 --- /dev/null +++ b/static/plan9-4e/man2/access.2 @@ -0,0 +1,64 @@ +.TH ACCESS 2 +.SH NAME +access \- determine accessibility of file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int access(char *name, int mode) +.SH DESCRIPTION +.I Access +evaluates the given +file +.I name +for accessibility. +If \fImode\fL&4\fR +is nonzero, +read permission is expected; +if \fImode\fL&2\fR, +write permission; +if \fImode\fL&1\fR, +execute permission. +If \fImode\fL==0\fR, +the file merely need exist. +In any case +all directories leading to the file +must permit searches. +Zero is returned if the desired access is permitted, +\-1 if not. +.PP +Only access bits are checked. +A file may look executable, but +.IR exec (2) +will fail unless it is in proper format. +.PP +The include file +.F +defines +.BR AEXIST =0, +.BR AEXEC =1, +.BR AWRITE =2, +and +.BR AREAD =4. +.PP +.SH SOURCE +.B /sys/src/libc/9sys/access.c +.SH SEE ALSO +.IR stat (2) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +Since file permissions are checked by the server and group information +is not known to the client, +.I access +must open the file to check permissions. +(It calls +.IR stat (2) +to check simple existence.) +Besides giving misleading information about the writability of directories, +this is as expensive as the open that +.I access +is often intended to avoid. diff --git a/static/plan9-4e/man2/addpt.2 b/static/plan9-4e/man2/addpt.2 new file mode 100644 index 00000000..9738c51b --- /dev/null +++ b/static/plan9-4e/man2/addpt.2 @@ -0,0 +1,188 @@ +.TH ADDPT 2 +.SH NAME +addpt, subpt, mulpt, divpt, rectaddpt, rectsubpt, insetrect, canonrect, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, combinerect, Dx, Dy, Pt, Rect, Rpt \- arithmetic on points and rectangles +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +Point addpt(Point p, Point q) +.PP +.B +Point subpt(Point p, Point q) +.PP +.B +Point mulpt(Point p, int a) +.PP +.B +Point divpt(Point p, int a) +.PP +.B +Rectangle rectaddpt(Rectangle r, Point p) +.PP +.B +Rectangle rectsubpt(Rectangle r, Point p) +.PP +.B +Rectangle insetrect(Rectangle r, int n) +.PP +.B +Rectangle canonrect(Rectangle r) +.PP +.B +int eqpt(Point p, Point q) +.PP +.B +int eqrect(Rectangle r, Rectangle s) +.PP +.B +int ptinrect(Point p, Rectangle r) +.PP +.B +int rectinrect(Rectangle r, Rectangle s) +.PP +.B +int rectXrect(Rectangle r, Rectangle s) +.PP +.B +int rectclip(Rectangle *rp, Rectangle b) +.PP +.B +void combinerect(Rectangle *rp, Rectangle b) +.PP +.B +int Dx(Rectangle r) +.PP +.B +int Dy(Rectangle r) +.PP +.B +Point Pt(int x, int y) +.PP +.B +Rectangle Rect(int x0, int y0, int x1, int y1) +.PP +.B +Rectangle Rpt(Point p, Point q) +.SH DESCRIPTION +The functions +.IR Pt , +.I Rect +and +.I Rpt +construct geometrical data types from their components. +.PP +.I Addpt +returns the Point +sum of its arguments: +.BI Pt( p .x+ q .x, +.IB p .y+ q .y) \f1. +.I Subpt +returns the Point +difference of its arguments: +.BI Pt( p .x- q .x, +.IB p .y- q .y) \f1. +.I Mulpt +returns the Point +.BI Pt( p .x* a , +.IB p .y* a ) \f1. +.I Divpt +returns the Point +.BI Pt( p .x/ a , +.IB p .y/ a ) \f1. +.PP +.I Rectaddpt +returns the Rectangle +.BI Rect(add( r .min, +.IB p ) \f1, +.BI add( r .max, +.IB p )) \f1; +.I rectsubpt +returns the Rectangle +.BI Rpt(sub( r .min, +.IB p ), +.BI sub( r .max, +.IB p ))\fR. +.PP +.I Insetrect +returns the Rectangle +.BI Rect( r .min.x+ n \f1, +.IB r .min.y+ n \f1, +.IB r .max.x- n \f1, +.IB r .max.y- n ) \f1. +.PP +.I Canonrect +returns a rectangle with the same extent as +.IR r , +canonicalized so that +.B min.x +≤ +.BR max.x , +and +.B min.y +≤ +.BR max.y . +.PP +.I Eqpt +compares its argument Points and returns +0 if unequal, +1 if equal. +.I Eqrect +does the same for its argument Rectangles. +.PP +.I Ptinrect +returns 1 if +.I p +is a point within +.IR r , +and 0 otherwise. +.PP +.I Rectinrect +returns 1 if all the pixels in +.I r +are also in +.IR s , +and 0 otherwise. +.PP +.I RectXrect +returns 1 if +.I r +and +.I s +share any point, and 0 otherwise. +.PP +.I Rectclip +clips in place +the Rectangle pointed to by +.I rp +so that it is completely contained within +.IR b . +The return value is 1 if any part of +.RI * rp +is within +.IR b . +Otherwise, the return value is 0 and +.RI * rp +is unchanged. +.PP +.I Combinerect +overwrites +.B *rp +with the smallest rectangle sufficient to cover all the pixels of +.B *rp +and +.BR b . +.PP +The functions +.I Dx +and +.I Dy +give the width (Δx) and height (Δy) of a Rectangle. +They are implemented as macros. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2) diff --git a/static/plan9-4e/man2/aes.2 b/static/plan9-4e/man2/aes.2 new file mode 100644 index 00000000..daf0043a --- /dev/null +++ b/static/plan9-4e/man2/aes.2 @@ -0,0 +1,50 @@ +.TH AES 2 +.SH NAME +setupAESstate, aesCBCencrypt, aesCBCdecrypt - advanced encryption standard (rijndael) +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupAESstate(AESstate *s, uchar key[], int keybytes, uchar *ivec) +.PP +.B +void aesCBCencrypt(uchar*, int, AESstate*) +.PP +.B +void aesCBCdecrypt(uchar*, int, AESstate*) +.PP +.SH DESCRIPTION +.PP +DES is being replaced by Rijndael, also known as AES, as the preferred +block ciper. +.IR setupAESstate , +.IR aesCBCencrypt , +and +.I aesCBCdecrypt +implement cipher block chaining encryption. +.I Keybytes +should be 16, 24, or 32. +The initialization vector +.I ivec +of +.I AESbsize +bytes should random enough to be unlikely to be reused but does not need to be +cryptographically strongly unpredictable. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/allocimage.2 b/static/plan9-4e/man2/allocimage.2 new file mode 100644 index 00000000..f49b962b --- /dev/null +++ b/static/plan9-4e/man2/allocimage.2 @@ -0,0 +1,348 @@ +.TH ALLOCIMAGE 2 +.SH NAME +allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images +.SH SYNOPSIS +.nf +.PP +.B +#include +.B +#include +.B +#include +.PP +.ta \w'\fLImage 'u +.B +Image *allocimage(Display *d, Rectangle r, +.br +.B + ulong chan, int repl, int col) +.PP +.B +Image *allocimagemix(Display *d, ulong one, ulong three) +.PP +.B +void freeimage(Image *i) +.PP +.B +int nameimage(Image *i, char *name, int in) +.PP +.B +Image *namedimage(Display *d, char *name) +.PP +.B +ulong setalpha(ulong color, uchar alpha) +.PP +.B +int loadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +int cloadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +int unloadimage(Image *i, Rectangle r, uchar *data, int ndata) +.PP +.B +Image *readimage(Display *d, int fd, int dolock) +.PP +.B +int writeimage(int fd, Image *i, int dolock) +.PP +.B +int bytesperline(Rectangle r, int d) +.PP +.B +int wordsperline(Rectangle r, int d) +.PP +.nf +.B +enum +.nf +.ft L +.ta +4n +20 +{ + DOpaque = 0xFFFFFFFF, + DTransparent = 0x00000000, + DBlack = 0x000000FF, + DWhite = 0xFFFFFFFF, + DRed = 0xFF0000FF, + DGreen = 0x00FF00FF, + DBlue = 0x0000FFFF, + DCyan = 0x00FFFFFF, + DMagenta = 0xFF00FFFF, + DYellow = 0xFFFF00FF, + DPaleyellow = 0xFFFFAAFF, + DDarkyellow = 0xEEEE9EFF, + DDarkgreen = 0x448844FF, + DPalegreen = 0xAAFFAAFF, + DMedgreen = 0x88CC88FF, + DDarkblue = 0x000055FF, + DPalebluegreen = 0xAAFFFFFF, + DPaleblue = 0x0000BBFF, + DBluegreen = 0x008888FF, + DGreygreen = 0x55AAAAFF, + DPalegreygreen = 0x9EEEEEFF, + DYellowgreen = 0x99994CFF, + DMedblue = 0x000099FF, + DGreyblue = 0x005DBBFF, + DPalegreyblue = 0x4993DDFF, + DPurpleblue = 0x8888CCFF, + + DNotacolor = 0xFFFFFF00, + DNofill = DNotacolor, + +}; +.fi +.SH DESCRIPTION +A new +.B Image +on +.B Display +.B d +is allocated with +.BR allocimage ; +it will have the rectangle, pixel channel format, +and replication flag +given by its arguments. +Convenient pixel channels like +.BR GREY1 , +.BR GREY2 , +.BR CMAP8 , +.BR RGB16 , +.BR RGB24 , +and +.BR RGBA32 +are predefined. +All the new image's pixels will have initial value +.IR col . +If +.I col +is +.BR DNofill , +no initialization is done. +Representative useful values of color are predefined: +.BR DBlack , +.BR DWhite , +.BR DRed , +and so on. +Colors are specified by 32-bit numbers comprising, +from most to least significant byte, +8-bit values for red, green, blue, and alpha. +The values correspond to illumination, so 0 is black and 255 is white. +Similarly, for alpha 0 is transparent and 255 is opaque. +The +.I id +field will have been set to the identifying number used by +.B /dev/draw +(see +.IR draw (3)), +and the +.I cache +field will be zero. +If +.I repl +is true, the clip rectangle is set to a very large region; if false, it is set to +.IR r . +The +.I depth +field will be set to the number of bits per pixel specified +by the channel descriptor +(see +.IR image (6)). +.I Allocimage +returns 0 if the server has run out of image memory. +.PP +.I Allocimagemix +is used to allocate background colors. +On 8-bit color-mapped displays, it +returns a 2×2 replicated image with one pixel colored +the color +.I one +and the other three with +.IR three . +(This simulates a wider range of tones than can be represented by a single pixel +value on a color-mapped display.) +On true color displays, it returns a 1×1 replicated image +whose pixel is the result of mixing the two colors in +a one to three ratio. +.PP +.I Freeimage +frees the resources used by its argument image. +.PP +.I Nameimage +publishes in the server the image +.I i +under the given +.IR name . +If +.I in +is non-zero, the image is published; otherwise +.I i +must be already named +.I name +and it is withdrawn from publication. +.I Namedimage +returns a reference to the image published under the given +.I name +on +.B Display +.IR d . +These routines permit unrelated applications sharing a display to share an image; +for example they provide the mechanism behind +.B getwindow +(see +.IR graphics (2)). +.PP +The RGB values in a color are +.I premultiplied +by the alpha value; for example, a 50% red is +.B 0x7F00007F +not +.BR 0xFF00007F . +The function +.I setalpha +performs the alpha computation on a given +.BR color , +ignoring its initial alpha value, multiplying the components by the supplied +.BR alpha . +For example, to make a 50% red color value, one could execute +.B setalpha(DRed, +.BR 0x7F) . +.PP +The remaining functions deal with moving groups of pixel +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)). +.PP +.I Unloadimage +reads a rectangle of pixels from image +.I i +into +.IR data , +whose length is specified by +.IR ndata . +It is an error if +.I ndata +is too small to accommodate the pixels. +.PP +.I Loadimage +replaces the specified rectangle in image +.I i +with the +.I ndata +bytes of +.IR data . +.PP +The pixels are presented one horizontal line at a time, +starting with the top-left pixel of +.IR r . +In the data processed by these routines, each scan line starts with a new byte in the array, +leaving the last byte of the previous line partially empty, if necessary. +Pixels are packed as tightly as possible within +.IR data , +regardless of the rectangle being extracted. +Bytes are filled from most to least significant bit order, +as the +.I x +coordinate increases, aligned so +.IR x =0 +would appear as the leftmost pixel of its byte. +Thus, for +.B depth +1, the pixel at +.I x +offset 165 within the rectangle will be in a +.I data +byte at bit-position +.B 0x04 +regardless of the overall +rectangle: 165 mod 8 equals 5, and +.B "0x80\ >>\ 5" +equals +.BR 0x04 . +.PP +.B Cloadimage +does the same as +.IR loadimage , +bu tfor +.I ndata +bytes of compressed image +.I data +(see +.IR image (6)). +On each call to +.IR cloadimage, +the +.I data +must be at the beginning of a compressed data block, in particular, +it should start with the +.B y +coordinate and data length for the block. +.PP +.IR Loadimage , +.IR cloadimage , +and +.I unloadimage +return the number of bytes copied. +.PP +.I Readimage +creates a image from data contained an external file (see +.IR image (6) +for the file format); +.I fd +is a file descriptor obtained by opening such a file for reading. +The returned image is allocated using +.IR allocimage . +The +.I dolock +flag specifies whether the +.B Display +should be synchronized for multithreaded access; single-threaded +programs can leave it zero. +.PP +.I Writeimage +writes image +.I i +onto file descriptor +.IR fd , +which should be open for writing. +The format is as described for +.IR readimage . +.PP +.I Readimage +and +.I writeimage +do not close +.IR fd . +.PP +.I Bytesperline +and +.I wordsperline +return the number of bytes or words occupied in memory by one scan line of rectangle +.I r +in an image with +.I d +bits per pixel. +.SH EXAMPLE +To allocate a single-pixel replicated image that may be used to paint a region red, +.EX + red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed); +.EE +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR graphics (2), +.IR draw (2), +.IR draw (3), +.IR image (6) +.SH DIAGNOSTICS +These functions return pointer 0 or integer \-1 on failure, usually due to insufficient +memory. +.PP +May set +.IR errstr . +.SH BUGS +.B Depth +must be a divisor or multiple of 8. diff --git a/static/plan9-4e/man2/arg.2 b/static/plan9-4e/man2/arg.2 new file mode 100644 index 00000000..e85ca13f --- /dev/null +++ b/static/plan9-4e/man2/arg.2 @@ -0,0 +1,122 @@ +.TH ARG 2 +.SH NAME +ARGBEGIN, ARGEND, ARGC, ARGF, EARGF, arginit, argopt \- process option letters from argv +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B ARGBEGIN { +.B char *ARGF(); +.B char *EARGF(code); +.B Rune ARGC(); +.B } ARGEND +.PP +.B extern char *argv0; +.SH DESCRIPTION +These macros assume the names +.I argc +and +.I argv +are in scope; see +.IR exec (2). +.I ARGBEGIN +and +.I ARGEND +surround code for processing program options. +The code +should be the cases of a C switch on +option characters; +it is executed once for each option character. +Options end after an argument +.BR -- , +before an argument +.BR - , +or before an argument that doesn't begin with +.BR - . +.PP +The function macro +.I ARGC +returns the current option character, as an integer. +.PP +The function macro +.I ARGF +returns the current option argument: +a pointer to the rest of the option string if not empty, +or the next argument in +.I argv +if any, or 0. +.I ARGF +must be called just once for each option +that takes an argument. +The macro +.I EARGF +is like +.I ARGF +but instead of returning zero +runs +.I code +and, if that returns, calls +.IR abort (2). +A typical value for +.I code +is +.BR usage() . +.PP +After +.IR ARGBEGIN , +.I argv0 +is a copy of +.BR argv[0] +(conventionally the name of the program). +.PP +After +.IR ARGEND , +.I argv +points at a zero-terminated list of the remaining +.I argc +arguments. +.SH EXAMPLE +This C program can take option +.B b +and option +.BR f , +which requires an argument. +.IP +.EX +.ta \w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +\w'12345678'u +#include +#include +void +main(int argc, char *argv[]) +{ + char *f; + print("%s", argv[0]); + ARGBEGIN { + case 'b': + print(" -b"); + break; + case 'f': + print(" -f(%s)", (f=ARGF())? f: "no arg"); + break; + default: + print(" badflag('%c')", ARGC()); + } ARGEND + print(" %d args:", argc); + while(*argv) + print(" '%s'", *argv++); + print("\en"); + exits(nil); +} +.EE +.PP +Here is the output from running the command +.B +prog -bffile1 -r -f file2 arg1 arg2 +.IP +.B +prog -b -f(file1) badflag('r') -f(file2) 2 args: 'arg1' 'arg2' +.PP +.SH SOURCE +.B /sys/include/libc.h diff --git a/static/plan9-4e/man2/arith3.2 b/static/plan9-4e/man2/arith3.2 new file mode 100644 index 00000000..f4e9e59b --- /dev/null +++ b/static/plan9-4e/man2/arith3.2 @@ -0,0 +1,269 @@ +.TH ARITH3 2 +.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 /sys/src/libgeometry +.SH "SEE ALSO +.IR matrix (2) diff --git a/static/plan9-4e/man2/assert.2 b/static/plan9-4e/man2/assert.2 new file mode 100644 index 00000000..3e952348 --- /dev/null +++ b/static/plan9-4e/man2/assert.2 @@ -0,0 +1,25 @@ +.TH ASSERT 2 +.SH NAME +assert \- check program invariants +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +#define assert if(cond);else _assert("cond") +.PP +.B +void _assert(int cond) +.SH DESCRIPTION +.I Assert +is a preprocessor macro that +(via +.IR _assert ) +prints a message and calls +.I abort +when +.I cond +is false. +.SH SOURCE +.B /sys/src/libc/port/_assert.c diff --git a/static/plan9-4e/man2/atof.2 b/static/plan9-4e/man2/atof.2 new file mode 100644 index 00000000..49246183 --- /dev/null +++ b/static/plan9-4e/man2/atof.2 @@ -0,0 +1,146 @@ +.TH ATOF 2 +.SH NAME +atof, atoi, atol, atoll, charstod, strtod, strtol, strtoll, strtoul, strtoull \- convert text to numbers +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.ta \w'\fLdouble 'u +.B +double atof(char *nptr) +.PP +.B +int atoi(char *nptr) +.PP +.B +long atol(char *nptr) +.PP +.B +vlong atoll(char *nptr) +.PP +.B +double charstod(int (*f)(void *), void *a) +.PP +.B +double strtod(char *nptr, char **rptr) +.PP +.B +long strtol(char *nptr, char **rptr, int base) +.PP +.B +vlong strtoll(char *nptr, char **rptr, int base) +.PP +.B +ulong strtoul(char *nptr, char **rptr, int base) +.PP +.B +vlong strtoull(char *nptr, char **rptr, int base) +.fi +.SH DESCRIPTION +.IR Atof , +.IR atoi , +.IR atol , +and +.I atoll +convert a string pointed to by +.I nptr +to floating, integer, long integer, and long long integer +.RB ( vlong ) +representation respectively. +The first unrecognized character ends the string. +Leading C escapes are understood, as in +.I strtol +with +.I base +zero (described below). +.PP +.I Atof +recognizes an optional string of tabs and spaces, +then an optional sign, then +a string of digits optionally containing a decimal +point, then an optional +.L e +or +.L E +followed +by an optionally signed integer. +.PP +.I Atoi +and +.I atol +recognize an optional string of tabs and spaces, +then an optional sign, then a string of +decimal digits. +.PP +.IR Strtod , +.IR strtol , +.IR strtoll , +.IR strtoul , +and +.I strtoull +behave similarly to +.I atof +and +.I atol +and, if +.I rptr +is not zero, set +.I *rptr +to point to the input character +immediately after the string converted. +.PP +.IR Strtol , +.IR strtoll , +.IR strtoul , +and +.IR strtoull +interpret the digit string in the specified +.IR base , +from 2 to 36, +each digit being less than the base. +Digits with value over 9 are represented by letters, +a-z or A-Z. +If +.I base +is 0, the input is interpreted as an integral constant in +the style of C (with no suffixed type indicators): +numbers are octal if they begin with +.LR 0 , +hexadecimal if they begin with +.L 0x +or +.LR 0X , +otherwise decimal. +.PP +.I Charstod +interprets floating point numbers in the manner of +.IR atof , +but gets successive characters by calling +.BR (*\fIf\fP)(a) . +The last call to +.I f +terminates the scan, so it must have returned a character that +is not a legal continuation of a number. +Therefore, it may be necessary to back up the input stream one character +after calling +.IR charstod . +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR fscanf (2) +.SH DIAGNOSTICS +Zero is returned if the beginning of the input string is not +interpretable as a number; even in this case, +.I rptr +will be updated. +.br +These routines set +.IR errstr . +.SH BUGS +.I Atoi +and +.I atol +accept octal and hexadecimal numbers in the style of C, +contrary to the ANSI specification. diff --git a/static/plan9-4e/man2/auth.2 b/static/plan9-4e/man2/auth.2 new file mode 100644 index 00000000..7dd92a39 --- /dev/null +++ b/static/plan9-4e/man2/auth.2 @@ -0,0 +1,395 @@ +.TH AUTH 2 +.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 (2) +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 (2)) +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 /sys/src/libauth +.SH SEE ALSO +.IR factotum (4), +.IR authsrv (2), +.IR bind (2) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/static/plan9-4e/man2/authsrv.2 b/static/plan9-4e/man2/authsrv.2 new file mode 100644 index 00000000..309e6251 --- /dev/null +++ b/static/plan9-4e/man2/authsrv.2 @@ -0,0 +1,217 @@ +.TH AUTHSRV 2 +.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 +.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 /sys/src/libauthsrv +.SH SEE ALSO +.IR passwd (1), +.IR cons (3), +.IR dial (2), +.IR authsrv (6), +.SH DIAGNOSTICS +These routines set +.IR errstr . +Integer-valued functions return -1 on error. diff --git a/static/plan9-4e/man2/bin.2 b/static/plan9-4e/man2/bin.2 new file mode 100644 index 00000000..f711b21d --- /dev/null +++ b/static/plan9-4e/man2/bin.2 @@ -0,0 +1,99 @@ +.TH BIN 2 +.SH NAME +binalloc, bingrow, binfree \- grouped memory allocation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.PP +.B +typedef struct Bin Bin; +.PP +.B +void *binalloc(Bin **bp, ulong size, int clr); +.PP +.B +void *bingrow(Bin **bp, void *op, ulong osize, +.br +.B + ulong size, int clr); +.PP +.B +void binfree(Bin **bp); +.SH DESCRIPTION +These routines provide simple grouped memory allocation and deallocation. +Items allocated with +.I binalloc +are added to the +.I Bin +pointed to by +.IR bp . +All items in a bin may be freed with one call to +.IR binfree ; +there is no way to free a single item. +.PP +.I Binalloc +returns a pointer to a new block of at least +.I size +bytes. +The block is suitably aligned for storage of any type of object. +No two active pointers from +.I binalloc +will have the same value. +The call +.B binalloc(0) +returns a valid pointer rather than null. +If +.I clr +is non-zero, the allocated memory is set to 0; +otherwise, the contents are undefined. +.PP +.I Bingrow +is used to extend the size of a block of memory returned by +.IR binalloc . +.I Bp +must point to the same bin group used to allocate the original block, +and +.I osize +must be the last size used to allocate or grow the block. +A pointer to a block of at least +.I size +bytes is returned, with the same contents in the first +.I osize +locations. +If +.I clr +is non-zero, the remaining bytes are set to 0, +and are undefined otherwise. +If +.I op +is +.BR nil , +it and +.I osize +are ignored, and the result is the same as calling +.IR binalloc . +.PP +.I Binalloc +and +.I bingrow +allocate large chunks of memory using +.IR malloc (2) +and return pieces of these chunks. +The chunks are +.IR free 'd +upon a call to +.IR binfree . +.SH SOURCE +.B /sys/src/libbin +.SH SEE ALSO +.IR malloc (2) +.SH DIAGNOSTICS +.I binalloc +and +.I bingrow +return 0 if there is no available memory. diff --git a/static/plan9-4e/man2/bind.2 b/static/plan9-4e/man2/bind.2 new file mode 100644 index 00000000..98feb41f --- /dev/null +++ b/static/plan9-4e/man2/bind.2 @@ -0,0 +1,236 @@ +.TH BIND 2 +.SH NAME +bind, mount, unmount \- change name space +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int bind(char *name, char *old, int flag) +.PP +.B +int mount(int fd, int afd, char *old, int flag, char *aname) +.PP +.B +int unmount(char *name, char *old) +.SH DESCRIPTION +.I Bind +and +.I mount +modify the file name space of the current process and other +processes in its name space group +(see +.IR fork (2)). +For both calls, +.I old +is the name of an existing file or directory in the +current name space where the modification is to be made. +The name +.I old +is +.I evaluated +as described in +.IR intro (2), +except that no translation of the final path element is done. +.PP +For +.IR bind , +.I name +is the name of another (or possibly the same) +existing file or directory in +the current name space. +After a successful +.I bind +call, the file name +.I old +is an alias for the object originally named by +.IR name ; +if the modification doesn't hide it, +.I name +will also still refer to its original file. +The evaluation of +.I new +happens at the time of the +.IR bind , +not when the binding is later used. +.PP +The +.I fd +argument to +.I mount +is a file descriptor of an open network connection +or pipe to a file server, while +.I afd +is a authentication file descriptor as created by +.IR fauth (2) +and subsequently authenticated. +If authentication is not required, +.I afd +should be -1. +The +.I old +file must be a directory. +After a successful +.I mount +the file tree +.I served +(see below) by +.I fd +will be visible with its root directory having name +.IR old . +.PP +The +.I flag +controls details of the modification made to the name space. +In the following, +.I new +refers to the file +as defined by +.I name +or the root directory served by +.IR fd . +Either both +.I old +and new files must be directories, +or both must not be directories. +.I Flag +can be one of: +.TF MBEFORE +.TP +.B MREPL +Replace the +.I old +file by the new one. +Henceforth, an evaluation of +.I old +will be translated to the new file. +If they are directories (for +.IR mount , +this condition is true by definition), +.I old +becomes a +.I "union directory" +consisting of one directory (the new file). +.TP +.B MBEFORE +Both the +.I old +and new files must be directories. +Add the constituent files of the new directory +to the union directory at +.I old +so its contents appear first in the union. +After an +.B MBEFORE +.I bind +or +.IR mount , +the new directory will be searched first when evaluating file names +in the union directory. +.TP +.B MAFTER +Like +.B MBEFORE +but the new directory goes at the end of the union. +.PD +.PP +The flags are defined in +.BR . +In addition, there is an +.B MCREATE +flag that can be OR'd with any of the above. +When a +.I create +system call (see +.IR open (2)) +attempts to create in a union directory, and the file does not exist, +the elements of the union are searched in order until one is found +with +.B MCREATE +set. +The file is created in that directory; if that attempt fails, +the +.I create +fails. +.PP +Finally, the +.B MCACHE +flag, valid for +.I mount +only, turns on caching for files made available by the mount. +By default, file contents are always retrieved from the server. +With caching enabled, the kernel may instead use a local cache to satisfy +.IR read (5) +requests for files accessible through this mount point. +The currency of cached data for a file is verified at each +.IR open (5) +of the file from this client machine. +.PP +With +.IR mount , +the file descriptor +.I fd +must be open for reading and writing +and prepared to respond to 9P messages +(see Section 5). +After the +.IR mount , +the file tree starting at +.I old +is served by a kernel +.IR mnt (3) +device. +That device will turn operations in the tree into messages on +.IR fd . +.I Aname +selects among different +file trees on the server; the null string chooses the default tree. +.PP +The file descriptor +.I fd +is automatically closed by a successful +.I mount +call. +.PP +The effects of +.I bind +and +.I mount +can be undone by +.IR unmount . +If +.I name +is zero, everything bound to or mounted upon +.I old +is unbound or unmounted. +If +.I name +is not zero, it is evaluated as described above for +.IR bind , +and the effect of binding or mounting that particular result on +.I old +is undone. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR bind (1), +.IR intro (2), +.IR fcall (2), +.IR auth (2) +(particularly +.BR amount ), +.IR intro (5), +.IR mnt (3), +.IR srv (3) +.SH DIAGNOSTICS +The return value is a positive integer (a unique sequence number) for +success, -1 for failure. +These routines set +.IR errstr . +.SH BUGS +.I Mount +will not return until it has successfully attached +to the file server, so the process doing a +.I mount +cannot be the one serving. diff --git a/static/plan9-4e/man2/bio.2 b/static/plan9-4e/man2/bio.2 new file mode 100644 index 00000000..a38b28e7 --- /dev/null +++ b/static/plan9-4e/man2/bio.2 @@ -0,0 +1,349 @@ +.TH BIO 2 +.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 +.SH SYNOPSIS +.ta \w'Biobuf* 'u +.B #include +.br +.B #include +.br +.B #include +.PP +.B +Biobuf* Bopen(char *file, int mode) +.PP +.B +int Binit(Biobuf *bp, int fd, int mode) +.PP +.B +int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) +.PP +.B +int Bterm(Biobufhdr *bp) +.PP +.B +int Bprint(Biobufhdr *bp, char *format, ...) +.PP +.B +int Bvprint(Biobufhdr *bp, char *format, va_list arglist); +.PP +.B +void* Brdline(Biobufhdr *bp, int delim) +.PP +.B +char* Brdstr(Biobufhdr *bp, int delim, int nulldelim) +.PP +.B +int Blinelen(Biobufhdr *bp) +.PP +.B +vlong Boffset(Biobufhdr *bp) +.PP +.B +int Bfildes(Biobufhdr *bp) +.PP +.B +int Bgetc(Biobufhdr *bp) +.PP +.B +long Bgetrune(Biobufhdr *bp) +.PP +.B +int Bgetd(Biobufhdr *bp, double *d) +.PP +.B +int Bungetc(Biobufhdr *bp) +.PP +.B +int Bungetrune(Biobufhdr *bp) +.PP +.B +vlong Bseek(Biobufhdr *bp, vlong n, int type) +.PP +.B +int Bputc(Biobufhdr *bp, int c) +.PP +.B +int Bputrune(Biobufhdr *bp, long c) +.PP +.B +long Bread(Biobufhdr *bp, void *addr, long nbytes) +.PP +.B +long Bwrite(Biobufhdr *bp, void *addr, long nbytes) +.PP +.B +int Bflush(Biobufhdr *bp) +.PP +.B +int Bbuffered(Biobufhdr *bp) +.PP +.SH DESCRIPTION +These routines implement fast buffered I/O. +I/O on different file descriptors is independent. +.PP +.I Bopen +opens +.I file +for mode +.B OREAD +or creates for mode +.BR OWRITE . +It calls +.IR malloc (2) +to allocate a buffer. +.PP +.I Binit +initializes a standard size buffer, type +.IR Biobuf , +with the open file descriptor passed in +by the user. +.I Binits +initializes a non-standard size buffer, type +.IR Biobufhdr , +with the open file descriptor, +buffer area, and buffer size passed in +by the user. +.I Biobuf +and +.I Biobufhdr +are related by the declaration: +.IP +.EX +typedef struct Biobuf Biobuf; +struct Biobuf +{ + Biobufhdr; + uchar b[Bungetsize+Bsize]; +}; +.EE +.PP +Arguments +of types pointer to Biobuf and pointer to Biobufhdr +can be used interchangeably in the following routines. +.PP +.IR Bopen , +.IR Binit , +or +.I Binits +should be called before any of the +other routines on that buffer. +.I Bfildes +returns the integer file descriptor of the associated open file. +.PP +.I Bterm +flushes the buffer for +.IR bp . +If the buffer was allocated by +.IR Bopen , +the buffer is +.I freed +and the file is closed. +.PP +.I Brdline +reads a string from the file associated with +.I bp +up to and including the first +.I delim +character. +The delimiter character at the end of the line is +not altered. +.I Brdline +returns a pointer to the start of the line or +.L 0 +on end-of-file or read error. +.I Blinelen +returns the length (including the delimiter) +of the most recent string returned by +.IR Brdline . +.PP +.I Brdstr +returns a +.IR malloc (2)-allocated +buffer containing the next line of input delimited by +.IR delim , +terminated by a NUL (0) byte. +Unlike +.IR Brdline , +which returns when its buffer is full even if no delimiter has been found, +.I Brdstr +will return an arbitrarily long line in a single call. +If +.I nulldelim +is set, the terminal delimiter will be overwritten with a NUL. +After a successful call to +.IR Brdstr , +the return value of +.I Blinelen +will be the length of the returned buffer, excluding the NUL. +.PP +.I Bgetc +returns the next character from +.IR bp , +or a negative value +at end of file. +.I Bungetc +may be called immediately after +.I Bgetc +to allow the same character to be reread. +.PP +.I Bgetrune +calls +.I Bgetc +to read the bytes of the next +.SM UTF +sequence in the input stream and returns the value of the rune +represented by the sequence. +It returns a negative value +at end of file. +.I Bungetrune +may be called immediately after +.I Bgetrune +to allow the same +.SM UTF +sequence to be reread as either bytes or a rune. +.I Bungetc +and +.I Bungetrune +may back up a maximum of five bytes. +.PP +.I Bgetd +uses +.I charstod +(see +.IR atof (2)) +and +.I Bgetc +to read the formatted +floating-point number in the input stream, +skipping initial blanks and tabs. +The value is stored in +.BR *d. +.PP +.I Bread +reads +.I nbytes +of data from +.I bp +into memory starting at +.IR addr . +The number of bytes read is returned on success +and a negative value is returned if a read error occurred. +.PP +.I Bseek +applies +.IR seek (2) +to +.IR bp . +It returns the new file offset. +.I Boffset +returns the file offset of the next character to be processed. +.PP +.I Bputc +outputs the low order 8 bits of +.I c +on +.IR bp . +If this causes a +.IR write +to occur and there is an error, +a negative value is returned. +Otherwise, a zero is returned. +.PP +.I Bputrune +calls +.I Bputc +to output the low order +16 bits of +.I c +as a rune +in +.SM UTF +format +on the output stream. +.PP +.I Bprint +is a buffered interface to +.IR print (2). +If this causes a +.IR write +to occur and there is an error, +a negative value +.RB ( Beof ) +is returned. +Otherwise, the number of bytes output is returned. +.I Bvprint +does the same except it takes as argument a +.B va_list +parameter, so it can be called within a variadic function. +.PP +.I Bwrite +outputs +.I nbytes +of data starting at +.I addr +to +.IR bp . +If this causes a +.IR write +to occur and there is an error, +a negative value is returned. +Otherwise, the number of bytes written is returned. +.PP +.I Bflush +causes any buffered output associated with +.I bp +to be written. +The return is as for +.IR Bputc . +.I Bflush +is called on +exit for every buffer still open +for writing. +.PP +.I Bbuffered +returns the number of bytes in the buffer. +When reading, this is the number of bytes still available from the last +read on the file; when writing, it is the number of bytes ready to be +written. +.SH SOURCE +.B /sys/src/libbio +.SH SEE ALSO +.IR open (2), +.IR print (2), +.IR exits (2), +.IR utf (6), +.SH DIAGNOSTICS +.I Bio +routines that return integers yield +.B Beof +if +.I bp +is not the descriptor of an open file. +.I Bopen +returns zero if the file cannot be opened in the given mode. +All routines set +.I errstr +on error. +.SH BUGS +.I Brdline +returns an error on strings longer than the buffer associated +with the file +and also if the end-of-file is encountered +before a delimiter. +.I Blinelen +will tell how many characters are available +in these cases. +In the case of a true end-of-file, +.I Blinelen +will return zero. +At the cost of allocating a buffer, +.I Brdstr +sidesteps these issues. +.PP +The data returned by +.I Brdline +may be overwritten by calls to any other +.I bio +routine on the same +.IR bp. diff --git a/static/plan9-4e/man2/blowfish.2 b/static/plan9-4e/man2/blowfish.2 new file mode 100644 index 00000000..7bf41960 --- /dev/null +++ b/static/plan9-4e/man2/blowfish.2 @@ -0,0 +1,51 @@ +.TH BLOWFISH 2 +.SH NAME +setupBFstate, bfCBCencrypt, bfCBCdecrypt, bfECBencrypt, bfECBdecrypt - blowfish encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupBFstate(BFstate *s, uchar key[], int keybytes, +.B + uchar *ivec) +.PP +.B +void bfCBCencrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfCBCdecrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfECBencrypt(uchar *data, int len, BFstate *s) +.PP +.B +void bfECBdecrypt(uchar *data, int len, BFstate *s) +.SH DESCRIPTION +.PP +Blowfish is Bruce Schneier's symmetric block cipher. It supports +variable length keys from 32 to 448 bits and has a block size of 64 +bits. Both CBC and ECB modes are supported. +.PP +setupBFstate takes a BFstate structure, a key of at most 56 bytes, the +length of the key in bytes, and an initialization vector of 8 bytes +(set to all zeroes if argument is nil). The encryption and decryption +functions take a BFstate structure, a data buffer, and a length, which +must be a multiple of eight bytes as padding is currently unsupported. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR des (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/brk.2 b/static/plan9-4e/man2/brk.2 new file mode 100644 index 00000000..f916a687 --- /dev/null +++ b/static/plan9-4e/man2/brk.2 @@ -0,0 +1,62 @@ +.TH BRK 2 +.SH NAME +brk, sbrk \- change memory allocation +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +int brk(void *addr) +.PP +.B +void* sbrk(ulong incr) +.SH DESCRIPTION +.I Brk +sets the system's idea of the lowest bss location not used by the program +(called the break) +to +.I addr +rounded up to the next multiple of 8 bytes. +Locations not less than +.I addr +and below the stack pointer +may cause a memory violation if accessed. +.PP +In the alternate function +.IR sbrk , +.I incr +more bytes are added to the +program's data space and a pointer to the +start of the new area is returned. +Rounding occurs as with +.IR brk . +.PP +When a program begins execution via +.I exec +the break is set at the +highest location defined by the program +and data storage areas. +Ordinarily, therefore, only programs with growing +data areas need to use +.IR brk . +A call to +.I sbrk +with a zero argument returns the lowest address +in the dynamic segment. +.SH SOURCE +.B /sys/src/libc/9sys/sbrk.c +.SH SEE ALSO +.IR intro (2), +.IR malloc (2), +.IR segattach (2), +.IR segbrk (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . +.PP +The error return from +.I sbrk +is +.BR (void*)-1 . diff --git a/static/plan9-4e/man2/cachechars.2 b/static/plan9-4e/man2/cachechars.2 new file mode 100644 index 00000000..fa1805f2 --- /dev/null +++ b/static/plan9-4e/man2/cachechars.2 @@ -0,0 +1,313 @@ +.TH CACHECHARS 2 +.SH NAME +cachechars, agefont, loadchar, Subfont, Fontchar, Font \- font utilities +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLCacheinfo 'u +.PP +.B +int cachechars(Font *f, char **s, Rune **r, ushort *c, int max, +.PP +.B + int *widp, char **sfname) +.PP +.B +int loadchar(Font *f, Rune r, Cacheinfo *c, int h, +.PP +.B + int noclr, char **sfname) +.PP +.B +void agefont(Font *f) +.SH DESCRIPTION +A +.I Font +may contain too many characters to hold in memory +simultaneously. +The graphics library and draw device (see +.IR draw (3)) +cooperate to solve this problem by maintaining a cache of recently used +character images. +The details of this cooperation need not be known by most programs: +.I initdraw +and its associated +.I font +variable, +.IR openfont , +.IR stringwidth , +.IR string , +and +.I freefont +are sufficient for most purposes. +The routines described below are used internally by the graphics library +to maintain the font cache. +.PP +A +.B Subfont +is a set of images for a contiguous range of characters, stored as a single +image +with the characters +placed side-by-side on a common baseline. +It is described by the following data structures. +.IP +.EX +.ta 6n +\w'Fontchar 'u +\w'bottom; 'u +typedef +struct Fontchar { + int x; /* left edge of bits */ + uchar top; /* first non-zero scan-line */ + uchar bottom; /* last non-zero scan-line */ + char left; /* offset of baseline */ + uchar width; /* width of baseline */ +} Fontchar; + +typedef +struct Subfont { + char *name; + short n; /* number of chars in subfont */ + uchar height; /* height of image */ + char ascent; /* top of image to baseline */ + Fontchar *info; /* n+1 Fontchars */ + Image *bits; /* of font */ +} Subfont; +.EE +.PP +The image fills the rectangle +\fL(0, 0, \fIw\fP, height)\fR, +where +.I w +is the sum of the horizontal extents (of non-zero pixels) +for all characters. +The pixels to be displayed for character +.I c +are in the rectangle +\fL(\fIi\fP->x, \fIi\fP->top, (\fIi\fP+1)->x, \%\fIi\fP->bottom)\fR +where +.I i +is +.B +&subfont->info[\fIc\fP]\fR. +When a character is displayed at +.B Point +.B p +in an image, +the character rectangle is placed at +.BI (p.x+ i ->left, +.B p.y) +and the next character of the string is displayed at +.BI (p.x+ i ->width, +.BR p.y) . +The baseline of the characters is +.L ascent +rows down from the top of the subfont image. +The +.L info +array has +.B n+1 +elements, one each for characters 0 to +.BR n-1 +plus an additional entry so the size of the last character +can be calculated. +Thus the width, +.IR w , +of the +.B Image +associated with a +.B Subfont +.B s +is +.BR s->info[s->n].x . +.PP +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)) +they represent. +Fonts are described by the following structures. +.IP +.EX +.ta 6n +\w'Cacheinfo 'u +\w'height; 'u +typedef +struct Cachefont { + Rune min; /* value of 0th char in subfont */ + Rune max; /* value+1 of last char in subfont */ + int offset; /* posn in subfont of char at min */ + char *name; /* stored in font */ + char *subfontname; /* to access subfont */ +} Cachefont; + +typedef +struct Cacheinfo { + ushort x; /* left edge of bits */ + uchar width; /* width of baseline */ + schar left; /* offset of baseline */ + Rune value; /* of char at this slot in cache */ + ushort age; +} Cacheinfo; + +typedef +struct Cachesubf { + ulong age; /* for replacement */ + Cachefont *cf; /* font info that owns us */ + Subfont *f; /* attached subfont */ +} Cachesubf; + +typedef +struct Font { + char *name; + Display *display; + short height; /* max ht of image;interline space*/ + short ascent; /* top of image to baseline */ + short width; /* widest so far; used in caching */ + short nsub; /* number of subfonts */ + ulong age; /* increasing counter; for LRU */ + int ncache; /* size of cache */ + int nsubf; /* size of subfont list */ + Cacheinfo *cache; + Cachesubf *subf; + Cachefont **sub; /* as read from file */ + Image *cacheimage; +} Font; +.EE +.PP +The +.LR height +and +.LR ascent +fields of Font are described in +.IR graphics (2). +.L Sub +contains +.L nsub +pointers to +.BR Cachefonts . +A +.B Cachefont +connects runes +.L min +through +.LR max , +inclusive, to the subfont +with file name +.LR name ; +it corresponds to a line of the file describing the font. +.PP +The characters +are taken from the subfont starting at character number +.L offset +(usually zero) in the subfont, permitting selection of parts of subfonts. +Thus +the image for rune +.I r +is found in position +.IB r -min+offset +of the subfont. +.PP +For each font, the library, with support from the +graphics server, +maintains a cache of +subfonts and a cache of recently used +character images. +The +.B subf +and +.B cache +fields are used by the library to maintain these caches. +The +.L width +of a font is the maximum of the horizontal extents of the characters +in the cache. +.I String +draws a string by loading the cache and emitting a sequence of +cache indices to draw. +.I Cachechars +guarantees the images for the characters pointed to by +.I *s +or +.I *r +(one of these must be nil in each call) +are in the cache of +.IR f . +It calls +.I loadchar +to put missing characters into the cache. +.I Cachechars +translates the character string into a set of cache indices +which it loads into the array +.IR c , +up to a maximum of +.I n +indices or the length of the string. +.I Cachechars +returns in +.I c +the number of cache indices emitted, +updates +.I *s +to point to the next character to be processed, and sets +.I *widp +to the total width of the characters processed. +.I Cachechars +may return before the end of the string if it cannot +proceed without destroying active data in the caches. +If it needs to load a new subfont, it will fill +.B *sfname +with the name of the subfont it needs and return \-1. +It can return zero if it is unable to make progress because +it cannot resize the caches. +.PP +.I Loadchar +loads a character image into the character cache. +Then it tells the graphics server to copy the character +into position +.I h +in the character cache. +If the current font +.L width +is smaller than the horizontal extent of the character being loaded, +.I loadfont +clears the cache and resets it to +accept characters with the bigger width, unless +.I noclr +is set, in which case it just returns \-1. +If the character does not exist in the font at all, +.I loadfont +returns 0; if it is unable to load the character +without destroying cached information, it returns \-1, +updating +.B *sfname +as described above. +It returns 1 to indicate success. +.PP +The +.L age +fields record when +subfonts and characters have been used. +The font +.L age +is increased every time the font is used +.RI ( agefont +does this). +A character or subfont +.L age +is set to the font age at each use. +Thus, characters or subfonts with small ages are the best candidates +for replacement when the cache is full. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR subfont (2), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). diff --git a/static/plan9-4e/man2/chdir.2 b/static/plan9-4e/man2/chdir.2 new file mode 100644 index 00000000..24e1626b --- /dev/null +++ b/static/plan9-4e/man2/chdir.2 @@ -0,0 +1,32 @@ +.TH CHDIR 2 +.SH NAME +chdir \- change working directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int chdir(char *dirname) +.SH DESCRIPTION +.I Chdir +changes the working directory +of the invoking process to +.IR dirname . +The working directory is the starting point for +evaluating file names that do not begin with +.L / +or +.LR # , +as explained in +.IR intro (2). +When Plan 9 boots, the initial process has +.L / +for its working directory. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/cleanname.2 b/static/plan9-4e/man2/cleanname.2 new file mode 100644 index 00000000..cd760e42 --- /dev/null +++ b/static/plan9-4e/man2/cleanname.2 @@ -0,0 +1,34 @@ +.TH CLEANNAME 2 +.SH NAME +cleanname \- clean a path name +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.B +char* cleanname(char *filename) +.SH DESCRIPTION +.I Cleanname +takes a +.I filename +and by lexical processing only returns the shortest string that names the same (possibly +hypothetical) file. +It eliminates multiple and trailing slashes, and it lexically interprets +.B . +and +.B .. +directory components in the name. +The string is overwritten in place. +.PP +The shortest string +.I cleanname +can return is two bytes: the null-terminated string +\f(CW"."\f1. +Therefore +.I filename +must contain room for at least two bytes. +.SH SOURCE +.B /sys/src/libc/port/cleanname.c +.SH SEE ALSO +.IR cleanname (1) diff --git a/static/plan9-4e/man2/color.2 b/static/plan9-4e/man2/color.2 new file mode 100644 index 00000000..27569cb9 --- /dev/null +++ b/static/plan9-4e/man2/color.2 @@ -0,0 +1,56 @@ +.TH COLOR 2 +.SH NAME +cmap2rgb, cmap2rgba, rgb2cmap \- colors and color maps +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int rgb2cmap(int red, int green, int blue) +.PP +.B +int cmap2rgb(int col) +.PP +.B +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) +for a description of RGBV, the standard color map. +.PP +.I Rgb2cmap +takes a trio of color values, scaled from 0 (no intensity) to 255 (full intensity), +and returns the index of the color in RGBV closest to that represented +by those values. +.PP +.I Cmap2rgb +decomposes the color of RGBV index +.I col +and returns a 24-bit integer with the low 8 bits representing the blue value, +the next 8 representing green, and the next 8 representing red. +.I Cmap2rgba +decomposes the color of RGBV index +.I col +and returns a 32-bit integer with the low 8 bits representing an alpha value, +defined to be 255, +and the next 8 representing blue, then green, then red, as for +.I cmap2rgba +shifted up 8 bits. +This 32-bit representation is the format used by +.IR draw (2) +and +.IR memdraw (2) +library routines that +take colors as arguments. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR image (6), +.IR color (6) diff --git a/static/plan9-4e/man2/control.2 b/static/plan9-4e/man2/control.2 new file mode 100644 index 00000000..dd9df509 --- /dev/null +++ b/static/plan9-4e/man2/control.2 @@ -0,0 +1,1829 @@ +.TH CONTROL 2 +.SH NAME +Control, +Controlset, +activate, +closecontrol, +closecontrolset, +controlcalled, +controlwire, +createbox, +createboxbox, +createbutton, +createcolumn, +createentry, +createkeyboard, +createlabel, +createmenu, +createradiobutton, +createrow, +createscribble, +createslider, +createstack, +createtab, +createtext, +createtextbutton, +ctlerror, +ctlmalloc, +ctlrealloc, +ctlstrdup, +ctlprint, +deactivate, +freectlfont, +freectlimage, +initcontrols, +namectlfont, +namectlimage, +newcontrolset, +resizecontrolset +\- interactive graphical controls +.SH SYNOPSIS +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +#include +#include +#include +#include +#include +#include +#include +.sp 0.8 +typedef struct Control Control; +typedef struct Controlset Controlset; +.sp 0.8 +struct Control +{ + char *name; + Rectangle rect; /* area on screen */ + Rectangle size; /* min/max Dx, Dy (not a rect) */ + Channel *event; /* chan(char*) to client */ + Channel *data; /* chan(char*) to client */ + \&... +}; +.sp 0.8 +struct Controlset +{ + \&... + Channel *ctl; + Channel *data; + \&... + int clicktotype; + \&... +}; +.sp 0.8 +void initcontrols(void) +.sp 0.8 +Controlset* newcontrolset(Image *i, + Channel *kc, Channel *mc, Channel *rc) +.sp 0.8 +void closecontrolset(Controlset *cs) +.sp 0.8 +int namectlfont(Font *font, char *name) +.sp 0.8 +int freectlfont(char *name) +.sp 0.8 +int namectlimage(Image *image, char *name) +.sp 0.8 +int freectlimage(char *name) +.sp 0.8 +Control* createbox(Controlset *cs, char *name) +.sp 0.8 +Control* createboxbox(Controlset *cs, char *name) +.sp 0.8 +Control* createbutton(Controlset *cs, char *name) +.sp 0.8 +Control* createcolumn(Controlset*, char*) +.sp 0.8 +Control* createentry(Controlset *cs, char *name) +.sp 0.8 +Control* createkeyboard(Controlset *cs, char *name) +.sp 0.8 +Control* createlabel(Controlset *cs, char *name) +.sp 0.8 +Control* createmenu(Controlset *cs, char *name) +.sp 0.8 +Control* createradiobutton(Controlset *cs, char *name) +.sp 0.8 +Control* createrow(Controlset*, char*) +.sp 0.8 +Control* createscribble(Controlset *cs, char *name) +.sp 0.8 +Control* createslider(Controlset *cs, char *name) +.sp 0.8 +Control* createstack(Controlset*, char*) +.sp 0.8 +Control* createtab(Controlset*, char *) +.sp 0.8 +Control* createtext(Controlset *cs, char *name) +.sp 0.8 +Control* createtextbutton(Controlset *cs, char *name) +.sp 0.8 +void closecontrol(Control *c) +.sp 0.8 +int ctlprint(Control*, char*, ...); +.sp 0.8 +void ctlerror(char *fmt, ...) +.sp 0.8 +Control* controlcalled(char *name) +.sp 0.8 +void controlwire(Control *c, char *cname, Channel *ch) +.sp 0.8 +void activate(Control *c) +.sp 0.8 +void deactivate(Control *c) +.sp 0.8 +void resizecontrolset(Controlset *cs) +.sp 0.8 +void* ctlmalloc(uint n) +.sp 0.8 +void* ctlrealloc(void *p, uint n) +.sp 0.8 +char* ctlstrdup(char *s) +.sp 0.8 +int ctldeletequits +.EE +.SH DESCRIPTION +.PP +This library provides a set of interactive +controls for graphical displays: buttons, sliders, text entry boxes, and so on. +It also provides aggregator controls: boxes, columns, rows and stacks of controls. +A stack is a collection of colocated controls, of which one is normally visible. +A +.B controlset +collects a group of controls that share mouse and keyboard. Each controlset +has a separate thread of control that processes keyboard and mouse events as +well as commands to be passed on to the controls. +Since each controlset uses a thread, programs using the control library must +be linked with the thread library, +.IR thread (2). +.PP +Controls are manipulated by reading and writing to the control channel, +.BR ctl , +of their controlset. +Channels are defined in +.IR thread (2). +Each control has two output channels: +.B Event +delivers messages about actions within the control (such as a button press) and +.B data +delivers (if requested by an appropriate write to +.BR ctl ) +control-specific data such as the contents of a field. +.PP +The library provides a simple mechanism for automatic layout: +the minimum and maximum sizes of each simple control can be specified. +.BR Boxbox , +.BR row , +.B column +and +.B stack +controls then use these sizes to lay out their constituent controls when called upon +to do so. See the description of these grouping controls for further details. +.SS "Message format +All messages are represented as +.SM UTF\c +-8 +text. +Numbers are formatted in decimal, and strings are transmitted in the +quoted form of +.IR quote (2). +.PP +Messages sent to a controlset are of the form, +.IP +.IR sender : +.I destination +.I verb +.RI [ argument +\&... ] +.LP +The sender (and the colon following it) may be ommitted. +For example, the initial field of a text entry control called +.I entry +could be set by sending the message, +.IP +.B "entry value 'Hello, world!' +.PP +to its controlset's +.B ctl +file. +This message contains the verb +.B value +and the single argument +.B "Hello, world!" +.PP +To make it easy to write messages, the function +.IR chanprint +(see +.IR thread (2)) +can be used to print formatted text to a controlset's channel. +.PP +The +.B %q +and +.B %Q +formats are convenient for properly quoting string arguments, +as in +.IP +.EX +chanprint(e->event, "value %q", "Don't touch!"); +.EE +.PP +It is wise to use +.B %q +always instead of +.BR %s +when sending messages, and avoid dealing with the quoting explicitly. +In the other direction, +.B tokenize +(see +.IR getfields (2)) +parses these messages and interprets the quotes correctly. +.PP +The destination of a message can be a named control, or a set of controls identified +by name or type. The command +.IP +.B "'entry slider' show +.PP +(note the quotation) sends the `show' command to the entry named +.I entry +and all controls of type +.IR slider . +If there were a control whose name was +.I slider +that control would also be shown. +.LP +\f2 +Note that we are still experimenting with destination names. One proposal is that +a destination of the form +\fR"`name1 name2 ⋯ type1 type2 ⋯'\fP +selects all controls of the named types in the control hierarchies (of columns, rows and +stacks) whose names precede the types. +.LP +.sp +Messages sent by a control on its +.B event +channel are of the form +.IP +.IB sender : +.IB event +.PP +The +.I sender +is the name of the control sending the message; +the +.I event +describes the event. Its format can often be controlled by setting the +control's +.IR "format string" . +For example, when the user types a newline at a text entry control named +.BR entry, +the control sends the message +.IP +.B entry:\ value\ 'Hello\ again!' +on its +.B event +channel. +.SS "Initialization and Control sets +After +.B initdraw +(see +.IR graphics (2)) +is called, +the function +.I initcontrols +should be called to initialize the library. +It calls +.I quotefmtinstall +to install the +.B %q +and +.B %Q +formats; see +.IR quote (2). +.PP +Each control is represented by a +.B Control +data structure and is associated with a +.B Controlset +that groups a set of controls sharing mouse, keyboard, and display. +Most applications will need only one +.BR Controlset ; +only those with multiple windows or unusual configurations will need +more than one. +The function +.I newcontrolset +creates a +.BR Controlset . +Its arguments are the image (usually a window) +on which its controls will appear, typically the +.B screen +variable in the draw library, and three channels: +.BR kc , +a channel of +.B Runes +from the keyboard; +.BR mc , +a channel of +.B Mouse +structures from the mouse; +and +.BR rc , +a channel of +.B int +that indicates when the window has been resized. +Any of the channels may be nil, +in which case +.I newcontrolset +will call +.B initkeyboard +and/or +.B initmouse +(see +.IR keyboard (2) +and +.IR mouse (2)) +to initialize the keyboard and mouse +and connect them to the control set. +The mouse and resize channels must both be nil or both be non-nil. +.PP +The function +.I closecontrolset +frees all the controls in the control set and tears down all the associated threads. +It does not close the mouse and keyboard. +.PP +The public elements of a +.B Controlset +are the flag +.BR clicktotype , +and the +.I ctl +and +.I data +channels. +.PP +.I Clicktotype +is zero by default. +If it is set to non-zero, the controls +in the set will acquire `focus' by the click-to-type paradigm. +Otherwise, focus is always given to the control under the mouse. +.PP +Commands for controls are sent through the controlset's +.I ctl +channel. +One special command is recognized by the controlset itself: Sending +the string +.B sync +to the +.I ctl +channel causes tha string to be echoed to the controlset's +.I data +channel when all commands up to the +.I sync +command have been processed. The string is +allocated and must be freed (see +.IR malloc (2)). +Synchronization is necessary between sending a command, for example, to resize +all controls, and using their +.I rect +fields. +.PP +The function +.I resizecontrolset +must be provided by the user. +When the associated window is resized, the library will call +.I resizecontrolset +with the affected +.BR Controlset ; +the function should reconnect to and redraw the window. +.PP +If all windows are organized in a hierachy of +.IR boxboxes , +.IR columns , +.I rows +and +.IR stacks , +and minimum and maximum sizes have already been supplied, only +the top control needs to be resized (see the +.I rect +command below). +.SS "Fonts and images +Fonts and images must be given names so they may be referenced +in messages. +The functions +.I namectlfont +and +.I namectlimage +associate a (unique) name with the specified font or image. +The association is removed by +.I freectlfont +and +.IR freectlimage . +The font or image is not freed by these functions, however. +.PP +The function +.I initcontrols +establishes name bindings for all the colors mentioned in +.BR , +such as +.BR black , +.BR white , +.BR red , +.BR yellow , +etc., as well as masks +.B transparent +and +.BR opaque . +It also sets the name +.B font +to refer to the default +.B font +variable set up by +.BR initdraw . +.SS Creation +Each type of control has an associated creation function: +.IR createbutton , +.IR createentry , +etc., +whose arguments are the +.B Controlset +to attach it to and a globally unique name for it. +A control may be destroyed by calling +.IR closecontrol . +.PP +The function +.I controlcalled +returns a pointer to the +.B Control +with the given +.IR name , +or nil if no such control exists. +.SS Configuration +After a control is created, it must be configured using the control-specific +commands documented below. +Commands are sent to the +.B ctl +channel of the controlset. +Multiple commands may be sent in a single message; newline characters +separate commands. +For an example, see the implementation of +.I resizecontrolset +in the EXAMPLES section. +Note that newline is a separator, not a terminator; the final command +does not need a newline. +.PP +Messages sent to the +.I ctl +channel are delivered to all controls that match the +.I destination +field. This field is a set of names separated by spaces, tabs or newlines. +A control matches the destination if its name or its type is among the set. +.PP +The recipient of a message ignores the initial +.IB sender : +field of the message, if present, +making it possible to send messages generated on an +.B event +channel directly to another control's +.B ctl +channel. +.SS Activation +When they are created, controls are disabled: they do not respond to +user input. +Not all controls need to be responsive; +for example, labels are static and a text display +might show a log of messages but not be useful to edit. +But buttons, entry boxes, and other text displays should be active. +.PP +To enable a control, call the +.I activate +function, which +specifies that the +.B Control +.I c +should respond to mouse and keyboard events; +.I deactivate +turns it off again. +.PP +Controls can be either +.I revealed +(default) or +.IR hidden . +When a control is hidden, it will not receive mouse or keyboard events +and state changes or +.I show +commands will be ignored until the control is once again +.IR revealed . +Control hiding is particularly useful when different controls are overlayed, +revealing only the `top' one. +.PP +The function +.I controlwire +permits rearrangement of the channels associated with a +.BR Control . +The channel +.I cname +(one of +\f5"data"\fP +or +\f5"event"\fP) +of +.B Control +.I c +is reassigned to the channel +.IR ch . +There are several uses for this operation: +one may reassign all the +.B event +channels to a single channel, in effect multiplexing all the events onto +a single channel; +or connect the +.B event +channel of a slider to the +.B ctl +channel for delivery to a text display (after setting the format for the slider's messages +to name the destination control and the appropriate syntax for the rest of the command) +to let the slider act as a scroll bar for the text without rerouting the messages explicitly. +.SS Controls +The following sections document the individual controls in alphabetical order. +The layout of each section is a brief description of the control's behavior, +followed by the messages it sends on +.BR event , +followed by the messages it accepts via the +.B ctl +channel. +The +.B event +messages are triggered +.I only +by mouse or keyboard action; messages to the +.B ctl +file do not cause events to be generated. +.PP +All controls accept the following messages: +.TP +.BI rect " minx miny maxx maxy +Set the bounding rectangle for the control on the display. +The syntax generated by the +.B %R +print format of the draw library is also acceptable for the coordinates. +.TP +.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ] +Set the minimum and maximum size for automatic layout in +.IR columns , +.I rows +and +.IR stacks . +Without its four arguments, this command is ignored by primitive controls +and used by grouping controls to calculate their minimum and maximum sizes +by examining those of their constituent members. +If all primitive controls have been assigned a size, a single size request addressed +to the top of a layout hierarchy will assign sizes to all grouping controls. +.TP +.B hide +Disable drawing of the control and ignore mouse and keyboard events +until the control is once again revealed. +Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent controls. +.TP +.B reveal +This is the opposite of +.BR hide : +the control is displayed and mouse and keyboard operations resume. +Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent controls. +The +.B reveal +command for +.I stacks +takes an optional argument naming the control to be revealed; all +other controls will be hidden. +.TP +.B show +Display the control on its screen if not hidden. +Some actions will also cause the controls to show themselves automatically +(but never when the control is hidden). +Grouping controls (\f2column\fP, \f2row\fP, and \f2stack\fP) pass the +request down to their constituent controls. +.PP +Many messages are common between multiple controls. +Such messages are described in detail here to avoid repetition. +In the individual descriptions, only the syntax is presented. +.TP +.BI align " n +Specify the alignment of (some part of) the control's display within its rectangle. +For textual controls, the alignment specifies where the text should appear. +For multiline text, the alignment refers to each line within its box, and only the +horizontal part is honored. +For other controls, the alignment affects the appearance of the display in +a reasonable way. +The valid alignments are words with obvious interpretations: +.BR upperleft , +.BR uppercenter , +.BR upperright , +.BR centerleft , +.BR center , +.BR centerright , +.BR lowerleft, +.BR lowercenter , +and +.BR lowerright . +.TP +.BI border " n +Inset the control (or separate constituent controls in +.IR boxbox , +.I column +and +.I row +controls after the next +.I rect +command) within its rectangle by +.I n +pixels, default zero. +.TP +.BI bordercolor " name +Paint the border of the control with the named color, default black. +.TP +.BI focus " n +The control now has (if +.I n +is non-zero) or does not have ( if +.I n +is zero) focus. +Most controls ignore the message; there are plans to make them react. +.TP +.BI format " fmt +Set the format of `value' messages sent on the +.B event +channel. +By default, the format is +.B \&"%q: value %q" +for string-valued controls, +.B \&"%q: value %d" +for integer-valued controls such as buttons, +and +.B \&"%q: value 0x%x" +for the keyboard and scribble controls. +The +.B %q +prints the name of the control; the rest the value. +Any supplied format string must be type-equivalent to the default for that control. +.TP +.BI image " name +.TP +.BI light " name +.TP +.BI mask " name +Many controls set a background image or color for display. +The +.B image +message sets the image. +The +.B mask +and +.B light +images together specify how the control shows it is enabled: +the +.B light +is printed through the +.B mask +when the state is `on' or `pressed'. +Otherwise, the image appears unmodified. +The default image is white; mask opaque; light yellow. +.TP +.BI font " name +.TP +.BI textcolor " name +These commands set the font and color for displaying text. +The defaults are the default +.B font +set up by the draw library, and black. +.TP +.BI value " v +Set the value of the control. Textual images accept an arbitrary string; +others an integral value. +.SS Box +A box is a trivial control that does nothing more than pass keyboard, mouse, +and focus messages back on its +.B event +channel. +Keyboard characters are sent in the format +.IP +.EX +boxname: key 0x\f2nn +.EE +.PP +where +.I nn +is the hexadecimal value of the character. +Mouse messages are sent in the format +.IP +.EX +boxname: mouse [\f2x\fP \f2y\fP] \f2but\fP \f2msec\fP +.EE +.PP +where +.IR x , +.IR y , +.IR but , +and +.I msec +are the various fields of the +.B Mouse +structure. +The focus message is just +.IP +.EX +boxname: focus \f2n\f1 +.EE +.PP +where +.I n +is 0 if the box has lost focus, 1 if it has acquired it. +.PP +The box displays within its rectangle +an image, under mask, with specified alignment. +The control messages it accepts are: +.TP +.BI align " a +Controls the placement of the image in the rectangle (unimplemented). +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI hide +.TP +.BI image " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.BI show +.TP +.BI size " minΔx minΔy maxΔx maxΔy +.PP +.SS Boxbox +A +.B boxbox +allows a set of controls (``boxes'') to be displayed in rows and columns within the +rectangle of the +.IR boxbox . +The maximum of the minimum heights of the constituent controls determines the +number of rows to be displayed. The number of columns is the minimum that +allows all controls to be displayed. This aggregator works well for collections +of buttons, labels, or textbuttons that all have a fixed height. +.TP +.BI add " name ... +adds the named control to the box of controls. The display order +is determined by the order of adding. The first named control is top left, +the second goes below it, etc. +It is possible to add one control to multiple grouping controls but +the layout of the result will be quite unpredictable. +.TP +.BI border " width +.TP +.BI bordercolor " color +.TP +.B hide +This command is passed on to the member controls. +.TP +.B image " color +Background color displayed between member controls. +.TP +.B reveal +This command is passed on to the member controls. +.TP +.BI separation " width +Set the separation between member controls to +.I n +pixels. +.TP +.BI rect " minx miny maxx maxy +The member controls are layed out within the given rectangle according to +the minimum and maximum sizes given. If the rectangle is not large enough +for the minimum a fatal error is currently generated. +If the controls at their maximum size are not big enough to fit, they are top-left justified +at their maximum size in the space given. +Otherwise, controls will get their minimum size and be enlarged proportional +to the extra size given by the maximum until they fit given rectangle. +The members are separated by borders of the width established by +.IR borderwidth . +.TP +.BI remove " name +Remove the named +control from the box. +.TP +.B show +This command is passed on to the member controls. +Show also (re)displays background and borders. +.TP +.BR size " \f2minΔx minΔy maxΔx maxΔy\fP +.PP +.SS Button +A button is a simple control that toggles its state when mouse button 1 is pressed on its rectangle. +Each state change triggers an event message: +.IP +.EX +buttonname: value \f2n\fP +.EE +where +.I n +encodes the mouse buttons used to make the selection. +.PP +The button displays an image (which may of course be a simple color) +and illuminates in the standard way when it is `on'. +The control messages it accepts are: +.TP +.BI align " a +Controls the placement of the image in the rectangle (unimplemented). +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI image " name +.TP +.BI light " name +.TP +.BI mask " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.B show +.TP +.BI size " minΔx minΔy maxΔx maxΔy +.TP +.BI value " n +Set the button to `on' (if +.I n +is non-zero) or `off' (if +.I n +is zero). +.PP +.SS Column +A column is a grouping control which lays out its members vertically, +from top to bottom. Currently, columns ignore mouse and keyboard +events, but there are plans to allow dragging the borders (when they +have non-zero width) between constituent members. +.TP +.BI add " name ... +adds the named control to the column of controls. The vertical order +is determined by the order of adding. The first named control goes at +the top. It is possible to add one control to multiple grouping controls but +the layout of the result will be quite unpredictable. +.TP +.BI border " width +Set the border between members to the width given. +.TP +.BI bordercolor " color +.TP +.B hide +.TP +.B image " color +Background color displayed between member controls. +.TP +.B reveal +.TP +.BI separation " width +Set the separation between member controls to +.I n +pixels. +.TP +.B show +These three commands are passed on to the member controls. +Show also (re)displays the borders between members. +.TP +.BI rect " minx miny maxx maxy +The member controls are layed out within the given rectangle according to +the minimum and maximum sizes given. If the rectangle is not large enough +for the minimum a fatal error is currently generated. However, see the example +at the end of this man page. +If the controls at their maximum size are not big enough to fit, they are centered +at their maximum size in the space given. +Otherwise, controls will get their minimum size and be enlarged proportional +to the extra size given by the maximum until they fit given rectangle. +The members are separated by borders of the width established by +.IR borderwidth . +.TP +.BI remove " name +Remove the named control from the column. +.TP +.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ] +Without arguments, this command computes the minimum and +maximum size of a column by adding the minimum and maximum +heights to set +.I minΔy +and +.IR maxΔy , +and it finds the largest minimum and maximum widths to set +.I minΔy +and +.IR maxΔy . +When called with arguments, it simply sets the minimum and maximum +sizes to those given. +.PP +.SS Entry +The entry control manages a single line of editable text. +When the user hits a carriage return anywhere +in the text, the control generates the event message, +.IP +.EX +entryname: value \f2s\fP +.EE +.PP +with +.I s +the complete text of the entry box. +.PP +The cursor can be moved by clicking button 1; at the moment, +there is no way to select characters, only a typing position. +Some control characters have special actions: +control-H (backspace) deletes the character before the cursor; +control-U clears the line; and +control-V pastes the snarf buffer at the typing position. +Most important, carriage return sends the text to the event channel. +.PP +To enter passwords and other secret text without displaying the +contents, set the font to one in which all characters are the same. +The easiest way to do this is to make a font containing only one character, +at position 0 (NUL), since that position is used to render all +characters not otherwise defined in the font (see +.IR draw (2)). +The file +.B /lib/font/bit/lucm/passwd.9.font +defines such a font. +.PP +The control messages the entry control accepts are: +.TP +.BI align " a +Controls the placement of the text in the rectangle. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI data +After receiving this message, the entry will send its value to its +.B data +channel as an unadorned, unquoted string. +.TP +.BI focus " n +When it receives focus, the entry box displays a typing cursor. +When it does not have focus, the cursor is not displayed. +.TP +.BI font " name +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI image " name +.TP +.BI rect " minx miny maxx maxy +.TP +.B reveal +.TP +.B show +.TP +.BI size " minΔx minΔy maxΔx maxΔy +.TP +.BI textcolor " name +.TP +.BI value " s +Set the string displayed in the entry box. +.SS Keyboard +The keyboard control implements a simulated keyboard useful on palmtop devices. +Keystrokes, generated by mouse button 1 on the simulated keys, +are sent as event messages: +.IP +.EX +keyboardname: value 0x\f2nn\f1 +.EE +.PP +where +.I nn +is the hexadecimal Unicode value of the character. +Shift, control, and caps lock are handled by the keyboard control itself; +shift and control affect only the next regular keystroke. +The Alt key is unimplemented; it will become equivalent to the standard Plan 9 +key for synthesizing non-ASCII characters. +.PP +There are two special keys, +.B Scrib +and +.BR Menu , +which return values +.B 0x10000 +and +.BR 0x10001 . +.PP +The image, mask, light rules are used to indicate that a key is pressed, +but to aid clumsy fingers the keystroke is not generated until the key is released, +so it is possible to slide the pointer to a different key to correct for bad aim. +.PP +The control messages the keyboard accepts are: +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI font " name1 name2 +Sets the font for the keys. +If only one font is named, it is used for all keys. +If two are named, the second is used for key caps with special names such +as Shift and Enter. +(Good choices on the Bitsy are +.B /lib/font/bit/lucidasans/boldlatin1.6.font +for the first and +.B /lib/font/bit/lucidasans/unicode.6.font +for the second argument.) +If neither is specified, both will be set to the default global font. +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI image " name +.TP +.BI light " name +.TP +.BI mask " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.B show +.TP +.BI size " minx miny maxx maxy +.SS Label +A label is like a textbutton +.RI ( q.v. ) +that does not react, but whose value is the text it displays. +The control messages it accepts are: +.TP +.BI align " a +Controls the placement of the image in the rectangle. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI font " name +.TP +.BI hide +.TP +.BI image " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.B show +.TP +.BI size " minx miny maxx maxy +.TP +.BI textcolor " name +.TP +.BI value " s +The value is a string that can be modified only by sending this message to the +.B ctl +file. +.SS Menu +A menu is a pop-up window containing a set of textual selections. +When a selection is made, it removes itself from the screen and reports the selection +by value: +.IP +.EX +menuname: value \f2n\fP +.EE +.PP +If no selection is made, no message is reported. +Because it creates a window, programs using a menu must have their +.B screen +variable (see +.IR graphics (2) +and +.IR window (2)) +set up to be refreshed properly. +The easiest way to do this is to call +.B getwindow +with refresh argument +.B Refbackup +(see +.IR graphics (2)); +most programs use +.BR Refnone . +.PP +The control messages accepted by a menu are: +.TP +.BI add " text +Add a line of +.I text +to the end of the menu. +.TP +.BI align " a +Controls the left-right placement of the text in its rectangle. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI font " name +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI image " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.BI size " minx miny maxx maxy +.TP +Only the origin of the rectangle is significant; menus calculate the appropriate size. +.TP +.BI selectcolor " name +Set the color in which to highlight selected lines; default yellow. +.TP +.BI selecttextcolor " name +Set the color in which to draw the text in selected lines; default black. +.TP +.B show +Display the menu. Not usually needed unless the menu is changed while visible; use +.I window +instead. +.TP +.B window +.TP +.BI window " n +With no arguments, toggle the menu's visibility; otherwise make it visible (1) or invisible (0). +When the selection is made, the menu will remove its window automatically. +.SS Radiobutton +The radiobutton assembles a group of buttons or textbuttons into a +single control with a numeric value. +Its value is \-1 if none of the constituent buttons is pressed; otherwise +it is the index, starting at zero, of the button that is pressed. +Only one button may be pressed; the radiobutton manipulates its +buttons to guarantee this. +State changes trigger an event message: +.IP +.EX +radiobuttonname: value \f2n\fP +.EE +.PP +Buttons are added to the radio button using the +.B add +message; there is no way to remove them, although they may be turned off +independently using +.IR deactivate . +The index reported in the value is defined by the order +in which the buttons are added. +The constituent buttons should be configured and layed out in the usual way; +the rectangle of the radiobutton is used only to `catch' mouse events and +should almost always correspond to the bounding box of the constituent +buttons. +In other words, the geometry is not maintained automatically. +.PP +The control messages the radiobutton accepts are: +.TP +.BI add " name +Add the control with the specified +.I name +to the radiobutton. +.TP +.BI focus " n +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.BI size " minx miny maxx maxy +.TP +.B show +.TP +.BI value " n +.SS Row +A row groups a number of member controls left to right in a rectangle. +Rows behave exactly like columns with the roles of +.I x +and +.I y +interchanged. +.TP +.BI add " name ... +.TP +.BI border " width +.TP +.BI bordercolor " color +.TP +.BI hide +.TP +.B image " color +.TP +.BI rect " minx miny maxx maxy +.TP +.BI remove " name +.TP +.BI reveal +.TP +.BI separation " width +.TP +.BI show +.TP +.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ] +.SS Scribble +The scribble control provides a region in which strokes drawn with mouse button +1 are interpreted as characters in the manner of +.IR scribble (2). +In most respects, including the format of its event messages, it is equivalent +to a keyboard control. +.PP +The control messages it accepts are: +.TP +.BI align " a +Controls the placement of the image in the rectangle (unimplemented). +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI font " name +Used to display the indicia. +.TP +.BI hide +TP +.BI image " name +.TP +.BI linecolor " name +The color in which to draw the strokes; default black. +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.BI size " minx miny maxx maxy +.TP +.B show +.SS Stack +A stack groups a number of member controls in the same shared rectangle. +Only one of these controls will be visible (revealed), the others are hidden. +.TP +.BI hide +.TP +.BI rect " minx miny maxx maxy +.TP +.BI remove " name +.TP +.BR reveal " [ \f2n\fP ] +Without argument, +.B reveal +is the opposite of +.BR hide : +it makes its selected control visible after it was hidden. +With an argument, it makes the +.IR n 'th +added control visible, hiding all others. +.TP +.BI show +.TP +.BR size " [ \f2minΔx minΔy maxΔx maxΔy\fP ] +Without argument, +.I size +computes the maximum of the minimum and maximum sizes of +its constituent controls. With arguments, it sets the size to the +given values. +.SS Slider +A slider controls an integer value by dragging the mouse with a button. +Configured appropriately, it can serve as a scroll bar with the standard +Plan 9 behavior. +When the value changes, an event message is sent: +.IP +.EX +slidername: value \f2n\f1 +.EE +.PP +The slider is a good candidate for connecting to another control +by setting its format and rewiring its +.B event +channel to the other's +.B ctl +channel. +.PP +The geometry of the slider is defined by three numbers: +.B max +is a number representing the range of the slider; +.B vis +is a number representing how much of what is being controlled is visible; +and +.B value +is a number representing the value of the slider within its range. +For example, if the slider is managing a textual display of 1000 lines, with +18 visible, and the first visible line (numbered starting form 0) is 304, +.B max +will be 1000, +.B vis +will be 18, and +.B value +will be 304. +The +.I indicator +is the visual representation of the +.I vis +portion of the controlled object. +.PP +The control messages the slider accepts are: +.TP +.BI absolute " n +If +.I n +is zero, +the slider behaves like a Plan 9 scroll bar: +button 2 sets absolute position, button 1 decreases the value, +and button 3 increases it. +If +.I n +is non-zero, all buttons behave like button 2, setting the absolute value. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI clamp " end n +The +.I end +is either the word +.B high +or +.BR low ; +.I n +sets whether that end is clamped or not. +If it is clamped, that end of the indicator is always at its supremum. +A standard scroll bar has neither end clamped; a volume slider would +have its low end clamped. +If the low end is clamped, the value of the slider is represented by the +high end of the indicator; otherwise it is represented by the low end. +.TP +.BI focus " n +.TP +.BI format " fmt +.TP +.BI hide +.TP +.BI image " name +.TP +.BI indicatorcolor " name +Set the color in which to draw the indicator; default black. +.TP +.BI max " n +Set the maximum value of the range covered by the slider. +.TP +.BI orient " dir +The string +.I dir +begins either +.B hor +or +.B ver +to specify the orientation of the slider. +The default is vertical. +The value always increases to the right for horizontal sliders and +downwards for vertical sliders. +.TP +.BI rect " minx miny maxx maxy +.TP +.BI reveal +.TP +.BI size " minx miny maxx maxy +.TP +.B show +.TP +.BI value " n +.TP +.BI vis " n +Set the visible area shown by the indicator. +.SS Tab +A tab control combines radiobottuns with a stack of windows giving the +appearance of tabbed controls. Currently, the tabs are positioned at the +top of the stack. The radiobutton consists of textbuttons, the stack +can be composed of any type of control. +.PP +Control messages are +.TP +.BI add " button control button control ... +Adds a button to the radiobutton, and an associated control to the stack. +Buttons and controls are numbered in the order of addition. There is +no remove operation. +.TP +.BI border " b +.TP +.BI bordercolor " color +.TP +.BI focus " n +.TP +.BI format " fmt +When a format string is defined, the tab control reports which tab +is selected using the format string (which must print a +.B char* +and an +.BR int ). +.TP +.BI image " color +Color between member controls. +.TP +.BI separation " n +Spacing between buttons in the radiobutton and between the row of +buttons and the stack below it. +.TP +.BI rect " n n n n +.TP +.B hide +.TP +.B reveal +.TP +.BI size " n n n n +.TP +.B show +.TP +.BI value " n +Value must be an integer indicating which tab to bring to the top. +.SS Text +A text control presents a set of lines of text. +The text cannot be edited with the keyboard, but can be +changed by control messages. +(A more interactive text control will be created eventually.) +The mouse can be used to select lines of text. +The only event message reports a state change in the selection of a line: +.IP +.EX +textname: select \f2n\f1 \f2s\f1 +.EE +.PP +states that line +.I n +has changed its selection state to +.IR s , +either zero (unselected) or non-zero (selected). +The non-zero value encodes the mouse buttons that were down +when the selection occurred. +.PP +.PP +The control messages the text control accepts are: +.TP +.BI accumulate " s +.TP +.BI accumulate " n s +.TP +.BI add " s +.TP +.BI add " n s +With one argument, append the string +.I s +as a new last line of the control; if +.I n +is specified, add the line +.I before +the current line +.IR n , +making the new line number +.IR n. +The lines are zero indexed and +.I n +can be no greater than the current number of lines. +.I Add +refreshes the display, but +.I accumulate +does not, to avoid n-squared behavior when assembling a piece of text. +.TP +.BI align " a +Controls the placement of each line of text left-to-right in its rectangle. +Vertically, lines are tightly packed with separation set by the font's interline +spacing. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI clear +Delete all text. +.TP +.BI delete " n +Delete line +.IR n . +.TP +.BI focus " n +.TP +.BI font " name +.TP +.BI image " name +.TP +.BI rect " minx miny maxx maxy +.TP +.BI replace " n s +Replace line +.I n +by the string +.IR s . +.TP +.BI reveal +.TP +.B scroll " n +If +.I n +is non-zero, the text will automatically scroll so the last line is always visible +when new text is added. +.TP +.BI select " n m +Set the selection state of line +.I n +to +.IR m . +.TP +.BI selectcolor " name +Set the color in which to highlight selected lines; default yellow. +.TP +.BI selectmode " s +The string +.I s +is either +.B single +or +.BR multi . +If +.BR single , +the default, +only one line may be selected at a time; when a line is selected, +other lines are unselected. +If +.BR multi , +the selection state of individual lines can be toggled independently. +.TP +.BI size " minx miny maxx maxy +.TP +.B show +.TP +.BI textcolor " name +.TP +.BI topline " n +Scroll the text so the top visible line is number +.IR n . +.TP +.BI value " s +Delete all the text in the control and then add the single line +.IR s . +.SS Textbutton +A textbutton is a textual variant of a plain button. +Each state change triggers an event message: +.IP +.EX +textbuttonname: value \f2n\fP +.EE +where +.I n +encodes the mouse buttons used to make the selection. +.PP +Like a regular button, the value of a textbutton is an integer; the +.I text +is the string that appears in the button. +It uses the image, light, mask method of indicating its state; +moreover, the color of the text can be set to change when the button is pressed. +The control messages it accepts are: +.TP +.BI align " a +Controls the placement of the text in the rectangle. +.TP +.BI border " b +.TP +.BI bordercolor " name +.TP +.BI focus " n +.TP +.BI font " name +.TP +.BI format " fmt +.TP +.B hide +.TP +.BI image " name +.TP +.BI light " name +.TP +.BI mask " name +.TP +.BI pressedtextcolor " name +Set the color in which to display text when the textbutton is pressed. +.TP +.BI rect " minx miny maxx maxy +.TP +.B reveal +.TP +.BI size " minx miny maxx maxy +.TP +.B show +.TP +.BI text " s +Set the text displayed in the button. +.TP +.BI textcolor " name +.TP +.BI value " n +Set the button to `on' (if +.I n +is non-zero) or `off' (if +.I n +is zero). +.SS "Helper functions +The function +.I ctlerror +is called when the library encounters an error. +It prints the formatted message and exits the program. +.PP +The functions +.IR ctlmalloc , +.IR ctlrealloc , +.IR ctlstrdup , +and +.I ctlrunestrdup +are packagings of the corresponding C library functions. +They call +.I ctlerror +if they fail to allocate memory, and +.I ctlmalloc +zeros the memory it returns. +.PP +Finally, for debugging, if the global variable +.I ctldeletequits +is set to a non-zero value, typing a +.SM DEL +will cause the program to call +.IP +.EX +ctlerror("delete"); +.EE +.SS Caveat +This library is very new and is still missing a number of important features. +The details are all subject to change. +Another level of library that handles geometry and has sensible default +appearances for the controls would be useful. +.PP +One unusual design goal of this library was to make the controls themselves +easy to implement. +The reader is encouraged +to create new controls by adapting the source to existing ones. +.SH EXAMPLES +This example creates two entry boxes, +.BR top +and +.BR bot , +and copies the contents of one to the other whenever a newline is typed. +.PP +.EX +#include +#include +#include +#include +#include +#include +#include + +Controlset *cs; + +int ctldeletequits = 1; + +void +resizecontrolset(Controlset*) +{ + int i; + Rectangle r, r1, r2; + + if(getwindow(display, Refnone) < 0) + sysfatal("resize failed: %r"); + r = insetrect(screen->r, 10); + r1 = r; + r2 = r; + r1.max.y = r1.min.y+1+font->height+1; + r2.min.y = r1.max.y+10; + r2.max.y = r2.min.y+1+font->height+1; + chanprint(cs->ctl, "top rect %R\enshow", r1); + chanprint(cs->ctl, "bot rect %R\enshow", r2); +} + +void +threadmain(int argc, char *argv[]) +{ + char *s, *args[3]; + Channel *c; + Contro *top, *bot; + int n; + + initdraw(0, 0, "example"); + initcontrols(); + cs = newcontrolset(screen, nil, nil, nil); + cs->clicktotype = 1; + + top = createentry(cs, "top"); + chanprint(cs->ctl, "top image paleyellow"); + chanprint(cs->ctl, "top border 1"); + bot = createentry(cs, "bot"); + chanprint(cs->ctl, "bot image paleyellow"); + chanprint(cs->ctl, "bot border 1"); + + c = chancreate(sizeof(char*), 0); + controlwire(top, "event", c); + controlwire(bot, "event", c); + + activate(top); + activate(bot); + resizecontrolset(cs); + + for(;;){ + s = recvp(c); + n = tokenize(s, args, nelem(args)); + if(n==3 && strcmp(args[1], "value")==0){ + if(strcmp(args[0], "top:") == 0) + chanprint(cs->ctl, "bot value %q", args[2]); + else + chanprint(cs->ctl, "top value %q", args[2]); + } + } + threadexitsall(nil); +} +.EE +.PP +A richer variant couples a text entry box to a slider. +Since the value of a slider is its numerical setting, as a decimal number, +all that needs changing is the setup of +.BR bot : +.PP +.EX + bot = createslider(cs, "bot"); + chanprint(cs->ctl, "bot border 1"); + chanprint(cs->ctl, "bot image paleyellow"); + chanprint(cs->ctl, "bot indicatorcolor red"); + chanprint(cs->ctl, "bot max 100"); + chanprint(cs->ctl, "bot clamp low 1"); + chanprint(cs->ctl, "bot orient horizontal"); +.EE +.PP +The rest is the same. +Of course, the value of the entry box is only meaningful to the slider +if it is also a decimal number. +.PP +Finally, we can avoid processing events altogether by cross-coupling +the controls. Replace the rest of +.B threadmain +with this: +.PP +.EX + chanprint(cs->ctl, "bot format %q", "%q: top value %q"); + chanprint(cs->ctl, "top format %q", "%q: bot value %q"); + + controlwire(top, "event", cs->ctl); + controlwire(bot, "event", cs->ctl); + + activate(top); + activate(bot); + resizecontrolset(cs); + + for(;;) + yield(); + threadexitsall(nil); +.EE +.SH SOURCE +.B /sys/src/libcontrol +.SH SEE ALSO +.IR draw (2) +.IR frame (2) +.IR graphics (2) +.IR quote (2) +.IR thread (2) +.SH BUGS +The library is strict about matters of formatting, argument count in messages, +etc., and calls +.I ctlerror +in situations where it may be fine to ignore the error and continue. diff --git a/static/plan9-4e/man2/cputime.2 b/static/plan9-4e/man2/cputime.2 new file mode 100644 index 00000000..5cb64f6e --- /dev/null +++ b/static/plan9-4e/man2/cputime.2 @@ -0,0 +1,34 @@ +.TH CPUTIME 2 +.SH NAME +cputime, times \- cpu time in this process and children +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +int times(long t[4]) +.PP +.B +double cputime(void) +.SH DESCRIPTION +If +.I t +is non-null, +.I times +fills it in +with the number of milliseconds spent in user code, system calls, +child processes in user code, and child processes in system calls. +.I Cputime +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 /sys/src/libc/9sys +.SH SEE ALSO +.IR cons (3) diff --git a/static/plan9-4e/man2/ctime.2 b/static/plan9-4e/man2/ctime.2 new file mode 100644 index 00000000..a4e07434 --- /dev/null +++ b/static/plan9-4e/man2/ctime.2 @@ -0,0 +1,129 @@ +.TH CTIME 2 +.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) +.PP +.B +/env/timezone +.SH DESCRIPTION +.I Ctime +converts a time +.I clock +such as returned by +.IR time (2) +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 . +.PP +When local time is first requested, +the program consults the +.B timezone +environment variable to determine the time zone and +converts accordingly. +(This variable is set at system boot time by +.IR init (8).) +The +.B timezone +variable contains +the normal time zone name and its difference from GMT +in seconds followed by an alternate (daylight) time zone name and +its difference followed by a newline. +The remainder is a list of pairs of times +(seconds past the start of 1970, in the first time zone) +when the alternate time zone applies. +For example: +.IP +.EX +EST -18000 EDT -14400 + 9943200 25664400 41392800 57718800 ... +.EE +.PP +Greenwich Mean Time is represented by +.IP +.EX +GMT 0 +.EE +.SH SOURCE +.B /sys/src/libc/9sys +.SH "SEE ALSO" +.IR date (1), +.IR time (2), +.IR init (8) +.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/static/plan9-4e/man2/ctype.2 b/static/plan9-4e/man2/ctype.2 new file mode 100644 index 00000000..4b8693ab --- /dev/null +++ b/static/plan9-4e/man2/ctype.2 @@ -0,0 +1,160 @@ +.TH CTYPE 2 +.SH NAME +isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, isascii, toascii, _toupper, _tolower, toupper, tolower \- ASCII character classification +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.2C +.B isalpha(c) +.PP +.B isupper(c) +.PP +.B islower(c) +.PP +.B isdigit(c) +.PP +.B isxdigit(c) +.PP +.B isalnum(c) +.PP +.B isspace(c) +.PP +.B ispunct(c) +.PP +.B isprint(c) +.PP +.B isgraph(c) +.PP +.B iscntrl(c) +.PP +.B isascii(c) +.PP +.B _toupper(c) +.PP +.B _tolower(c) +.PP +.B toupper(c) +.PP +.B tolower(c) +.PP +.B toascii(c) +.1C +.SH DESCRIPTION +These macros classify +.SM ASCII\c +-coded integer values +by table lookup. +Each is a predicate returning nonzero for true, +zero for false. +.I Isascii +is defined on all integer values; the rest +are defined only where +.I isascii +is true and on the single non-\c +.SM ASCII +value +.BR EOF ; +see +.IR fopen (2). +.TP "\w'isalnum 'u" +.I isalpha +.I c +is a letter, a\-z or A\-Z +.TP +.I isupper +.I c +is an upper case letter, A\-Z +.TP +.I islower +.I c +is a lower case letter, a\-z +.TP +.I isdigit +.I c +is a digit, 0\-9 +.TP +.I isxdigit +.I c +is a hexadecimal digit, 0\-9 or a\-f or A\-F +.TP +.I isalnum +.I c +is an alphanumeric character, a\-z or A\-Z or 0\-9 +.TP +.I isspace +.I c +is a space, horizontal tab, newline, vertical tab, formfeed, or carriage return +(0x20, 0x9, 0xA, 0xB, 0xC, 0xD) +.TP +.I ispunct +.I c +is a punctuation character +(one of +.L +!"#$%&'()*+,-./:;<=>?@[\e]^_`{|}~\fR) +.TP +.I isprint +.I c +is a printing character, 0x20 (space) +through 0x7E (tilde) +.TP +.I isgraph +.I c +is a visible printing character, 0x21 (exclamation) through 0x7E +(tilde) +.TP +.I iscntrl +.I c +is a delete character, 0x7F, +or ordinary control character, 0x0 through 0x1F +.TP +.I isascii +.I c +is an +.SM ASCII +character, 0x0 through 0x7F +.PP +.I Toascii +is not a classification macro; +it converts its argument to +.SM ASCII +range by +.IR and ing +with 0x7F. +.PP +If +.I c +is an upper case letter, +.I tolower +returns the lower case version of the character; +otherwise it returns the original character. +.I Toupper +is similar, returning the upper case version of a character +or the original character. +.I Tolower +and +.I toupper +are functions; +.I _tolower +and +.I _toupper +are corresponding macros which should only be used when it +is known that the argument is upper case or lower case, respectively. +.SH SOURCE +.TF /sys/src/libc/port/ctype.c +.TP +.B /sys/include/ctype.h +for the macros. +.TP +.B /sys/src/libc/port/ctype.c +for the tables. +.SH "SEE ALSO +.IR isalpharune (2) +.SH BUGS +These macros are +.SM ASCII \c +-centric. diff --git a/static/plan9-4e/man2/debugger.2 b/static/plan9-4e/man2/debugger.2 new file mode 100644 index 00000000..5a2ec634 --- /dev/null +++ b/static/plan9-4e/man2/debugger.2 @@ -0,0 +1,386 @@ +.TH DEBUGGER 2 +.SH NAME +cisctrace, risctrace, ciscframe, riscframe, localaddr, symoff, +fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos, +leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.nf +.B +int cisctrace(Map *map, ulong pc, ulong sp, ulong link, +.B + Tracer trace) +.PP +.nf +.B +int risctrace(Map *map, ulong pc, ulong sp, ulong link, +.B + Tracer trace) +.PP +.nf +.B +ulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp, +.B + ulong link) +.PP +.nf +.B +ulong riscframe(Map *map, ulong addr, ulong pc, ulong sp, +.B + ulong link) +.PP +.nf +.B +int localaddr(Map *map, char *fn, char *var, long *ret, +.B + Rgetter rget) +.PP +.B +int symoff(char *buf, int n, long addr, int type) +.PP +.B +int fpformat(Map *map, Reglist *rp, char *buf, int n, int code) +.PP +.B +int beieee80ftos(char *buf, int n, void *fp) +.PP +.B +int beieeesftos(char *buf, int n, void *fp) +.PP +.B +int beieeedftos(char *buf, int n, void *fp) +.PP +.B +int leieee80ftos(char *buf, int n, void *fp) +.PP +.B +int leieeesftos(char *buf, int n, void *fp) +.PP +.B +int leieeedftos(char *buf, int n, void *fp) +.PP +.B +int ieeesftos(char *buf, int n, ulong f) +.PP +.B +int ieeedftos(char *buf, int n, ulong high, ulong low) +.PP +.B +extern Machdata *machdata; +.SH DESCRIPTION +These functions provide machine-independent implementations +of common debugger functions. +Many of the functions assume that global variables +.I mach +and +.I machdata +point to the +.I Mach +and +.I Machdata +data structures describing the target architecture. +The former contains machine parameters and a description of +the register set; it is usually +set by invoking +.I crackhdr +(see +.IR mach (2)) +to interpret the header of an executable. +The +.I Machdata +structure +is primarily a jump table specifying +functions appropriate for processing an +executable image for a given architecture. +Each application is responsible for setting +.I machdata +to the address of the +.I Machdata +structure for the target architecture. +Many of the functions described here are not +called directly; instead, they are invoked +indirectly through the +.I Machdata +jump table. +.PP +These functions must retrieve data and register contents +from an executing image. The +.I Map +(see +.IR mach (2)) +data structure +supports the consistent retrieval of data, but +no uniform access mechanism exists for registers. +The application passes the address of a register +retrieval function as an argument to those functions +requiring register values. +This function, called an +.IR Rgetter , +is of the form +.PP +.RS +.B "ulong rget(Map *map, char *name); +.RE +.PP +It returns the contents of a register when given +the address of a +.I Map +associated with an executing image and the name of the register. +.PP +.I Cisctrace +and +.I risctrace +unwind the stack for up to 40 levels or until the frame for +.I main +is found. They return the +count of the number of levels unwound. These functions +process stacks conforming to the generic compiler model for +.SM RISC +and +.SM CISC +architectures, respectively. +.I Map +is the address of a +.I Map +data structure associated with the image +of an executing process. +.IR Sp , +.I pc +and +.I link +are starting values for the stack pointer, program counter, and +link register from which the unwinding is to take place. Normally, they are +the current contents of the appropriate +registers but they can be any values defining a legitimate +process context, for example, an alternate stack in a +multi-threaded process. +.I Trace +is the address of an application-supplied function to be called +on each iteration as the frame unwinds. The prototype of this +function is: +.PP +.RS +.B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s); +.RE +.PP +where +.I Map +is the +.I Map +pointer passed to +.I cisctrace +or +.I risctrace +and +.I pc +and +.I fp +are the program counter and frame pointer. +.I S +is the address of a +.I Symbol +structure, as defined in +.IR symbol (2), +containing the symbol table information for the +function owning the frame (i.e., the function that +caused the frame to be instantiated). +.PP +.I Ciscframe +and +.I riscframe +calculate the frame pointer associated with +a function. They are suitable for +programs conforming to the +.SM CISC +and +.SM RISC +stack models. +.I Map +is the address of a +.I Map +associated with the memory image of an executing +process. +.I Addr +is the entry point of the desired function. +.IR Pc , +.I sp +and +.I link +are the program counter, stack pointer and link register of +an execution context. As with the stack trace +functions, these can be the current values of the +registers or any legitimate execution context. +The value of the frame pointer is returned. A return +value of zero indicates an error. +.PP +.I Localaddr +fills the location +pointed to by +.I ret +with the address of a local variable. +.I Map +is the address of a +.I Map +associated with an executing memory image. +.I Fn +and +.I var +are pointers to the names of the function and variable of interest. +.I Rget +is the address of a register retrieval function. +If both +.I fn +and +.I var +are non-zero, the frame for function +.I fn +is calculated and the address of the automatic or +argument named +.I var +in that frame is returned. +If +.I var +is zero, the address of the +frame for function +.I fn +is returned. +In all cases, the frame for the function named +.I fn +must be instantiated somewhere on the current stack. +If there are multiple frames for the function (that is, if +it is recursive), the most recent frame is used. +The search starts from the context defined by the +current value of the program counter and stack pointer. +If a valid address is found, +.I localaddr +returns 1. A negative return indicates an error in +resolving the address. +.PP +.I Symoff +converts a virtual address to a symbolic reference. The +string containing that reference is of +the form `name+offset', where `name' is the name of the +nearest symbol with an address less than +or equal to the target address and `offset' is the hexadecimal offset +beyond that symbol. If `offset' is zero, only the name of +the symbol is printed. If no symbol is found within 4,096 +bytes of the address, the address is formatted as a hexadecimal +address. +.I Buf +is the address of a buffer of +.I n +characters to receive the formatted string. +.I Addr +is the address to be converted. +.I Type +is the type code of the search space: +.BR CTEXT , +.BR CDATA , +or +.BR CANY . +.I Symoff +returns the length of the formatted string contained in +.IR buf . +.PP +.I Fpformat +converts the contents of a floating point register to a +string. +.I Map +is the address of a +.I Map +associated with an executing process. +.I Rp +is the address of a +.I Reglist +data structure describing the desired register. +.I Buf +is the address of a buffer of +.I n +characters to hold the resulting string. +.I Code +must be either +.B F +or +.BR f, +selecting double +or single precision, respectively. If +.I code +is +.BR F , +the contents of the specified register and +the following register +are interpreted as a double precision floating point +number; this +is only meaningful for architectures that implement +double precision floats by combining adjacent +single precision registers. +For +.I code +.BR f , +the specified register is formatted +as a single precision float. +.I Fpformat +returns 1 if the number is successfully converted or \-1 +in the case of an error. +.PP +.IR Beieee80ftos , +.I beieeesftos +and +.I beieeedftos +convert big-endian 80-bit extended, 32-bit single precision, +and 64-bit double precision floating point values to +a string. +.IR Leieee80ftos , +.IR leieeesftos , +and +.I leieeedftos +are the little-endian counterparts. +.I Buf +is the address of a buffer of +.I n +characters to receive the formatted string. +.I Fp +is the address of the floating point value to be +converted. These functions return the length of +the resulting string. +.PP +.I Ieeesftos +converts the 32-bit single precision floating point value +.IR f , +to a string in +.IR buf , +a buffer of +.I n +bytes. It returns the length of the resulting string. +.PP +.I Ieeedftos +converts a 64-bit double precision floating point value +to a character string. +.I Buf +is the address of a buffer of +.I n +characters to hold the resulting string. +.I High +and +.I low +contain the most and least significant 32 bits of +the floating point value, respectively. +.I Ieeedftos +returns the number of characters in the resulting string. +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR symbol (2), +.IR errstr (2) +.SH DIAGNOSTICS +Set +.IR errstr . diff --git a/static/plan9-4e/man2/des.2 b/static/plan9-4e/man2/des.2 new file mode 100644 index 00000000..82e538e7 --- /dev/null +++ b/static/plan9-4e/man2/des.2 @@ -0,0 +1,143 @@ +.TH DES 2 +.SH NAME +setupDESstate, des_key_setup, block_cipher, desCBCencrypt, desCBCdecrypt, desECBencrypt, desECBdecrypt, des3CBCencrypt, des3CBCdecrypt, des3ECBencrypt, des3ECBdecrypt, key_setup, des56to64, des64to56, setupDES3state, triple_block_cipher, - single and triple digital encryption standard +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void des_key_setup(uchar key[8], ulong schedule[32]) +.PP +.B +void block_cipher(ulong *schedule, uchar *data, +.B + int decrypting) +.PP +.B +void setupDESstate(DESstate *s, uchar key[8], uchar *ivec) +.PP +.B +void desCBCencrypt(uchar*, int, DESstate*) +.PP +.B +void desCBCdecrypt(uchar*, int, DESstate*) +.PP +.B +void desECBencrypt(uchar*, int, DESstate*) +.PP +.B +void desECBdecrypt(uchar*, int, DESstate*) +.PP +.B +void triple_block_cipher(ulong keys[3][32], uchar*, int) +.PP +.B +void setupDES3state(DES3state *s, uchar key[3][8], +.B + uchar *ivec) +.PP +.B +void des3CBCencrypt(uchar*, int, DES3state*) +.PP +.B +void des3CBCdecrypt(uchar*, int, DES3state*) +.PP +.B +void des3ECBencrypt(uchar*, int, DES3state*) +.PP +.B +void des3ECBdecrypt(uchar*, int, DES3state*) +.PP +.B +void key_setup(uchar[7], ulong[32]) +.PP +.B +void des56to64(uchar *k56, uchar *k64) +.PP +.B +void des64to56(uchar *k64, uchar *k56) +.SH DESCRIPTION +.PP +The Digital Encryption Standard (DES) +is a shared key or symmetric encryption using either +a 56 bit key for single DES or three 56 bit keys for triple des. +The keys are encoded into 64 bits where every eight bit +is parity. +.PP +The basic DES function, +.IR block_cipher , +works on a block of 8 bytes, converting them in place. +It takes a key schedule, a pointer to the block, and +a flag indicating encrypting (0) or decrypting (1). +The key schedule is created from the key using +.IR des_key_setup . +.PP +Since it is a bit awkward, +.I block_cipher +is rarely called directly. Instead, one normally uses +routines that encrypt larger buffers of data and +which may chain the encryption state from one buffer +to the next. +These routines keep track of the state of the +encryption using a +.B DESstate +structure that contains the key schedule and any chained +state. +.I SetupDESstate +sets up the +.B DESstate +structure using the key and an 8 byte initialization vector. +.PP +Electronic code book, using +.I desECBencrypt +and +.IR desECBdecrypt , +is the less secure mode. The encryption of each 8 bytes +does not depend on the encryption of any other. +Hence the encryption is a substitution +cipher using 64 bit characters. +.PP +Cipher block chaining mode, using +.I desCBCencrypt +and +.IR desCBCdecrypt , +is more secure. Every block encrypted depends on the initialization +vector and all blocks encrypted before it. +.PP +For both CBC and ECB modes, a stream of data can be encrypted as +multiple buffers. However, all buffers except the last must +be a multiple of 8 bytes to ensure successful decryption of +the stream. +.PP +There are equivalent triple DES functions for each of the +DES functions. +.PP +In the past Plan 9 used a 56 bit or 7 byte +format for DES keys. To be compatible with the rest +of the world, we've abandoned this format. +There are two functions: +.I des56to64 +and +.I des64to56 +to convert back and forth between the two formats. +Also a key schedule can be set up from the 7 byte format +using +.IR key_setup . +.PP +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/dial.2 b/static/plan9-4e/man2/dial.2 new file mode 100644 index 00000000..408ba6c2 --- /dev/null +++ b/static/plan9-4e/man2/dial.2 @@ -0,0 +1,331 @@ +.TH DIAL 2 +.SH NAME +dial, hangup, announce, listen, accept, reject, netmkaddr, setnetmtpt, getnetconninfo, freenetconninfo \- make and break network connections +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +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 +int listen(char *dir, char *newdir) +.PP +.B +int accept(int ctl, char *dir) +.PP +.B +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*) +.SH DESCRIPTION +For these routines, +.I addr +is a network address of the form +.IB network ! netaddr ! service\f1, +.IB network ! netaddr\f1, +or simply +.IR netaddr . +.I Network +is any directory listed in +.B /net +or the special token, +.BR net . +.B Net +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)). +.PP +If a connection attempt is successful and +.I dir +is non-zero, +the path name of 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. +.PP +.I Dial +makes a call to destination +.I addr +on a multiplexed network. +If the network in +.I addr +is +.BR net , +.I dial +will try in succession all +networks in common between source and destination +until a call succeeds. +It returns a file descriptor open for reading and writing the +.B data +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 +.I cfdp +is non-zero, +.BI * cfdp +is set to a file descriptor open for reading and +writing the control file. +.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 +are the complements of +.IR dial . +.I Announce +establishes a network +name to which calls can be made. +Like +.IR dial , +.I announce +returns an open +.B ctl +file. +The +.I netaddr +used in announce may be a local address or an asterisk, +to indicate all local addresses, e.g. +.BR tcp!*!echo . +The +.I listen +routine takes as its first argument the +.I dir +of a previous +.IR announce . +When a call is received, +.I listen +returns an open +.B ctl +file for the line the call was received on. +It sets +.I newdir +to the path name of the new line directory. +.I Accept +accepts a call received by +.IR listen , +while +.I reject +refuses the call because of +.IR cause . +.I Accept +returns a file descriptor for the data file opened +.BR ORDWR . +.PP +.I Netmkaddr +makes an address suitable for dialing or announcing. +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 (2) +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: +.IP +.EX +int callkremvax(void) +{ + return dial("kremvax", 0, 0, 0); +} +.EE +.PP +Call the local authentication server: +.IP +.EX +int dialauth(char *service) +{ + return dial(netmkaddr("$auth", 0, service), 0, 0, 0); +} +.EE +.PP +Announce as +.B kremvax +on TCP/IP and +loop forever receiving calls and echoing back +to the caller anything sent: +.IP +.EX +int +bekremvax(void) +{ + int dfd, acfd, lcfd; + char adir[40], ldir[40]; + int n; + char buf[256]; + + acfd = announce("tcp!*!7", adir); + if(acfd < 0) + return -1; + for(;;){ + /* listen for a call */ + lcfd = listen(adir, ldir); + if(lcfd < 0) + return -1; + /* fork a process to echo */ + switch(fork()){ + case -1: + perror("forking"); + close(lcfd); + break; + case 0: + /* accept the call and open the data file */ + dfd = accept(lcfd, ldir); + if(dfd < 0) + return -1; + + /* echo until EOF */ + while((n = read(dfd, buf, sizeof(buf))) > 0) + write(dfd, buf, n); + exits(0); + default: + close(lcfd); + break; + } + } +} +.EE +.SH SOURCE +.BR /sys/src/libc/9sys , +.B /sys/src/libc/port +.SH "SEE ALSO" +.IR auth (2), +.IR ip (3), +.IR ndb (8) +.SH DIAGNOSTICS +.IR Dial , +.IR announce , +and +.I listen +return \-1 if they fail. +.I Hangup +returns nonzero if it fails. diff --git a/static/plan9-4e/man2/dirread.2 b/static/plan9-4e/man2/dirread.2 new file mode 100644 index 00000000..6a3ad34c --- /dev/null +++ b/static/plan9-4e/man2/dirread.2 @@ -0,0 +1,103 @@ +.TH DIRREAD 2 +.SH NAME +dirread, dirreadall \- read directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long dirread(int fd, Dir **buf) +.PP +.B +long dirreadall(int fd, Dir **buf) +.PP +.B +#define STATMAX 65535U +.PP +.B +#define DIRMAX (sizeof(Dir)+STATMAX) +.SH DESCRIPTION +The data returned by a +.IR read (2) +on a directory is a set of complete directory entries +in a machine-independent format, exactly equivalent to +the result of a +.IR stat (2) +on each file or subdirectory in the directory. +.I Dirread +decodes the directory entries into a machine-dependent form. +It reads from +.IR fd +and unpacks the data into an array of +.B Dir +structures +whose address is returned in +.B *buf +(see +.IR stat (2) +for the layout of a +.BR Dir ). +The array is allocated with +.IR malloc (2) +each time +.I dirread +is called. +.PP +.I Dirreadall +is like +.IR dirread , +but reads in the entire directory; by contrast, +.I dirread +steps through a directory one +.IR read (2) +at a time. +.PP +Directory entries have variable length. +A successful +.I read +of a directory always returns an integral number of complete directory entries; +.I dirread +always returns complete +.B Dir +structures. +See +.IR read (5) +for more information. +.PP +The constant +.B STATMAX +is the maximum size that a directory entry can occupy. +The constant +.B DIRMAX +is an upper limit on the size necessary to hold a +.B Dir +structure and all the associated data. +.PP +.I Dirread +and +.I dirreadall +return the number of +.B Dir +structures filled in +.BR buf . +The file offset is advanced by the number of bytes actually read. +.SH SOURCE +.B /sys/src/libc/9sys/dirread.c +.SH SEE ALSO +.IR intro (2), +.IR open (2), +.IR read (2) +.SH DIAGNOSTICS +.I Dirread +and +.I Dirreadall +return zero for end of file and a negative value for error. +In either case, +.B *buf +is set to +.B nil +so the pointer can always be freed with impunity. +.PP +These functions set +.IR errstr . diff --git a/static/plan9-4e/man2/disk.2 b/static/plan9-4e/man2/disk.2 new file mode 100644 index 00000000..72613139 --- /dev/null +++ b/static/plan9-4e/man2/disk.2 @@ -0,0 +1,172 @@ +.TH DISK 2 +.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 +.IR floppy (3) +and +.IR sd (3) +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 /sys/src/libdisk/disk.c +.SH SEE ALSO +.IR floppy (3), +.IR sd (3) diff --git a/static/plan9-4e/man2/draw.2 b/static/plan9-4e/man2/draw.2 new file mode 100644 index 00000000..15d600fc --- /dev/null +++ b/static/plan9-4e/man2/draw.2 @@ -0,0 +1,779 @@ +.TH DRAW 2 +.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 +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.br +.B #include +.br +.PP +.ft L +typedef +struct Image +{ + Display *display; /* display holding data */ + int id; /* id of system-held Image */ + Rectangle r; /* rectangle in data area, local coords */ + Rectangle clipr; /* clipping region */ + ulong chan; /* pixel channel format descriptor */ + int depth; /* number of bits per pixel */ + int repl; /* flag: data replicates to tile clipr */ + Screen *screen; /* 0 if not a window */ + Image *next; /* next in list of windows */ +} Image; +.ft +.PP +.ta \w'\fLPoint 'u +.PP +.B +void draw(Image *dst, Rectangle r, +.br +.B + Image *src, Image *mask, Point p) +.PP +.B +void gendraw(Image *dst, Rectangle r, +.br +.B + Image *src, Point sp, Image *mask, Point mp) +.PP +.B +int drawreplxy(int min, int max, int x) +.PP +.B +Point drawrepl(Rectangle r, Point p) +.PP +.B +void replclipr(Image *i, int repl, Rectangle clipr) +.PP +.B +void line(Image *dst, Point p0, Point p1, int end0, int end1, +.br +.B + int radius, Image *src, Point sp) +.PP +.B +void poly(Image *dst, Point *p, int np, int end0, int end1, +.br +.B + int radius, Image *src, Point sp) +.PP +.B +void fillpoly(Image *dst, Point *p, int np, int wind, +.br +.B + Image *src, Point sp) +.PP +.B +int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3, +.br +.B + int end0, int end1, int radius, Image *src, Point sp) +.PP +.B +int bezspline(Image *dst, Point *pt, int npt, int end0, int end1, +.br +.B + int radius, Image *src, Point sp) +.PP +.B +int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3, +.br +.B + int w, Image *src, Point sp) +.PP +.B +int fillbezspline(Image *dst, Point *pt, int npt, int w, +.br +.B + Image *src, Point sp) +.PP +.B +void ellipse(Image *dst, Point c, int a, int b, int thick, +.br +.B + Image *src, Point sp) +.PP +.B +void fillellipse(Image *dst, Point c, int a, int b, +.br +.B + Image *src, Point sp) +.PP +.B +void arc(Image *dst, Point c, int a, int b, int thick, +.br +.B + Image *src, Point sp, int alpha, int phi) +.PP +.B +void fillarc(Image *dst, Point c, int a, int b, Image *src, +.br +.B + Point sp, int alpha, int phi) +.PP +.B +int icossin(int deg, int *cosp, int *sinp) +.PP +.B +int icossin2(int x, int y, int *cosp, int *sinp) +.PP +.B +void border(Image *dst, Rectangle r, int i, Image *color, Point sp) +.br +.PP +.B +Point string(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, char *s) +.PP +.B +Point stringn(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, char *s, int len) +.PP +.B +Point runestring(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, Rune *r) +.PP +.B +Point runestringn(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, Rune *r, int len) +.PP +.B +Point stringbg(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, char *s, Image *bg, Point bgp) +.PP +.B +Point stringnbg(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, char *s, int len, Image *bg, Point bgp) +.PP +.B +Point runestringbg(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, Rune *r, Image *bg, Point bgp) +.PP +.B +Point runestringnbg(Image *dst, Point p, Image *src, Point sp, +.br +.B + Font *f, Rune *r, int len, Image *bg, Point bgp) +.PP +.B +Point _string(Image *dst, Point p, Image *src, +.br +.B + Point sp, Font *f, char *s, Rune *r, int len, +.br +.B + Rectangle clipr, Image *bg, Point bgp) +.PP +.B +void drawsetdebug(int on) +.PP +.ft L +enum +{ + /* line ends */ + Endsquare = 0, + Enddisc = 1, + Endarrow = 2, + Endmask = 0x1F +}; + +#define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23)) +.ft P +.fi +.SH DESCRIPTION +The +.B Image +type defines rectangular pictures and the methods to draw upon them; +it is also the building block for higher level objects such as +windows and fonts. +In particular, a window is represented as an +.BR Image ; +no special operators are needed to draw on a window. +.PP +.TP 10 +.B r +The coordinates of the rectangle in the plane for which the +.B Image +has defined pixel values. +It should not be modified after the image is created. +.TP +.B clipr +The clipping rectangle: operations that read or write +the image will not access pixels outside +.BR clipr . +Frequently, +.B clipr +is the same as +.BR r , +but it may differ; see in particular the discussion of +.BR repl . +The clipping region may be modified dynamically using +.I replclipr +.RI ( q.v. ). +.TP +.B chan +The pixel channel format descriptor, as described in +.IR image (6). +The value should not be modified after the image is created. +.TP +.B depth +The +number of bits per pixel in the picture; +it is identically +.B chantodepth(chan) +(see +.IR graphics (2)) +and is provided as a convenience. +The value should not be modified after the image is created. +.TP +.B repl +A boolean value specifying whether the image is tiled to cover +the plane when used as a source for a drawing operation. +If +.B repl +is zero, operations are restricted to the intersection of +.B r +and +.BR clipr . +If +.B repl +is set, +.B r +defines the tile to be replicated and +.B clipr +defines the portion of the plane covered by the tiling, in other words, +.B r +is replicated to cover +.BR clipr ; +in such cases +.B r +and +.B clipr +are independent. +.IP +For example, a replicated image with +.B r +set to ((0,\ 0),\ (1,\ 1)) and +.B clipr +set to ((0,\ 0),\ (100,\ 100)), +with the single pixel of +.B r +set to blue, +behaves identically to an image with +.B r +and +.B clipr +both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue. +However, +the first image requires far less memory. +The replication flag may be modified dynamically using +.I replclipr +.RI ( q.v. ). +.TP +.BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p ) +.I Draw +is the standard drawing function. +Only those pixels within the intersection of +.IB dst ->r +and +.IB dst ->clipr +will be affected; +.I draw +ignores +.IB dst ->repl\fR. +The operation proceeds as follows +(this is a description of the behavior, not the implementation): +.RS +.IP 1. +If +.B repl +is set in +.I src +or +.IR mask , +replicate their contents to fill +their clip rectangles. +.IP 2. +Translate +.I src +and +.I mask +so +.I p +is aligned with +.IB r .min\fR. +.IP 3. +Set +.I r +to the intersection of +.I r +and +.IB dst ->r\fR. +.IP 4. +Intersect +.I r +with +.IB src ->clipr\fR. +If +.IB src ->repl +is false, also intersect +.I r +with +.IB src ->r\fR. +.IP 5. +Intersect +.I r +with +.IB mask ->clipr\fR. +If +.IB mask ->repl +is false, also intersect +.I r +with +.IB mask ->r\fR. +.IP 6. +For each location in +.IR r , +combine the +.I dst +pixel with the +.I src +pixel using the alpha value +corresponding to the +.I mask +pixel. +If the +.I mask +has an explicit alpha channel, the alpha value +corresponding to the +.I mask +pixel is simply that pixel's alpha channel. +Otherwise, the alpha value is the NTSC greyscale equivalent +of the color value, with white meaning opaque and black transparent. +In terms of the Porter-Duff compositing algebra, +.I draw +replaces the +.I dst +pixels with +.RI ( src +in +.IR mask ) +over +.IR dst . +.RE +.IP +The various +pixel channel formats +involved need not be identical. +If the channels involved are smaller than 8-bits, they will +be promoted before the calculation by replicating the extant bits; +after the calculation, they will be truncated to their proper sizes. +.TP +\f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP +Similar to +.I draw +except that +.I gendraw +aligns the source and mask differently: +.I src +is aligned so +.I p0 +corresponds to +.IB r .min +and +.I mask +is aligned so +.I p1 +corresponds to +.IB r .min . +For most purposes with simple masks and source images, +.B draw +is sufficient, but +.B gendraw +is the general operator and the one all other drawing primitives are built upon. +.TP +.BI drawreplxy( min , max , x\f5) +Clips +.I x +to be in the half-open interval [\fImin\fP, \fImax\fP) by adding +or subtracting a multiple of \fImax-min\fP. +.TP +.BI drawrepl( r , p ) +Clips the point \fIp\fP to be within the rectangle \fIr\fP +by translating the point horizontally by an integer multiple of rectangle width +and vertically by the height. +.TP +.BI replclipr( i , repl , clipr\f5) +Because the image data is stored on the server, local modifications to the +.B Image +data structure itself will have no effect. +.I Repclipr +modifies the local +.B Image +data structure's +.B repl +and +.B clipr +fields, and notifies the server of their modification. +.TP +\f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +Line +draws in +.I dst +a line of width +.RI 1+2* thick +pixels joining points +.I p0 +and +.IR p1 . +The line is drawn using pixels from the +.I src +image aligned so +.I sp +in the source corresponds to +.I p0 +in the destination. +The line touches both +.I p0 +and +.IR p1 , +and +.I end0 +and +.I end1 +specify how the ends of the line are drawn. +.B Endsquare +terminates the line perpendicularly to the direction of the line; a thick line with +.B Endsquare +on both ends will be a rectangle. +.B Enddisc +terminates the line by drawing a disc of diameter +.RI 1+2* thick +centered on the end point. +.B Endarrow +terminates the line with an arrowhead whose tip touches the endpoint. +.IP +The macro +.B ARROW +permits explicit control of the shape of the arrow. +If all three parameters are zero, it produces the default arrowhead, +otherwise, +.I a +sets the distance along line from end of the regular line to tip, +.I b +sets the distance along line from the barb to the tip, +and +.I c +sets the distance perpendicular to the line from edge of line to the tip of the barb, +all in pixels. +.IP +.I Line +and the other geometrical operators are equivalent to calls to +.I gendraw +using a mask produced by the geometric procedure. +.TP +\f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Poly +draws a general polygon; it +is conceptually equivalent to a series of calls to +.I line +joining adjacent points in the +array of +.B Points +.IR p , +which has +.I np +elements. +The ends of the polygon are specified as in +.IR line ; +interior lines are terminated with +.B Enddisc +to make smooth joins. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +.TP +\f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillpoly +is like +.I poly +but fills in the resulting polygon rather than outlining it. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +The winding rule parameter +.I wind +resolves ambiguities about what to fill if the polygon is self-intersecting. +If +.I wind +is +.BR ~0 , +a pixel is inside the polygon if the polygon's winding number about the point +is non-zero. +If +.I wind +is +.BR 1 , +a pixel is inside if the winding number is odd. +Complementary values (0 or ~1) cause outside pixels to be filled. +The meaning of other values is undefined. +The polygon is closed with a line if necessary. +.TP +\f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Bezier +draws the +cubic Bezier curve defined by +.B Points +.IR a , +.IR b , +.IR c , +and +.IR d . +The end styles are determined by +.I end0 +and +.IR end1 ; +the thickness of the curve is +.RI 1+2* thick . +The source is aligned so +.I sp +in +.I src +corresponds to +.I a +in +.IR dst . +.TP +\f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Bezspline +takes the same arguments as +.I poly +but draws a quadratic B-spline (despite its name) rather than a polygon. +If the first and last points in +.I p +are equal, the spline has periodic end conditions. +.TP +\f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillbezier +is to +.I bezier +as +.I fillpoly +is to +.IR poly . +.TP +\f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.I Fillbezspline +is like +.I fillpoly +but fills the quadratic B-spline rather than the polygon outlined by +.IR p . +The spline is closed with a line if necessary. +.TP +\f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.I Ellipse +draws in +.I dst +an ellipse centered on +.I c +with horizontal and vertical semiaxes +.I a +and +.IR b . +The source is aligned so +.I sp +in +.I src +corresponds to +.I c +in +.IR dst . +The ellipse is drawn with thickness +.RI 1+2* thick . +.TP +\f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP) +.I Fillellipse +is like +.I ellipse +but fills the ellipse rather than outlining it. +.TP +\f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP) +.I Arc +is like +.IR ellipse , +but draws only that portion of the ellipse starting at angle +.I alpha +and extending through an angle of +.IR phi . +The angles are measured in degrees counterclockwise from the positive +.I x +axis. +.TP +\f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP) +.I Fillarc +is like +.IR arc , +but fills the sector with the source color. +.TP +\f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP) +.I Icossin +stores in +.BI * cosp +and +.BI * sinp +scaled integers representing the cosine and sine of the angle +.IR deg , +measured in integer degrees. +The values are scaled so cos(0) is 1024. +.TP +\f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP) +.I Icossin2 +is analogous to +.IR icossin, +with the angle represented not in degrees but implicitly by the point +.RI ( x , y ). +It is to +.I icossin +what +.B atan2 +is to +.B atan +(see +.IR sin (2)). +.TP +.BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP) +.I Border +draws an outline of rectangle +.I r +in the specified +.IR color . +The outline has width +.IR i ; +if positive, the border goes inside the rectangle; negative, outside. +The source is aligned so +.I sp +corresponds to +.IB r .min . +.TP +.BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s ) +.I String +draws in +.I dst +characters specified by the string +.I s +and +.IR font ; +it is equivalent to a series of calls to +.I gendraw +using source +.I src +and masks determined by the character shapes. +The text is positioned with the left of the first character at +.IB p .x +and the top of the line of text at +.IB p .y\f1. +The source is positioned so +.I sp +in +.I src +corresponds to +.I p +in +.IR dst . +.I String +returns a +.B Point +that is the position of the next character that would be drawn if the string were longer. +.IP +For characters with undefined +or zero-width images in the font, the character at font position 0 (NUL) is drawn. +.IP +The other string routines are variants of this basic form, and +have names that encode their variant behavior. +Routines whose names contain +.B rune +accept a string of Runes rather than +.SM UTF\c +-encoded bytes. +Routines ending in +.B n +accept an argument, +.IR n , +that defines the number of characters to draw rather than accepting a NUL-terminated +string. +Routines containing +.B bg +draw the background behind the characters in the specified color +.RI ( bg ) +and +alignment +.RI ( bgp ); +normally the text is drawn leaving the background intact. +.IP +The routine +.I _string +captures all this behavior into a single operator. Whether it draws a +.SM UTF +string +or Rune string depends on whether +.I s +or +.I r +is null (the string length is always determined by +.IR len ). +If +.I bg +is non-null, it is used as a background color. +The +.I clipr +argument allows further management of clipping when drawing the string; +it is intersected with the usual clipping rectangles to further limit the extent of the text. +.TP +.BI drawsetdebug( on ) +Turns on or off debugging output (usually +to a serial line) according to whether +.I on +is non-zero. +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR stringsize (2), +.IR color (6), +.IR utf (6), +.IR addpt (2) +.PP +T. Porter, T. Duff. +``Compositing Digital Images'', +.I "Computer Graphics +(Proc. SIGGRAPH), 18:3, pp. 253-259, 1984. +.SH DIAGNOSTICS +These routines call the graphics error function on fatal errors. +.SH BUGS +Anti-aliased characters can be drawn by defining a font +with multiple bits per pixel, but there are +no anti-aliasing geometric primitives. diff --git a/static/plan9-4e/man2/dup.2 b/static/plan9-4e/man2/dup.2 new file mode 100644 index 00000000..cd341410 --- /dev/null +++ b/static/plan9-4e/man2/dup.2 @@ -0,0 +1,42 @@ +.TH DUP 2 +.SH NAME +dup \- duplicate an open file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int dup(int oldfd, int newfd) +.SH DESCRIPTION +Given a file descriptor, +.IR oldfd , +referring to an open file, +.I dup +returns a new file descriptor referring to the same file. +.PP +If +.I newfd +is \-1 the system chooses the lowest available file descriptor. +Otherwise, +.I dup +will use +.I newfd +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 /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR dup (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/elgamal.2 b/static/plan9-4e/man2/elgamal.2 new file mode 100644 index 00000000..5fcd8cf7 --- /dev/null +++ b/static/plan9-4e/man2/elgamal.2 @@ -0,0 +1,92 @@ +.TH ELGAMAL 2 +.SH NAME +eggen, egencrypt, egdecrypt, egsign, egverify, egalloc, egfree, egpuballoc, egpubfree, egprivalloc, egprivfree, egsigalloc, egsigfree, egprivtopub - elgamal encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +EGpriv* eggen(int nlen, int nrep) +.PP +.B +mpint* egencrypt(EGpub *k, mpint *in, mpint *out) +.PP +.B +mpint* egdecrypt(EGpriv *k, mpint *in, mpint *out) +.PP +.B +EGsig* egsign(EGpriv *k, mpint *m) +.PP +.B +int egverify(EGpub *k, EGsig *sig, mpint *m) +.PP +.B +EGpub* egpuballoc(void) +.PP +.B +void egpubfree(EGpub*) +.PP +.B +EGpriv* egprivalloc(void) +.PP +.B +void egprivfree(EGpriv*) +.PP +.B +EGsig* egsigalloc(void) +.PP +.B +void egsigfree(EGsig*) +.PP +.B +EGpub* egprivtopub(EGpriv*) +.SH DESCRIPTION +.PP +The corresponding keys for the ElGamal algorithm are: +.EX + struct EGpub + { + mpint *p; // modulus + mpint *alpha; // generator + mpint *key; // (encryption key) alpha**secret mod p + }; +.EE +and +.EX + struct EGpriv + { + EGpub pub; + mpint *secret; // (decryption key) + }; +.EE +.I Egsign +signs message +.I m +using a private key +.I k +yielding a +.EX + struct EGsig + { + mpint *r, *s; + }; +.EE +.I Egverify +returns 0 if the signature is valid and \-1 if not. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR rc4 (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/encode.2 b/static/plan9-4e/man2/encode.2 new file mode 100644 index 00000000..10dcdf54 --- /dev/null +++ b/static/plan9-4e/man2/encode.2 @@ -0,0 +1,82 @@ +.TH ENCODE 2 +.SH NAME +dec64, enc64, dec32, enc32, dec16, enc16, encodefmt \- encoding byte arrays as strings +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int dec64(uchar *out, int lim, char *in, int n) +.PP +.B +int enc64(char *out, int lim, uchar *in, int n) +.PP +.B +int dec32(uchar *out, int lim, char *in, int n) +.PP +.B +int enc32(char *out, int lim, uchar *in, int n) +.PP +.B +int dec16(uchar *out, int lim, char *in, int n) +.PP +.B +int enc16(char *out, int lim, uchar *in, int n) +.PP +.B +int encodefmt(Fmt*) +.SH DESCRIPTION +.PP +.IR Enc16 , +.I enc32 +and +.I enc64 +create null terminated strings. They return the size of the +encoded string (without the null) or -1 if the encoding fails. +The encoding fails if +.IR lim , +the length of the output buffer, is too small. +.PP +.IR Dec16 , +.I dec32 +and +.I dec64 +return the number of bytes decoded or -1 if the decoding fails. +The decoding fails if the output buffer is not large enough or, +for base 32, if the input buffer length is not a multiple +of 8. +.PP +.I Encodefmt +can be used with +.IR fmtinstall (2) +and +.IR print (2) +to print encoded representations of byte arrays. +The verbs are +.TP +.B H +base 16 (i.e. hexadecimal) +.TP +.B < +base 32 +.TP +.B [ +base 64 (same as MIME) +.PD +.PP +The length of the array is specified as +.IR f2 . +For example, to display a 15 byte array as hex: +.EX + + char x[15]; + + fmtinstall('H', encodefmt); + print("%.*H\\n", sizeof x, x); + +.EE +.SH SOURCE +.B /sys/src/libc/port/u32.c +.br +.B /sys/src/libc/port/u64.c diff --git a/static/plan9-4e/man2/encrypt.2 b/static/plan9-4e/man2/encrypt.2 new file mode 100644 index 00000000..3f7b41da --- /dev/null +++ b/static/plan9-4e/man2/encrypt.2 @@ -0,0 +1,76 @@ +.TH ENCRYPT 2 +.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 /sys/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/static/plan9-4e/man2/errstr.2 b/static/plan9-4e/man2/errstr.2 new file mode 100644 index 00000000..3aa4d74a --- /dev/null +++ b/static/plan9-4e/man2/errstr.2 @@ -0,0 +1,75 @@ +.TH ERRSTR 2 +.SH NAME +errstr, rerrstr, werrstr \- description of last system call error +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int errstr(char *err, uint nerr) +.PP +.B +void rerrstr(char *err, uint nerr) +.PP +.B +void werrstr(char *fmt, ...) +.SH DESCRIPTION +When a system call fails it returns \-1 and +records a string describing the error in a per-process buffer. +.I Errstr +swaps the contents of that buffer with the contents of the array +.IR err . +.I Errstr +will write at most +.I nerr +bytes into +.IR err ; +if the per-process error string does not fit, +it is silently truncated at a UTF character boundary. +The returned string is NUL-terminated. +Usually +.I errstr +will be called with an empty string, +but the exchange property provides a mechanism for +libraries to set the return value for the next call to +.IR errstr . +.PP +If no system call has generated an error since the last call to +.I errstr +with an empty string, +the result is an empty string. +.PP +The verb +.B r +in +.IR print (2) +calls +.I errstr +and outputs the error string. +.PP +.I Rerrstr +reads the error string but does not modify the per-process buffer, so +a subsequent +.I errstr +will recover the same string. +.PP +.I Werrstr +takes a +.I print +style format as its argument and uses it to format +a string to pass to +.IR errstr . +The string returned from +.I errstr +is discarded. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/9sys/werrstr.c +.SH DIAGNOSTICS +.I Errstr +always returns 0. +.SH SEE ALSO +.IR intro (2), +.IR perror (2) diff --git a/static/plan9-4e/man2/event.2 b/static/plan9-4e/man2/event.2 new file mode 100644 index 00000000..11324a9a --- /dev/null +++ b/static/plan9-4e/man2/event.2 @@ -0,0 +1,384 @@ +.TH EVENT 2 +.SH NAME +event, einit, estart, estartfn, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereadmouse, eatomouse, eresized, egetrect, edrawgetrect, emenuhit, emoveto, esetcursor, Event, Mouse, Menu \- graphics events +.SH SYNOPSIS +.nf +.PP +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.ta \w'\fLRectangle 'u +.PP +.B +void einit(ulong keys) +.PP +.B +ulong event(Event *e) +.PP +.B +Mouse emouse(void) +.PP +.B +int ekbd(void) +.PP +.B +int ecanmouse(void) +.PP +.B +int ecankbd(void) +.PP +.B +int ereadmouse(Mouse *m) +.PP +.B +int eatomouse(Mouse *m, char *buf, int n) +.PP +.B +ulong estart(ulong key, int fd, int n) +.PP +.B +ulong estartfn(int id, ulong key, int fd, int n, +.B + int (*fn)(Event*, uchar*, int)) +.PP +.B +ulong etimer(ulong key, int n) +.PP +.B +ulong eread(ulong keys, Event *e) +.PP +.B +int ecanread(ulong keys) +.PP +.B +void eresized(int new) +.PP +.B +Rectangle egetrect(int but, Mouse *m) +.PP +.B +void edrawgetrect(Rectangle r, int up) +.PP +.B +int emenuhit(int but, Mouse *m, Menu *menu) +.PP +.PP +.B +int emoveto(Point p) +.PP +.PP +.B +int esetcursor(Cursor *c) +.PP +.B +extern Mouse *mouse +.PP +.B +enum{ +.B + Emouse = 1, +.B + Ekeyboard = 2, +.B +}; +.PP +.SH DESCRIPTION +These routines provide an interface to multiple sources of input for unthreaded +programs. +Threaded programs (see +.IR thread (2)) +should instead use the threaded mouse and keyboard interface described +in +.IR mouse (2) +and +.IR keyboard (2). +.PP +.I Einit +must be called first. +If the argument to +.I einit +has the +.B Emouse +and +.B Ekeyboard +bits set, +the mouse and keyboard events will be enabled; +in this case, +.IR initdraw +(see +.IR graphics (2)) +must have already been called. +The user must provide a function called +.IR eresized +to be called whenever the window in which the process +is running has been resized; the argument +.I new +is a flag specifying whether the program must call +.I getwindow +(see +.IR graphics (2)) +to re-establish a connection to its window. +After resizing (and perhaps calling +.IR getwindow ), +the global variable +.B screen +will be updated to point to the new window's +.B Image +structure. +.PP +As characters are typed on the keyboard, they are read by the +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)), +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, +a new mouse event is queued by the event mechanism. +.I Emouse +returns the next mouse event from the queue, blocking until the +queue is non-empty. +.I Emouse +returns a +.B Mouse +structure: +.IP +.EX +.ta 6n +\w'Point 'u +struct Mouse +{ + int buttons; + Point xy; + ulong msec; +}; +.EE +.PP +.B Buttons&1 +is set when the left mouse button is pressed, +.B buttons&2 +when the middle button is pressed, +and +.B buttons&4 +when the right button is pressed. +The current mouse position is always returned in +.BR xy . +.B Msec +is a time stamp in units of milliseconds. +.PP +.I Ecankbd +and +.I ecanmouse +return non-zero when there are keyboard or mouse events available +to be read. +.PP +.I Ereadmouse +reads the next mouse event from the file descriptor connected to the mouse, +converts the textual data into a +.B Mouse +structure by calling +.I eatomouse +with the buffer and count from the read call, +and returns the number of bytes read, or \-1 for an error. +.PP +.I Estart +can be used to register additional file descriptors to scan for input. +It takes as arguments the file descriptor to register, +the maximum length of an event message on that descriptor, +and a key to be used in accessing the event. +The key must be a power of 2 and must not conflict with any previous keys. +If a zero key is given, a key will be allocated and returned. +.I Estartfn +is similar to +.IR estart , +but processes the data received by calling +.I fn +before returning the event to the user. +The function +.I fn +is called with the +.B id +of the event; it should return +.B id +if the event is to be passed to the user, +.B 0 +if it is to be ignored. +The variable +.B Event.v +can be used by +.I fn +to attach an arbitrary data item to the returned +.B Event +structure. +.B +Ekeyboard +and +.B Emouse +are the keyboard and mouse event keys. +.PP +.I Etimer +starts a repeating timer with a period of +.I n +milliseconds; it returns the timer event key, or zero if it fails. +Only one timer can be started. +Extra timer events are not queued and the timer channel has no associated data. +.PP +.I Eread +waits for the next event specified by the mask +.I keys +of event keys submitted to +.IR estart . +It fills in the appropriate field of the argument +.B Event +structure, which looks like: +.IP +.EX +struct Event +{ + int kbdc; + Mouse mouse; + int n; + void *v; + uchar data[EMAXMSG]; +}; +.EE +.PP +.B Data +is an array which is large enough to hold a 9P message. +.I Eread +returns the key for the event which was chosen. +For example, if a mouse event was read, +.B Emouse +will be returned. +.PP +.I Event +waits for the next event of any kind. +The return is the same as for +.IR eread . +.PP +As described in +.IR graphics (2), +the graphics functions are buffered. +.IR Event , +.IR eread , +.IR emouse , +and +.I ekbd +all cause a buffer flush unless there is an event of the +appropriate type already queued. +.PP +.I Ecanread +checks whether a call to +.B eread(keys) +would block, returning 0 if it would, 1 if it would not. +.PP +.I Getrect +prompts the user to sweep a rectangle. +It should be called with +.I m +holding the mouse event that triggered the +.I egetrect +(or, if none, a +.B Mouse +with +.B buttons +set to 7). +It changes to the sweep cursor, +waits for the buttons all to be released, +and then waits for button number +.I but +to be pressed, marking the initial corner. +If another button is pressed instead, +.I egetrect +returns a rectangle +with zero for both corners, after +waiting for all the buttons to be released. +Otherwise, +.I egetrect +continually draws the swept rectangle +until the button is released again, and returns the swept rectangle. +The mouse structure pointed to by +.I m +will contain the final mouse event. +.PP +.I Egetrect +uses successive calls to +.I edrawgetrect +to maintain the red rectangle showing the sweep-in-progress. +The rectangle to be drawn is specified by +.I rc +and the +.I up +parameter says whether to draw (1) or erase (0) the rectangle. +.PP +.I Emenuhit +displays a menu and returns a selected menu item number. +It should be called with +.I m +holding the mouse event that triggered the +.IR emenuhit ; +it will call +.I emouse +to update it. +A +.B Menu +is a structure: +.IP +.EX +struct Menu +{ + char **item; + char *(*gen)(int); + int lasthit; +}; +.EE +.PP +If +.B item +is nonzero, it should be a null-terminated array of the character strings +to be displayed as menu items. +Otherwise, +.B gen +should be a function that, given an item number, returns the character +string for that item, or zero if the number is past the end of the list. +Items are numbered starting at zero. +.I Menuhit +waits until +.I but +is released, and then returns the number of the selection, +or \-1 for no selection. +The +.I m +argument is filled in with the final mouse event. +.PP +.I Emoveto +moves the mouse cursor to the position +.B p +on the screen. +.PP +.I Esetcursor +changes the cursor image to that described by the +.B Cursor +.I c +(see +.IR mouse (2)). +If +.B c +is nil, it restores the image to the default arrow. +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR rio (1), +.IR graphics (2), +.IR plumb (2), +.IR cons (3), +.IR draw (3) diff --git a/static/plan9-4e/man2/exec.2 b/static/plan9-4e/man2/exec.2 new file mode 100644 index 00000000..f190e102 --- /dev/null +++ b/static/plan9-4e/man2/exec.2 @@ -0,0 +1,159 @@ +.TH EXEC 2 +.SH NAME +exec, execl, _clock, _privates, _nprivates \- execute a file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +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 +and +.I execl +overlay the calling process with the named file, then +transfer to the entry point of the image of the file. +.PP +.I Name +points to the name of the file +to be executed; it must not be a directory, and the permissions +must allow the current user to execute it +(see +.IR stat (2)). +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 +(see +.IR rc (1)). +The first line of a +shell script must begin with +.L #! +followed by the name of the program to interpret the file +and any initial arguments to that program, for example +.IP +.EX +#!/bin/rc +ls | mc +.EE +.PP +When a C program is executed, +it is called as follows: +.IP +.EX +void main(int argc, char *argv[]) +.EE +.PP +.I Argv +is a copy of the array of argument pointers passed to +.IR exec ; +that array must end in a null pointer, and +.I argc +is the number of elements before the null pointer. +By convention, the first argument should be the name of +the program to be executed. +.I Execl +is like +.I exec +except that +.I argv +will be an array of the parameters that follow +.I name +in the call. The last argument to +.I execl +must be a null pointer. +.PP +For a file beginning +.BR #! , +the arguments passed to the program +.RB ( /bin/rc +in the example above) will be the name of the file being +executed, any arguments on the +.B #! +line, the name of the file again, +and finally the second and subsequent arguments given to the original +.I exec +call. +The result honors the two conventions of a program accepting as argument +a file to be interpreted and +.B argv[0] +naming the file being +executed. +.PP +Most attributes of the calling process are carried +into the result; in particular, +files remain open across +.I exec +(except those opened with +.B OCEXEC +OR'd +into the open mode; see +.IR open (2)); +and the working directory and environment +(see +.IR env (3)) +remain the same. +However, a newly +.I exec'ed +process has no notification handler +(see +.IR notify (2)). +.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 /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/execl.c +.SH SEE ALSO +.IR prof (1), +.IR intro (2), +.IR stat (2) +.SH DIAGNOSTICS +If these functions fail, they return and set +.IR errstr . +There can be no return from a successful +.I exec +or +.IR execl ; +the calling image is lost. diff --git a/static/plan9-4e/man2/exits.2 b/static/plan9-4e/man2/exits.2 new file mode 100644 index 00000000..78e3f6d2 --- /dev/null +++ b/static/plan9-4e/man2/exits.2 @@ -0,0 +1,81 @@ +.TH EXITS 2 +.SH NAME +exits, _exits, atexit, atexitdont, terminate \- terminate process, process cleanup +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +void _exits(char *msg) +.B +void exits(char *msg) +.PP +.B +int atexit(void(*)(void)) +.PP +.B +void atexitdont(void(*)(void)) +.fi +.SH DESCRIPTION +.I Exits +is the conventional way to terminate a process. +.I _Exits +is the underlying system call. +They +can never return. +.PP +.I Msg +conventionally includes a brief (maximum length +.BR ERRLEN ) +explanation of the reason for +exiting, or a null pointer or empty string to indicate normal termination. +The string is passed to the parent process, prefixed by the name and process +id of the exiting process, when the parent does a +.IR wait (2). +.PP +Before calling +.I _exits +with +.I msg +as an argument, +.I exits +calls in reverse order all the functions +recorded by +.IR atexit . +.PP +.I Atexit +records +.I fn +as a function to be called by +.IR exits . +It returns zero if it failed, +nonzero otherwise. +A typical use is to register a cleanup routine for an I/O package. +To simplify programs that fork or share memory, +.I exits +only calls those +.IR atexit -registered +functions that were registered by the same +process as that calling +.IR exits . +.PP +Calling +.I atexit +twice (or more) with the same function argument causes +.I exits +to invoke the function twice (or more). +.PP +There is a limit to the number of exit functions +that will be recorded; +.I atexit +returns 0 if that limit has been reached. +.PP +.I Atexitdont +cancels a previous registration of an exit function. +.SH SOURCE +.B /sys/src/libc/port/atexit.c +.SH "SEE ALSO" +.IR fork (2), +.IR wait (2) diff --git a/static/plan9-4e/man2/exp.2 b/static/plan9-4e/man2/exp.2 new file mode 100644 index 00000000..55147ed9 --- /dev/null +++ b/static/plan9-4e/man2/exp.2 @@ -0,0 +1,62 @@ +.TH EXP 2 +.SH NAME +exp, log, log10, pow, pow10, sqrt \- exponential, logarithm, power, square root +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +double exp(double x) +.PP +.B +double log(double x) +.PP +.B +double log10(double x) +.PP +.B +double pow(double x, double y) +.PP +.B +double pow10(int n) +.PP +.B +double sqrt(double x) +.fi +.SH DESCRIPTION +.I Exp +returns the exponential function of +.IR x . +.PP +.I Log +returns the natural logarithm of +.IR x ; +.I log10 +returns the base 10 logarithm. +.PP +.I Pow +returns +.if t .I x\u\s8y\s10\d +.if n x^y, +and +.I pow10 +returns +.if t .I 10\u\s8n\s10\d +.if n 10^n +as a double. +.PP +.I Sqrt +returns the square root of +.IR x . +.SH SOURCE +All these routines have portable C implementations in +.BR /sys/src/libc/port . +Most also have machine-dependent implementations, written either in assembler +or C, in +.BR /sys/src/libc/$objtype . +.SH SEE ALSO +.IR hypot (2), +.IR sinh (2), +.IR intro (2) diff --git a/static/plan9-4e/man2/fauth.2 b/static/plan9-4e/man2/fauth.2 new file mode 100644 index 00000000..4b666ee8 --- /dev/null +++ b/static/plan9-4e/man2/fauth.2 @@ -0,0 +1,66 @@ +.TH FAUTH 2 +.SH NAME +fauth \- set up authentication on a file descriptor to a file server +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +.PP +.ft P +.B +int fauth(int fd, char *aname) +.SH DESCRIPTION +.PP +.I Fauth +is used to establish authentication for the current user to access +the resources available through the 9P connection represented by +.IR fd . +The return value is a file descriptor, conventionally called +.BR afd , +that is subsequently used to negotiate the authentication protocol +for the server, typically using +.IR auth_proxy +or +.IR fauth_proxy +(see +.IR auth (2)). +After successful authentication, +.B afd +may be passed as the second argument to a subsequent +.B mount +call (see +.IR bind (2)), +with the same +.IR aname, +as a ticket-of-entry for the user. +.PP +If +.I fauth +returns -1, the error case, that means the file server does not require +authentication for the connection, and +.B afd +should be set to -1 +in the call to +.BR mount. +.PP +It is rare to use +.IR fauth +directly; more commonly +.I amount +(see +.IR auth (2)) +is used. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR attach (5), +.IR auth (2) +(particularly +.BR amount ), +.IR authsrv (6), +.IR auth (8) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/fcall.2 b/static/plan9-4e/man2/fcall.2 new file mode 100644 index 00000000..bcfe7fe6 --- /dev/null +++ b/static/plan9-4e/man2/fcall.2 @@ -0,0 +1,351 @@ +.TH FCALL 2 +.SH NAME +Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeD2M \- interface to Plan 9 File protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.br +.B #include +.PP +.B +uint convS2M(Fcall *f, uchar *ap, uint nap) +.PP +.B +uint convD2M(Dir *d, uchar *ap, uint nap) +.PP +.B +uint convM2S(uchar *ap, uint nap, Fcall *f) +.PP +.B +uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) +.PP +.B +int dirfmt(Fmt*) +.PP +.B +int fcallfmt(Fmt*) +.PP +.B +int dirmodefmt(Fmt*) +.PP +.B +int read9pmsg(int fd, uchar *buf, uint nbuf); +.PP +.B +int statcheck(uchar *buf, uint nbuf); +.PP +.B +uint sizeD2M(Dir *d) +.SH DESCRIPTION +These +routines convert messages in the machine-independent format of +the Plan 9 file protocol, +9P, to and from a more convenient form, +an +.B Fcall +structure: +.PP +.EX +.if n .ta 4n +6n +5n +6n +18n +4n +.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u +#define MAXWELEM 16 + +typedef +struct Fcall +{ + uchar type; + u32int fid; + ushort tag; + union { + struct { + u32int msize; /* Tversion, Rversion */ + char *version; /* Tversion, Rversion */ + }; + struct { + u32int oldtag; /* Tflush */ + }; + struct { + char *ename; /* Rerror */ + }; + struct { + Qid qid; /* Rattach, Ropen, Rcreate */ + u32int iounit; /* Ropen, Rcreate */ + ushort nrauth; /* Rattach */ + uchar *rauth; /* Rattach */ + }; + struct { + char *uname; /* Tattach */ + char *aname; /* Tattach */ + ushort nauth; /* Tattach */ + uchar *auth; /* Tattach */ + }; + struct { + char *authid; /* Rsession */ + char *authdom; /* Rsession */ + ushort nchal; /* Tsession/Rsession */ + uchar *chal; /* Tsession/Rsession */ + }; + struct { + u32int perm; /* Tcreate */ + char *name; /* Tcreate */ + uchar mode; /* Tcreate, Topen */ + }; + struct { + u32int newfid; /* Twalk */ + ushort nwname; /* Twalk */ + char *wname[MAXWELEM]; /* Twalk */ + }; + struct { + ushort nwqid; /* Rwalk */ + Qid wqid[MAXWELEM]; /* Rwalk */ + }; + struct { + vlong offset; /* Tread, Twrite */ + u32int count; /* Tread, Twrite, Rread */ + char *data; /* Twrite, Rread */ + }; + struct { + ushort nstat; /* Twstat, Rstat */ + uchar *stat; /* Twstat, Rstat */ + }; + }; +} Fcall; +.EE +.EX + +/* these are implemented as macros */ + +uchar GBIT8(uchar*) +ushort GBIT16(uchar*) +ulong GBIT32(uchar*) +vlong GBIT64(uchar*) + +void PBIT8(uchar*, uchar) +void PBIT16(uchar*, ushort) +void PBIT32(uchar*, ulong) +void PBIT64(uchar*, vlong) + +#define BIT8SZ 1 +#define BIT16SZ 2 +#define BIT32SZ 4 +#define BIT64SZ 8 +.EE +.PP +This structure is defined in +.BR . +See section 5 +for a full description of 9P messages and their encoding. +For all message types, the +.B type +field of an +.B Fcall +holds one of +.BR Tnop , +.BR Rnop , +.BR Tsession , +.BR Rsession , +etc. (defined in an enumerated type in +.BR ). +.B Fid +is used by most messages, and +.B tag +is used by all messages. +The other fields are used selectively by the message types +given in comments. +.PP +.I ConvM2S +takes a 9P message at +.I ap +of length +.IR nap , +and uses it to fill in +.B Fcall +structure +.IR f . +If the passed message +including any data for +.B Twrite +and +.B Rread +messages +is formatted properly, +the return value is the number of bytes the message occupied in the buffer +.IR ap , +which will always be less than or equal to +.IR nap ; +otherwise it is 0. +For +.B Twrite +and +.B Tread +messages, +.B data +is set to a pointer into the argument message, +not a copy. +.PP +.I ConvS2M +does the reverse conversion, turning +.I f +into a message starting at +.IR ap . +The length of the resulting message is returned. +For +.B Twrite +and +.B Rread +messages, +.B count +bytes starting at +.B data +are copied into the message. +.PP +The constant +.B IOHDRSZ +is a suitable amount of buffer to reserve for storing +the 9P header; +the data portion of a +.B Twrite +or +.B Rread +will be no more than the buffer size negotiated in the +.BR Tversion/Rversion +exchange, minus +.BR IOHDRSZ . +.PP +Another structure is +.BR Dir , +used by the routines described in +.IR stat (2). +.I ConvM2D +converts the machine-independent form starting at +.I ap +into +.IR d +and returns the length of the machine-independent encoding. +The strings in the returned +.B Dir +structure are stored at successive locations starting at +.BR strs . +Usually +.B strs +will point to storage immediately after the +.B Dir +itself. +It can also be a +.B nil +pointer, in which case the string pointers in the returned +.B Dir +are all +.BR nil ; +however, the return value still includes their length. +.PP +.I ConvD2M +does the reverse translation, +also returning the length of the encoding. +If the buffer is too short, the return value will be +.B BIT16SZ +and the correct size will be returned in the first +.B BIT16SZ +bytes. +(If the buffer is less that +.BR BIT16SZ , +the return value is zero; therefore a correct test for +complete packing of the message is that the return value is +greater than +.BR BIT16SZ ). +The macro +.B GBIT16 +can be used to extract the correct value. +The related macros with different sizes retrieve the corresponding-sized quantities. +.B PBIT16 +and its brethren place values in messages. +With the exception of handling short buffers in +.IR convD2M , +these macros are not usually needed except by internal routines. +.PP +The routine +.B statcheck +checks whether the +.I nbuf +bytes of +.I buf +contain a validly formatted machine-independent +.B Dir +entry suitable as an argument, for example, for the +.B wstat +(see +.IR stat (2)) +system call. +It checks that the sizes of all the elements of the the entry sum to exactly +.IR nbuf , +which is a simple but effective test of validity. +.I Nbuf +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)); +in other words, +.I nbuf +is 2 plus the sum of the sizes of the entry itself. +.I Statcheck +also verifies that the length field has the correct value (that is, +.IB nbuf -2\r1). +It returns +.B 0 +for a valid entry and +.B -1 +for an incorrectly formatted entry. +.PP +The routine +.I sizeD2M +returns the number of bytes required to store the machine-independent representation of the +.B Dir +structure +.IR d , +including its initial 16-bit size field. +In other words, it reports the number of bytes produced +by a successful call to +.IR convD2M . +.PP +.IR Dirfmt , +.IR fcallfmt , +and +.I dirmodefmt +are formatting routines, suitable for +.IR fmtinstall (2). +They convert +.BR Dir* , +.BR Fcall* , +and +.BR long +values into string representations of the directory buffer, +.B Fcall +buffer, +or file mode value. +.I Fcallfmt +assumes that +.I dirfmt +has been installed with format letter +.L D +and +.I dirmodefmt +with format letter +.LR M . +.PP +.I Read9pmsg +calls +.IR read (2) +multiple times, if necessary, to read an entire 9P message into +.BR buf . +The return value is 0 for end of file, or -1 for error; it does not return +partial messages. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR intro (2), +.IR 9p (2), +.IR stat (2), +.IR intro (5) diff --git a/static/plan9-4e/man2/fd2path.2 b/static/plan9-4e/man2/fd2path.2 new file mode 100644 index 00000000..9876c132 --- /dev/null +++ b/static/plan9-4e/man2/fd2path.2 @@ -0,0 +1,57 @@ +.TH FD2PATH 2 +.SH NAME +fd2path \- return file name associated with file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int fd2path(int fd, char *buf, int nbuf) +.SH DESCRIPTION +As described in +.IR intro (2), +the kernel stores a rooted path name with every open file or directory; +typically, it is the name used in the original access of the file. +.I Fd2path +returns the path name associated with open file descriptor +.IR fd . +Up to +.I nbuf +bytes of the name are stored in +.IR buf ; +if the name is too long, it will be silently truncated at a UTF-8 +character boundary. +The name is always null-terminated. +The return value of +.I fd2path +will be zero unless an error occurs. +.PP +Changes to the underlying name space do not update the path name +stored with the file descriptor. +Therefore, +the path returned by +.I fd2path +may no longer refer to the same file (or indeed any file) +after some component directory or file in the path has been removed, renamed +or rebound. +.PP +As an example, +.IR getwd (2) +is implemented by opening +.B . +and executing +.I fd2path +on the resulting file descriptor. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR bind (1), +.IR ns (1), +.IR bind (2), +.IR intro (2), +.IR getwd (2), +.IR proc (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/fgetc.2 b/static/plan9-4e/man2/fgetc.2 new file mode 100644 index 00000000..bf68e567 --- /dev/null +++ b/static/plan9-4e/man2/fgetc.2 @@ -0,0 +1,211 @@ +.TH FGETC 2 +.SH NAME +fgetc, getc, getchar, fputc, putc, putchar, ungetc, fgets, gets, fputs, puts, fread, fwrite \- Stdio input and output +.SH SYNOPSIS +.B #include +.ta \w'\fLlong 'u +.PP +.B +int fgetc(FILE *f) +.PP +.B +int getc(FILE *f) +.PP +.B +int getchar(void) +.PP +.B +int fputc(int c, FILE *f) +.PP +.B +int putc(int c, FILE *f) +.PP +.B +int putchar(int c) +.PP +.B +int ungetc(int c, FILE *f) +.PP +.B +char *fgets(char *s, int n, FILE *f) +.PP +.B +char *gets(char *s) +.PP +.B +int fputs(char *s, FILE *f) +.PP +.B +int puts(char *s) +.PP +.B +long fread(void *ptr, long itemsize, long nitems, FILE *stream) +.PP +.B +long fwrite(void *ptr, long itemsize, long nitems, FILE *stream) +.SH DESCRIPTION +The functions described here work on open Stdio streams (see +.IR fopen ). +.PP +.I Fgetc +returns as an +.B int +the next +.B unsigned +.B char +from input stream +.IR f . +If the stream is at end-of-file, the end-of-file indicator for the +stream is set and +.I fgetc +returns +.BR EOF . +If a read error occurs, the error indicator for the stream is set and +.I fgetc +returns +.BR EOF . +.I Getc +is like +.I fgetc +except that it is implemented as a macro. +.I Getchar +is like +.I getc +except that it always reads from +.BR stdin . +.PP +.I Ungetc +pushes character +.I c +back onto the input stream +.BR f . +The pushed-back character will be returned by subsequent reads in +the reverse order of their pushing. +A successful intervening +.IR fseek , +.IR fsetpos , +or +.I rewind +on +.I f +discards any pushed-back characters for +.IR f . +One character of push-back is guaranteed. +.I Ungetc +returns the character pushed back (converted to +.B unsigned +.BR char ), +or +.B EOF +if the operation fails. +A successful call to +.I ungetc +clears the end-of-file indicator for the stream. +The file position indicator for the stream after reading or discarding +all pushed-back characters is the same as it was before the +characters were pushed back. +.PP +.I Fputc +writes character +.I c +(converted to +.B unsigned +.BR char ) +to output stream +.IR f +at the position indicated by the position indicator for the stream +and advances the indicator appropriately. +If the file cannot support positioning requests, or if the stream was +opened with append mode, the character is appended to the output stream. +.I Fputc +returns the character written or +.B EOF +if there was a write error. +.I Putc +is like +.IR fputc +but is implemented as a macro. +.I Putchar +is like +.I putc +except that it always writes to +.BR stdout . +.PP +All other input takes place as if characters were read by successive +calls to +.I fgetc +and all other output takes place as if characters were written by +successive calls to +.IR fputc . +.PP +.I Fgets +reads up to and including the next newline, but not past end-of-file +or more than +.IR n -1 +characters, from stream +.I f +into array +.IR s . +A null character is written immediately after the last character read +into the array (if any characters are read at all). +.I Fgets +returns +.I s +if successful, otherwise a null pointer. +.I Gets +is similar to +.IR fgets +except that it always reads from +.B stdin +and it discards the terminating newline, if any. +.I Gets +does not check for overflow of the receiving array, so its use is deprecated. +.PP +.I Fputs +writes the string +.I s +to stream +.IR f , +returning +.B EOF +if a write error occurred, otherwise a nonnegative value. +The terminating null character is not written. +.I Puts +is the same, writing to +.BR stdout . +.PP +.I Fread +reads from the named input +.IR stream +at most +.I nitems +of data of size +.I itemsize +and the type of +.I *ptr +into a block beginning at +.IR ptr . +It returns the number of items actually read. +.PP +.I Fwrite +appends to the named output +.I stream +at most +.I nitems +of data of size +.I itemsize +and the type of +.I *ptr +from a block beginning at +.IR ptr . +It returns the number of items actually written. +.SH SOURCE +.B /sys/src/libstdio +.SH "SEE ALSO" +.IR read (2), +.IR fopen (2), +.IR bio (2) +.SH BUGS +Stdio does not handle +.SM UTF +or runes; use Bio instead. diff --git a/static/plan9-4e/man2/flate.2 b/static/plan9-4e/man2/flate.2 new file mode 100644 index 00000000..39f4c108 --- /dev/null +++ b/static/plan9-4e/man2/flate.2 @@ -0,0 +1,207 @@ +.TH FLATE 2 +.SH NAME +deflateinit, deflate, deflatezlib, deflateblock, deflatezlibblock, inflateinit, inflate, inflatezlib, inflateblock, inflatezlibblock, flateerr, mkcrctab, blockcrc, adler32 \- deflate compression +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'ulongmm'u +.PP +.B +int deflateinit(void) +.PP +.B +int deflate(void *wr, int (*w)(void*,void*,int), +.br +.B + void *rr, int (*r)(void*,void*,int), +.br +.B + int level, int debug) +.PP +.B +int deflatezlib(void *wr, int (*w)(void*,void*,int), +.br +.B + void *rr, int (*r)(void*,void*,int), +.br +.B + int level, int debug) +.PP +.B +int deflateblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize, +.br +.B + int level, int debug) +.PP +.B +int deflatezlibblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize, +.br +.B + int level, int debug) +.PP +.B +int inflateinit(void) +.PP +.B +int inflate(void *wr, int (*w)(void*, void*, int), +.br +.B + void *getr, int (*get)(void*)) +.PP +.B +int inflatezlib(void *wr, int (*w)(void*, void*, int), +.br +.B + void *getr, int (*get)(void*)) +.PP +.B +int inflateblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize) +.PP +.B +int inflatezlibblock(uchar *dst, int dsize, +.br +.B + uchar *src, int ssize) +.PP +.B +char *flateerr(int error) +.PP +.B +ulong *mkcrctab(ulong poly) +.PP +.B +ulong blockcrc(ulong *tab, ulong crc, void *buf, int n) +.PP +.B +ulong adler32(ulong adler, void *buf, int n) +.SH DESCRIPTION +These routines compress and decompress data using the deflate compression algorithm, +which is used for most gzip, zip, and zlib files. +.PP +.I Deflate +compresses input data retrieved by calls to +.I r +with arguments +.IR rr , +an input buffer, and a count of bytes to read. +.I R +should return the number of bytes read; +end of input is signaled by returning zero, an input error by +returning a negative number. +The compressed output is written to +.I w +with arguments +.IR wr , +the output data, and the number of bytes to write. +.I W +should return the number of bytes written; +writing fewer than the requested number of bytes is an error. +.I Level +indicates the amount of computation deflate should do while compressing the data. +Higher +.I levels +usually take more time and produce smaller outputs. +Valid values are 1 to 9, inclusive; 6 is a good compromise. +If +.I debug +is non-zero, cryptic debugging information is produced on standard error. +.PP +.I Inflate +reverses the process, converting compressed data into uncompressed output. +Input is retrieved one byte at a time by calling +.I get +with the argument +.IR getr . +End of input of signaled by returning a negative value. +The uncompressed output is written to +.IR w , +which has the same interface as for +.IR deflate . +.PP +.I +Deflateblock +and +.I inflateblock +operate on blocks of memory but are otherwise similar to +.I deflate +and +.IR inflate . +.PP +The zlib functions are similar, but operate on files with a zlib header and trailer. +.PP +.I Deflateinit +or +.I inflateinit +must be called once before any call to the corresponding routines. +.PP +If the above routines fail, +they return a negative number indicating the problem. +The possible values are +.IR FlateNoMem , +.IR FlateInputFail , +.IR FlateOutputFail , +.IR FlateCorrupted , +and +.IR FlateInternal . +.I Flateerr +converts the number into a printable message. +.I FlateOk +is defined to be zero, +the successful return value for +.IR deflateinit , +.IR deflate , +.IR deflatezlib , +.IR inflateinit , +.IR inflate , +and +.IR inflatezlib . +The block functions return the number of bytes produced when they succeed. +.PP +.I Mkcrctab +allocates +(using +.IR malloc (2)), +initializes, and returns a table for rapid computation of 32 bit CRC values using the polynomial +.IR poly . +.I Blockcrc +uses +.IR tab , +a table returned by +.IR mkcrctab , +to update +.I crc +for the +.I n +bytes of data in +.IR buf , +and returns the new value. +.I Crc +should initially be zero. +.I Blockcrc +pre-conditions and post-conditions +.I crc +by ones complementation. +.PP +.I Adler32 +updates the Adler 32-bit checksum of the +.I n +butes of data in +.IR buf. +The initial value of +.I adler +(that is, its value after seeing zero bytes) should be 1. +.SH SOURCE +.B /sys/src/libflate diff --git a/static/plan9-4e/man2/floor.2 b/static/plan9-4e/man2/floor.2 new file mode 100644 index 00000000..9205c011 --- /dev/null +++ b/static/plan9-4e/man2/floor.2 @@ -0,0 +1,58 @@ +.TH FLOOR 2 +.SH NAME +fabs, fmod, floor, ceil \- absolute value, remainder, floor, ceiling functions +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +double floor(double x) +.PP +.B +double ceil(double x) +.PP +.B +double fabs(double x) +.PP +.B +double fmod(double x, double y) +.SH DESCRIPTION +.I Fabs +returns the absolute value +.RI | \|x\| |. +.PP +.I Floor +returns the +largest integer +not greater than +.IR x . +.PP +.I Ceil +returns the +smallest integer +not less than +.IR x . +.PP +.I Fmod +returns +.I x +if +.I y +is zero, otherwise the number +.I f +with the same sign as +.IR x , +such that +.I "x = iy + f\|" +for some integer +.IR i , +and +.RI | \|f\| | +< +.RI | \|y\| |. +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR abs (2), +.IR frexp (2) diff --git a/static/plan9-4e/man2/fmtinstall.2 b/static/plan9-4e/man2/fmtinstall.2 new file mode 100644 index 00000000..7e5df733 --- /dev/null +++ b/static/plan9-4e/man2/fmtinstall.2 @@ -0,0 +1,372 @@ +.TH FMTINSTALL 2 +.SH NAME +fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt \- support for user-defined print formats and output routines +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ft L +.nf +.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u +typedef struct Fmt Fmt; +struct Fmt{ + uchar runes; /* output buffer is runes or chars? */ + void *start; /* of buffer */ + void *to; /* current place in the buffer */ + void *stop; /* end of the buffer; overwritten if flush fails */ + int (*flush)(Fmt*); /* called when to == stop */ + void *farg; /* to make flush a closure */ + int nfmt; /* num chars formatted so far */ + va_list args; /* args passed to dofmt */ + int r; /* % format Rune */ + int width; + int prec; + ulong flags; +}; + +enum{ + FmtWidth = 1, + FmtLeft = FmtWidth << 1, + FmtPrec = FmtLeft << 1, + FmtSharp = FmtPrec << 1, + FmtSpace = FmtSharp << 1, + FmtSign = FmtSpace << 1, + FmtZero = FmtSign << 1, + FmtUnsigned = FmtZero << 1, + FmtShort = FmtUnsigned << 1, + FmtLong = FmtShort << 1, + FmtVLong = FmtLong << 1, + FmtComma = FmtVLong << 1, + + FmtFlag = FmtComma << 1 +}; +.fi +.PP +.B +.ta \w'\fLchar* 'u + +.PP +.B +int fmtfdinit(Fmt *f, int fd, char *buf, int nbuf); +.PP +.B +int fmtfdflush(Fmt *f); +.PP +.B +int fmtstrinit(Fmt *f); +.PP +.B +char* fmtstrflush(Fmt *f); +.PP +.B +int runefmtstrinit(Fmt *f); +.PP +.B +Rune* runefmtstrflush(Fmt *f); + +.PP +.B +int fmtinstall(int c, int (*fn)(Fmt*)); +.PP +.B +int dofmt(Fmt *f, char *fmt); +.PP +.B +int dorfmt(Fmt*, Rune *fmt); +.PP +.B +int fmtprint(Fmt *f, char *fmt, ...); +.PP +.B +int fmtvprint(Fmt *f, char *fmt, va_list v); +.PP +.B +int fmtrune(Fmt *f, int r); +.PP +.B +int fmtstrcpy(Fmt *f, char *s); +.PP +.B +int fmtrunestrcpy(Fmt *f, Rune *s); +.PP +.B +int errfmt(Fmt *f); +.SH DESCRIPTION +The interface described here allows the construction of custom +.IR print (2) +verbs and output routines. +In essence, they provide access to the workings of the formatted print code. +.PP +The +.IR print (2) +suite maintains its state with a data structure called +.BR Fmt . +A typical call to +.IR print (2) +or its relatives initializes a +.B Fmt +structure, passes it to subsidiary routines to process the output, +and finishes by emitting any saved state recorded in the +.BR Fmt . +The details of the +.B Fmt +are unimportant to outside users, except insofar as the general +design influences the interface. +The +.B Fmt +records whether the output is in runes or bytes, +the verb being processed, its precision and width, +and buffering parameters. +Most important, it also records a +.I flush +routine that the library will call if a buffer overflows. +When printing to a file descriptor, the flush routine will +emit saved characters and reset the buffer; when printing +to an allocated string, it will resize the string to receive more output. +The flush routine is nil when printing to fixed-size buffers. +User code need never provide a flush routine; this is done internally +by the library. +.SS Custom output routines +To write a custom output routine, such as an error handler that +formats and prints custom error messages, the output sequence can be run +from outside the library using the routines described here. +There are two main cases: output to an open file descriptor +and output to a string. +.PP +To write to a file descriptor, call +.I fmtfdinit +to initialize the local +.B Fmt +structure +.IR f , +giving the file descriptor +.IR fd , +the buffer +.IR buf , +and its size +.IR nbuf . +Then call +.IR fmtprint +or +.IR fmtvprint +to generate the output. +These behave just like +.B fprint +(see +.IR print (2)) +or +.B vfprint +except that the characters are buffered until +.I fmtfdflush +is called. +A typical example of this sequence appears in the Examples section. +.PP +The same basic sequence applies when outputting to an allocated string: +call +.I fmtstrinit +to initialize the +.BR Fmt , +then call +.I fmtprint +and +.I fmtvprint +to generate the output. +Finally, +.I fmtstrflush +will return the allocated string, which should be freed after use. +To output to a rune string, use +.I runefmtstrinit +and +.IR runefmtstrflush . +Regardless of the output style or type, +.I fmtprint +or +.I fmtvprint +generates the characters. +.SS Custom format verbs +.I Fmtinstall +is used to install custom verbs and flags labeled by character +.IR c , +which may be any non-zero Unicode character. +.I Fn +should be declared as +.IP +.EX +int fn(Fmt*) +.EE +.PP +.IB Fp ->r +is the flag or verb character to cause +.I fn +to be called. +In +.IR fn , +.IB fp ->width , +.IB fp ->prec +are the width and precision, and +.IB fp ->flags +the decoded flags for the verb (see +.IR print (2) +for a description of these items). +The standard flag values are: +.B FmtSign +.RB ( + ), +.B FmtLeft +.RB ( - ), +.B FmtSpace +.RB ( '\ ' ), +.B FmtSharp +.RB ( # ), +.B FmtComma +.RB ( , ), +.B FmtLong +.RB ( l ), +.B FmtShort +.RB ( h ), +.B FmtUnsigned +.RB ( u ), +and +.B FmtVLong +.RB ( ll ). +The flag bits +.B FmtWidth +and +.B FmtPrec +identify whether a width and precision were specified. +.PP +.I Fn +is passed a pointer to the +.B Fmt +structure recording the state of the output. +If +.IB fp ->r +is a verb (rather than a flag), +.I fn +should use +.B Fmt->args +to fetch its argument from the list, +then format it, and return zero. +If +.IB fp ->r +is a flag, +.I fn +should return a negative value: +the negation of one of the above flag values, or some otherwise unused power of two. +All interpretation of +.IB fp ->width\f1, +.IB fp ->prec\f1, +and +.IB fp-> flags +is left up to the conversion routine. +.I Fmtinstall +returns 0 if the installation succeeds, \-1 if it fails. +.PP +.IR Fmtprint +and +.IR fmtvprint +may be called to +help prepare output in custom conversion routines. +However, these functions clear the width, precision, and flags. +The functions +.I dofmt +and +.I dorfmt +are the underlying formatters; they +use the existing contents of +.B Fmt +and should be called only by sophisticated conversion routines. +All these routines return the number of characters (bytes of UTF or runes) +produced. +.PP +Some internal functions may be useful to format primitive types. +They honor the width, precision and flags as described in +.IR print (2). +.I Fmtrune +formats a single character +.BR r . +.I Fmtstrcpy +formats a string +.BR s ; +.I fmtrunestrcpy +formats a rune string +.BR s . +.I Errfmt +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. +.SH EXAMPLES +This function prints an error message with a variable +number of arguments and then quits. +Compared to the corresponding example in +.IR print (2), +this version uses a smaller buffer, will never truncate +the output message, but might generate multiple +.B write +system calls to produce its output. +.IP +.EX +.ta 6n +6n +6n +6n +6n +6n +6n +6n +6n +#pragma varargck argpos error 1 + +void fatal(char *fmt, ...) +{ + Fmt f; + char buf[64]; + va_list arg; + + fmtfdinit(&f, 1, buf, sizeof buf); + fmtprint(&f, "fatal: "); + va_start(arg, fmt); + fmtvprint(&f, fmt, arg); + va_end(arg); + fmtprint(&f, "\en"); + fmtfdflush(&f); + exits("fatal error"); +} +.EE +.PP +This example adds a verb to print complex numbers. +.IP +.EX +typedef +struct { + double r, i; +} Complex; + +#pragma varargck type "X" Complex + +int +Xfmt(Fmt *f) +{ + Complex c; + + c = va_arg(f->args, Complex); + return fmtprint(f, "(%g,%g)", c.r, c.i); +} + +main(...) +{ + Complex x = (Complex){ 1.5, -2.3 }; + + fmtinstall('X', Xfmt); + print("x = %X\en", x); +} +.EE +.SH SOURCE +.B /sys/src/libc/fmt +.SH SEE ALSO +.IR print (2), +.IR utf (6), +.IR errstr (2) +.SH DIAGNOSTICS +These routines return negative numbers or nil for errors and set +.IR errstr . +.SH BUGS diff --git a/static/plan9-4e/man2/fopen.2 b/static/plan9-4e/man2/fopen.2 new file mode 100644 index 00000000..40abf9d7 --- /dev/null +++ b/static/plan9-4e/man2/fopen.2 @@ -0,0 +1,352 @@ +.TH FOPEN 2 +.SH NAME +fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror, clearerr \- standard buffered input/output package +.SH SYNOPSIS +.B #include +.PP +.ta \w'\fLFILE 'u +.B +FILE *fopen(char *filename, char *mode) +.PP +.B +FILE *freopen(char *filename, char *mode, FILE *f) +.PP +.B +FILE *fdopen(int fd, char *mode) +.PP +.B +int fileno(FILE *f) +.PP +.B +FILE *sopenr(char *s) +.PP +.B +FILE *sopenw(void) +.PP +.B +char *sclose(FILE *f) +.PP +.B +int fclose(FILE *f) +.PP +.B +int fflush(FILE *f) +.PP +.B +int setvbuf(FILE *f, char *buf, int type, long size) +.PP +.B +void setbuf(FILE *f, char *buf) +.PP +.B +int fgetpos(FILE *f, long *pos) +.PP +.B +long ftell(FILE *f) +.PP +.B +int fsetpos(FILE *f, long *pos) +.PP +.B +int fseek(FILE *f, long offset, int whence) +.PP +.B +void rewind(FILE *f) +.PP +.B +int feof(FILE *f) +.PP +.B +int ferror(FILE *f) +.PP +.B +void clearerr(FILE *f) +.SH DESCRIPTION +The functions described in this and related pages +.RI ( fgetc (2), +.IR fprintf (2), +.IR fscanf (2), +and +.IR tmpfile (2)) +implement the +ANSI C buffered I/O package with extensions. +.PP +A file with associated buffering is called a +.I stream +and is declared to be a pointer to a defined type +.BR FILE . +.IR Fopen (2) +creates certain descriptive data for a stream +and returns a pointer to designate the stream in all +further transactions. +There are three normally open streams with constant +pointers declared in +the include file and associated with the standard open files: +.TP 10n +.BR stdin +standard input file +.br +.ns +.TP +.B stdout +standard output file +.br +.ns +.TP +.B stderr +standard error file +.PP +A constant pointer +.B NULL +designates no stream at all. +.PP +.I Fopen +opens the file named by +.I filename +and associates a stream with it. +.I Fopen +returns a pointer to be used to identify +the stream in subsequent operations, or +.B NULL +if the open fails. +.I Mode +is a character string having one of the following values: +.nf +.ta 8n +\fL"r"\fP open for reading +\fL"w"\fP truncate to zero length or create for writing +\fL"a"\fP append; open or create for writing at end of file +\fL"r+"\fP open for update (reading and writing) +\fL"w+"\fP truncate to zero length or create for update +\fL"a+"\fP append; open or create for update at end of file +.fi +.PP +In addition, each of the above strings can have a +.L b +somewhere after the first character, +meaning `binary file', but this implementation makes no distinction +between binary and text files. +.PP +.I Fclose +causes the stream pointed to by +.I f +to be flushed (see below) and does a +.I close +(see +.IR open (2)) +on the associated file. +It frees any automatically allocated buffer. +.I Fclose +is called automatically on +.IR exits (2) +for all open streams. +.PP +.I Freopen +is like open except that it reuses stream pointer +.IR f . +.I Freopen +first attempts to close any file associated with +.IR f ; +it ignores any errors in that close. +.PP +.I Fdopen +associates a stream with an open Plan 9 file descriptor. +.PP +.I Fileno +returns the number of the Plan 9 file descriptor associated with the stream. +.PP +.I Sopenr +associates a read-only stream with a null-terminated string. +.PP +.I Sopenw +opens a stream for writing. +No file descriptor is associated with the stream; +instead, all output is written to the stream buffer. +.PP +.I Sclose +closes a stream opened with +.I sopenr +or +.IR sopenw . +It returns a pointer to the 0 terminated buffer associated with the stream. +.PP +By default, output to a stream is fully buffered: it is accumulated in +a buffer until the buffer is full, and then +.I write +(see +.IR read (2)) +is used to write the buffer. +An exception is standard error, which is line buffered: +output is accumulated in a buffer until +a newline is written. +Input is also fully buffered by default; this means that +.IR read (2) +is used to fill a buffer as much as it can, and then characters +are taken from that buffer until it empties. +.I Setvbuf +changes the buffering method for file +.I f +according to +.IR type: +either +.B _IOFBF +for fully buffered, +.B _IOLBF +for line buffered, +or +.B _IONBF +for unbuffered (each character causes a +.I read +or +.IR write). +If +.I buf +is supplied, it is used as the buffer and +.I size +should be its size; +If +.I buf +is zero, a buffer of the given size is allocated (except for the unbuffered case) using +.IR malloc (2). +.PP +.I Setbuf +is an older method for changing buffering. If +.I buf +is supplied, it changes to fully buffered with the given buffer, which should +be of size +.B BUFSIZ +(defined in +.BR stdio.h ). +If +.I buf +is zero, the buffering method changes to unbuffered. +.PP +.I Fflush +flushes the buffer of output stream +.IR f , +delivering any unwritten buffered data to the host file. +.PP +There is a +.I file position indicator +associated with each stream. +It starts out pointing at the first character (unless the file is opened +with append mode, in which case the indicator is always ignored). +The file position indicator is maintained by the reading and writing +functions described in +.IR fgetc (2). +.PP +.I Fgetpos +stores the current value of the file position indicator for stream +.I f +in the object pointed to by +.IR pos . +It returns zero on success, nonzero otherwise. +.I Ftell +returns the current value of the file position indicator. +The file position indicator is to +be used only as an argument to +.IR fseek. +.PP +.I Fsetpos +sets the file position indicator for stream +.I f +to the value of the object pointed to by +.IR pos , +which shall be a value returned by an earlier call to +.I fgetpos +on the same stream. +It returns zero on success, nonzero otherwise. +.I Fseek +obtains a new position, measured in characters from the beginning +of the file, by adding +.I offset +to the position specified by +.IR whence : +the beginning of the file if +.I whence +is +.BR SEEK_SET ; +the current value of the file position indicator for +.BR SEEK_CUR ; +and the end-of-file for +.BR SEEK_END . +.I Rewind +sets the file position indicator to the beginning of the file. +.PP +An integer constant +.B EOF +is returned +upon end of file or error by integer-valued functions that +deal with streams. +.I Feof +returns non-zero if and only if +.I f +is at its end of file. +.PP +.I Ferror +returns non-zero if and only if +.I f +is in the error state. It can get into the error state +if a system call failed on the associated file +or a memory allocation failed. +.I Clearerr +takes a stream out of the error state. +.SH SOURCE +.B /sys/src/libstdio +.SH "SEE ALSO" +.IR fprintf (2), +.IR fscanf (2), +.IR fgetc (2) +.br +.IR open (2), +.IR read (2) +.SH DIAGNOSTICS +The value +.B EOF +is returned uniformly to indicate that a +.B FILE +pointer has not been initialized with +.IR fopen , +input (output) has been attempted on an output (input) stream, +or a +.B FILE +pointer designates corrupt or otherwise unintelligible +.B FILE +data. +.br +Some of these functions set +.IR errstr . +.SH BUGS +Buffering of output can prevent output data +from being seen until long after it is computed \- perhaps +never, as when an abort occurs between buffer filling and flushing. +.br +Buffering of input can cause a process to consume +more input than it actually uses. +This can cause trouble across +.IR exec (2). +.br +Buffering may delay the receipt of a write error until a subsequent +.I stdio +writing, seeking, or file-closing call. +.br +ANSI says that a file can be fully buffered only if +the file is not attached to an interactive device. +In Plan 9 all are fully buffered except standard error. +.PP +.IR Fdopen , +.IR fileno , +.IR sopenr , +.IR sopenw , +and +.I sclose +are not ANSI Stdio functions. +.PP +Stdio offers no support for runes or +.SM UTF +characters. +Unless external compatibility is necessary, use +.IR bio (2), +which supports +.SM UTF +and is smaller, faster, and simpler than Stdio. diff --git a/static/plan9-4e/man2/fork.2 b/static/plan9-4e/man2/fork.2 new file mode 100644 index 00000000..6f80e68d --- /dev/null +++ b/static/plan9-4e/man2/fork.2 @@ -0,0 +1,166 @@ +.TH FORK 2 +.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 (2)); +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 (2)) +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 (2)) +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 (2) +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 /sys/src/libc/9syscall +.br +.B /sys/src/libc/9sys/fork.c +.SH SEE ALSO +.IR intro (2), +.IR proc (3), +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/static/plan9-4e/man2/fprintf.2 b/static/plan9-4e/man2/fprintf.2 new file mode 100644 index 00000000..934f4554 --- /dev/null +++ b/static/plan9-4e/man2/fprintf.2 @@ -0,0 +1,504 @@ +.TH FPRINTF 2 +.SH NAME +fprintf, printf, sprintf, snprintf, vfprintf, vprintf, vsprintf, vsnprintf \- print formatted output +.SH SYNOPSIS +.B #include +.PP +.B +int fprintf(FILE *f, char *format, ...) +.PP +.B +int printf(char *format, ...) +.PP +.B +int sprintf(char *s, char *format, ...) +.PP +.B +int snprintf(char *s, int n, char *format, ...) +.PP +.B +int vfprintf(FILE *f, char *format, va_list args) +.PP +.B +int vprintf(char *format, va_list args) +.PP +.B +int vsprintf(char *s, char *format, va_list args) +.PP +.B +int vsnprintf(char *s, int n, char *format, va_list args) +.SH DESCRIPTION +.I Fprintf +places output on the named output stream +.I f +(see +.IR fopen (2)). +.I Printf +places output on the standard output stream +.IR stdout . +.I Sprintf +places output +followed by the null character +.RB ( \e0 ) +in consecutive bytes starting at +.IR s ; +it is the user's responsibility to ensure that +enough storage is available. +.I Snprintf +is like +.I sprintf +but writes at most +.I n +bytes (including the null character) +into +.IR s . +.IR Vfprintf , +.IR vprintf , +.IR vsnprintf , +and +.I vsprintf +are the same, except the +.I args +argument is the argument list of the +calling function, and the effect is as if the calling function's +argument list from that point on is passed to the +.I printf +routines. +.PP +Each function returns the number of characters +transmitted (not including the +.B \e0 +in the case of +.IR sprintf +and friends), +or +a negative value if an output error was encountered. +.PP +These functions +convert, format, and print their +trailing arguments +under control of a +.IR format +string. +The +.I format +contains two types of objects: +plain characters, which are simply copied to the +output stream, +and conversion specifications, +each of which results in fetching of +zero or more +arguments. +The results are undefined if there are arguments of the +wrong type or too few +arguments for the format. +If the format is exhausted while +arguments remain, the excess +are ignored. +.PP +Each conversion specification is introduced by +the character +.BR % . +After the +.BR % , +the following +appear in sequence: +.PP +.RS +Zero or more +.IR flags , +which modify the meaning of +the conversion specification. +.PP +An optional decimal digit string specifying a minimum +.IR "field width" . +If the converted value has fewer characters +than the field width, it will be padded with spaces on the +left (or right, if the left adjustment, described later, has been given) +to the field width. +.PP +An optional +.I precision\^ +that gives +the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, +the number of digits to appear after the +decimal point for the +.BR e , +.BR E , +and +.B f +conversions, +the maximum number of significant digits +for the +.B g +and +.B G +conversions, +or the maximum number of characters +to be written from a string in +.B s +conversion. +The precision takes the form of a period +.RB ( \&. ) +followed by an optional decimal integer; +if the integer is omitted, it is treated as zero. +.PP +An optional +.B h +specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x +or +.BR X +conversion specifier applies to a +.B short +.B int +or +.B unsigned +.B short +argument (the argument will have been promoted according to the integral +promotions, and its value shall be converted to +.B short +or +.B unsigned +.B short +before printing); +an optional +.B h +specifying that a following +.B n +conversion specifier applies to a pointer to a +.B short +argument; +an optional +.B l +(ell) specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.B X +conversion character applies to a +.B long +or +.B unsigned +.B long +argument; +an optional +.B l +specifying that a following +.B n +conversion specifier applies to a pointer to a +.B long +.B int +argument; +or an optional +.B L +specifying that a following +.BR e , +.BR E , +.BR f , +.BR g , +or +.B G +conversion specifier applies to a +.B long double +argument. +If an +.BR h , +.BR l , +or +.B L +appears with any other conversion specifier, the behavior is undefined. +.PP +A character that indicates the type of +conversion to be applied. +.RE +.PP +A field width or precision, or both, may be +indicated by an asterisk +.RB ( * ) +instead of a digit string. +In this case, an +.B int +.I arg\^ +supplies +the field width or precision. +The arguments specifying field width or precision, or both, +shall appear (in that order) before the argument (if any) to be converted. +A negative field width argument is taken as a +.B - +flag followed by a positive field width. +A negative precision is taken as if it were missing. +.PP +The flag characters and their meanings are: +.PD 0 +.TP 10 +.B - +The result of the conversion is left-justified within the field. +.TP +.B + +The result of a signed +conversion always begins with a sign +.RB ( + +or +.BR - ). +.TP +blank +If the first character of a signed conversion is not a sign, +or a signed conversion results in no characters, +a blank +is prefixed to the result. +This implies that if the blank and +.B + +flags both appear, the blank flag is ignored. +.TP +.B # +The result is to be converted +to an ``alternate form.'' +For +.B o +conversion, it increases the precision to force +the first digit of the result to be a zero. +For +.B x +or +.B X +conversion, a non-zero result has +.B 0x +or +.B 0X +prefixed to it. +For +.BR e , +.BR E , +.BR f , +.BR g , +and +.B G +conversions, the result always contains a decimal point, +even if no digits follow the point (normally, a decimal point +appears in the result of these conversions only if a digit +follows it). +For +.B g +and +.B G +conversions, trailing zeros are +.I not\^ +be removed from the result +as they normally are. +For other conversions, the behavior is undefined. +.TP +.B 0 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR e , +.BR E , +.BR f , +.BR g , +and +.B G +conversions, leading zeros (following any indication of sign or base) +are used to pad the field width; no space padding is performed. +If the +.B 0 +and +.B - +flags both appear, the +.B 0 +flag will be ignored. +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, if a precision is specified, the +.B 0 +flag will be ignored. +For other conversions, the behavior is undefined. +.PD +.PP +The conversion characters +and their meanings are: +.PP +.PD 0 +.TP 10 +\fLd\fP,\fLo\fP,\fLu\fP,\fLx\fP,\fLX\fP +The integer +.I arg\^ +is converted to signed decimal +.RB ( d +or +.BR i ), +unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal notation +.RB ( x +or +.BR X ); +the letters +.B abcdef +are used for +.B x +conversion and the letters +.B ABCDEF +for +.B X +conversion. +The precision specifies the minimum number of digits +to appear; if the value being converted can be represented +in fewer digits, it is expanded with leading zeros. +The default precision is 1. +The result of converting a zero value with a precision +of zero is no characters. +.TP +.BR f +The +.B double +argument is converted to decimal notation +in the style +[\-]\fIddd\fL.\fIddd\fR, +where the number of digits after the decimal point +is equal to the precision specification. +If the precision +is missing, +it is taken as 6; +if the precision is explicitly +.LR 0 , +no decimal point appears. +.TP +.BR e , E +The +.B double +argument is converted in the style +[\-]\fId\fL.\fIddd\fLe\fR±\fIdd\fR, +where there is one digit before the decimal point and +the number of digits after it is equal to the +precision; +when the precision is missing, it is taken as 6; +if the precision is zero, no decimal point appears. +The +.B E +format code produces a number with +.B E +instead of +.B e +introducing the exponent. +The exponent always contains at least two digits. +.TP +.BR g , G +The +.B double +argument is printed in style +.BR f +or +.BR e +(or in style +.B E +in the case of a +.B G +conversion specifier), +with the precision specifying the number of significant digits. +If an explicit precision is zero, it is taken as 1. +The style used depends on the value converted: +style +.B e +is used only if the exponent resulting from +the conversion is less than \-4 +or greater than or equal to the precision. +Trailing zeros are removed from the fractional portion of the result; +a decimal point appears only if it is followed by a digit. +.TP +.B c +The +.B int +argument is converted to an +.B unsigned +.BR char , +and the resulting character is written. +.TP +.B s +The +argument is taken to be a string (character pointer) +and characters from the string are printed until +a null character +.RB ( \e0 ) +is encountered or +the number of characters indicated by the precision +specification is reached. +If the precision is missing, it is taken to be infinite, so +all characters up to the first null character are printed. +A +zero +value for +the argument yields undefined results. +.TP +.B P +The +.B void* +argument is printed in an implementation-defined way (for Plan 9: +the address as hexadecimal number). +.TP +.B n +The argument shall be a pointer to an integer into which is +.I written +the number of characters written to the output stream so far by +this call to +.IR fprintf . +No argument is converted. +.TP +.B % +Print a +.BR % ; +no argument is converted. +.PD +.PP +If a conversion specification is invalid, the behavior is undefined. +.PP +If any argument is, or points to, a union or an aggregate +(except for an array of character type using +.B %s +conversion, or a pointer cast to be a pointer to +.B void +using +.B %P +conversion), the behavior is undefined. +.PP +In no case does a nonexistent or small field width cause truncation +of a field; if the result of a conversion is wider than the field width, +the field is expanded to contain the conversion result. +.SH SOURCE +.B /sys/src/libstdio +.SH SEE ALSO +.IR fopen (2), +.IR fscanf (2), +.IR print (2) +.SH BUGS +There is no way to print a wide character (rune); use +.IR print (2) +or +.IR bio (2). diff --git a/static/plan9-4e/man2/frame.2 b/static/plan9-4e/man2/frame.2 new file mode 100644 index 00000000..1ef43dbf --- /dev/null +++ b/static/plan9-4e/man2/frame.2 @@ -0,0 +1,362 @@ +.TH FRAME 2 +.SH NAME +frinit, frsetrects, frinittick, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frtick, frselectpaint, frdrawsel, frdrawsel0, frgetmouse \- frames of text +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +void frinit(Frame *f, Rectangle r, Font *ft, Image *b, Image **cols) +.PP +.B +void frsetrects(Frame *f, Rectangle r, Image *b) +.PP +.B +void frinittick(Frame *f) +.PP +.B +void frclear(Frame *f, int resize) +.PP +.B +ulong frcharofpt(Frame *f, Point pt) +.PP +.B +Point frptofchar(Frame *f, ulong p) +.PP +.B +void frinsert(Frame *f, Rune *r0, Rune *r1, ulong p) +.PP +.B +int frdelete(Frame *f, ulong p0, ulong p1) +.PP +.B +void frselect(Frame *f, Mousectl *m) +.PP +.B +void frtick(Frame *f, Point pt, int up) +.PP +.B +void frselectpaint(Frame *f, Point p0, Point p1, Image *col) +.PP +.B +void frdrawsel(Frame *f, Point pt0, ulong p0, ulong p1, +.B + int highlighted) +.PP +.B +void frdrawsel0(Frame *f, Point pt0, ulong p0, ulong p1, +.B + Image *back, Image *text) +.PP +.ft L +enum{ + BACK, + HIGH, + BORD, + TEXT, + HTEXT, + NCOL +}; +.fi +.SH DESCRIPTION +This library supports +.I frames +of editable text in a single font on raster displays, such as in +.IR sam (1) +and +.IR rio (1). +Frames may hold any character except NUL (0). +Long lines are folded and tabs are at fixed intervals. +.PP +The user-visible data structure, a +.BR Frame , +is defined in +.BR : +.IP +.EX +.ta 6n +\w'Rectangle 'u +\w'lastlinefull; 'u +typedef struct Frame Frame; +struct Frame +{ + Font *font; /* of chars in the frame */ + Display *display; /* on which frame appears */ + Image *b; /* on which frame appears */ + Image *cols[NCOL]; /* text and background colors */ + Rectangle r; /* in which text appears */ + Rectangle entire; /* of full frame */ + Frbox *box; + ulong p0, p1; /* selection */ + ushort nbox, nalloc; + ushort maxtab; /* max size of tab, in pixels */ + ushort nchars; /* # runes in frame */ + ushort nlines; /* # lines with text */ + ushort maxlines; /* total # lines in frame */ + ushort lastlinefull; /* last line fills frame */ + ushort modified; /* changed since frselect() */ + Image *tick; /* typing tick */ + Image *tickback; /* saved image under tick */ + int ticked; /* flag: is tick onscreen? */ +}; +.EE +.PP +.B Frbox +is an internal type and is not used by the interface. +.B P0 +and +.B p1 +may be changed by the application provided the selection routines are called +afterwards to maintain a consistent display. +.I Maxtab +determines the size of tab stops. +.I Frinit +sets it to 8 times the width of a +.B 0 +(zero) +character in the font; +it may be changed before any text is added to the frame. +The other elements of the structure are maintained by the library and +should not be modified directly. +.PP +The text within frames +is not directly addressable; +instead frames are designed to work alongside +another structure that holds the text. +The typical application is to display a section of a longer document such +as a text file or terminal session. +Usually the program will keep its own copy of the +text in the window (probably as +an array of +.BR Runes ) +and pass components of this text to the frame routines to +display the visible portion. +Only the text that is visible is held by the +.BR Frame ; +the application must check +.BR maxlines , +.BR nlines , +and +.B lastlinefull +to determine, for example, whether new text needs to be appended +at the end of the +.B Frame +after calling +.I frdelete +(q.v.). +.PP +There are no routines in the library to allocate +.BR Frames ; +instead the interface assumes that +.B Frames +will be components of larger structures. +.I Frinit +prepares the +.B Frame +.I f +so characters drawn in it will appear +in the single +.B Font +.IR ft . +It then calls +.I frsetrects +and +.I frinittick +to initialize the geometry for the +.BR Frame . +The +.B Image +.I b +is where the +.B Frame +is to be drawn; +.B Rectangle +.I r +defines the limit of the portion of the +.B Image +the text will occupy. +The +.B Image +pointer +may be null, allowing the other routines to be called to maintain the +associated data structure in, for example, an obscured window. +.PP +The array of +.B Images +cols sets the colors in which text and borders will be drawn. The background of the frame will be drawn in +.BR cols[BACK] ; +the background of highlighted text in +.BR cols[HIGH] ; +borders and scroll bar in +.BR cols[BORD] ; +regular text in +.BR cols[TEXT] ; +and highlighted text in +.BR cols[HTEXT] . +.PP +.I Frclear +frees the internal structures associated with +.IR f , +permitting another +.I frinit +or +.I frsetrects +on the +.BR Frame . +It does not clear the associated display. +If +.I f +is to be deallocated, the associated +.B Font +and +.B Image +must be freed separately. +The +.B resize +argument should be non-zero if the frame is to be redrawn with +a different font; otherwise the frame will maintain some +data structures associated with the font. +.PP +To resize a +.BR Frame , +use +.I frclear +and +.I frinit +and then +.I frinsert +(q.v.) to recreate the display. +If a +.B Frame +is being moved but not resized, that is, if the shape of its containing +rectangle is unchanged, it is sufficient to use +.IR draw (2) +to copy the containing rectangle from the old to the new location and then call +.I frsetrects +to establish the new geometry. +(It is unnecessary to call +.I frinittick +unless the font size has changed.) +No redrawing is necessary. +.PP +.B Frames +hold text as runes, +not as bytes. +.I Frptofchar +returns the location of the upper left corner of the +.I p'th +rune, starting from 0, in the +.B Frame +.IR f . +If +.I f +holds fewer than +.I p +runes, +.I frptofchar +returns the location of the upper right corner of the last character in +.IR f . +.I Frcharofpt +is the inverse: it +returns the index of the closest rune whose image's upper left corner +is up and to the left of +.IR pt . +.PP +.I Frinsert +inserts into +.B Frame +.I f +starting at rune index +.I p +the runes between +.I r0 +and +.IR r1 . +If a NUL (0) character +is inserted, chaos will ensue. +Tabs and newlines +are handled by the library, but all other characters, +including control characters, are just displayed. +For example, backspaces are printed; to erase +a character, use +.IR frdelete . +.PP +.I Frdelete +deletes from the +.B Frame +the text between +.I p0 +and +.IR p1 ; +.I p1 +points at the first rune beyond the deletion. +.PP +.I Frselect +tracks the mouse to select a contiguous string of text in the +.BR Frame . +When called, a mouse button is typically down. +.I Frselect +will return when the button state has changed (some buttons may +still be down) and will set +.IB f ->p0 +and +.IB f ->p1 +to the selected range of text. +.PP +Programs that wish to manage the selection themselves have several routines to help. +They involve the maintenance of the `tick', the vertical line indicating a null selection +between characters, and the colored region representing a non-null selection. +.I Frtick +draws (if +.I up +is non-zero) or removes (if +.I up +is zero) the tick at the screen position indicated by +.IR pt . +.I Frdrawsel +repaints a section of the frame, delimited by character positions +.I p0 +and +.IR p1 , +either with plain background or +entirely highlighted, according to the flag +.IR highlighted , +managing the tick appropriately. +The point +.I pt0 +is the geometrical location of +.I p0 +on the screen; like all of the selection-helper routines' +.B Point +arguments, it must be a value generated by +.IR frptofchar . +.I Frdrawsel0 +is a lower-level routine, taking as arguments a background color, +.IR back , +and text color, +.IR text . +It assumes that the tick is being handled (removed beforehand, replaced afterwards, as required) +by its caller. +.I Frselectpaint +uses a solid color, +.IR col , +to paint a region of the frame defined by the +.B Points +.I p0 +and +.IR p1 . +.SH SOURCE +.B /sys/src/libframe +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR cachechars (2). diff --git a/static/plan9-4e/man2/frexp.2 b/static/plan9-4e/man2/frexp.2 new file mode 100644 index 00000000..b78a57b3 --- /dev/null +++ b/static/plan9-4e/man2/frexp.2 @@ -0,0 +1,47 @@ +.TH FREXP 2 +.SH NAME +frexp, ldexp, modf \- split into mantissa and exponent +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +double frexp(double value, int *eptr) +.PP +.B +double ldexp(double value, int exp) +.PP +.B +double modf(double value, double *iptr) +.SH DESCRIPTION +.I Frexp +returns the mantissa of +.I value +and stores the exponent indirectly through +.IR eptr , +so that +.I value += +.if t .IR frexp ( value )×2\u\s-2 (*eptr) \s0\d +.if n .IR frexp ( value )*2** (*eptr). +.PP +.I Ldexp +returns the quantity +.if t .IR value ×2\u\s-2 exp \s0\d. +.if n .IR value *2** exp. +.PP +.I Modf +returns the positive fractional part of +.I value +and stores the integer part indirectly +through +.IR iptr . +.SH SOURCE +.B /sys/src/libc/port/frexp.c +.SH SEE ALSO +.IR intro (2) +.SH DIAGNOSTICS +.I Ldexp +returns 0 for underflow and the appropriately signed infinity +for overflow. diff --git a/static/plan9-4e/man2/fscanf.2 b/static/plan9-4e/man2/fscanf.2 new file mode 100644 index 00000000..bb94924f --- /dev/null +++ b/static/plan9-4e/man2/fscanf.2 @@ -0,0 +1,402 @@ +.TH FSCANF 2 +.SH NAME +fscanf, scanf, sscanf, vfscanf \- scan formatted input +.SH SYNOPSIS +.B "#include " +.PP +.B +int fscanf(FILE *f, char *format, ...) +.PP +.B +int scanf(char *format, ... ) +.PP +.B +int sscanf(char *s, char *format, ...) +.PP +.B +int vfscanf(FILE *stream, char *format, char *args) +.SH DESCRIPTION +.I Fscanf +reads from the named input stream +.I f +(see +.IR fopen (2)) +under control of the string pointed to by +.I format +that specifies the admissible input sequences and how they are to be converted +for assignment, using subsequent arguments as pointers to the objects +to receive the converted input. +If there are insufficient arguments for the format, the behavior is undefined. +If the format is exhausted while arguments remain, the excess arguments +are evaluated (as always) but are otherwise ignored. +.PP +.I Scanf +and +.I sscanf +are the same, but they read from +.I stdin +and the character string +.IR s , +respectively. +.I Vfscanf +is like +.IR scanf , +except the +.I args +argument is a pointer to an argument in an argument list of the +calling function and the effect is as if the calling function's +argument list from that point on is passed to the scanf routines. +.PP +The format is composed of zero or more directives: +one or more white-space characters; an ordinary character (not +.BR % ); +or a conversion specification. +Each conversion specification is introduced by the character +.BR %. +After the +.BR % , +the following appear in sequence: +.PP +.RS +An optional assignment-suppressing character +.BR * . +.PP +An optional decimal integer that specifies the maximum field width. +.PP +An optional +.BR h , +.B l +(ell) or +.B L +indicating the size of the receiving object. +The conversion specifiers +.BR d , +.BR i , +and +.B n +shall be preceded by +.B h +if the corresponding argument is a pointer to +.B short +rather than a pointer to +.BR int , +or by +.B l +if it is a pointer to +.BR long . +Similarly, the conversion specifiers +.BR o , +.BR u , +and +.B x +shall be preceded by +.B h +if the corresponding argument is a pointer to +.B unsigned +.B short +rather than a pointer to +.BR unsigned , +or by +.B l +if it is a pointer to +.B unsigned +.BR long . +Finally, the conversion specifiers +.BR e , +.BR f , +and +.B g +shall be preceded by +.B l +if the corresponding argument is a pointer to +.B double +rather than a pointer to +.BR float , +or by +.B L +if it is a pointer to +.B long +.BR double . +If an +.BR h , +.BR l , +or +.B L +appears with any other conversion specifier, the behavior is undefined. +.PP +A character that specifies the type of conversion to be applied. +The valid conversion specifiers are described below. +.RE +.PP +.I Fscanf +executes each directive of the format in turn. +If a directive fails, as detailed below, +.I fscanf +returns. +Failures are described as input failures (due to the unavailability +of input), +or matching failures (due to inappropriate input). +.PP +A directive composed of white space is executed by reading input up +to the first non-white-space character (which remains unread), +or until no more characters can be read. +.PP +A directive that is an ordinary character is executed by reading +the next character from the stream. +If if differs from the one comprising the directive, +the directive fails, and the differing and subsequent characters +remain unread. +.PP +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each specifier. +A conversion specification is executed in the following steps: +.PP +Input white-space characters (as specified by +.IR isspace , +see +.IR ctype (2)) +are skipped, unless the specification includes a +.BR [ , +.BR c , +or +.B n +specifier. +.PP +An input item is read from the stream, +unless the specification includes an +.B n +specifier. +An input item is defined as the longest sequence of input characters +(up to any specified maximum field width) which is an initial +subsequence of a matching sequence. +The first character, if any, after the input item remains unread. +If the length of the input item is zero, the execution of +the directive fails: this condition is a matching failure, +unless an error prevented input from the stream, +in which case it is an input failure. +.PP +Except in the case of a +.B % +specifier, the input item (or, in the case of a +.B %n +directive, the count of input characters) +is converted to a type appropriate to the conversion specifier. +If the input item is not a matching sequence, the execution of +the directive fails: this condition is a matching failure. +Unless assignment suppression was indicated by a +.BR * , +the result of the conversion is placed in the object pointed to by the +first argument following the +.I format +argument that has not already received a conversion result. +If this object does not have an appropriate type, +or if the result of the conversion cannot be represented +in the space provided, the behavior is undefined. +.PP +The following conversion specifiers are valid: +.TP 6 +.B d +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtol +(see +.IR atof (2)) +function with 10 for the +.B base +argument. +The corresponding argument shall be a pointer to +.BR int . +.TP +.B i +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtol +function with 0 for the +.B base +argument. +The corresponding argument shall be a pointer to +.BR int . +.TP +.B o +Matches an optionally signed octal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +(see +.IR atof (2)) +function with 8 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.B u +Matches an optionally signed decimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +function with 10 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.B x +Matches an optionally signed hexadecimal integer, +whose format is the same as expected for the subject sequence +of the +.I strtoul +function with 16 for the +.B base +argument. +The corresponding argument shall be a pointer to +.B unsigned +.BR int . +.TP +.BR e , f , g +Matches an optionally signed floating-point number, whose format is +the same as expected for the subject string of the +.I strtod +(see +.IR atof (2)) +function. +The corresponding argument shall be a pointer to +.BR float . +.TP +.B s +Matches a sequence of non-white-space characters. +The corresponding argument shall be a pointer to the initial +character of an array large enough to accept the sequence +and a terminating NUL (0) character, which will be added automatically. +.TP +.B [ +Matches a nonempty sequence of characters from a set of expected +characters (the +.IR scanset ). +The corresponding argument shall be a pointer to the initial +character of an array large enough to accept the sequence and a terminating +NUL character, which will be added automatically. +The conversion specifier includes all subsequent characters in the +.I format +string, up to and including the matching right brace +.RB ( ] ). +The characters between the brackets (the +.IR scanlist ) +comprise the scanset, unless the character after the left bracket +is a circumflex +.RB ( ^ ), +in which case the scanset contains all characters that do not appear +in the scanlist between the circumflex and the right bracket. +As a special case, if the conversion specifier begins with +.B [] +or +.BR [^] , +the right bracket character is in the scanlist and the next +right bracket character is the matching right bracket +that ends the specification. +If a +.B - +character is in the scanlist and is not the first, nor the second +where the first character is a +.BR ^ , +nor the last character, the behavior is implementation-defined +(in Plan 9: the scanlist includes all characters in the +.SM ASCII +(sic) +range between the two characters on either side of the +.BR - ). +.TP +.B c +Matches a sequence of characters of the number specified by the field width +(1 if no field width is present in the directive). +The corresponding argument shall be a pointer to the initial character +of an array large enough to accept the sequence. +No NUL character is added. +.TP +.B P +Matches an implementation-defined set of sequences, +which should be the same as the set of sequences that may be +produced by the +.B %P +conversion of the +.IR fprintf (2) +function +(in Plan 9, a hexadecimal number). +The corresponding argument shall be a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation defined; +however, for any input item other than a value converted earlier +during the same program execution, the behavior of the +.B %P +conversion is undefined. +.TP +.B n +No input is consumed. +The corresponding argument shall be a pointer to integer into which +is written the number of characters read from the input stream so far +by this call to +.IR fscanf . +Execution of a +.B %n +directive does not increment the assignment count returned at the +completion of +.IR fscanf . +.TP +.B % +Matches a single +.BR % ; +no conversion or assignment occurs. +The complete conversion specification shall be +.BR %% . +.PD +.PP +If a conversion specification is invalid, the behavior is undefined. +.PP +The conversion specifiers +.BR E , +.BR G , +and +.B X +are also valid and behave the same as, respectively, +.BR e , +.BR g , +and +.BR x . +.PP +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any characters matching the current +directive have been read (other than leading white space, +where permitted), execution of the current directive terminates with +an input failure; +otherwise, unless execution of the current directive is terminated +with a matching failure, execution of the following directive +(if any) is terminated with an input failure. +.PP +If conversion terminates on a conflicting input character, +the offending input character is left unread in the input stream. +Trailing white space (including newline characters) is left unread +unless matched by a directive. +The success of literal matches and suppressed assignments is not +directly determinable other than via the +.B %n +directive. +.PP +The return value from +.I fscanf +is the number of input items assigned, which can be fewer than +provided for, or even zero, in the event of an early matching failure. +However, if an input failure occurs before any conversion, +.B EOF +is returned. +.SH SOURCE +.B /sys/src/libstdio +.SH "SEE ALSO" +.IR fopen (2), +.IR fgetc (2) +.SH BUGS +Does not know about +.SM UTF. diff --git a/static/plan9-4e/man2/fversion.2 b/static/plan9-4e/man2/fversion.2 new file mode 100644 index 00000000..711cca7b --- /dev/null +++ b/static/plan9-4e/man2/fversion.2 @@ -0,0 +1,72 @@ +.TH FVERSION 2 +.SH NAME +fversion \- initialize 9P connection and negotiate version +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +.PP +.ft P +.B +int fversion(int fd, int bufsize, char *version, int nversion) +.SH DESCRIPTION +.PP +.I Fversion +is used to initialize the 9P connection represented by +.I fd +and to negotiate the version of the protocol to be used. +.PP +The +.I bufsize +determines the size of the I/O buffer used to stage 9P requests to the server, +subject to the constraints of the server itself. +The +.I version +is a text string that represents the highest version level the protocol will support. +The +.I version +will be overwritten with the negotiated, possibly lower, version of the protocol. +The return value of +.I fversion +is the length of the returned version string; the value of +.I nversion +is therefore not the length of the version string presented to the system call, +but the total length of the buffer to accept the final result, in the manner of a read system call. +.PP +Default values of zero for +.I bufsize +and the empty string for +.I version +will negotiate sensible defaults for the connection. +If +.I version +is the empty string, +.I nversion +must still be large enough to receive the returned version string. +.PP +The interpretation of the version strings is defined in +.IR version (5). +.PP +It is rare to use +.IR fversion +directly; usually the default negotiation performed +by the kernel during +.B mount +(see +.IR bind (2)) +or even more commonly +.B amount +(see +.IR auth (2)) +is sufficient. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (5), +.IR version (5), +.IR fauth (2). +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/genrandom.2 b/static/plan9-4e/man2/genrandom.2 new file mode 100644 index 00000000..6cc1475d --- /dev/null +++ b/static/plan9-4e/man2/genrandom.2 @@ -0,0 +1,44 @@ +.TH GENRANDOM 2 +.SH NAME +genrandom, prng \- random number generation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void genrandom(uchar *buf, int nbytes) +.PP +.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 +.I Genrandom +fills a buffer with bytes from the X9.17 pseudo-random +number generator. The X9.17 generator is seeded by 24 +truly random bytes read from +.BR /dev/random . +.PP +.I Prng +uses the native +.IR rand (2) +pseudo-random number generator to fill the buffer. Used with +.IR srand , +this function can produce a reproducible stream of pseudo random +numbers useful in testing. +.PP +Both functions may be passed to +.I mprand +(see +.IR mp (2)). +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2) diff --git a/static/plan9-4e/man2/getcallerpc.2 b/static/plan9-4e/man2/getcallerpc.2 new file mode 100644 index 00000000..f7505ce5 --- /dev/null +++ b/static/plan9-4e/man2/getcallerpc.2 @@ -0,0 +1,38 @@ +.TH GETCALLERPC 2 +.SH NAME +getcallerpc \- fetch return PC of current function +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.PP +.B ulong getcallerpc(void *firstarg) +.SH DESCRIPTION +.I Getcallerpc +is a portable way to discover the PC to which the current function will return. +.I Firstarg +should be a pointer to the first argument to the function in question. +.SH EXAMPLE +.IP +.EX +void +printpc(ulong arg) +{ + print("Called from %.8lux\en", getcallerpc(&arg)); +} + +void +main(int argc, char *argv[]) +{ + printpc(0); + printpc(0); + printpc(0); +} +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/getcallerpc.[cs] +.SH BUGS +The +.I firstarg +parameter should not be necessary. diff --git a/static/plan9-4e/man2/getenv.2 b/static/plan9-4e/man2/getenv.2 new file mode 100644 index 00000000..339acb82 --- /dev/null +++ b/static/plan9-4e/man2/getenv.2 @@ -0,0 +1,44 @@ +.TH GETENV 2 +.SH NAME +getenv, putenv \- access environment variables +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +char* getenv(char *name) +.br +.B +int putenv(char *name, char *val) +.fi +.SH DESCRIPTION +.I Getenv +reads the contents of +.BI /env/ name +(see +.IR env (3)) +into memory allocated with +.IR malloc (2), +0-terminates it, +and returns a pointer to that area. +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. +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR env (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/getfcr.2 b/static/plan9-4e/man2/getfcr.2 new file mode 100644 index 00000000..3f742a8e --- /dev/null +++ b/static/plan9-4e/man2/getfcr.2 @@ -0,0 +1,125 @@ +.TH GETFCR 2 +.SH NAME +getfcr, setfcr, getfsr, setfsr \- control floating point +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +ulong getfcr(void) +.PP +.B +void setfcr(ulong fcr) +.PP +.B +ulong getfsr(void) +.PP +.B +void setfsr(ulong fsr) +.SH DESCRIPTION +These routines provide a fairly portable interface to control the +rounding and exception characteristics of IEEE 754 floating point units. +In effect, they define a pair of pseudo-registers, the floating +point control register, +.BR fcr , +which affects rounding, precision, and exceptions, and the +floating point status register, +.BR fsr , +which holds the accrued exception bits. +Each register has a +.I get +routine to retrieve its value, a +.I set +routine to modify it, +and macros that identify its contents. +.PP +The +.B fcr +contains bits that, when set, halt execution upon exceptions: +.B FPINEX +(enable inexact exceptions), +.B FPOVFL +(enable overflow exceptions), +.B FPUNFL +(enable underflow exceptions), +.B FPZDIV +(enable zero divide exceptions), and +.B FPINVAL +(enable invalid operation exceptions). +Rounding is controlled by installing in +.BR fcr , +under mask +.BR FPRMASK , +one of the values +.B FPRNR +(round to nearest), +.B FPRZ +(round towards zero), +.B FPRPINF +(round towards positive infinity), and +.B FPRNINF +(round towards negative infinity). +Precision is controlled by installing in +.BR fcr , +under mask +.BR FPPMASK , +one of the values +.B FPPEXT +(extended precision), +.B FPPSGL +(single precision), and +.B FPPDBL +(double precision). +.PP +The +.B fsr +holds the accrued exception bits +.BR FPAINEX , +.BR FPAOVFL , +.BR FPAUNFL , +.BR FPAZDIV , +and +.BR FPAINVAL , +corresponding to the +.B fsr +bits without the +.B A +in the name. +.PP +Not all machines support all modes. If the corresponding mask +is zero, the machine does not support the rounding or precision modes. +On some machines it is not possible to clear selective accrued +exception bits; a +.I setfsr +clears them all. +The exception bits defined here work on all architectures. +By default, the initial state is equivalent to +.IP +.EX +setfcr(FPPDBL|FPRNR|FPINVAL|FPZDIV|FPOVFL); +.EE +.PP +The default state of the floating point unit is fixed for a given +architecture but is undefined across Plan 9: the default is +to provide what the hardware does most efficiently. +Use these routines +if you need guaranteed behavior. +Also, gradual underflow is not available on some machines. +.SH EXAMPLE +To enable overflow traps and make sure registers are rounded +to double precision (for example on the MC68020, where the +internal registers are 80 bits long): +.EX +.IP +.ft L +ulong fcr; +fcr = getfcr(); +fcr |= FPOVFL; +fcr &= ~FPPMASK; +fcr |= FPPDBL; +setfcr(fcr); +.ft +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/getfcr.s diff --git a/static/plan9-4e/man2/getfields.2 b/static/plan9-4e/man2/getfields.2 new file mode 100644 index 00000000..9f899773 --- /dev/null +++ b/static/plan9-4e/man2/getfields.2 @@ -0,0 +1,88 @@ +.TH GETFIELDS 2 +.SH NAME +getfields, gettokens, tokenize \- break a string into fields +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* \fP'u +.B +int getfields(char *str, char **args, int maxargs, int multiflag, +.br +.B + char *delims) +.PP +.B +int gettokens(char *str, char **args, int maxargs, char *delims) +.PP +.B +int tokenize(char *str, char **args, int maxargs) +.SH DESCRIPTION +.I Getfields +breaks the null-terminated +.SM UTF +string +.I str +into at most +.I maxargs +null-terminated fields and places pointers to the start of these fields in the array +.IR args . +Some of the bytes in +.I str +are overwritten. +If there are more than +.I maxargs +fields, +only the first +.I maxargs +fields will be set. +.I Delims +is a +.SM UTF +string defining a set of delimiters. +.PP +If +.I multiflag +is zero, +adjacent fields are separated by exactly one delimiter. +A string containing +.I n +delimiter characters +contains +.IR n +1 +fields. +If the +.I multiflag +argument is not zero, +a field is a non-empty string of non-delimiters. +.PP +Getfields +returns the number of tokens processed. +.PP +.I Gettokens +is the same as +.I getfields +with +.I multiflag +non-zero, +except that fields may be quoted using single quotes, in the manner +of +.IR rc (1). +See +.IR quote (2) +for related quote-handling software. +.PP +.I Tokenize +is +.I gettokens +with +.I delims +set to \f5"\et\er\en "\fP. +.SH SOURCE +.B /sys/src/libc/port/tokenize.c +.SH SEE ALSO +.I strtok +in +.IR strcat (2), +.IR quote (2). diff --git a/static/plan9-4e/man2/getpid.2 b/static/plan9-4e/man2/getpid.2 new file mode 100644 index 00000000..1c49f3ab --- /dev/null +++ b/static/plan9-4e/man2/getpid.2 @@ -0,0 +1,41 @@ +.TH GETPID 2 +.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 /sys/src/libc/9sys +.SH SEE ALSO +.IR intro (2), +.IR cons (3), +.IR proc (3) +.SH DIAGNOSTICS +Returns 0 and +sets +.I errstr +if unsuccessful. diff --git a/static/plan9-4e/man2/getuser.2 b/static/plan9-4e/man2/getuser.2 new file mode 100644 index 00000000..7303fe24 --- /dev/null +++ b/static/plan9-4e/man2/getuser.2 @@ -0,0 +1,37 @@ +.TH GETUSER 2 +.SH NAME +getuser, sysname \- get user or system name +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* getuser(void) +.PP +.B +char* sysname(void) +.SH DESCRIPTION +.I Getuser +returns a pointer to static data which contains the +null-terminated +name of the user who +owns the current process. +.I Getuser +reads +.B /dev/user +to find the name. +.PP +.I Sysname +provides the same service for the file +.BR #c/sysname , +which contains the name of the machine. +Unlike +.IR getuser , +.I sysname +caches the string, reading the file only once. +.SH SOURCE +.B /sys/src/libc/port/getuser.c +.SH SEE ALSO +.IR intro (2), +.IR cons (3) diff --git a/static/plan9-4e/man2/getwd.2 b/static/plan9-4e/man2/getwd.2 new file mode 100644 index 00000000..ac99719e --- /dev/null +++ b/static/plan9-4e/man2/getwd.2 @@ -0,0 +1,37 @@ +.TH GETWD 2 +.SH NAME +getwd \- get current directory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char* getwd(char *buf, int size) +.SH DESCRIPTION +.I Getwd +fills +.I buf +with a null-terminated string representing the current directory +and returns +.IR buf . +.PP +.I Getwd +places no more than +.I size +bytes in the buffer provided. +.SH SOURCE +.B /sys/src/libc/9sys/getwd.c +.SH "SEE ALSO" +.IR pwd (1), +.IR fd2path (2) +.SH DIAGNOSTICS +On error, zero is returned. +.IR Errstr (2) +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/static/plan9-4e/man2/graphics.2 b/static/plan9-4e/man2/graphics.2 new file mode 100644 index 00000000..e318967f --- /dev/null +++ b/static/plan9-4e/man2/graphics.2 @@ -0,0 +1,632 @@ +.TH GRAPHICS 2 +.SH NAME +Display, Point, Rectangle, Cursor, initdraw, geninitdraw, drawerror, initdisplay, closedisplay, getdefont, getwindow, gengetwindow, flushimage, bufimage, lockdisplay, unlockdisplay, cursorswitch, cursorset, openfont, buildfont, freefont, Pfmt, Rfmt, strtochan, chantostr, chantodepth \- interactive graphics +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +#include +.ft P +.PP +.ta \w'\fLFont* 'u +.B +int initdraw(void (*errfun)(Display*, char*), char *font, +.B + char *label) +.PP +.B +int geninitdraw(char *devdir, void(*errfun)(Display*, char*), +.PP +.B + char *font, char *label, char *mousedir, char *windir, +.B + int ref) +.PP +.B +void drawerror(Display *d, char *msg) +.PP +.B +Display* initdisplay(char *devdir, char *win, void(*errfun)(Display*, char*)) +.PP +.B +void closedisplay(Display *d) +.PP +.B +Font* getdefont(Display *d) +.PP +.B +int flushimage(Display *d, int vis) +.PP +.B +int bufimage(Display *d, int n) +.PP +.B +int lockdisplay(Display *d) +.PP +.B +int unlockdisplay(Display *d) +.PP +.B +int getwindow(Display *d, int ref) +.PP +.B +int gengetwindow(Display *d, char *winname, +.br +.B + Image **ip, Screen **sp, int ref) +.PP +.B +void cursorswitch(Cursor *curs) +.PP +.B +void cursorset(Point p) +.PP +.B +Font* openfont(Display *d, char *name) +.PP +.B +Font* buildfont(Display *d, char *desc, char *name) +.PP +.B +void freefont(Font *f) +.PP +.B +int Pfmt(Fmt*) +.PP +.B +int Rfmt(Fmt*) +.PP +.B +ulong strtochan(char *s) +.PP +.B +char* chantostr(char *s, ulong chan) +.PP +.B +int chantodepth(ulong chan) +.PP +.B +extern Display *display +.PP +.B +extern Image *screen +.PP +.B +extern Screen *_screen +.PP +.B +extern Font *font +.fi +.SH DESCRIPTION +A +.B Display +structure represents a connection to the graphics device, +.IR draw (3), +holding all graphics resources associated with the connection, +including in particular raster image data in use by the client program. +The structure is defined (in part) as: +.IP +.EX +.ta 6n +10n +typedef +struct Display +{ + ... + ulong chan; + int depth; + void (*error)(Display*, char*); + ... + Image *black; + Image *white; + Image *opaque; + Image *transparent; + Image *image; + Font *defaultfont; + Subfont *defaultsubfont; + ... +}; +.EE +.PP +A +.B Point +is a location in an Image +(see below and +.IR draw (2)), +such as the display, and is defined as: +.IP +.EX +.ta 6n +typedef +struct Point { + int x; + int y; +} Point; +.EE +.PP +The coordinate system has +.I x +increasing to the right and +.I y +increasing down. +.PP +A +.B Rectangle +is a rectangular area in an image. +.IP +.EX +.ta 6n +typedef +struct Rectangle { + Point min; /* upper left */ + Point max; /* lower right */ +} Rectangle; +.EE +.PP +By definition, +.BR min.x ≤ max.x +and +.BR min.y ≤ max.y . +By convention, the right (maximum +.IR x ) +and bottom (maximum +.IR y ) +edges are +excluded from the represented rectangle, so abutting rectangles have no +points in common. +Thus, +.B max +contains the coordinates of the first point beyond the rectangle. +.PP +The +.B Image +data structure is defined in +.IR draw (2). +.PP +A +.B Font +is a set of character images, indexed by runes (see +.IR utf (6)). +The images are organized into +.BR Subfonts , +each containing the images for a small, contiguous set of runes. +The detailed format of these data structures, +which are described in detail in +.IR cachechars (2), +is immaterial for most applications. +.B Font +and +.B Subfont +structures contain two interrelated fields: +.LR ascent , +the distance from the top of the highest character +(actually the top of the image holding all the characters) +to the baseline, +and +.LR height , +the distance from the top of the highest character to the bottom of +the lowest character (and hence, the interline spacing). +See +.IR cachechars (2) +for more details. +.PP +.I Buildfont +parses the font description in the buffer +.BR desc , +returning a +.B Font* +pointer that can be used by +.B string +(see +.IR draw (2)) +to draw characters from the font. +.I Openfont +does the same, but reads the description +from the named file. +.I Freefont +frees a font. +The convention for naming font files is: +.IP +.B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font +.PD +.PP +where +.I size +is approximately the height in pixels of the lower case letters +(without ascenders or descenders). +.I Range +gives some indication of which characters will be available: for example +.BR ascii , +.BR latin1 , +.BR euro , +or +.BR unicode . +.B Euro +includes most European languages, punctuation marks, the International Phonetic +Alphabet, etc., but no Oriental languages. +.B Unicode +includes every character for which appropriate-sized images exist on the system. +.PP +A +.I Cursor +is defined: +.IP +.EX +.ta 6n +\w'Point 'u +typedef struct +Cursor { + Point offset; + uchar clr[2*16]; + uchar set[2*16]; +} Cursor; +.EE +.PP +The arrays are arranged in rows, two bytes per row, left to +right in big-endian order to give 16 rows +of 16 bits each. +A cursor is displayed on the screen by adding +.B offset +to the current mouse position, using +.B clr +as a mask to draw white at the pixels where +.B clr +is one, and then drawing black at the pixels where +.B set +is one. +.PP +The routine +.I initdraw +connects to the display; it returns \-1 if it fails and sets the error string. +.I Initdraw +sets up the global variables +.B display +(the +.B Display +structure representing the connection), +.B screen +(an +.B Image +representing the display memory itself or, if +.IR rio (1) +is running, the client's window), +and +.B font +(the default font for text). +The arguments to +.I initdraw +include a +.IR label , +which is written to +.B /dev/label +if non-nil +so that it can be used to identify the window when hidden (see +.IR rio (1)). +The font is created by reading the named +.I font +file. If +.B font +is null, +.I initdraw +reads the file named in the environment variable +.BR $font ; +if +.B $font +is not set, it imports the default (usually minimal) +font from the operating system. +The global +.I font +will be set to point to the resulting +.B Font +structure. +The +.I errfun +argument is a +.I graphics error function +to call in the event of a fatal error in the library; it must never return. +Its arguments are the +display pointer and an error string. +If +.I errfun +is nil, the library provides a default, called +.IR drawerror . +Another effect of +.I initdraw +is that it installs +.IR print (2) +formats +.I Pfmt +and +.I Rfmt +as +.L %P +and +.L %R +for printing +.B Points +and +.BR Rectangles . +.PP +The +.I geninitdraw +function provides a less automated way to establish a connection, for programs +that wish to connect to multiple displays. +.I Devdir +is the name of the directory containing the device files for the display +(if nil, default +.BR /dev ); +.IR errfun , +.IR font , +and +.I label +are as in +.IR initdraw ; +.I mousedir +and +.I windir +are the directories holding the +.B mouse +and +.B winname +files; and +.I ref +specifies the refresh function to be used to create the window, if running under +.IR rio (1) +(see +.IR window (2)). +.PP +.I Initdisplay +is part of +.IR geninitdraw ; +it sets up the display structures but does not allocate any fonts or call +.IR getwindow . +The arguments are similar to those of +.IR initdraw ; +.I win +names the directory, default +.BR /dev , +in which the files associated with the window reside. +.I Closedisplay +disconnects the display and frees the associated data structures. +.I Getdefont +builds a +.B Font +structure from in-core data describing a default font. +None of these routines is needed by most programs, since +.I initdraw +calls them as needed. +.PP +The data structures associated with the display must be protected in a multi-process program, +because they assume only one process will be using them at a time. +Multi-process programs should set +.B display->locking +to +.BR 1 , +to notify the library to use a locking protocol for its own accesses, +and call +.I lockdisplay +and +.I unlockdisplay +around any calls to the graphics library that will cause messages to be sent to the display device. +.I Initdraw +and +.I geninitdraw +initialize the display to the locked state. +.PP +.I Getwindow +returns a pointer to the window associated with the application; it is called +automatically by +.I initdraw +to establish the +.B screen +pointer but must be called after each resizing of the window to restore +the library's connection to the window. +If +.B rio +is not running, it returns +.BR display->image ; +otherwise it negotiates with +.B rio +by looking in +.B /dev/winname +to find the name of the window and opening it using +.B namedimage +(see +.IR allocimage (2)). +The resulting window will be created using the refresh method +.I ref +(see +.IR window (2)); +this should almost always be +.B Refnone +because +.B rio +provides backing store for the window. +.PP +.I Getwindow +overwrites the global variables +.BR screen , +a pointer to the +.B Image +defining the window (or the overall display, if no window system is running); and +.BR _screen , +a pointer to the +.B Screen +representing the root of the window's hierarchy. (See +.IR window (2). +The overloading of the +.B screen +word is an unfortunate historical accident.) +.I Getwindow +arranges that +.B screen +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. +.IR Gengetwindow 's +extra arguments are the full path of the window's +.B winname +file and pointers to be overwritten with the values of the `global' +.B Image +and +.B Screen +variables for the new window. +.PP +The mouse cursor is always displayed. +The initial cursor is an arrow. +.I Cursorswitch +causes the argument cursor to be displayed instead. +A zero argument causes a switch back to the arrow cursor. +.I Cursorset +moves the mouse cursor to position +.IR p , +provided (if in a window) that the requesting program is +executing in the current window and the mouse is within +the window boundaries; otherwise +.I cursorset +is a no-op. +.PP +The graphics functions described in +.IR draw (2), +.IR allocimage (2), +.IR cachechars (2), +and +.IR subfont (2) +are implemented by writing commands to files under +.B /dev/draw +(see +.IR draw (3)); +the writes are buffered, so the functions may not take effect immediately. +.I Flushimage +flushes the buffer, doing all pending graphics operations. +If +.I vis +is non-zero, any changes are also copied from the `soft screen' (if any) in the +driver to the visible frame buffer. +The various allocation routines in the library flush automatically, as does the event +package (see +.IR event (2)); +most programs do not need to call +.IR flushimage . +It returns \-1 on error. +.PP +.I Bufimage +is used to allocate space for +.I n +bytes in the display buffer. +It is used by all the graphics routines to send messages to the display. +.PP +The functions +.I strtochan +and +.I chantostr +convert between the channel descriptor strings +used by +.IR image (6) +and the internal +.B ulong +representation +used by the graphics protocol +(see +.IR draw (3)'s +.B b +message). +.B Chantostr +writes at most nine bytes into the buffer pointed at by +.I s +and returns +.I s +on success, +0 +on failure. +.B Chantodepth +returns the number of bits per pixel used by the +format specified by +.IR chan . +Both +.B chantodepth +and +.B strtochan +return 0 when presented +with bad input. +.SH EXAMPLES +To reconnect to the window after a resize event, +.IP +.EX +if(getwindow(display, Refnone) < 0) + sysfatal("resize failed: %r"); +.EE +.PP +To create and set up a new +.IR rio (1) +window, +.IP +.EX +Image *screen2; +Screen *_screen2; + +srvwsys = getenv("wsys"); +if(srvwsys == nil) + sysfatal("can't find $wsys: %r"); +rfork(RFNAMEG); /* keep mount of rio private */ + +fd = open(srvwsys, ORDWR); +if(fd < 0) + sysfatal("can't open $wsys: %r"); + +/* mount creates window; see \f2rio\fP(4) */ +if(mount(fd, "/tmp", MREPL, "new -dx 300-dy 200") < 0) + sysfatal("can't mount new window: %r"); +if(gengetwindow(display, "/tmp/winname", + &screen2, &_screen2, Refnone) < 0) + sysfatal("resize failed: %r"); + +/* now open /tmp/cons, /tmp/mouse */ +\&... +.EE +.SH FILES +.BR /lib/font/bit " directory of fonts +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR rio (1), +.IR addpt (2), +.IR allocimage (2), +.IR cachechars (2), +.IR subfont (2), +.IR draw (2), +.IR event (2), +.IR frame (2), +.IR print (2), +.IR window (2), +.IR draw (3), +.IR rio (4), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +An error function may call +.IR errstr (2) +for further diagnostics. +.SH BUGS +The names +.B clr +and +.B set +in the +.B Cursor +structure are reminders of an archaic color map +and might be more appropriately called +.B white +and +.BR black . diff --git a/static/plan9-4e/man2/html.2 b/static/plan9-4e/man2/html.2 new file mode 100644 index 00000000..ef641e41 --- /dev/null +++ b/static/plan9-4e/man2/html.2 @@ -0,0 +1,1420 @@ +.TH HTML 2 +.SH NAME +parsehtml, +printitems, +validitems, +freeitems, +freedocinfo, +dimenkind, +dimenspec, +targetid, +targetname, +fromStr, +toStr +\- HTML parser +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.ft P +.PP +.ta \w'\fLToken* 'u +.B +Item* parsehtml(uchar* data, int datalen, Rune* src, int mtype, +.B + int chset, Docinfo** pdi) +.PP +.B +void printitems(Item* items, char* msg) +.PP +.B +int validitems(Item* items) +.PP +.B +void freeitems(Item* items) +.PP +.B +void freedocinfo(Docinfo* d) +.PP +.B +int dimenkind(Dimen d) +.PP +.B +int dimenspec(Dimen d) +.PP +.B +int targetid(Rune* s) +.PP +.B +Rune* targetname(int targid) +.PP +.B +uchar* fromStr(Rune* buf, int n, int chset) +.PP +.B +Rune* toStr(uchar* buf, int n, int chset) +.SH DESCRIPTION +.PP +This library implements a parser for HTML 4.0 documents. +The parsed HTML is converted into an intermediate representation that +describes how the formatted HTML should be laid out. +.PP +.I Parsehtml +parses an entire HTML document contained in the buffer +.I data +and having length +.IR datalen . +The URL of the document should be passed in as +.IR src . +.I Mtype +is the media type of the document, which should be either +.B TextHtml +or +.BR TextPlain . +The character set of the document is described in +.IR chset , +which can be one of +.BR US_Ascii , +.BR ISO_8859_1 , +.B UTF_8 +or +.BR Unicode . +The return value is a linked list of +.B Item +structures, described in detail below. +As a side effect, +.BI * pdi +is set to point to a newly created +.B Docinfo +structure, containing information pertaining to the entire document. +.PP +The library expects two allocation routines to be provided by the +caller, +.B emalloc +and +.BR erealloc . +These routines are analogous to the standard malloc and realloc routines, +except that they should not return if the memory allocation fails. +In addition, +.B emalloc +is required to zero the memory. +.PP +For debugging purposes, +.I printitems +may be called to display the contents of an item list; individual items may +be printed using the +.B %I +print verb, installed on the first call to +.IR parsehtml . +.I validitems +traverses the item list, checking that all of the pointers are valid. +It returns +.B 1 +is everything is ok, and +.B 0 +if an error was found. +Normally, one would not call these routines directly. +Instead, one sets the global variable +.I dbgbuild +and the library calls them automatically. +One can also set +.IR warn , +to cause the library to print a warning whenever it finds a problem with the +input document, and +.IR dbglex , +to print debugging information in the lexer. +.PP +When an item list is finished with, it should be freed with +.IR freeitems . +Then, +.I freedocinfo +should be called on the pointer returned in +.BI * pdi\f1. +.PP +.I Dimenkind +and +.I dimenspec +are provided to interpret the +.B Dimen +type, as described in the section +.IR "Dimension Specifications" . +.PP +Frame target names are mapped to integer ids via a global, permanent mapping. +To find the value for a given name, call +.IR targetid , +which allocates a new id if the name hasn't been seen before. +The name of a given, known id may be retrieved using +.IR targetname . +The library predefines +.BR FTtop , +.BR FTself , +.B FTparent +and +.BR FTblank . +.PP +The library handles all text as Unicode strings (type +.BR Rune* ). +Character set conversion is provided by +.I fromStr +and +.IR toStr . +.I FromStr +takes +.I n +Unicode characters from +.I buf +and converts them to the character set described by +.IR chset . +.I ToStr +takes +.I n +bytes from +.IR buf , +interpretted as belonging to character set +.IR chset , +and converts them to a Unicode string. +Both routines null-terminate the result, and use +.B emalloc +to allocate space for it. +.SS Items +The return value of +.I parsehtml +is a linked list of variant structures, +with the generic portion described by the following definition: +.PP +.EX +.ta 6n +\w'Genattr* 'u +typedef struct Item Item; +struct Item +{ + Item* next; + int width; + int height; + int ascent; + int anchorid; + int state; + Genattr* genattr; + int tag; +}; +.EE +.PP +The field +.B next +points to the successor in the linked list of items, while +.BR width , +.BR height , +and +.B ascent +are intended for use by the caller as part of the layout process. +.BR Anchorid , +if non-zero, gives the integer id assigned by the parser to the anchor that +this item is in (see section +.IR Anchors ). +.B State +is a collection of flags and values described as follows: +.PP +.EX +.ta 6n +\w'IFindentshift = 'u +enum +{ + IFbrk = 0x80000000, + IFbrksp = 0x40000000, + IFnobrk = 0x20000000, + IFcleft = 0x10000000, + IFcright = 0x08000000, + IFwrap = 0x04000000, + IFhang = 0x02000000, + IFrjust = 0x01000000, + IFcjust = 0x00800000, + IFsmap = 0x00400000, + IFindentshift = 8, + IFindentmask = (255< +element. +.B Background +is as described in the section +.IR "Background Specifications" , +and +.B backgrounditem +is set to be an image item for the document's background image (if given as a URL), +or else nil. +.B Text +gives the default foregound text color of the document, +.B link +the unvisited hyperlink color, +.B vlink +the visited hyperlink color, and +.B alink +the color for highlighting hyperlinks (all in 24-bit RGB format). +.B Target +is the default target frame id. +.B Chset +and +.B mediatype +are as for the +.I chset +and +.I mtype +parameters to +.IR parsehtml . +.B Scripttype +is the type of any scripts contained in the document, and is always +.BR TextJavascript . +.B Hasscripts +is set if the document contains any scripts. +Scripting is currently unsupported. +.B Refresh +is the contents of a +.B "" +tag, if any. +.B Kidinfo +is set if this document is a frameset (see section +.IR Frames ). +.B Frameid +is this document's frame id. +.PP +.B Anchors +is a list of hyperlinks contained in the document, +and +.B dests +is a list of hyperlink destinations within the page (see the following section for details). +.BR Forms , +.B tables +and +.B maps +are lists of the various forms, tables and client-side maps contained +in the document, as described in subsequent sections. +.B Images +is a list of all the image items in the document. +.SS Anchors +.PP +The library builds two lists for all of the +.B +elements (anchors) in a document. +Each anchor is assigned a unique anchor id within the document. +For anchors which are hyperlinks (the +.B href +attribute was supplied), the following structure is defined: +.PP +.EX +.ta 6n +\w'Anchor* 'u +typedef struct Anchor Anchor; +struct Anchor +{ + Anchor* next; + int index; + Rune* name; + Rune* href; + int target; +}; +.EE +.PP +.B Next +points to the next anchor in the list (the head of this list is +.BR Docinfo.anchors ). +.B Index +is the anchor id; each item within this hyperlink is tagged with this value +in its +.B anchorid +field. +.B Name +and +.B href +are the values of the correspondingly named attributes of the anchor +(in particular, href is the URL to go to). +.B Target +is the value of the target attribute (if provided) converted to a frame id. +.PP +Destinations within the document (anchors with the name attribute set) +are held in the +.B Docinfo.dests +list, using the following structure: +.PP +.EX +.ta 6n +\w'DestAnchor* 'u +typedef struct DestAnchor DestAnchor; +struct DestAnchor +{ + DestAnchor* next; + int index; + Rune* name; + Item* item; +}; +.EE +.PP +.B Next +is the next element of the list, +.B index +is the anchor id, +.B name +is the value of the name attribute, and +.B item +is points to the item within the parsed document that should be considered +to be the destination. +.SS Forms +.PP +Any forms within a document are kept in a list, headed by +.BR Docinfo.forms . +The elements of this list are as follows: +.PP +.EX +.ta 6n +\w'Formfield* 'u +typedef struct Form Form; +struct Form +{ + Form* next; + int formid; + Rune* name; + Rune* action; + int target; + int method; + int nfields; + Formfield* fields; +}; +.EE +.PP +.B Next +points to the next form in the list. +.B Formid +is a serial number for the form within the document. +.B Name +is the value of the form's name or id attribute. +.B Action +is the value of any action attribute. +.B Target +is the value of the target attribute (if any) converted to a frame target id. +.B Method +is one of +.B HGet +or +.BR HPost . +.B Nfields +is the number of fields in the form, and +.B fields +is a linked list of the actual fields. +.PP +The individual fields in a form are described by the following structure: +.PP +.EX +.ta 6n +\w'Formfield* 'u +typedef struct Formfield Formfield; +struct Formfield +{ + Formfield* next; + int ftype; + int fieldid; + Form* form; + Rune* name; + Rune* value; + int size; + int maxlength; + int rows; + int cols; + uchar flags; + Option* options; + Item* image; + int ctlid; + SEvent* events; +}; +.EE +.PP +Here, +.B next +points to the next field in the list. +.B Ftype +is the type of the field, which can be one of +.BR Ftext , +.BR Fpassword , +.BR Fcheckbox , +.BR Fradio , +.BR Fsubmit , +.BR Fhidden , +.BR Fimage , +.BR Freset , +.BR Ffile , +.BR Fbutton , +.B Fselect +or +.BR Ftextarea . +.B Fieldid +is a serial number for the field within the form. +.B Form +points back to the form containing this field. +.BR Name , +.BR value , +.BR size , +.BR maxlength , +.B rows +and +.B cols +each contain the values of corresponding attributes of the field, if present. +.B Flags +contains per-field flags, of which +.B FFchecked +and +.B FFmultiple +are defined. +.B Image +is only used for fields of type +.BR Fimage ; +it points to an image item containing the image to be displayed. +.B Ctlid +is reserved for use by the caller, typically to store a unique id +of an associated control used to implement the field. +.B Events +is the same as the corresponding field of the generic attributes +associated with the item containing this field. +.B Options +is only used by fields of type +.BR Fselect ; +it consists of a list of possible options that may be selected for that +field, using the following structure: +.PP +.EX +.ta 6n +\w'Option* 'u +typedef struct Option Option; +struct Option +{ + Option* next; + int selected; + Rune* value; + Rune* display; +}; +.EE +.PP +.B Next +points to the next element of the list. +.B Selected +is set if this option is to be displayed initially. +.B Value +is the value to send when the form is submitted if this option is selected. +.B Display +is the string to display on the screen for this option. +.SS Tables +.PP +The library builds a list of all the tables in the document, +headed by +.BR Docinfo.tables . +Each element of this list has the following format: +.PP +.EX +.ta 6n +\w'Tablecell*** 'u +typedef struct Table Table; +struct Table +{ + Table* next; + int tableid; + Tablerow* rows; + int nrow; + Tablecol* cols; + int ncol; + Tablecell* cells; + int ncell; + Tablecell*** grid; + Align align; + Dimen width; + int border; + int cellspacing; + int cellpadding; + Background background; + Item* caption; + uchar caption_place; + Lay* caption_lay; + int totw; + int toth; + int caph; + int availw; + Token* tabletok; + uchar flags; +}; +.EE +.PP +.B Next +points to the next element in the list of tables. +.B Tableid +is a serial number for the table within the document. +.B Rows +is an array of row specifications (described below) and +.B nrow +is the number of elements in this array. +Similarly, +.B cols +is an array of column specifications, and +.B ncol +the size of this array. +.B Cells +is a list of all cells within the table (structure described below) +and +.B ncell +is the number of elements in this list. +Note that a cell may span multiple rows and/or columns, thus +.B ncell +may be smaller than +.BR nrow*ncol . +.B Grid +is a two-dimensional array of cells within the table; the cell +at row +.B i +and column +.B j +is +.BR Table.grid[i][j] . +A cell that spans multiple rows and/or columns will +be referenced by +.B grid +multiple times, however it will only occur once in +.BR cells . +.B Align +gives the alignment specification for the entire table, +and +.B width +gives the requested width as a dimension specification. +.BR Border , +.B cellspacing +and +.B cellpadding +give the values of the corresponding attributes for the table, +and +.B background +gives the requested background for the table. +.B Caption +is a linked list of items to be displayed as the caption of the +table, either above or below depending on whether +.B caption_place +is +.B ALtop +or +.BR ALbottom . +Most of the remaining fields are reserved for use by the caller, +except +.BR tabletok , +which is reserved for internal use. +The type +.B Lay +is not defined by the library; the caller can provide its +own definition. +.PP +The +.B Tablecol +structure is defined for use by the caller. +The library ensures that the correct number of these +is allocated, but leaves them blank. +The fields are as follows: +.PP +.EX +.ta 6n +\w'Point 'u +typedef struct Tablecol Tablecol; +struct Tablecol +{ + int width; + Align align; + Point pos; +}; +.EE +.PP +The rows in the table are specified as follows: +.PP +.EX +.ta 6n +\w'Background 'u +typedef struct Tablerow Tablerow; +struct Tablerow +{ + Tablerow* next; + Tablecell* cells; + int height; + int ascent; + Align align; + Background background; + Point pos; + uchar flags; +}; +.EE +.PP +.B Next +is only used during parsing; it should be ignored by the caller. +.B Cells +provides a list of all the cells in a row, linked through their +.B nextinrow +fields (see below). +.BR Height , +.B ascent +and +.B pos +are reserved for use by the caller. +.B Align +is the alignment specification for the row, and +.B background +is the background to use, if specified. +.B Flags +is used by the parser; ignore this field. +.PP +The individual cells of the table are described as follows: +.PP +.EX +.ta 6n +\w'Background 'u +typedef struct Tablecell Tablecell; +struct Tablecell +{ + Tablecell* next; + Tablecell* nextinrow; + int cellid; + Item* content; + Lay* lay; + int rowspan; + int colspan; + Align align; + uchar flags; + Dimen wspec; + int hspec; + Background background; + int minw; + int maxw; + int ascent; + int row; + int col; + Point pos; +}; +.EE +.PP +.B Next +is used to link together the list of all cells within a table +.RB ( Table.cells ), +whereas +.B nextinrow +is used to link together all the cells within a single row +.RB ( Tablerow.cells ). +.B Cellid +provides a serial number for the cell within the table. +.B Content +is a linked list of the items to be laid out within the cell. +.B Lay +is reserved for the user to describe how these items have +been laid out. +.B Rowspan +and +.B colspan +are the number of rows and columns spanned by this cell, +respectively. +.B Align +is the alignment specification for the cell. +.B Flags +is some combination of +.BR TFparsing , +.B TFnowrap +and +.B TFisth +or'd together. +Here +.B TFparsing +is used internally by the parser, and should be ignored. +.B TFnowrap +means that the contents of the cell should not be +wrapped if they don't fit the available width, +rather, the table should be expanded if need be +(this is set when the nowrap attribute is supplied). +.B TFisth +means that the cell was created by the +.B +element (rather than the +.B +element), +indicating that it is a header cell rather than a data cell. +.B Wspec +provides a suggested width as a dimension specification, +and +.B hspec +provides a suggested height in pixels. +.B Background +gives a background specification for the individual cell. +.BR Minw , +.BR maxw , +.B ascent +and +.B pos +are reserved for use by the caller during layout. +.B Row +and +.B col +give the indices of the row and column of the top left-hand +corner of the cell within the table grid. +.SS Client-side Maps +.PP +The library builds a list of client-side maps, headed by +.BR Docinfo.maps , +and having the following structure: +.PP +.EX +.ta 6n +\w'Rune* 'u +typedef struct Map Map; +struct Map +{ + Map* next; + Rune* name; + Area* areas; +}; +.EE +.PP +.B Next +points to the next element in the list, +.B name +is the name of the map (use to bind it to an image), and +.B areas +is a list of the areas within the image that comprise the map, +using the following structure: +.PP +.EX +.ta 6n +\w'Dimen* 'u +typedef struct Area Area; +struct Area +{ + Area* next; + int shape; + Rune* href; + int target; + Dimen* coords; + int ncoords; +}; +.EE +.PP +.B Next +points to the next element in the map's list of areas. +.B Shape +describes the shape of the area, and is one of +.BR SHrect , +.B SHcircle +or +.BR SHpoly . +.B Href +is the URL associated with this area in its role as +a hypertext link, and +.B target +is the target frame it should be loaded in. +.B Coords +is an array of coordinates for the shape, and +.B ncoords +is the size of this array (number of elements). +.SS Frames +.PP +If the +.B Docinfo.kidinfo +field is set, the document is a frameset. +In this case, it is typical for +.I parsehtml +to return nil, as a document which is a frameset should have no actual +items that need to be laid out (such will appear only in subsidiary documents). +It is possible that items will be returned by a malformed document; the caller +should check for this and free any such items. +.PP +The +.B Kidinfo +structure itself reflects the fact that framesets can be nested within a document. +If is defined as follows: +.PP +.EX +.ta 6n +\w'Kidinfo* 'u +typedef struct Kidinfo Kidinfo; +struct Kidinfo +{ + Kidinfo* next; + int isframeset; + + // fields for "frame" + Rune* src; + Rune* name; + int marginw; + int marginh; + int framebd; + int flags; + + // fields for "frameset" + Dimen* rows; + int nrows; + Dimen* cols; + int ncols; + Kidinfo* kidinfos; + Kidinfo* nextframeset; +}; +.EE +.PP +.B Next +is only used if this structure is part of a containing frameset; it points to the next +element in the list of children of that frameset. +.B Isframeset +is set when this structure represents a frameset; if clear, it is an individual frame. +.PP +Some fields are used only for framesets. +.B Rows +is an array of dimension specifications for rows in the frameset, and +.B nrows +is the length of this array. +.B Cols +is the corresponding array for columns, of length +.BR ncols . +.B Kidinfos +points to a list of components contained within this frameset, each +of which may be a frameset or a frame. +.B Nextframeset +is only used during parsing, and should be ignored. +.PP +The remaining fields are used if the structure describes a frame, not a frameset. +.B Src +provides the URL for the document that should be initially loaded into this frame. +Note that this may be a relative URL, in which case it should be interpretted +using the containing document's URL as the base. +.B Name +gives the name of the frame, typically supplied via a name attribute in the HTML. +If no name was given, the library allocates one. +.BR Marginw , +.B marginh +and +.B framebd +are the values of the marginwidth, marginheight and frameborder attributes, respectively. +.B Flags +can contain some combination of the following: +.B FRnoresize +(the frame had the noresize attribute set, and the user should not be allowed to resize it), +.B FRnoscroll +(the frame should not have any scroll bars), +.B FRhscroll +(the frame should have a horizontal scroll bar), +.B FRvscroll +(the frame should have a vertical scroll bar), +.B FRhscrollauto +(the frame should be automatically given a horizontal scroll bar if its contents +would not otherwise fit), and +.B FRvscrollauto +(the frame gets a vertical scrollbar only if required). +.SH SOURCE +.B /sys/src/libhtml +.SH SEE ALSO +.IR fmt (1) +.PP +W3C World Wide Web Consortium, +``HTML 4.01 Specification''. +.SH BUGS +The entire HTML document must be loaded into memory before +any of it can be parsed. diff --git a/static/plan9-4e/man2/httpd.2 b/static/plan9-4e/man2/httpd.2 new file mode 100644 index 00000000..d39ca58e --- /dev/null +++ b/static/plan9-4e/man2/httpd.2 @@ -0,0 +1,307 @@ +.TH HTTPD 2 +.SH NAME +HConnect, +HContent, +HContents, +HETag, +HFields, +Hio, +Htmlesc, +HttpHead, +HttpReq, +HRange, +HSPairs, +hmydomain, +hversion, +htmlesc, +halloc, +hbodypush, +hbuflen, +hcheckcontent, +hclose, +hdate2sec, +hdatefmt, +hfail, +hflush, +hgetc, +hgethead, +hinit, +hiserror, +hload, +hlower, +hmkcontent, +hmkhfields, +hmkmimeboundary, +hmkspairs, +hmoved, +hokheaders, +hparseheaders, +hparsequery, +hparsereq, +hprint, +hputc, +hreadbuf, +hredirected, +hreqcleanup, +hrevhfields, +hrevspairs, +hstrdup, +http11, +httpfmt, +httpunesc, +hunallowed, +hungetc, +hunload, +hurlfmt, +hurlunesc, +hwrite, +hxferenc, + \- routines for creating an http server +.SH SYNOPSIS +.nf +.B #include +.nf +.B #include +.B #include +.B #include +.PP +.ft L +typedef struct HConnect HConnect; +typedef struct HContent HContent; +typedef struct HContents HContents; +typedef struct HETag HETag; +typedef struct HFields HFields; +typedef struct Hio Hio; +typedef struct Htmlesc Htmlesc; +typedef struct HttpHead HttpHead; +typedef struct HttpReq HttpReq; +typedef struct HRange HRange; +typedef struct HSPairs HSPairs; + +typedef struct Bin Bin; +.ta \w'\fLHContents 'u +\w'\fLHContentsxx 'u +\w'\fLheader[HBufSize + 2]; 'u + +struct Htmlesc +{ + char *name; + Rune value; +}; + +struct HContent +{ + HContent *next; + char *generic; + char *specific; + float q; /* desirability of this kind of file */ + int mxb; /* max uchars until worthless */ +}; + +struct HContents +{ + HContent *type; + HContent *encoding; +}; + +/* + * generic http header with a list of tokens, + * each with an optional list of parameters + */ +struct HFields +{ + char *s; + HSPairs *params; + HFields *next; +}; + +/* + * list of pairs a strings + * used for tag=val pairs for a search or form submission, + * and attribute=value pairs in headers. + */ +struct HSPairs +{ + char *s; + char *t; + HSPairs *next; +}; + +/* + * byte ranges within a file + */ +struct HRange +{ + int suffix; /* is this a suffix request? */ + ulong start; + ulong stop; /* ~0UL -> not given */ + HRange *next; +}; + +/* + * list of http/1.1 entity tags + */ +struct HETag +{ + char *etag; + int weak; + HETag *next; +}; + +/* + * HTTP custom IO + * supports chunked transfer encoding + * and initialization of the input buffer from a string. + */ +enum +{ + Hnone, + Hread, + Hend, + Hwrite, + Herr, + + Hsize = HBufSize +}; + +struct Hio { + Hio *hh; /* next lower layer Hio, or nil if reads from fd */ + int fd; /* associated file descriptor */ + ulong seek; /* of start */ + uchar state; /* state of the file */ + uchar xferenc; /* chunked transfer encoding state */ + uchar *pos; /* current position in the buffer */ + uchar *stop; /* last character active in the buffer */ + uchar *start; /* start of data buffer */ + ulong bodylen; /* remaining length of message body */ + uchar buf[Hsize+32]; +}; + +/* + * request line + */ +struct HttpReq +{ + char *meth; + char *uri; + char *urihost; + char *search; + int vermaj; + int vermin; +}; + +/* + * header lines + */ +struct HttpHead +{ + int closeit; /* http1.1 close connection after this request? */ + uchar persist; /* http/1.1 requests a persistent connection */ + + uchar expectcont; /* expect a 100-continue */ + uchar expectother; /* expect anything else; should reject with ExpectFail */ + ulong contlen; /* if != ~0UL, length of included message body */ + HFields *transenc; /* if present, encoding of included message body */ + char *client; + char *host; + HContent *okencode; + HContent *oklang; + HContent *oktype; + HContent *okchar; + ulong ifmodsince; + ulong ifunmodsince; + ulong ifrangedate; + HETag *ifmatch; + HETag *ifnomatch; + HETag *ifrangeetag; + HRange *range; + char *authuser; /* authorization info */ + char *authpass; + + /* + * experimental headers + */ + int fresh_thresh; + int fresh_have; +}; + +/* + * all of the state for a particular connection + */ +struct HConnect +{ + void *private; /* for the library clients */ + void (*replog)(HConnect*, char*, ...); /* called when reply sent */ + + HttpReq req; + HttpHead head; + + Bin *bin; + + ulong reqtime; /* time at start of request */ + char xferbuf[HBufSize]; /* buffer for making up or transferring data */ + uchar header[HBufSize + 2]; /* room for \\n\\0 */ + uchar *hpos; + uchar *hstop; + Hio hin; + Hio hout; +}; + +/* + * configuration for all connections within the server + */ +extern char *hmydomain; +extern char *hversion; +extern Htmlesc htmlesc[]; + +void *halloc(HConnect *c, ulong size); +Hio *hbodypush(Hio *hh, ulong len, HFields *te); +int hbuflen(Hio *h, void *p); +int hcheckcontent(HContent*, HContent*, char*, int); +void hclose(Hio*); +ulong hdate2sec(char*); +int hdatefmt(Fmt*); +int hfail(HConnect*, int, ...); +int hflush(Hio*); +int hgetc(Hio*); +int hgethead(HConnect *c, int many); +int hinit(Hio*, int, int); +int hiserror(Hio *h); +int hload(Hio*, char*); +char *hlower(char*); +HContent *hmkcontent(HConnect *c, char *generic, char *specific, HContent *next); +HFields *hmkhfields(HConnect *c, char *s, HSPairs *p, HFields *next); +char *hmkmimeboundary(HConnect *c); +HSPairs *hmkspairs(HConnect *c, char *s, char *t, HSPairs *next); +int hmoved(HConnect *c, char *uri); +void hokheaders(HConnect *c); +int hparseheaders(HConnect*, int timeout); +HSPairs *hparsequery(HConnect *c, char *search); +int hparsereq(HConnect *c, int timeout); +int hprint(Hio*, char*, ...); +int hputc(Hio*, int); +void *hreadbuf(Hio *h, void *vsave); +int hredirected(HConnect *c, char *how, char *uri); +void hreqcleanup(HConnect *c); +HFields *hrevhfields(HFields *hf); +HSPairs *hrevspairs(HSPairs *sp); +char *hstrdup(HConnect *c, char *s); +int http11(HConnect*); +int httpfmt(Fmt*); +char *httpunesc(HConnect *c, char *s); +int hunallowed(HConnect *, char *allowed); +int hungetc(Hio *h); +char *hunload(Hio*); +int hurlfmt(Fmt*); +char *hurlunesc(HConnect *c, char *s); +int hwrite(Hio*, void*, int); +int hxferenc(Hio*, int); +.ft R +.SH DESCRIPTION +For now, look at the source, or +.IR httpd (8). +.SH SOURCE +.B /sys/src/libhttpd +.SH SEE ALSO +.IR bin (2) +.SH BUGS +This is a rough implementation and many details are going to change. + diff --git a/static/plan9-4e/man2/hypot.2 b/static/plan9-4e/man2/hypot.2 new file mode 100644 index 00000000..dc25ed2d --- /dev/null +++ b/static/plan9-4e/man2/hypot.2 @@ -0,0 +1,21 @@ +.TH HYPOT 2 +.SH NAME +hypot \- Euclidean distance +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +double hypot(double x, double y) +.fi +.SH DESCRIPTION +.I Hypot +returns +.EX + sqrt(x*x + y*y) +.EE +taking precautions against unwarranted overflows. +.SH SOURCE +.B /sys/src/libc/port/hypot.c diff --git a/static/plan9-4e/man2/intmap.2 b/static/plan9-4e/man2/intmap.2 new file mode 100644 index 00000000..22dec998 --- /dev/null +++ b/static/plan9-4e/man2/intmap.2 @@ -0,0 +1,126 @@ +.TH INTMAP 2 +.SH NAME +Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, +deletekey \- integer to data structure maps +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLIntmap* 'u +Intmap* allocmap(void (*inc)(void*)) +void freemap(Intmap *map, void (*dec)(void*)) +void* lookupkey(Intmap *map, ulong key) +void* insertkey(Intmap *map, ulong key, void *val) +int caninsertkey(Intmap *map, ulong key, void *val) +void* lookupkey(Intmap *map, ulong key) +void* deletekey(Intmap *map, ulong key) +.fi +.SH DESCRIPTION +An +.B Intmap +is an arbitrary mapping from integers to pointers. +.I Allocmap +creates a new map, and +.I freemap +destroys it. +The +.I inc +function is called each time a new pointer is added +to the map; similarly, +.I dec +is called on each pointer left in the map +when it is being freed. +Typically these functions maintain reference counts. +New entries are added to the map by calling +.IR insertkey , +which will return the previous value +associated with the given +.IR key , +or zero if there was no previous value. +.I Caninsertkey +is like +.I insertkey +but only inserts +.I val +if there is no current mapping. +It returns 1 if +.I val +was inserted, 0 otherwise. +.I Lookupkey +returns the pointer associated with +.IR key , +or zero if there is no such pointer. +.I Deletekey +removes the entry for +.I id +from the map, returning the +associated pointer, if any. +.PP +Concurrent access to +.BR Intmap s +is safe, +moderated via a +.B QLock +stored in the +.B Intmap +structure. +.PP +In anticipation of the storage of reference-counted +structures, an increment function +.I inc +may be specified +at map creation time. +.I Lookupkey +calls +.I inc +(if non-zero) +on pointers before returning them. +If the reference count adjustments were +left to the caller (and thus not protected by the lock), +it would be possible to accidentally reclaim a structure +if, for example, it was deleted from the map and its +reference count decremented between the return +of +.I insertkey +and the external increment. +.IR Insertkey +and +.IR caninsertkey +do +.I not +call +.I inc +when inserting +.I val +into the map, nor do +.I insertkey +or +.I deletekey +call +.I inc +when returning old map entries. +The rationale is that calling +an insertion function transfers responsibility for the reference +to the map, and responsibility is given back via the return value of +.I deletekey +or the next +.IR insertkey . +.PP +.BR Intmap s +are used by the 9P library to implement +.BR Fidpool s +and +.BR Reqpool s. +.SH SOURCE +.B /sys/src/lib9p/intmap.c +.SH SEE ALSO +.IR 9p (2), +.IR 9pfid (2). diff --git a/static/plan9-4e/man2/iounit.2 b/static/plan9-4e/man2/iounit.2 new file mode 100644 index 00000000..a31d7079 --- /dev/null +++ b/static/plan9-4e/man2/iounit.2 @@ -0,0 +1,37 @@ +.TH IOUNIT 2 +.SH NAME +iounit \- return size of atomic I/O unit for file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int iounit(int fd) +.SH DESCRIPTION +Reads and writes of files are transmitted using the 9P protocol (see +.IR intro (5)) +and in general, operations involving large amounts of data must be +broken into smaller pieces by the operating system. +The `I/O unit' associated with each file descriptor records the maximum +size, in bytes, that may be read or written without breaking up the transfer. +.PP +The +.I iounit +routine uses the +.IR dup (3) +interface to discover the I/O unit size for the file descriptor +.I fd +and returns its value. +Certain file descriptors, particularly those associated with devices, may +have no specific I/O unit, in which case +.I iounit +will return +.BR 0 . +.SH SOURCE +.B /sys/src/libc/9sys +.SH SEE ALSO +.IR dup (3), +.IR read (5) +.SH DIAGNOSTICS +Returns zero if any error occurs or if the I/O unit size of the fd is unspecified or unknown. diff --git a/static/plan9-4e/man2/ip.2 b/static/plan9-4e/man2/ip.2 new file mode 100644 index 00000000..dc4c86fd --- /dev/null +++ b/static/plan9-4e/man2/ip.2 @@ -0,0 +1,335 @@ +.TH IP 2 +.SH NAME +eipfmt, parseip, parseipmask, v4parseip, v4parsecidr, parseether, myipaddr, myetheraddr, maskip, equivip, defmask, isv4, v4tov6, v6tov4, nhgetl, nhgets, hnputl, hnputs, ptclbsum, readipifc \- Internet protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int eipfmt(Fmt*) +.PP +.B +ulong parseip(uchar *ipaddr, char *str) +.PP +.B +ulong parseipmask(uchar *ipaddr, char *str) +.PP +.B +char* v4parseip(uchar *ipaddr, char *str) +.PP +.B +ulong v4parsecidr(uchar *addr, uchar *mask, char *str) +.PP +.B +int parseether(uchar *eaddr, char *str) +.PP +.B +int myetheraddr(uchar *eaddr, char *dev) +.PP +.B +int myipaddr(uchar *ipaddr, char *net) +.PP +.B +void maskip(uchar *from, uchar *mask, uchar *to) +.PP +.B +int equivip(uchar *ipaddr1, uchar *ipaddr2) +.PP +.B +uchar* defmask(uchar *ipaddr) +.PP +.B +int isv4(uchar *ipaddr) +.PP +.B +void v4tov6(uchar *ipv6, uchar *ipv4) +.PP +.B +void v6tov4(uchar *ipv4, uchar *ipv6) +.PP +.B +ushort nhgets(void *p) +.PP +.B +uint nhgetl(void *p) +.PP +.B +void hnputs(void *p, ushort v) +.PP +.B +void hnputl(void *p, uint v) +.PP +.B +ushort ptclbsum(uchar *a, int n) +.PP +.B +Ipifc* readipifc(char *net, Ipifc *ifc, int index) +.PP +.B +uchar IPv4bcast[IPaddrlen]; +.PP +.B +uchar IPv4allsys[IPaddrlen]; +.PP +.B +uchar IPv4allrouter[IPaddrlen]; +.PP +.B +uchar IPallbits[IPaddrlen]; +.PP +.B +uchar IPnoaddr[IPaddrlen]; +.PP +.B +uchar v4prefix[IPaddrlen]; +.SH DESCRIPTION +These routines are used by Internet Protocol (IP) programs to +manipulate IP and Ethernet addresses. +Plan 9, by default, uses V6 format IP addresses. Since V4 +addresses fit into the V6 space, all IP addresses can be represented. +IP addresses are stored as a string of 16 +.B unsigned +.BR chars , +Ethernet +addresses as 6 +.B unsigned +.BR chars . +Either V4 or V6 string representation can be used for IP addresses. +For V4 addresses, the representation can be (up to) 4 decimal +integers from 0 to 255 separated by periods. +For V6 addresses, the representation is (up to) 8 hex integers +from 0x0 to 0xFFFF separated by colons. +Strings of 0 integers can be elided using two colons. +For example, +.B FFFF::1111 +is equivalent to +.BR FFFF:0:0:0:0:0:0:1111 . +The string representation for IP masks is a superset of the +address representation. It includes slash notation that indicates +the number of leading 1 bits in the mask. Thus, a +V4 class C mask can be represented as +.BR FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00 , +.BR 255.255.255.0 , +or +.BR /120. +The string representation of Ethernet addresses is exactly +12 hexadecimal digits. +.PP +.I Eipfmt +is a +.IR print (2) +formatter for Ethernet (verb +.BR E ) +addresses, +IP V6 (verb +.BR I ) +addresses, +IP V4 (verb +.BR V ) +addresses, +and IP V6 (verb +.BR M ) +masks. +.PP +.I Parseip +converts a string pointed to by +.I str +to a 16-byte IP address starting at +.IR ipaddr . +As a concession to backwards compatibility, +if the string is a V4 address, the return value +is an unsigned long integer containing the big-endian V4 address. +If not, the return value is 6. +.I Parseipmask +converts a string pointed to by +.I str +to a 6-byte IP mask starting at +.IR ipaddr . +It too returns an unsigned long big-endian V4 address or 6. +Both routines return -1 on errors. +.PP +.I V4parseip +converts a string pointed to by +.I str +to a 4-byte V4 IP address starting at +.IR ipaddr . +.PP +.I V4parsecidr +converts a string of the form +addr/mask, pointed to by +.IR str , +to a 4-byte V4 IP address starting at +.I ipaddr +and a 4-byte V4 IP mask starting at +.IR mask . +.PP +.I Myipaddr +returns the first valid IP address in +the IP stack rooted at +.IR net . +.PP +.I Parseether +converts a string pointed to by +.I str +to a 6-byte Ethernet address starting at +.IR eaddr . +.I Myetheraddr +reads the Ethernet address string from file +.IB dev /1/stats +and parses it into +.IR eaddr . +Both routines return a negative number on errors. +.PP +.I Maskip +places the bit-wise AND of the IP addresses pointed +to by its first two arguments into the buffer pointed +to by the third. +.PP +.I Equivip +returns non-zero if the IP addresses pointed to by its two +arguments are equal. +.PP +.I Defmask +returns the standard class A, B, or C mask for +.IR ipaddr . +.PP +.I Isv4 +returns non-zero if the V6 address is in the V4 space, that is, +if it starts with +.BR 0:0:0:0:0:0:FFFF . +.I V4tov6 +converts the V4 address, +.IR v4ip , +to a V6 address and puts the result in +.IR v6ip . +.I V6tov4 +converts the V6 address, +.IR v6ip , +to a V4 address and puts the result in +.IR v4ip . +.PP +.I Hnputs +and +.I hnputl +are used to store 16-bit and 32-bit integers into IP big-endian form. +.I Nhgets +and +.I nhgetl +convert big-endian 2 and 4 byte quantities into integers. +.PP +.I Pctlbsum +returns the one's complement checksum used in IP protocols, typically invoked as +.EX +hnputs(hdr->cksum, ~ptclbsum(data, len) & 0xffff); +.EE +.PP +A number of standard IP addresses in V6 format are also defined. They +are: +.IP \f5IPv4bcast +the V4 broadcast address +.IP \f5IPv4allsys +the V4 all systems multicast address +.IP \f5IPv4allrouter +the V4 all routers multicast address +.IP \f5IPallbits +the V6 all bits on address +.IP \f5IPnoaddr +the V6 null address, all zeros +.IP \f5v4prefix +the IP V6 prefix to all embedded V4 addresses +.PP +.I Readipifc +returns information about +a particular interface (\fIindex\fP >= 0) +or all IP interfaces (\fIindex\fP < 0) +configured under a +mount point +.IR net , +default +.BR /net . +Each interface is described by one +.I Ipifc +structure which in turn points to a linked list of +.IR Iplifc +structures describing the addresses assigned +to this interface. +If the list +.IR ifc +is supplied, +that list is freed. +Thus, subsequent calls can be used +to free the list returned by the previous call. +.I Ipifc +is: +.PP +.EX +typedef struct Ipifc +{ + Ipifc *next; + Iplifc *lifc; /* local addressses */ + + /* per ip interface */ + int index; /* number of interface in ipifc dir */ + char dev[64]; /* associated physical device */ + int mtu; /* max transfer unit */ + + long validlt; /* valid life time */ + long preflt; /* preferred life time */ + uchar sendra6; /* on == send router adv */ + uchar recvra6; /* on == rcv router adv */ + + ulong pktin; /* packets read */ + ulong pktout; /* packets written */ + ulong errin; /* read errors */ + ulong errout; /* write errors */ + Ipv6rp rp; /* route advertisement params */ +} Ipifc; +.EE +.PP +.I Iplifc +is: +.PP +.EX +struct Iplifc +{ + Iplifc *next; + + uchar ip[IPaddrlen]; + uchar mask[IPaddrlen]; + uchar net[IPaddrlen]; /* ip & mask */ + ulong preflt; /* preferred lifetime */ + ulong validlt; /* valid lifetime */ +}; +.EE +.PP +.I Ipv6rp +is: +struct Ipv6rp +{ + int mflag; + int oflag; + int maxraint; /* max route adv interval */ + int minraint; /* min route adv interval */ + int linkmtu; + int reachtime; + int rxmitra; + int ttl; + int routerlt; +}; +.PP +.I Dev +contains the first 64 bytes of the device configured with this +interface. +.I Net +is +.IB ip & mask +if the network is multipoint or +the remote address if the network is +point to point. +.SH SOURCE +.B /sys/src/libip +.SH SEE ALSO +.IR print (2) diff --git a/static/plan9-4e/man2/isalpharune.2 b/static/plan9-4e/man2/isalpharune.2 new file mode 100644 index 00000000..a6a7507f --- /dev/null +++ b/static/plan9-4e/man2/isalpharune.2 @@ -0,0 +1,51 @@ +.TH ISALPHARUNE 2 +.SH NAME +isalpharune, islowerrune, isspacerune, istitlerune, isupperrune, tolowerrune, totitlerune, toupperrune \- Unicode character classes and cases +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int isalpharune(Rune c) +.PP +.B +int islowerrune(Rune c) +.PP +.B +int isspacerune(Rune c) +.PP +.B +int istitlerune(Rune c) +.PP +.B +int isupperrune(Rune c) +.PP +.B +Rune tolowerrune(Rune c) +.PP +.B +Rune totitlerune(Rune c) +.PP +.B +Rune toupperrune(Rune c) +.SH DESCRIPTION +These routines examine and operate on Unicode characters, +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 (2) +for +.SM ASCII\c +, +these routines +test types and modify cases for Unicode characters. +The names are self-explanatory. +.PP +The case-conversion routines return the character unchanged if it has no case. +.SH SOURCE +.B /sys/src/libc/port/runetype.c +.SH "SEE ALSO +.IR ctype (2) , +.IR "The Unicode Standard" . diff --git a/static/plan9-4e/man2/keyboard.2 b/static/plan9-4e/man2/keyboard.2 new file mode 100644 index 00000000..d0463f78 --- /dev/null +++ b/static/plan9-4e/man2/keyboard.2 @@ -0,0 +1,104 @@ +.TH KEYBOARD 2 +.SH NAME +initkeyboard, ctlkeyboard, closekeyboard \- keyboard control +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +Keyboardctl *initkeyboard(char *file) +.PP +.B +int ctlkeyboard(Keyboardctl *kc, char *msg) +.PP +.B +void closekeyboard(Keyboard *kc) +.SH DESCRIPTION +These functions access and control a keyboard interface +for character-at-a-time I/O in a multi-threaded environment, usually in combination with +.IR mouse (2). +They use the message-passing +.B Channel +interface in the threads library +(see +.IR thread (2)); +programs that wish a more event-driven, single-threaded approach should use +.IR event (2). +.PP +.I Initkeyboard +opens a connection to the keyboard and returns a +.B Keyboardctl +structure: +.IP +.EX +.ta 6n +\w'Channel 'u +\w'consfd; 'u +typedef struct Keyboardct Keyboardctl; +struct Keyboardctl +{ + Channel *c; /* chan(Rune[20]) */ + + char *file; + int consfd; /* to cons file */ + int ctlfd; /* to ctl file */ + int pid; /* of slave proc */ +}; +.EE +.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. +.PP +Once the +.B Keyboardctl +is set up a +message containing a +.BR Rune +will be sent on the +.B Channel +.B Keyboardctl.c +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)). +It writes the string +.I msg +to the control file associated with the device, which is assumed to be the regular device file name +with the string +.B ctl +appended. +.PP +.I Closekeyboard +closes the file descriptors associated with the keyboard, kills the slave processes, +and frees the +.B Keyboardctl +structure. +.PP +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR event (2), +.IR thread (2). +.SH BUGS +Because the interface delivers complete runes, +there is no way to report lesser actions such as +shift keys or even individual bytes. diff --git a/static/plan9-4e/man2/lock.2 b/static/plan9-4e/man2/lock.2 new file mode 100644 index 00000000..ef36d37a --- /dev/null +++ b/static/plan9-4e/man2/lock.2 @@ -0,0 +1,180 @@ +.TH LOCK 2 +.SH NAME +lock, canlock, unlock, +qlock, canqlock, qunlock, +rlock, runlock, canrlock, +wlock, wunlock, canwlock, +incref, decref +\- shared memory spin locks, rendez-vous locks, reader-writer locks, and +atomic increment and decrement +.SH SYNOPSIS +.B +#include +.br +.B +#include +.PP +.B +void lock(Lock *l) +.PP +.B +int canlock(Lock *l) +.PP +.B +void unlock(Lock *l) +.PP +.B +void qlock(QLock *l) +.PP +.B +void qunlock(QLock *l) +.PP +.B +int canqlock(QLock *l) +.PP +.B +void rlock(RWLock *l) +.PP +.B +void runlock(RWLock *l) +.PP +.B +int canrlock(RWLock *l) +.PP +.B +void wlock(RWLock *l) +.PP +.B +void wunlock(RWLock *l) +.PP +.B +int canwlock(RWLock *l) +.PP +.PP +.B +#include +.PP +.B +typedef struct Ref { +.br +.B + long ref; +.br +.B +} Ref; +.PP +.B +void incref(Ref*) +.PP +.B +long decref(Ref*) +.SH DESCRIPTION +These routines are used to synchronize processes sharing memory. +.PP +The first group +.RI ( lock , +.IR canlock , +.IR unlock ) +uses spin locks in shared memory. +The second group +.RI ( qlock , +.IR canqlock , +.IR qunlock ), +uses rendezvous locks in shared +memory. +The third group +.RI ( rlock , +.IR runlock , +.IR canrlock , +.IR wlock , +.IR wunlock , +.IR canwlock ), +also uses rendezvous locks but has slightly different +semantics. +.PP +Locks work in regular programs as well as programs that use the thread library +(see +.IR thread (2)). +The thread library replaces the +.B rendezvous +system call +(see +.IR rendezvous (2)) +with its own implementation, +.BR threadrendezvous , +so that threads as well as processes may be synchronized by locking calls +in threaded programs. +.PP +Used carelessly, spin locks can be expensive and can easily generate deadlocks. +Their use is discouraged, especially in programs that use the +thread library because they prevent context switches between threads. +.PP +.I Lock +blocks until the lock has been obtained. +.I Canlock +is non-blocking. +It tries to obtain a lock and returns a non-zero value if it +was successful, 0 otherwise. +.I Unlock +releases a lock. +.PP +.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. +.PP +Although +.B Locks +are the more primitive lock, they have limitations; for example, +they cannot synchronize between tasks in the same +.IR proc . +Use +.B QLocks +instead. +.PP +.B RWLocks +manage access to a data structure that has distinct readers and writers. +.I Rlock +grants read access; +.I runlock +releases it. +.I Wlock +grants write access; +.I wunlock +releases it. +.I Canrlock +and +.I canwlock +are the non-blocking versions. +There may be any number of simultaneous readers, +but only one writer. +Moreover, +if write access is granted no one may have +read access until write access is released. +.PP +All types of lock should be initialized to all zeros before use; this +puts them in the unlocked state. +.PP +A +.B Ref +contains a +.B long +that can be incremented and decremented atomically: +.I Incref +increments the +.I Ref +in one atomic operation. +.I Decref +atomically decrements the +.B Ref +and returns zero if the resulting value is zero, non-zero otherwise. +.SH SOURCE +.B /sys/src/libc/port/lock.c +.br +.B /sys/src/libc/9sys/qlock.c +.br +.B /sys/src/libthread/ref.c +.SH SEE ALSO +.I rfork +in +.IR fork (2) diff --git a/static/plan9-4e/man2/mach.2 b/static/plan9-4e/man2/mach.2 new file mode 100644 index 00000000..b75b1d86 --- /dev/null +++ b/static/plan9-4e/man2/mach.2 @@ -0,0 +1,393 @@ +.TH MACH 2 +.SH NAME +crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap, +loadmap, attachproc, get1, get2, get4, get8, put1, put2, put4, put8, +beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int crackhdr(int fd, Fhdr *fp) +.PP +.B +void machbytype(int type) +.PP +.B +int machbyname(char *name) +.PP +.B +Map *newmap(Map *map, int n) +.PP +.B +int setmap(Map *map, int fd, ulong base, ulong end, +.PP +.B + ulong foffset, char *name) +.PP +.B +int findseg(Map *map, char *name) +.PP +.B +void unusemap(Map *map, int seg) +.PP +.B +Map *loadmap(Map *map, int fd, Fhdr *fp) +.PP +.B +int attachproc(int pid, int kflag, int corefd, Fhdr *fp) +.PP +.B +int get1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int get2(Map *map, ulong addr, ushort *val) +.PP +.B +int get4(Map *map, ulong addr, long *val) +.PP +.B +int get8(Map *map, ulong addr, vlong *val) +.PP +.B +int put1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int put2(Map *map, ulong addr, ushort val) +.PP +.B +int put4(Map *map, ulong addr, long val) +.PP +.B +int put8(Map *map, ulong addr, vlong val) +.PP +.B +ushort beswab(ushort val) +.PP +.B +long beswal(long val) +.PP +.B +long beswav(vlong val) +.PP +.B +ushort leswab(ushort val) +.PP +.B +long leswal(long val) +.PP +.B +long leswav(vlong val) +.PP +.B +extern Mach mach; +.PP +.B +extern Machdata machdata; +.SH DESCRIPTION +These functions provide +a processor-independent interface for accessing +the executable files or executing images of all +architectures. +Related library functions described in +.IR symbol (2) +and +.IR object (2) +provide similar access to symbol tables and object files. +.PP +An +.I executable +is a file containing an executable program or the +.B text +file of the +.B /proc +file system associated with an executing process as +described in +.IR proc (3). +After opening an executable, an application +invokes a library function which parses the +file header, +determines the target architecture and +initializes data structures with parameters +and pointers to functions appropriate for +that architecture. Next, the application +invokes functions to construct one or more +.IR maps , +data structures that translate references +in the address space of the executable +to offsets in the file. Each +.I map +comprises one or more +.BR segments , +each associating a non-overlapping range of +memory addresses with a logical section of +the executable. +Other library functions then use a map +and the architecture-specific data structures +to provide a generic interface to the +processor-dependent data. +.PP +.I Crackhdr +interprets the header of the executable +associated with +the open file descriptor +.IR fd . +It loads the data structure +.I fp +with a machine-independent description +of the header information and +points global variable +.I mach +to the +.B Mach +data structure containing processor-dependent parameters +of the target architecture. +.PP +.I Machbytype +selects architecture-specific data structures and parameter +values based on +the code stored in the +field named +.I type +in the +.B Fhdr +data structure. +.I Machbyname +performs the same selection based +on the name of a processor class; see +.IR 2c (1) +for a list of valid names. +Both functions point global variables +.I mach +and +.I machdata +to the +.I Mach +and +.I Machdata +data structures appropriate for the +target architecture and load global variable +.I asstype +with the proper disassembler type code. +.PP +.I Newmap +creates an empty map with +.I n +segments. +If +.I map +is zero, the new map is dynamically +allocated, otherwise it is assumed to +point to an existing dynamically allocated map whose +size is adjusted, as necessary. +A zero return value indicates an allocation error. +.PP +.I Setmap +loads the first unused segment in +.I map +with the +segment mapping parameters. +.I Fd +is an open file descriptor associated with +an executable. +.I Base +and +.I end +contain the lowest and highest virtual addresses +mapped by the segment. +.I Foffset +is the offset to the start of the segment in the file. +.I Name +is a name to be attached to the segment. +.PP +.I Findseg +returns the index of the the +segment named +.I name +in +.IR map . +A return of -1 indicates that no +segment matches +.IR name . +.PP +.I Unusemap +marks segment number +.I seg +in map +.I map +unused. Other +segments in the map remain unaffected. +.PP +.I Loadmap +initializes a default map containing +segments named `text' and `data' that +map the instruction and data segments +of the executable described in the +.B Fhdr +structure pointed to by +.IR fp . +Usually that structure was loaded by +.IR crackhdr +and can be passed to this function without +modification. +If +.I map +is non-zero, that map, which must have been +dynamically allocated, is resized to contain two segments; +otherwise a new map is allocated. +This function returns zero if allocation fails. +.I Loadmap +is usually used to build a map for accessing +a static executable, for example, an executable +program file. +.PP +.I Attachproc +constructs a map for accessing a +running process. It +returns the address of a +.I Map +containing segments mapping the +address space of the running process +whose process ID is +.BR pid . +If +.B kflag +is non-zero, the process is assumed to be +a kernel process. +.B Corefd +is an file descriptor opened to +.BR /proc/\fIpid\fP/mem . +.B Fp +points to the +.I Fhdr +structure describing the header +of the executable. For most architectures +the resulting +.I Map +contains four segments named `text', `data', +`regs' and `fpregs'. The latter two provide access to +the general and floating point registers, respectively. +If the executable is a kernel process (indicated by a +non-zero +.B kflag +argument), the data segment extends to the maximum +supported address, currently 0xffffffff, and the +register sets are read-only. In user-level programs, +the data segment extends to the +top of the stack or 0x7fffffff if the stack top +cannot be found, and the register sets are readable +and writable. +.I Attachproc +returns zero if it is unable to build the map +for the specified process. +.PP +.IR Get1 , +.IR get2 , +.IR get4 , +and +.I get8 +retrieve the data stored at address +.I addr +in the executable associated +with +.IR map . +.I Get1 +retrieves +.I n +bytes of data beginning at +.I addr +into +.IR buf . +.IR Get2 , +.I get4 +and +.I get8 +retrieve 16-bit, 32-bit and 64-bit values respectively, +into the location pointed to by +.IR val . +The value is byte-swapped if the source +byte order differs from that of the current architecture. +This implies that the value returned by +.IR get2 , +.IR get4 , +and +.I get8 +may not be the same as the byte sequences +returned by +.I get1 +when +.I n +is two, four or eight; the former may be byte-swapped, the +latter reflects the byte order of the target architecture. +If the file descriptor associated with the applicable segment in +.I map +is negative, the address itself is placed in the +return location. These functions return the number +of bytes read or a \-1 when there is an error. +.PP +.IR Put1 , +.IR put2 , +.IR put4 , +and +.I put8 +write to +the executable associated with +.IR map . +The address is translated using the +map parameters and multi-byte quantities are +byte-swapped, if necessary, before they are written. +.I Put1 +transfers +.I n +bytes stored at +.IR buf ; +.IR put2 , +.IR put4 , +and +.I put8 +write the 16-bit, 32-bit or 64-bit quantity contained in +.IR val , +respectively. The number of bytes transferred is returned. +A \-1 return value indicates an error. +.PP +.IR Beswab , +.IR beswal , +and +.I beswav +return the +.BR ushort , +.BR long , +and +.B vlong +big-endian representation of +.IR val , +respectively. +.IR Leswab , +.IR leswal , +and +.I leswav +return the little-endian representation of the +.BR ushort , +.BR long , +and +.B vlong +contained in +.IR val . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR 2c (1), +.IR symbol (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/static/plan9-4e/man2/malloc.2 b/static/plan9-4e/man2/malloc.2 new file mode 100644 index 00000000..52183079 --- /dev/null +++ b/static/plan9-4e/man2/malloc.2 @@ -0,0 +1,198 @@ +.TH MALLOC 2 +.SH NAME +malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +void* malloc(ulong size) +.PP +.B +void* mallocz(ulong size, int clr) +.PP +.B +void free(void *ptr) +.PP +.B +void* realloc(void *ptr, ulong size) +.PP +.B +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) +.PP +.B +void setrealloctag(void *ptr, ulong tag) +.PP +.B +ulong getrealloctag(void *ptr, ulong tag) +.PP +.SH DESCRIPTION +.I Malloc +and +.I free +provide a simple memory allocation package. +.I Malloc +returns a pointer to a new block of at least +.I size +bytes. +The block is suitably aligned for storage of any type of object. +No two active pointers from +.I malloc +will have the same value. +Incompatibly with ANSI C, +the call +.B malloc(0) +returns a valid pointer rather than null. +.PP +The argument to +.I free +is a pointer to a block previously allocated by +.IR malloc ; +this space is made available for further allocation. +It is legal to free a null pointer; the effect is a no-op. +The contents of the space returned by +.I malloc +are undefined. +.I Mallocz +behaves as +.IR malloc , +except that if +.I clr +is non-zero, the memory returned will be zeroed. +.PP +.I Realloc +changes the size of the block pointed to by +.I ptr +to +.I size +bytes and returns a pointer to the (possibly moved) +block. +The contents will be unchanged up to the +lesser of the new and old sizes. +The call +.B "realloc(0,\ size) +means the same as +.LR malloc(size) . +Further, +the call +.B "realloc(ptr,\ 0) +means the same as +.LR free(ptr) . +.PP +.I Calloc +allocates space for +an array of +.I nelem +elements of size +.IR elsize . +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 +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. +These may be set or examined with +.IR setmalloctag , +.IR getmalloctag , +.IR setrealloctag , +and +.IR getrealloctag . +When allocating blocks directly with +.I malloc +and +.IR realloc , +these tags will be set properly. +If a custom allocator wrapper is used, +the allocator wrapper can set the tags +itself (usually by passing the result of +.IR getcallerpc (2) +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 (2) +routines. +.SH SOURCE +.B /sys/src/libc/port/malloc.c +.SH SEE ALSO +.IR leak (1), +.I trump +(in +.IR acid (1)), +.IR brk (2), +.IR getcallerpc (2), +.IR pool (2) +.SH DIAGNOSTICS +.I Malloc, realloc +and +.I calloc +return 0 if there is no available memory. +.I Errstr +is likely to be set. +If the allocated blocks have no malloc or realloc tags, +.I getmalloctag +and +.I getrealloctag +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 +.I acid +can be used to obtain traces of malloc execution; see +.IR acid (1). +.SH BUGS +The different specification of +.I calloc +is bizarre. +.PP +User errors can corrupt the storage arena. +The most common gaffes are (1) freeing an already freed block, +(2) storing beyond the bounds of an allocated block, and (3) +freeing data that was not obtained from the allocator. +When +.I malloc +and +.I free +detect such corruption, they abort. diff --git a/static/plan9-4e/man2/matrix.2 b/static/plan9-4e/man2/matrix.2 new file mode 100644 index 00000000..6291aa6d --- /dev/null +++ b/static/plan9-4e/man2/matrix.2 @@ -0,0 +1,350 @@ +.TH MATRIX 2 +.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 /sys/src/libgeometry/matrix.c +.SH "SEE ALSO +.IR arith3 (2) diff --git a/static/plan9-4e/man2/memdraw.2 b/static/plan9-4e/man2/memdraw.2 new file mode 100644 index 00000000..a349cd3b --- /dev/null +++ b/static/plan9-4e/man2/memdraw.2 @@ -0,0 +1,450 @@ +.TH MEMDRAW 2 +.SH NAME +Memimage, +Memdata, +Memdrawparam, +memimageinit, +wordaddr, +byteaddr, +memimagemove, +allocmemimage, +allocmemimaged, +readmemimage, +creadmemimage, +writememimage, +freememimage, +memsetchan, +loadmemimage, +cloadmemimage, +unloadmemimage, +memfillcolor, +memarc, +mempoly, +memellipse, +memfillpoly, +memimageline, +memimagedraw, +drawclip, +memlinebbox, +memlineendsize, +allocmemsubfont, +openmemsubfont, +freememsubfont, +memsubfontwidth, +getmemdefont, +memimagestring, +iprint, +hwdraw \- drawing routines for memory-resident images +.SH SYNOPSIS +.nf +.B #include +.nf +.B #include +.B #include +.B #include +.B #include +.PP +.ft L +typedef struct Memdata +{ + ulong *base; /* allocated data pointer */ + uchar *bdata; /* first byte of actual data; word-aligned */ + int ref; /* number of Memimages using this data */ + void* imref; /* last image that pointed at this */ + int allocd; /* is this malloc'd? */ +} Memdata; + +enum { + Frepl = 1<<0, /* is replicated */ + Fsimple = 1<<1, /* is 1x1 */ + Fgrey = 1<<2, /* is grey */ + Falpha = 1<<3, /* has explicit alpha */ + Fcmap = 1<<4, /* has cmap channel */ + Fbytes = 1<<5, /* has only 8-bit channels */ +}; + +typedef struct Memimage +{ + Rectangle r; /* rectangle in data area, local coords */ + Rectangle clipr; /* clipping region */ + int depth; /* number of bits of storage per pixel */ + int nchan; /* number of channels */ + ulong chan; /* channel descriptions */ + + Memdata *data; /* pointer to data */ + int zero; /* data->bdata+zero==&byte containing (0,0) */ + ulong width; /* width in words of a single scan line */ + Memlayer *layer; /* nil if not a layer*/ + ulong flags; + \fI...\fP +} Memimage; + +typedef struct Memdrawparam +{ + Memimage *dst; + Rectangle r; + Memimage *src; + Rectangle sr; + Memimage *mask; + Rectangle mr; + \fI...\fP +} Memdrawparam; + +.ta \w'\fLMemsubfont* 'u +int drawdebug; +.ft +.PP +.ft L +.nf +void memimageinit(void) +ulong* wordaddr(Memimage *i, Point p) +uchar* byteaddr(Memimage *i, Point p) +void memimagemove(void *from, void *to) +.PP +.ft L +.nf +Memimage* allocmemimage(Rectangle r, ulong chan) +Memimage* allocmemimaged(Rectangle r, ulong chan, Memdata *data) +Memimage* readmemimage(int fd) +Memimage* creadmemimage(int fd) +int writememimage(int fd, Memimage *i) +void freememimage(Memimage *i) +int memsetchan(Memimage*, ulong) +.PP +.ft L +.nf +int loadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +int cloadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +int unloadmemimage(Memimage *i, Rectangle r, + uchar *buf, int nbuf) +void memfillcolor(Memimage *i, ulong color) +.PP +.ft L +.nf +void memarc(Memimage *dst, Point c, int a, int b, int thick, + Memimage *src, Point sp, int alpha, int phi) +void mempoly(Memimage *dst, Point *p, int np, int end0, + int end1, int radius, Memimage *src, Point sp) +void memellipse(Memimage *dst, Point c, int a, int b, + int thick, Memimage *src, Point sp) +void memfillpoly(Memimage *dst, Point *p, int np, int wind, + Memimage *src, Point sp) +void memimageline(Memimage *dst, Point p0, Point p1, int end0, + int end1, int radius, Memimage *src, Point sp) +void memimagedraw(Memimage *dst, Rectangle r, Memimage *src, + Point sp, Memimage *mask, Point mp) +.PP +.ft L +.nf +int drawclip(Memimage *dst, Rectangle *dr, Memimage *src, + Point *sp, Memimage *mask, Point *mp, + Rectangle *sr, Rectangle *mr) +Rectangle memlinebbox(Point p0, Point p1, int end0, int end1, + int radius) +int memlineendsize(int end) +.PP +.ft L +.nf +Memsubfont* allocmemsubfont(char *name, int n, int height, + int ascent, Fontchar *info, Memimage *i) +Memsubfont* openmemsubfont(char *name) +void freememsubfont(Memsubfont *f) +Point memsubfontwidth(Memsubfont *f, char *s) +Memsubfont* getmemdefont(void) +Point memimagestring(Memimage *dst, Point p, Memimage *color, + Point cp, Memsubfont *f, char *cs) +.PP +.ft L +.nf +int iprint(char *fmt, ...) +int hwdraw(Memdrawparam *param) +.ft R +.SH DESCRIPTION +The +.B Memimage +type defines memory-resident rectangular pictures and the methods to draw upon them; +.BR Memimage s +differ from +.BR Image s +(see +.IR draw (2)) +in that they are manipulated directly in user memory rather than by +RPCs to the +.B /dev/draw +hierarchy. +The +.Bmemdraw +library is the basis for the kernel +.IR draw (3) +driver and also used by a number of programs that must manipulate +images without a display. +.PP +The +.BR r, +.BR clipr , +.BR depth , +.BR nchan , +and +.BR chan +structure elements are identical to +the ones of the same name +in the +.B Image +structure. +.PP +The +.B flags +element of the +.B Memimage +structure holds a number of bits of information about the image. +In particular, it subsumes the +purpose of the +.B repl +element of +.B Image +structures. +.PP +.I Memimageinit +initializes various static data that the library depends on, +as well as the replicated solid color images +.BR memopaque , +.BR memtransparent , +.BR memblack , +and +.BR memwhite . +It should be called before referring to any of these images +and before calling any of the other library functions. +.PP +Each +.B Memimage +points at a +.B Memdata +structure that in turn points at the actual pixel data for the image. +This allows multiple images to be associated with the same +.BR Memdata . +The first word of the data pointed at by +the +.B base +element of +.B Memdata +points back at the +.B Memdata +structure, so that the +memory allocator (see +.IR pool (2)) +can compact image memory +using +.IR memimagemove . +.PP +Because images can have different coordinate systems, +the +.B zero +element of the +.B Memimage +structure contains the offset that must be added +to the +.B bdata +element of the corresponding +.B Memdata +structure in order to yield a pointer to the data for the pixel (0,0). +Adding +.BR width +machine words +to this pointer moves it down one scan line. +The +.B depth +element can be used to determine how to move the +pointer horizontally. +Note that this method works even for images whose rectangles +do not include the origin, although one should only dereference +pointers corresponding to pixels within the image rectangle. +.I Wordaddr +and +.IR byteaddr +perform these calculations, +returning pointers to the word and byte, respectively, +that contain the beginning of the data for a given pixel. +.PP +.I Allocmemimage +allocages +images with a given rectangle and channel descriptor +(see +.B strtochan +in +.IR graphics (2)), +creating a fresh +.B Memdata +structure and associated storage. +.I Allocmemimaged +is similar but uses the supplied +.I Memdata +structure rather than a new one. +The +.I readmemimage +function reads an uncompressed bitmap +from the given file descriptor, +while +.I creadmemimage +reads a compressed bitmap. +.I Writememimage +writes a compressed representation of +.I i +to file descriptor +.IR fd . +For more on bitmap formats, see +.IR image (6). +.I Freememimage +frees images returned by any of these routines. +The +.B Memimage +structure contains some tables that are used +to store precomputed values depending on the channel descriptor. +.I Memsetchan +updates the +.B chan +element of the structure as well as these tables, +returning \-1 if passed a bad channel descriptor. +.PP +.I Loadmemimage +and +.I cloadmemimage +replace the pixel data for a given rectangle of an image +with the given buffer of uncompressed or compressed +data, respectively. +When calling +.IR cloadmemimage , +the buffer must contain an +integral number of +compressed chunks of data that exactly cover the rectangle. +.I Unloadmemimage +retrieves the uncompressed pixel data for a given rectangle of an image. +All three return the number of bytes consumed on success, +and \-1 in case of an error. +.PP +.I Memfillcolor +fills an image with the given color, a 32-bit number as +described in +.IR color (2). +.PP +.IR Memarc , +.IR mempoly , +.IR memellipse , +.IR memfillpoly , +.IR memimageline , +and +.I memimagedraw +are identical to the +.IR arc , +.IR poly , +.IR ellipse , +.IR fillpoly , +.IR line , +and +.IR gendraw , +routines described in +.IR draw (2), +except that they operate on +.BR Memimage s +rather than +.BR Image s. +Similarly, +.IR allocmemsubfont , +.IR openmemsubfont , +.IR freememsubfont , +.IR memsubfontwidth , +.IR getmemdefont , +and +.I memimagestring +are the +.B Memimage +analogues of +.IR allocsubfont , +.IR openfont , +.IR freesubfont , +.IR strsubfontwidth , +.IR getdefont , +and +.B string +(see +.IR subfont (2) +and +.IR graphics (2)), +except that they operate +only on +.BR Memsubfont s +rather than +.BR Font s. +.PP +.I Drawclip +takes the images involved in a draw operation, +together with the destination rectangle +.B dr +and source +and mask alignment points +.B sp +and +.BR mp , +and +clips them according to the clipping rectangles of the images involved. +It also fills in the rectangles +.B sr +and +.B mr +with rectangles congruent to the returned destination rectangle +but translated so the upper left corners are the returned +.B sp +and +.BR mp . +.I Drawclip +returns zero when the clipped rectangle is empty. +.I Memlinebbox +returns a conservative bounding box containing a line between +two points +with given end styles +and radius. +.I Memlineendsize +calculates the extra length added to a line by attaching +an end of a given style. +.PP +The +.I hwdraw +and +.I iprint +functions are no-op stubs that may be overridden by clients +of the library. +.I Hwdraw +is called at each call to +.I memimagedraw +with the current request's parameters. +If it can satisfy the request, it should do so +and return 1. +If it cannot satisfy the request, it should return 0. +This allows (for instance) the kernel to take advantage +of hardware acceleration. +.I Iprint +should format and print its arguments; +it is given much debugging output when +the global integer variable +.B drawdebug +is non-zero. +In the kernel, +.I iprint +prints to a serial line rather than the screen, for obvious reasons. +.SH SOURCE +.B /sys/src/libmemdraw +.SH SEE ALSO +.IR addpt (2), +.IR color (2), +.IR draw (2), +.IR graphics (2), +.IR memlayer (2), +.IR stringsize (2), +.IR subfont (2), +.IR color (6), +.IR utf (6) +.SH BUGS +.I Memimagestring +is unusual in using a subfont rather than a font, +and in having no parameter to align the source. diff --git a/static/plan9-4e/man2/memlayer.2 b/static/plan9-4e/man2/memlayer.2 new file mode 100644 index 00000000..6c3cd9f3 --- /dev/null +++ b/static/plan9-4e/man2/memlayer.2 @@ -0,0 +1,305 @@ +.TH MEMLAYER 2 +.SH NAME +memdraw, memlalloc, memldelete, memlexpose, memlfree, memlhide, memline, memlnorefresh, memload, memunload, memlorigin, memlsetrefresh, memltofront, memltofrontn, memltorear, memltorearn \- windows of memory-resident images +.SH SYNOPSIS +.nf +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ft L +typedef struct Memscreen Memscreen; +typedef struct Memlayer Memlayer; +typedef void (*Refreshfn)(Memimage*, Rectangle, void*); +.ta 4n +\w'\fLRefreshfn 'u +\w'\fL*frontmost; 'u + +struct Memscreen +{ + Memimage *frontmost; /* frontmost layer on screen */ + Memimage *rearmost; /* rearmost layer on screen */ + Memimage *image; /* upon which all layers are drawn */ + Memimage *fill; /* if non-zero, picture to use when repainting */ +}; + +struct Memlayer +{ + Rectangle screenr; /* true position of layer on screen */ + Point delta; /* add delta to go from image coords to screen */ + Memscreen *screen; /* screen this layer belongs to */ + Memimage *front; /* window in front of this one */ + Memimage *rear; /* window behind this one*/ + int clear; /* layer is fully visible */ + Memimage *save; /* save area for obscured parts */ + Refreshfn refreshfn; /* fn to refresh obscured parts if save==nil */ + void *refreshptr; /* argument to refreshfn */ +}; +.ft +.ta \w'\fLMemimage* 'u +.PP +.B +Memimage* memlalloc(Memscreen *s, Rectangle r, Refreshfn fn, void *arg, ulong col) +.PP +.B void memlnorefresh(Memimage *i, Rectangle r, void *arg) +.PP +.B +int memlsetrefresh(Memimage *i, Refreshfn fn, void *arg) +.PP +.B +int memldelete(Memimage *i) +.PP +.B +int memlfree(Memimage *i) +.PP +.B +int memlexpose(Memimage *i, Rectangle r) +.PP +.B +int memlhide(Memimage *i, Rectangle r) +.PP +.B +void memltofront(Memimage *i) +.PP +.B +void memltofrontn(Memimage**ia, int n) +.PP +.B +void memltorear(Memimage *i) +.PP +.B +void memltorearn(Memimage **ia , int n) +.PP +.B +int memlorigin(Memimage *i, Point log, Point phys) +.PP +.B +void memdraw(Image *dst, Rectangle r, +.br +.B + Image *src, Point sp, Image *mask, Point mp) +.fi +.B +int memload(Memimage *i, Rectangle r, +.br +.B + uchar *buf, int n, int iscompressed) +.PP +.B +int memunload(Memimage *i, Rectangle r, +.br +.B + uchar *buf, int n) +.PP +.SH DESCRIPTION +These functions build upon the +.IR memdraw (2) +interface to maintain overlapping graphical windows on in-memory images. +They are used by the kernel to implement the windows interface presented by +.IR draw (3) +and +.IR window (2) +and probably have little use outside of the kernel. +.PP +The basic function is to extend the definition of a +.B Memimage +(see +.IR memdraw (2)) +to include overlapping windows defined by the +.B Memlayer +type. +The first fields of the +.B Memlayer +structure are identical to those in +.BR Memimage , +permitting a function that expects a +.B Memimage +to be passed a +.BR Memlayer , +and vice versa. +Both structures have a +.B save +field, which is nil in a +.B Memimage +and points to `backing store' in a +.BR Memlayer . +The layer routines accept +.B Memimages +or +.BR Memlayers ; +if the image is a +.B Memimage +the underlying +.B Memimage +routine is called; otherwise the layer routines recursively +subdivide the geometry, reducing the operation into a smaller +component that ultimately can be performed on a +.BR Memimage , +either the display on which the window appears, or the backing store. +.PP +.B Memlayers +are associated with a +.B Memscreen +that holds the data structures to maintain the windows and connects +them to the associated +.BR image . +The +.B fill +color is used to paint the background when a window is deleted. +There is no function to establish a +.BR Memscreen ; +to create one, allocate the memory, zero +.B frontmost +and +.BR rearmost , +set +.B fill +to a valid fill color or image, and set +.B image +to the +.B Memimage +(or +.BR Memlayer ) +on which the windows will be displayed. +.PP +.I Memlalloc +allocates a +.B Memlayer +of size +.I r +on +.B Memscreen +.IR s . +If +.I col +is not +.BR DNofill , +the new window will be initialized by painting it that color. +.PP +The refresh function +.I fn +and associated argument +.I arg +will be called by routines in the library to restore portions of the window +uncovered due to another window being deleted or this window being pulled to the front of the stack. +The function, when called, +receives a pointer to the image (window) being refreshed, the rectangle that has been uncovered, +and the +.I arg +recorded when the window was created. +A couple of predefined functions provide built-in management methods: +.I memlnorefresh +does no backup at all, useful for making efficient temporary windows; +while a +.I nil +function specifies that the backing store +.RB ( Memlayer.save ) +will be used to keep the obscured data. +Other functions may be provided by the client. +.I Memlsetrefresh +allows one to change the function associated with the window. +.PP +.I Memldelete +deletes the window +.IR i , +restoring the underlying display. +.I Memlfree +frees the data structures without unlinking the window from the associated +.B Memscreen +or doing any graphics. +.PP +.I Memlexpose +restores rectangle +.I r +within the window, using the backing store or appropriate refresh method. +.I Memlhide +goes the other way, backing up +.I r +so that that portion of the screen may be modified without losing the data in this window. +.PP +.I Memltofront +pulls +.I i +to the front of the stack of windows, making it fully visible. +.I Memltofrontn +pulls the +.I n +windows in the array +.I ia +to the front as a group, leaving their internal order unaffected. +.I Memltorear +and +.I memltorearn +push the windows to the rear. +.PP +.I Memlorigin +changes the coordinate systems associated with the window +.IR i . +The points +.I log +and +.I phys +represent the upper left corner +.RB ( min ) +of the window's internal coordinate system and its physical location on the screen. +Changing +.I log +changes the interpretation of coordinates within the window; for example, setting it to +(0,\ 0) makes the upper left corner of the window appear to be the origin of the coordinate +system, regardless of its position on the screen. +Changing +.I phys +changes the physical location of the window on the screen. +When a window is created, its logical and physical coordinates are the same, so +.EX + memlorigin(i, i->r.min, i->r.min) +.EE +would be a no-op. +.PP +.I Memdraw +and +.I memline +are implemented in the layer library but provide the main entry points for drawing on +memory-resident windows. +They have the signatures of +.I memimagedraw +and +.I memimageline +(see +.IR memdraw (2)) +but accept +.B Memlayer +or +.B Memimage +arguments both. +.PP +.I Memload +and +.I memunload +are similarly layer-savvy versions of +.I loadmemimage +and +.IR unloadmemimage . +The +.I iscompressed +flag to +.I memload +specifies whether the +.I n +bytes of data in +.I buf +are in compressed image format +(see +.IR image (6)). +.SH SOURCE +.B /sys/src/libmemlayer +.SH SEE ALSO +.IR graphics (2), +.IR memdraw (2), +.IR stringsize (2), +.IR window (2), +.IR draw (3) diff --git a/static/plan9-4e/man2/memory.2 b/static/plan9-4e/man2/memory.2 new file mode 100644 index 00000000..1548e9ac --- /dev/null +++ b/static/plan9-4e/man2/memory.2 @@ -0,0 +1,126 @@ +.TH MEMORY 2 +.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 /sys/src/libc/port . +Most also have machine-dependent assembly language implementations in +.BR /sys/src/libc/$objtype . +.SH SEE ALSO +.IR strcat (2) +.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/static/plan9-4e/man2/mktemp.2 b/static/plan9-4e/man2/mktemp.2 new file mode 100644 index 00000000..683620ac --- /dev/null +++ b/static/plan9-4e/man2/mktemp.2 @@ -0,0 +1,40 @@ +.TH MKTEMP 2 +.SH NAME +mktemp \- make a unique file name +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +char* mktemp(char *template) +.fi +.SH DESCRIPTION +.I Mktemp +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 a name that can be accessed +(see +.IR access (2)) +is generated. +If no such name can be generated, +.I mktemp +returns +\f5"/"\f1 . +.SH SOURCE +.B /sys/src/libc/port/mktemp.c +.SH "SEE ALSO" +.IR getpid (2), +.IR access (2) diff --git a/static/plan9-4e/man2/mouse.2 b/static/plan9-4e/man2/mouse.2 new file mode 100644 index 00000000..196a156e --- /dev/null +++ b/static/plan9-4e/man2/mouse.2 @@ -0,0 +1,249 @@ +.TH MOUSE 2 +.SH NAME +initmouse, readmouse, closemouse, moveto, cursorswitch, getrect, drawgetrect, menuhit, setcursor \- mouse control +.SH SYNOPSIS +.nf +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.B +#include +.PP +.B +Mousectl *initmouse(char *file, Image *i) +.PP +.B +int readmouse(Mousectl *mc) +.PP +.B +int atomouse(); +.PP +.B +void closemouse(Mousectl *mc) +.PP +.B +void moveto(Mousectl *mc, Point pt) +.PP +.B +void setcursor(Mousectl *mc, Cursor *c) +.PP +.B +Rectangle getrect(int but, Mousectl *mc) +.PP +.B +void drawgetrect(Rectangle r, int up) +.PP +.B +int menuhit(int but, Mousectl *mc, Menu *menu, Screen *scr) +.fi +.SH DESCRIPTION +These functions access and control a mouse in a multi-threaded environment. +They use the message-passing +.B Channel +interface in the threads library +(see +.IR thread (2)); +programs that wish a more event-driven, single-threaded approach should use +.IR event (2). +.PP +The state of the mouse is recorded in a structure, +.BR Mouse , +defined in +.BR : +.IP +.EX +.ta 6n +\w'Rectangle 'u +\w'buttons; 'u +typedef struct Mouse Mouse; +struct Mouse +{ + int buttons; /* bit array: LMR=124 */ + Point xy; + ulong msec; +}; +.EE +.PP +The +.B Point +.B xy +records the position of the cursor, +.B buttons +the state of the buttons (three bits representing, from bit 0 up, the buttons from left to right, +0 if the button is released, 1 if it is pressed), +and +.BR msec , +a millisecond time stamp. +.PP +The routine +.B initmouse +returns a structure through which one may access the mouse: +.IP +.EX +typedef struct Mousectl Mousectl; +struct Mousectl +{ + Mouse; + Channel *c; /* chan(Mouse)[16] */ + Channel *resizec; /* chan(int)[2] */ + + char *file; + int mfd; /* to mouse file */ + int cfd; /* to cursor file */ + int pid; /* of slave proc */ + Image* image; /* of associated window/display */ +}; +.EE +.PP +The arguments to +.I initmouse +are a +.I file +naming the device file connected to the mouse and an +.I Image +(see +.IR draw (2)) +on which the mouse will be visible. +Typically the file is +nil, +which requests the default +.BR /dev/mouse ; +and the image is the window in which the program is running, held in the variable +.B screen +after a call to +.IR initdraw . +.PP +Once the +.B Mousectl +is set up, +mouse motion will be reported by messages of type +.B Mouse +sent on the +.B Channel +.BR Mousectl.c . +Typically, a message will be sent every time a read of +.B /dev/mouse +succeeds, which is every time the state of the mouse changes. +.PP +When the window is resized, a message is sent on +.BR Mousectl.resizec . +The actual value sent may be discarded; the receipt of the message +tells the program that it should call +.B getwindow +(see +.IR graphics (2)) +to reconnect to the window. +.PP +.I Readmouse +updates the +.B Mouse +structure held in the +.BR Mousectl , +blocking if the state has not changed since the last +.I readmouse +or message sent on the channel. +It calls +.B flushimage +(see +.IR graphics (2)) +before blocking, so any buffered graphics requests are displayed. +.PP +.I Closemouse +closes the file descriptors associated with the mouse, kills the slave processes, +and frees the +.B Mousectl +structure. +.PP +.I Moveto +moves the mouse cursor on the display to the position specified by +.IR pt . +.PP +.I Setcursor +sets the image of the cursor to that specified by +.IR c . +If +.I c +is nil, the cursor is set to the default. +The format of the cursor data is spelled out in +.B +and described in +.IR graphics (2). +.PP +.I Getrect +returns the dimensions of a rectangle swept by the user, using the mouse, +in the manner +.IR rio (1) +or +.IR sam (1) +uses to create a new window. +The +.I but +argument specifies which button the user must press to sweep the window; +any other button press cancels the action. +The returned rectangle is all zeros if the user cancels. +.PP +.I Getrect +uses successive calls to +.I drawgetrect +to maintain the red rectangle showing the sweep-in-progress. +The rectangle to be drawn is specified by +.I rc +and the +.I up +parameter says whether to draw (1) or erase (0) the rectangle. +.PP +.I Menuhit +provides a simple menu mechanism. +It uses a +.B Menu +structure defined in +.BR : +.IP +.EX +typedef struct Menu Menu; +struct Menu +{ + char **item; + char *(*gen)(int); + int lasthit; +}; +.EE +.PP +.IR Menuhit +behaves the same as its namesake +.I emenuhit +described in +.IR event (2), +with two exceptions. +First, it uses a +.B Mousectl +to access the mouse rather than using the event interface; +and second, +it creates the menu as a true window on the +.B Screen +.I scr +(see +.IR window (2)), +permitting the menu to be displayed in parallel with other activities on the display. +If +.I scr +is null, +.I menuhit +behaves like +.IR emenuhit , +creating backing store for the menu, writing the menu directly on the display, and +restoring the display when the menu is removed. +.PP +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR event (2), +.IR keyboard (2), +.IR thread (2). diff --git a/static/plan9-4e/man2/mp.2 b/static/plan9-4e/man2/mp.2 new file mode 100644 index 00000000..01be7c3c --- /dev/null +++ b/static/plan9-4e/man2/mp.2 @@ -0,0 +1,568 @@ +.TH MP 2 +.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 +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +mpint* mpnew(int n) +.PP +.B +void mpfree(mpint *b) +.PP +.B +void mpsetminbits(int n) +.PP +.B +void mpbits(mpint *b, int n) +.PP +.B +void mpnorm(mpint *b) +.PP +.B +mpint* mpcopy(mpint *b) +.PP +.B +void mpassign(mpint *old, mpint *new) +.PP +.B +mpint* mprand(int bits, void (*gen)(uchar*, int), mpint *b) +.PP +.B +mpint* strtomp(char *buf, char **rptr, int base, mpint *b) +.PP +.B +char* mptoa(mpint *b, int base, char *buf, int blen) +.PP +.B +int mpfmt(Fmt*) +.PP +.B +mpint* betomp(uchar *buf, uint blen, mpint *b) +.PP +.B +int mptobe(mpint *b, uchar *buf, uint blen, uchar **bufp) +.PP +.B +mpint* letomp(uchar *buf, uint blen, mpint *b) +.PP +.B +int mptole(mpint *b, uchar *buf, uint blen, uchar **bufp) +.PP +.B +uint mptoui(mpint*) +.PP +.B +mpint* uitomp(uint, mpint*) +.PP +.B +int mptoi(mpint*) +.PP +.B +mpint* itomp(int, mpint*) +.PP +.B +mpint* vtomp(vlong, mpint*) +.PP +.B +vlong mptov(mpint*) +.PP +.B +mpint* uvtomp(uvlong, mpint*) +.PP +.B +uvlong mptouv(mpint*) +.PP +.B +void mpadd(mpint *b1, mpint *b2, mpint *sum) +.PP +.B +void mpmagadd(mpint *b1, mpint *b2, mpint *sum) +.PP +.B +void mpsub(mpint *b1, mpint *b2, mpint *diff) +.PP +.B +void mpmagsub(mpint *b1, mpint *b2, mpint *diff) +.PP +.B +void mpleft(mpint *b, int shift, mpint *res) +.PP +.B +void mpright(mpint *b, int shift, mpint *res) +.PP +.B +void mpmul(mpint *b1, mpint *b2, mpint *prod) +.PP +.B +void mpexp(mpint *b, mpint *e, mpint *m, mpint *res) +.PP +.B +void mpmod(mpint *b, mpint *m, mpint *remainder) +.PP +.B +void mpdiv(mpint *dividend, mpint *divisor, mpint *quotient, mpint *remainder) +.PP +.B +int mpcmp(mpint *b1, mpint *b2) +.PP +.B +int mpmagcmp(mpint *b1, mpint *b2) +.PP +.B +void mpextendedgcd(mpint *a, mpint *b, mpint *d, mpint *x, mpint *y) +.PP +.B +void mpinvert(mpint *b, mpint *m, mpint *res) +.PP +.B +int mpsignif(mpint *b) +.PP +.B +int mplowbits0(mpint *b) +.PP +.B +void mpdigdiv(mpdigit *dividend, mpdigit divisor, mpdigit *quotient) +.PP +.B +void mpvecadd(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *sum) +.PP +.B +void mpvecsub(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *diff) +.PP +.B +void mpvecdigmuladd(mpdigit *b, int n, mpdigit m, mpdigit *p) +.PP +.B +int mpvecdigmulsub(mpdigit *b, int n, mpdigit m, mpdigit *p) +.PP +.B +void mpvecmul(mpdigit *a, int alen, mpdigit *b, int blen, mpdigit *p) +.PP +.B +int mpveccmp(mpdigit *a, int alen, mpdigit *b, int blen) +.PP +.B +CRTpre* crtpre(int nfactors, mpint **factors) +.PP +.B +CRTres* crtin(CRTpre *crt, mpint *x) +.PP +.B +void crtout(CRTpre *crt, CRTres *r, mpint *x) +.PP +.B +void crtprefree(CRTpre *cre) +.PP +.B +void crtresfree(CRTres *res) +.PP +.B +mpint *mpzero, *mpone, *mptwo +.SH DESCRIPTION +.PP +These routines perform extended precision integer arithmetic. +The basic type is +.BR mpint , +which points to an array of +.BR mpdigit s, +stored in little-endian order: +.sp +.EX +typedef struct mpint mpint; +struct mpint +{ + int sign; /* +1 or -1 */ + int size; /* allocated digits */ + int top; /* significant digits */ + mpdigit *p; + char flags; +}; +.EE +.PP +The sign of 0 is +1. +.PP +The size of +.B mpdigit +is architecture-dependent and defined in +.BR /$cputype/include/u.h . +.BR Mpint s +are dynamically allocated and must be explicitly freed. Operations +grow the array of digits as needed. +.PP +In general, the result parameters are last in the +argument list. +.PP +Routines that return an +.B mpint +will allocate the +.B mpint +if the result parameter is +.BR nil . +This includes +.IR strtomp , +.IR itomp , +.IR uitomp , +and +.IR btomp . +These functions, in addition to +.I mpnew +and +.IR mpcopy , +will return +.B nil +if the allocation fails. +.PP +Input and result parameters may point to the same +.BR mpint . +The routines check and copy where necessary. +.PP +.I Mpnew +creates an +.B mpint +with an initial allocation of +.I n +bits. +If +.I n +is zero, the allocation will be whatever was specified in the +last call to +.I mpsetminbits +or to the initial value, 1056. +.I Mpfree +frees an +.BR mpint . +.I Mpbits +grows the allocation of +.I b +to fit at least +.I n +bits. If +.B b->top +doesn't cover +.I n +bits it increases it to do so. +Unless you are writing new basic operations, you +can restrict yourself to +.B mpnew(0) +and +.BR mpfree(b) . +.PP +.I Mpnorm +normalizes the representation by trimming any high order zero +digits. All routines except +.B mpbits +return normalized results. +.PP +.I Mpcopy +creates a new +.B mpint +with the same value as +.I b +while +.I mpassign +sets the value of +.I new +to be that of +.IR old . +.PP +.I Mprand +creates an +.I n +bit random number using the generator +.IR gen . +.I Gen +takes a pointer to a string of uchar's and the number +to fill in. +.PP +.I Strtomp +and +.I mptoa +convert between +.SM ASCII +and +.B mpint +representations using the base indicated. +Only the bases 10, 16, 32, and 64 are +supported. Anything else defaults to 16. +.IR Strtomp +skips any leading spaces or tabs. +.IR Strtomp 's +scan stops when encountering a digit not valid in the +base. If +.I rptr +is not zero, +.I *rptr +is set to point to the character immediately after the +string converted. +If the parse pterminates before any digits are found, +.I strtomp +return +.BR nil . +.I Mptoa +returns a pointer to the filled buffer. +If the parameter +.I buf +is +.BR nil , +the buffer is allocated. +.I Mpfmt +can be used with +.IR fmtinstall (2) +and +.IR print (2) +to print hexadecimal representations of +.BR mpint s. +.PP +.I Mptobe +and +.I mptole +convert an +.I mpint +to a byte array. The former creates a big endian representation, +the latter a little endian one. +If the destination +.I buf +is not +.BR nil , +it specifies the buffer of length +.I blen +for the result. If the representation +is less than +.I blen +bytes, the rest of the buffer is zero filled. +If +.I buf +is +.BR nil , +then a buffer is allocated and a pointer to it is +deposited in the location pointed to by +.IR bufp . +.PP +.IR Betomp , +and +.I letomp +convert from a big or little endian byte array at +.I buf +of length +.I blen +to an +.IR mpint . +If +.I b +is not +.IR nil , +it refers to a preallocated +.I mpint +for the result. +If +.I b +is +.BR nil , +a new integer is allocated and returned as the result. +.PP +The integer conversions are: +.TF Mptouv +.TP +.I mptoui +.BR mpint -> "unsigned int" +.TP +.I uitomp +.BR "unsigned int" -> mpint +.TP +.I mptoi +.BR mpint -> "int" +.TP +.I itomp +.BR "int" -> mpint +.TP +.I mptouv +.BR mpint -> "unsigned vlong" +.TP +.I uvtomp +.BR "unsigned vlong" -> mpint +.TP +.I mptov +.BR mpint -> "vlong" +.TP +.I vtomp +.BR "vlong" -> mpint +.PD +.PP +When converting to the base integer types, if the integer is too large, +the largest integer of the appropriate sign +and size is returned. +.PP +The mathematical functions are: +.TF mpmagadd +.TP +.I mpadd +.BR "sum = b1 + b2" . +.TP +.I mpmagadd +.BR "sum = abs(b1) + abs(b2)" . +.TP +.I mpsub +.BR "diff = b1 - b2" . +.TP +.I mpmagsub +.BR "diff = abs(b1) - abs(b2)" . +.TP +.I mpleft +.BR "res = b<>shift" . +.TP +.I mpmul +.BR "prod = b1*b2" . +.TP +.I mpexp +if +.I m +is nil, +.BR "res = b**e" . +Otherwise, +.BR "res = b**e mod m" . +.TP +.I mpmod +.BR "remainder = b % m" . +.TP +.I mpdiv +.BR "quotient = dividend/divisor" . +.BR "remainder = dividend % divisor" . +.TP +.I mpcmp +returns -1, 0, or +1 as +.I b1 +is less than, equal to, or greater than +.IR b2 . +.TP +.I mpmagcmp +the same as +.I mpcmp +but ignores the sign and just compares magnitudes. +.PD +.PP +.I Mpextendedgcd +computes the greatest common denominator, +.IR d , +of +.I a +and +.IR b . +It also computes +.I x +and +.I y +such that +.BR "a*x + b*y = d" . +.PP +.I Mpinverse +computes the multiplicative inverse of +.I b +.B mod +.IR m . +.PP +.I Mpsignif +returns the bit offset of the left most 1 bit in +.IR b . +.I Mplowbits0 +returns the bit offset of the right most 1 bit. +For example, for 0x14, +.I mpsignif +would return 4 and +.I mplowbits0 +would return 2. +.PP +The remaining routines all work on arrays of +.B mpdigit +rather than +.BR mpint 's. +They are the basis of all the other routines. They are separated out +to allow them to be rewritten in assembler for each architecture. There +is also a portable C version for each one. +.TF mpvecdigmuladd +.TP +.I mpdigdiv +.BR "quotient = dividend[0:1] / divisor" . +.TP +.I mpvecadd +.BR "sum[0:alen] = a[0:alen-1] + b[0:blen-1]" . +We assume alen >= blen and that sum has room for alen+1 digits. +.TP +.I mpvecsub +.BR "diff[0:alen-1] = a[0:alen-1] - b[0:blen-1]" . +We assume that alen >= blen and that diff has room for alen digits. +.TP +.I mpvecdigmuladd +.BR "p[0:n] += m * b[0:n-1]" . +This multiplies a an array of digits times a scalar and adds it to another array. +We assume p has room for n+1 digits. +.TP +.I mpvecdigmulsub +.BR "p[0:n] -= m * b[0:n-1]" . +This multiplies a an array of digits times a scalar and subtracts it fromo another array. +We assume p has room for n+1 digits. It returns +1 is the result is positive and +-1 if negative. +.TP +.I mpvecmul +.BR "p[0:alen*blen] = a[0:alen-1] * b[0:blen-1]" . +We assume that p has room for alen*blen+1 digits. +.TP +.I mpveccmp +This returns -1, 0, or +1 as a - b is negative, 0, or positive. +.PD +.PP +.IR mptwo , +.I mpone +and +.I mpzero +are the constants 2, 1 and 0. These cannot be freed. +.SS "Chinese remainder theorem +.PP +When computing in a non-prime modulus, +.IR n, +it is possible to perform the computations on the residues modulo the prime +factors of +.I n +instead. Since these numbers are smaller, multiplication and exponentiation +can be much faster. +.PP +.I Crtin +computes the residues of +.I x +and returns them in a newly allocated structure: +.EX + typedef struct CRTres CRTres; + { + int n; // number of residues + mpint *r[n]; // residues + }; +.EE +.PP +.I Crtout +takes a residue representation of a number and converts it back into +the number. It also frees the residue structure. +.PP +.I Crepre +saves a copy of the factors and precomputes the constants necessary +for converting the residue form back into a number modulo +the product of the factors. It returns a newly allocated structure +containing values. +.PP +.I Crtprefree +and +.I crtresfree +free +.I CRTpre +and +.I CRTres +structures respectively. +.SH SOURCE +.B /sys/src/libmp diff --git a/static/plan9-4e/man2/muldiv.2 b/static/plan9-4e/man2/muldiv.2 new file mode 100644 index 00000000..93444bd5 --- /dev/null +++ b/static/plan9-4e/man2/muldiv.2 @@ -0,0 +1,31 @@ +.TH MULDIV 2 +.SH NAME +muldiv, umuldiv \- high-precision multiplication and division +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long muldiv(long a, long b, long c) +.PP +.B +ulong umuldiv(ulong a, ulong b, ulong c) +.SH DESCRIPTION +.I Muldiv +returns +.BR a*b/c , +using a +.B vlong +to hold the intermediate result. +.I Umuldiv +is the equivalent for unsigned integers. +They can be used to scale integer values without worry about +overflowing the intermediate result. +.PP +On some architectures, these routines can generate a trap if the +final result does not fit in a +.B long +or +.BR ulong ; +on others they will silently truncate. diff --git a/static/plan9-4e/man2/nan.2 b/static/plan9-4e/man2/nan.2 new file mode 100644 index 00000000..84ede0db --- /dev/null +++ b/static/plan9-4e/man2/nan.2 @@ -0,0 +1,44 @@ +.TH NAN 2 +.SH NAME +NaN, Inf, isNaN, isInf \- not-a-number and infinity functions +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +double NaN(void) +.PP +.B +double Inf(int) +.PP +.B +int isNaN(double) +.PP +.B +int isInf(double, int) +.SH DESCRIPTION +The IEEE floating point standard defines values called +`not-a-number' and positive and negative `infinity'. +These values can be produced by such things as overflow +and division by zero. +Also, the library functions sometimes return them when +the arguments are not in the domain, or the result is +out of range. +.PP +.I NaN +returns a double that is not-a-number. +.I IsNaN +returns true if its argument is not-a-number. +.PP +.IR Inf ( i ) +returns positive infinity if +.I i +is greater than or equal to zero, +else negative infinity. +.I IsInf +returns true if its first argument is infinity +with the same sign as the second argument. +.SH SOURCE +.B /sys/src/libc/port/nan.c diff --git a/static/plan9-4e/man2/ndb.2 b/static/plan9-4e/man2/ndb.2 new file mode 100644 index 00000000..9386686e --- /dev/null +++ b/static/plan9-4e/man2/ndb.2 @@ -0,0 +1,366 @@ +.TH NDB 2 +.SH NAME +ndbopen, ndbcat, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetval, ndbfree, ipattr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetval, ndblookval, dnsquery \- network database +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.ta \w'\fLNdbtuplexx 'u +.PP +.B +Ndb* ndbopen(char *file) +.PP +.B +Ndb* ndbcat(Ndb *db1, Ndb *db2) +.PP +.B +int ndbreopen(Ndb *db) +.PP +.B +void ndbclose(Ndb *db) +.PP +.B +Ndbtuple* ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val) +.PP +.B +Ndbtuple* ndbsnext(Ndbs *s, char *attr, char *val) +.PP +.B +Ndbtuple* ndbgetval(Ndb *db, Ndbs *s, char *attr, char *val, +.br +.B + char *rattr, char *buf) +.PP +.B +Ndbtuple* csgetval(char *netroot, char *attr, char *val, char *rattr, char *buf) +.PP +.B +void ndbfree(Ndbtuple *db) +.PP +.B +char* ipattr(char *name) +.PP +.B +Ndbtuple* ndbipinfo(Ndb *db, char *attr, char *val, char **attrs, +.br +.B int nattr) +.PP +.B +Ndbtuple* csipinfo(char *netroot, char *attr, char *val, char **attrs, +.br +.B int nattr) +.PP +.B +ulong ndbhash(char *val, int hlen) +.PP +.B +Ndbtuple* ndbparse(Ndb *db) +.PP +.B +Ndbtuple* dnsquery(char *netroot, char *domainname, char *type) +.PP +.B +Ndbtuple* ndblookval(Ndbtuple *entry, Ndbtuple *line, char *attr, char *to) +.SH DESCRIPTION +These routines are used by network administrative programs to search +the network database. +They operate on the database files described in +.IR ndb (6). +.PP +.I Ndbopen +opens the database +.I file +and calls +.IR malloc (2) +to allocate a buffer for it. +If +.I file +is zero, all network database files are opened. +.PP +.I Ndbcat +concatenates two open databases. Either argument may be +nil. +.PP +.I Ndbreopen +checks if the database files associated with +.I db +have changed and if so throws out any cached information and reopens +the files. +.PP +.I Ndbclose +closes any database files associated with +.I db +and frees all storage associated with them. +.PP +.I Ndbsearch +and +.I ndbsnext +search a database for an entry containing the +attribute/value pair, +.IR attr = val . +.I Ndbsearch +is used to find the first match and +.I ndbsnext +is used to find each successive match. +On a successful search both return a linked list of +.I Ndbtuple +structures acquired by +.IR malloc (2) +that represent the attribute/value pairs in the +entry. +On failure they return zero. +.IP +.EX +typedef struct Ndbtuple Ndbtuple; +struct Ndbtuple { + char attr[Ndbalen]; + char val[Ndbvlen]; + Ndbtuple *entry; + Ndbtuple *line; + ulong ptr; /* for the application; starts 0 */ +}; +.EE +.LP +The +.I entry +pointers chain together all pairs in the entry in a null-terminated list. +The +.I line +pointers chain together all pairs on the same line +in a circular list. +Thus, a program can implement 2 levels of binding for +pairs in an entry. +In general, pairs on the same line are bound tighter +than pairs on different lines. +.PP +The argument +.I s +of +.I ndbsearch +has type +.I Ndbs +and should be pointed to valid storage before calling +.IR ndbsearch , +which will fill it with information used by +.I ndbsnext +to link successive searches. +The structure +.I Ndbs +looks like: +.IP +.EX +typedef struct Ndbs Ndbs; +struct Ndbs { + Ndb *db; /* data base file being searched */ + ... + Ndbtuple *t; /* last attribute value pair found */ +}; +.EE +.LP +The +.I t +field points to the pair within the entry matched by the +.I ndbsearch +or +.IR ndbsnext . +.PP +.I Ndbgetval +searches the database for an entry containing not only an +attribute/value pair, +.IR attr = val , +but also a pair with the attribute +.IR rattr . +If successful, it copies the value associated with +.I rattr +into +.IR buf . +.I Buf +must point to an area at least +.I Ndbvlen +long. +.I Csgetval +is like +.I ndbgetval +but queries the connection server +instead of looking directly at the database. +It's first argument specifies the network root to use. +If the argument is 0, it defaults to +\f5"/net"\f1. +.PP +.I Ndbfree +frees a list of tuples returned by one of the other +routines. +.PP +.I Ipattr +takes the name of an IP system and returns the attribute +it corresponds to: +.RS +.TP +.B dom +domain name +.TP +.B ip +Internet number +.TP +.B sys +system name +.RE +.PP +.I Ndbipinfo +looks up Internet protocol information about a system. +This is an IP aware search. It looks first for information +in the system's database entry and then in the database entries +for any IP subnets or networks containing the system. +The system is identified by the +attribute/value pair, +.IR attr = val . +.I Ndbipinfo +returns a list of tuples whose attributes match the +attributes in the +.I n +element array +.IR attrs . +For example, consider the following database entries describing a network, +a subnetwork, and a system. +.PP +.EX +ipnet=big ip=10.0.0.0 ipsubmask=255.255.255.0 + dns=dns.big.com + smtp=smtp.big.com +ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0 + smtp=smtp1.big.com +ip=10.1.1.4 dom=x.big.com + bootf=/386/9pc +.EE +.PP +Calling +.PP +.EX + ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3) +.EE +.PP +will return the tuples +.BR bootf=/386/9pc , +.BR smtp=smtp1.big.com , +and +.BR dns=dns.big.com . +.PP +.I Csipinfo +is to +.I ndbipinfo +as +.I csgetval +is to +.IR ndbgetval . +.PP +The last three calls are used by programs that create the +hash tables and database files. +.I Ndbhash +computes a hash offset into a table of length +.I hlen +for the string +.IR val . +.I Ndbparse +reads and parses the next entry from the database file. +Multiple calls to +.IR ndbparse +parse sequential entries in the database file. +A zero is returned at end of file. +.PP +.I Dnsquery +submits a query about +.I domainname +to the +.I ndb/dns +mounted at +.IB netroot /dns. +It returns a linked list of +.I Ndbtuple's +representing a single database entry. +The tuples are logicly arranged into lines using the +.B line +fieldin the structure. +The possible +.IR type 's +of query are and the attributes on each returned tuple line is: +.TP +.B ip +find the IP addresses. Returns +domain name +.RI ( dom ) +and ip address +.RI ( ip ) +.TP +.B mx +look up the mail exchangers. Returns preference +.RI ( pref ) +and exchanger +.RI ( mx ) +.TP +.B ptr +do a reverse query. Here +.I domainname +must be an +.SM ASCII +IP address. Returns reverse name +.RI ( ptr ) +and domain name +.RI ( dom ) +.TP +.B cname +get the system that this name is a nickname for. Returns the nickname +.RI ( dom ) +and the real name +.RI ( cname ) +.TP +.B soa +return the start of area record for this field. Returns +area name +.RI ( dom ), +primary name server +.RI ( ns ), +serial number +.RI ( serial ), +refresh time in seconds +.RI ( refresh ), +retry time in seconds +.RI ( retry ), +expiration time in seconds +.RI ( expire ), +and minimum time to lie +.RI ( ttl ). +.TP +.B ns +name servers. Returns domain name +.RI ( dom ) +and name server +.RI ( ns ) +.PP +.I Ndblookval +searches +.I entry +for the tuple +with attribute +.IR attr , +copies the value into +.IR to , +and returns a pointer to the tuple. +If +.I line +points to a particular line in the entry, the +search starts there and then wraps around to the beginning +of the entry. +.SH FILES +.BR /lib/ndb " directory of network database files +.SH SOURCE +.B /sys/src/libndb +.SH SEE ALSO +.IR ndb (6) +.IR ndb (8) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/static/plan9-4e/man2/notify.2 b/static/plan9-4e/man2/notify.2 new file mode 100644 index 00000000..e5ea81ac --- /dev/null +++ b/static/plan9-4e/man2/notify.2 @@ -0,0 +1,243 @@ +.TH NOTIFY 2 +.SH NAME +notify, noted, atnotify \- handle asynchronous process notification +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int notify(void (*f)(void*, char*)) +.PP +.B +int noted(int v) +.PP +.B +int atnotify(int (*f)(void*, char*), int in) +.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 (2)) +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. +The +.I notify +function registers a +.I "notification handler +to be called within the process when a note is received. +The argument to +.I notify +replaces the previous handler, if any. +An argument of zero cancels a previous handler, +restoring the default action. +A +.IR fork (2) +system call leaves the handler registered in +both the parent and the child; +.IR exec (2) +restores the default behavior. +.PP +After a note is posted, +the handler is called with two arguments: +the first is a pointer to a +.B Ureg +structure (defined in +.BR /$objtype/include/ureg.h ) +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. +.PP +A notification handler must finish either by exiting the program or by calling +.IR noted ; +if the handler returns the behavior +is undefined and probably erroneous. +Until the program calls +.IR noted , +any further externally-generated notes +(e.g., +.B hangup +or +.BR alarm ) +will be held off, and any further notes generated by +erroneous behavior by the program +(such as divide by zero) will kill the program. +The argument to +.I noted +defines the action to take: +.B NDFLT +instructs the system to perform the default action +as if the handler had never been registered; +.B NCONT +instructs the system to resume the process +at the point it was notified. +In neither case does +.I noted +return to the handler. +If the note interrupted an incomplete system call, +that call returns an error (with error string +.BR interrupted ) +after the process resumes. +A notification handler can also jump out to an environment +set up with +.I setjmp +using the +.I notejmp +function (see +.IR setjmp (2)), +which is implemented by modifying the saved state and calling +.BR noted(NCONT) . +.PP +Regardless of the origin of the note or the presence of a handler, +if the process is being debugged +(see +.IR proc (3)) +the arrival of a note puts the process in the +.B Stopped +state and awakens the debugger. +.PP +Rather than using the system calls +.I notify +and +.IR noted , +most programs should use +.I atnotify +to register notification handlers. +The parameter +.I in +is non-zero to register the function +.IR f , +and zero to cancel registration. +A handler must return a non-zero number +if the note was recognized (and resolved); +otherwise it must return zero. +When the system posts a note to the process, +each handler registered with +.I atnotify +is called with arguments as +described above +until one of the handlers returns non-zero. +Then +.I noted +is called with argument +.BR NCONT . +If no registered function returns non-zero, +.I atnotify +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 +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) +.fi +.RE +.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. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/atnotify.c +.SH SEE ALSO +.IR intro (2), +.I notejmp +in +.IR setjmp (2) +.SH BUGS +Since +.IR exec (2) +discards the notification handler, there is a window +of vulnerability to notes in a new process. diff --git a/static/plan9-4e/man2/object.2 b/static/plan9-4e/man2/object.2 new file mode 100644 index 00000000..29a6bde3 --- /dev/null +++ b/static/plan9-4e/man2/object.2 @@ -0,0 +1,150 @@ +.TH OBJECT 2 +.SH NAME +objtype, readobj, objtraverse, isar, nextar, readar \- object file interpretation functions +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int objtype(Biobuf *bp, char **name) +.PP +.B +int readobj(Biobuf *bp, int objtype) +.PP +.B +void objtraverse(void(*)(Sym*, void*), void*) +.PP +.B +int isar(Biobuf *bp) +.PP +.B +int nextar(Biobuf *bp, int offset, char *buf) +.PP +.B +int readar(Biobuf *bp, int objtype, int end) +.SH DESCRIPTION +These functions provide machine-independent access to object files +in a directory or an archive. +.IR Mach (2) +and +.IR symbol (2) +describe additional library functions +for interpreting executable files and executing images. +.PP +Object files contain no formal symbol table; instead, references +to symbols must be extracted from the encoded object representation +and resolved. The resulting symbol information is loaded +into a dummy symbol table where it is available for processing by an +application. The organization of the dummy symbol +table is identical +to that produced by the loader and described in +.IR symbol (2) +and +.IR a.out (6): +a vector of +.B Sym +data structures defining the name, type and relative offset of +each symbol. +.PP +.I Objtype +reads the header at the current position of the +file associated with +.I bp +(see +.IR Bio (2)) +to see if it is an intermediate object file. +If it is, a code indicating the architecture type of the file +is returned and the second argument, if it is non-zero, +is set pointing to a string describing the type of the file. +If the header does not indicate an object file, +\-1 is returned. +The header may be at the start of an object +file or at the beginning of an archive member. The +file is rewound to its starting +position after decoding the header. +.PP +.I Readobj +constructs a symbol table for the object file associated with +.IR bp . +The second argument contains the type code produced by +function +.IR objtype . +The file must be positioned at the start of the object file. +Each invocation of +.I readobj +destroys the symbol definitions for any previous file. +.PP +.I Objtraverse +scans the symbol table previously built by +.I readobj +or +.IR readar . +.I Objtraverse +requires two arguments: +the address of a call-back function and a +generic pointer. The call-back function +is invoked once for each symbol in the symbol table with +the address of a +.I Sym +data structure as the first argument and the +generic pointer as the second. +.PP +.I Isar +reads the header at the current point in the file +associated with +.I bp +and returns 1 if it is an archive or zero otherwise. +The file is positioned at the end of the archive +header and at the beginning of the first member of the archive. +.PP +.I Nextar +extracts information describing the archive member stored +at +.I offset +in the file associated with +.IR bp . +If the header describing the member can be +extracted and decoded, the size of the member is +returned. Adding this value to +.I offset +yields the offset of the beginning of the next member +in the archive. On return the input file is positioned +at the end of the member header +and the name of the member is stored in +.IR buf , +a buffer of +.B SARNAME +characters. +If there are no more members, +.I nextar +returns zero; a negative return indicates a missing +or malformed header. +.PP +.I Readar +constructs the symbol table of the object file stored +at the current position in the archive associated with +.IR bp . +This function operates exactly as +.IR readobj ; +the only difference is the extra argument, +.IR end , +specifying the offset to the beginning of the +next member in the archive. +.I Readar +leaves the file positioned at that point. +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR symbol (2), +.IR bio (2), +.IR a.out (6) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/static/plan9-4e/man2/open.2 b/static/plan9-4e/man2/open.2 new file mode 100644 index 00000000..10852cff --- /dev/null +++ b/static/plan9-4e/man2/open.2 @@ -0,0 +1,148 @@ +.TH OPEN 2 +.SH NAME +open, create, close \- open a file for reading or writing, create file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int open(char *file, int omode) +.PP +.B +int create(char *file, int omode, ulong perm) +.PP +.B +int close(int fd) +.SH DESCRIPTION +.I Open +opens the +.I file +for I/O and returns an associated file descriptor. +.I Omode +is one of +.BR OREAD , +.BR OWRITE , +.BR ORDWR , +or +.BR OEXEC , +asking for permission to read, write, read and write, or execute, respectively. +In addition, there are three values that can be ORed with the +.IR omode : +.B OTRUNC +says to truncate the file +to zero length before opening it; +.B OCEXEC +says to close the file when an +.IR exec (2) +or +.I execl +system call is made; +and +.B ORCLOSE +says to remove the file when it is closed (by everyone who has a copy of the file descriptor). +.I Open +fails if the file does not exist or the user does not have +permission to open it for the requested purpose +(see +.IR stat (2) +for a description of permissions). +The user must have write permission on the +.I file +if the +.B OTRUNC +bit is set. +For the +.I open +system call +(unlike the implicit +.I open +in +.IR exec (2)), +.B OEXEC +is actually identical to +.BR OREAD . +.PP +.I Create +creates a new +.I file +or prepares to rewrite an existing +.IR file , +opens it according to +.I omode +(as described for +.IR open ), +and returns an associated file descriptor. +If the file is new, +the owner is set to the userid of the creating process group; +the group to that of the containing directory; +the permissions to +.I perm +ANDed with the permissions of the containing directory. +If the file already exists, +it is truncated to 0 length, +and the permissions, owner, and group remain unchanged. +The created file is a directory if the +.B DMDIR +bit is set in +.IR perm , +an exclusive-use file if the +.B DMEXCL +bit is set, and an append-only file if the +.B DMAPPEND +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). +.PP +.I Create +fails if the path up to the last element of +.I file +cannot be evaluated, if the user doesn't have write permission +in the final directory, if the file already exists and +does not permit the access defined by +.IR omode , +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 (2)) +then the constituent directory where the file is created +depends on the structure of the union: see +.IR bind (2). +.PP +Since +.I create +may succeed even if the file exists, a special mechanism is necessary +for those applications that require an atomic create operation. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.IR create, +the call succeeds only if the file does not already exist; +see +.IR open (5) +for details. +.PP +.I Close +closes the file associated with a file descriptor. +Provided the file descriptor is a valid open descriptor, +.I close +is guaranteed to close it; there will be no error. +Files are closed automatically upon termination of a process; +.I close +allows the file descriptor to be reused. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR bind (2), +.IR stat (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/static/plan9-4e/man2/perror.2 b/static/plan9-4e/man2/perror.2 new file mode 100644 index 00000000..9d2856cb --- /dev/null +++ b/static/plan9-4e/man2/perror.2 @@ -0,0 +1,92 @@ +.TH PERROR 2 +.SH NAME +perror, syslog, sysfatal \- system error messages +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +void perror(char *s) +.PP +.B +void syslog(int cons, char *logname, char *fmt, ...) +.PP +.B +void sysfatal(char *fmt, ...) +.SH DESCRIPTION +.I Perror +produces a short error message +on the standard error file +describing the last error encountered during a call +to the system. +First the argument string +.I s +is printed, then a colon, then the message and a newline. +If +.I s +is nil, only the error message and newline are printed. +.PP +.I Syslog +logs messages in the file named by +.I logname +in the directory +.BR /sys/log ; +the file must already exist and should be append-only. +.I Logname +must contain no slashes. +The message is a line with several fields: +the name of the machine writing the message; +the date and time; +the message specified by the +.IR print (2) +format +.I fmt +and any following arguments; +and a final newline. +If +.I cons +is set or the log file cannot be opened, the message is also printed +on the system console. +.I Syslog +can be used safely in multi-threaded programs. +.PP +.I Sysfatal +prints to standard error the name of the running program, +a colon and a space, +the message described by the +.IR print (2) +format string +.I fmt +and subsequent arguments, and a newline. +It then calls +.IR exits (2) +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 (2) +interface to process its arguments. +If +.B argv0 +is null, it is ignored and the following colon and space are suppressed. +.SH SOURCE +.B /sys/src/libc/port/perror.c +.br +.B /sys/src/libc/9sys/syslog.c +.br +.B /sys/src/libc/9sys/sysfatal.c +.SH "SEE ALSO" +.IR intro (2), +.IR errstr (2), +the +.B %r +format in +.IR print (2) +.SH BUGS +.I Perror +is a holdover; the +.B %r +format in +.IR print (2) +is preferred. diff --git a/static/plan9-4e/man2/pipe.2 b/static/plan9-4e/man2/pipe.2 new file mode 100644 index 00000000..d91fc081 --- /dev/null +++ b/static/plan9-4e/man2/pipe.2 @@ -0,0 +1,74 @@ +.TH PIPE 2 +.SH NAME +pipe \- create an interprocess channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int pipe(int fd[2]) +.SH DESCRIPTION +.I Pipe +creates a buffered channel for interprocess I/O communication. +Two file descriptors are returned in +.IR fd . +Data written to +.B fd[1] +is available for reading from +.B fd[0] +and data written to +.B fd[0] +is available for reading from +.BR fd[1] . +.PP +After the pipe has been established, +cooperating processes +created by subsequent +.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 (2) +is reported +in the +.B Length +field returned by +.I fstat +or +.I dirfstat +on a pipe (see +.IR stat (2)). +.PP +When all the data has been read from a pipe and the writer has closed the pipe or exited, +.IR read (2) +will return 0 bytes. Writes to a pipe with no reader will generate a note +.BR "sys: write on closed pipe" . +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR read (2), +.IR pipe (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. diff --git a/static/plan9-4e/man2/plumb.2 b/static/plan9-4e/man2/plumb.2 new file mode 100644 index 00000000..c9d52165 --- /dev/null +++ b/static/plan9-4e/man2/plumb.2 @@ -0,0 +1,240 @@ +.TH PLUMB 2 +.SH NAME +eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLPlumbattr* 'u +.PP +.B +int plumbopen(char *port, int omode) +.PP +.B +int plumbsend(int fd, Plumbmsg *m) +.PP +.B +int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data) +.PP +.B +void plumbfree(Plumbmsg *m) +.PP +.B +Plumbmsg* plumbrecv(int fd) +.PP +.B +char* plumbpack(Plumbmsg *m, int *np) +.PP +.B +Plumbmsg* plumbunpack(char *buf, int n) +.PP +.B +Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep) +.PP +.B +char* plumbpackattr(Plumbattr *a) +.PP +.B +Plumbattr* plumbunpackattr(char *a) +.PP +.B +char* plumblookup(Plumbattr *a, char *name) +.PP +.B +Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) +.PP +.B +Plumbattr* plumbdelattr(Plumbattra *a, char *name) +.PP +.B +int eplumb(int key, char *port) +.SH DESCRIPTION +These routines manipulate +.IR plumb (6) +messages, transmitting them, receiving them, and +converting them between text and these data structures: +.IP +.EX +.ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u +typedef +struct Plumbmsg +{ + char *src; + char *dst; + char *wdir; + char *type; + Plumbattr *attr; + int ndata; + char *data; +} Plumbmsg; + +typedef +struct Plumbattr +{ + char *name; + char *value; + Plumbattr *next; +} Plumbattr; +.EE +.PP +.I Plumbopen +opens the named plumb +.IR port , +using +.IR open (2) +mode +.IR omode . +If +.I port +begins with a slash, it is taken as a literal file name; +otherwise +.I plumbopen +searches for the location of the +.IR plumber (4) +service and opens the port there. +.PP +For programs using the +.IR event (2) +interface, +.I eplumb +registers, using the given +.IR key , +receipt of messages from the named +.IR port . +.PP +.I Plumbsend +formats and writes message +.I m +to the file descriptor +.IR fd , +which will usually be the result of +.B plumbopen("send", +.BR OWRITE) . +.I Plumbsendtext +is a simplified version for text-only messages; it assumes +.B type +is +.BR text , +sets +.B attr +to nil, +and sets +.B ndata +to +.BI strlen( data )\f1. +.PP +.I Plumbfree +frees all the data associated with the message +.IR m , +all the components of which must therefore have been allocated with +.IR malloc (2). +.PP +.I Plumbrecv +returns the next message available on the file descriptor +.IR fd , +or nil for error. +.PP +.I Plumbpack +encodes message +.I m +as a character string in the format of +.IR plumb (6) , +setting +.BI * np +to the length in bytes of the string. +.I Plumbunpack +does the inverse, translating the +.I n +bytes of +.I buf +into a +.BR Plumbmsg . +.PP +.I Plumbunpackpartial +enables unpacking of messages that arrive in pieces. +The first call to +.I plumbunpackpartial +for a given message must be sufficient to unpack the header; +subsequent calls permit unpacking messages with long data sections. +For each call, +.I buf +points to the beginning of the complete message received so far, and +.I n +reports the total number of bytes received for that message. +If the message is complete, the return value will be as in +.IR plumbunpack . +If not, and +.I morep +is not null, the return value will be +.B nil +and +.BR * morep +will be set to the number of bytes remaining to be read for this message to be complete +(recall that the byte count is in the header). +Those bytes should be read by the caller, placed at location +.IB buf + n \f1, +and the message unpacked again. +If an error is encountered, the return value will be +.B nil +and +.BI * morep +will be zero. +.PP +.I Plumbpackattr +converts the list +.I a +of +.B Plumbattr +structures into a null-terminated string. +If an attribute value contains white space, quote characters, or equal signs, +the value will be quoted appropriately. +A newline character will terminate processing. +.I Plumbunpackattr +converts the null-terminated string +.I a +back into a list of +.I Plumbattr +structures. +.PP +.I Plumblookup +searches the +.B Plumbattr +list +.I a +for an attribute with the given +.I name +and returns the associated value. +The returned string is the original value, not a copy. +If the attribute has no value, the returned value will be the empty string; +if the attribute does not occur in the list at all, the value will be nil. +.PP +.I Plumbaddattr +appends the +.I new +.B Plumbattr +(which may be a list) to the attribute list +.IR a +and returns the new list. +.I Plumbattr +searches the list +.I a +for the first attribute with name +.I name +and deletes it from the list, returning the resulting list. +.I Plumbdelattr +is a no-op if no such attribute exists. +.SH SOURCE +.B /sys/src/libplumb +.SH SEE ALSO +.IR plumb (1), +.IR event (2), +.IR plumber (4), +.IR plumb (6) +.SH DIAGNOSTICS +When appropriate, including when a +.I plumbsend +fails, these routine set +.IR errstr . diff --git a/static/plan9-4e/man2/pool.2 b/static/plan9-4e/man2/pool.2 new file mode 100644 index 00000000..d4b46a08 --- /dev/null +++ b/static/plan9-4e/man2/pool.2 @@ -0,0 +1,329 @@ +.TH POOL 2 +.SH NAME +poolalloc, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck, +pooldump \- general memory management routines +.SH SYNOPSIS +.B #include +.PP +.B #include +.PP +.B #include +.PP +.B +void* poolalloc(Pool* pool, ulong size) +.PP +.B +void poolfree(Pool* pool, void* ptr) +.PP +.B +ulong poolmsize(Pool* pool, void* ptr) +.PP +.B +void* poolrealloc(Pool* pool, void* ptr, ulong size) +.PP +.B +void poolcompact(Pool* pool) +.PP +.B +void poolcheck(Pool *pool) +.PP +.B +void poolblockcheck(Pool *pool, void *ptr) +.PP +.B +void pooldump(Pool *pool); +.SH DESCRIPTION +These routines provide a general memory management facility. +Memory is retrieved from a coarser allocator (e.g. +.I sbrk +or the kernel's +.IR xalloc ) +and then allocated to callers. +The routines are locked and thus may safely be used in +multiprocess programs. +.PP +.I Poolalloc +attempts to allocate a block of size +.BR size ; +it returns a pointer to the block when successful and nil otherwise. +The call +.B "poolalloc(0) +returns a non-nil pointer. +.I Poolfree +returns an allocated block to the pool. +It is an error to free a block more than once or to free a +pointer not returned by +.IR poolalloc . +The call +.B "poolfree(nil) +is legal and is a no-op. +.I Poolrealloc +attempts to resize to +.B nsize +bytes the block associated with +.BR ptr , +which must have been previously returned by +.I poolalloc +or +.IR poolrealloc . +If the block's size can be adjusted, a (possibly different) pointer to the new block is returned. +The contents up to the lesser of the old and new sizes are unchanged. +After a successful call to +.IR poolrealloc , +the return value should be used rather than +.B ptr +to access the block. +If the request cannot be satisfied, +.I poolrealloc +returns nil, and the old pointer remains valid. +.PP +When blocks are allocated, there is often some extra space left at the end +that would usually go unused. +.IR Poolmsize +grows the block to encompass this extra space and returns the new size. +.PP +The +.I poolblockcheck +and +.I poolcheck +routines validate a single allocated block or the entire pool, respectively. +They call +.B panic +(see below) +if corruption is detected. +.I Pooldump +prints a summary line for every block in the +pool, using the +.B print +function (see below). +.PP +The +.B Pool +structure itself provides much of the setup interface. +.IP +.EX +.ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u +typedef struct Pool Pool; +struct Pool { + char* name; + ulong maxsize; /* of entire Pool */ + ulong cursize; /* of Pool */ + ulong curfree; /* total free bytes in Pool */ + ulong curalloc; /* total allocated bytes in Pool */ + ulong minarena; /* smallest size of new arena */ + ulong quantum; /* allocated blocks should be multiple of */ + ulong minblock; /* smallest newly allocated block */ + int flags; + int nfree; /* number of calls to free */ + int lastcompact; /* nfree at time of last poolcompact */ + void* (*alloc)(ulong); + int (*merge)(void*, void*); + void (*move)(void* from, void* to); + void (*lock)(Pool*); + void (*unlock)(Pool*); + void (*print)(Pool*, char*, ...); + void (*panic)(Pool*, char*, ...); + void (*logstack)(Pool*); + void* private; +}; +.ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u +enum { /* flags */ + POOL_ANTAGONISM = 1<<0, + POOL_PARANOIA = 1<<1, + POOL_VERBOSITY = 1<<2, + POOL_DEBUGGING = 1<<3, + POOL_LOGGING = 1<<4, + POOL_TOLERANCE = 1<<5, + POOL_NOREUSE = 1<<6, +}; +.EE +.PP +The pool obtains arenas of memory to manage by calling the the given +.B alloc +routine. +The total number of requested bytes will not exceed +.BR maxsize . +Each allocation request will be for at least +.B minarena +bytes. +.PP +When a new arena is allocated, the pool routines try to +merge it with the surrounding arenas, in an attempt to combat fragmentation. +If +.B merge +is non-nil, it is called with the addresses of two blocks from +.B alloc +that the pool routines suspect might be adjacent. +If they are not mergeable, +.B merge +must return zero. +If they are mergeable, +.B merge +should merge them into one block in its own bookkeeping +and return non-zero. +.PP +To ease fragmentation and make +block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of +.B quantum +before +the carrying out requests. +If, after rounding, the block size is still less than +.B minblock +bytes, +.B minblock +will be used as the block size. +.PP +.I Poolcompact +defragments the pool, moving blocks in order to aggregate +the free space. +Each time it moves a block, it notifies the +.B move +routine that the contents have moved. +At the time that +.B move +is called, the contents have already moved, +so +.B from +should never be dereferenced. +If no +.B move +routine is supplied (i.e. it is nil), then calling +.I poolcompact +is a no-op. +.PP +When the pool routines need to allocate a new arena but cannot, +either because +.B alloc +has returned nil or because doing so would use more than +.B maxsize +bytes, +.I poolcompact +is called once to defragment the memory +and the request is retried. +.PP +.I Pools +are protected by the pool routines calling +.B lock +(when non-nil) +before modifying the pool, and +calling +.B unlock +when finished. +.PP +When internal corruption is detected, +.B panic +is called with a +.IR print (2) +style argument that specifies what happened. +It is assumed that +.B panic +never returns. +When the pool routines wish to convey a message +to the caller (usually because logging is turned on; see below), +.B print +is called, also with a +.IR print (2) +style argument. +.PP +.B Flags +is a bit vector that tweaks the behavior of the pool routines +in various ways. +Most are useful for debugging in one way or another. +When +.B POOL_ANTAGONISM +is set, +.I poolalloc +fills blocks with non-zero garbage before releasing them to the user, +and +.I poolfree +fills the blocks on receipt. +This tickles both user programs and the innards of the allocator. +Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed +with a constant. +The pointer value is the pointer to the beginning of the allocated block +and the constant varies in order to distinguish different markings. +Freed blocks use the constant +.BR 0xF7000000 , +newly allocated blocks +.BR 0xF9000000 , +and newly created unallocated blocks +.BR 0xF1000000 . +For example, if +.B POOL_ANTAGONISM +is set and +.I poolalloc +returns a block starting at +.BR 0x00012345 , +each word of the block will contain the value +.BR 0xF90012345 . +Recognizing these numbers in memory-related crashes can +help diagnose things like double-frees or dangling pointers. +.PP +Setting +.B POOL_PARANOIA +causes the allocator to walk the entire pool whenever locking or unlocking itself, +looking for corruption. +This slows runtime by a few orders of magnitude +when many blocks are in use. +If +.B POOL_VERBOSITY +is set, +the entire pool structure is printed +(via +.BR print ) +each time the pool is locked or unlocked. +.B POOL_DEBUGGING +enables internal +debugging output, +whose format is unspecified and volatile. +It should not be used by most programs. +When +.B POOL_LOGGING +is set, a single line is printed via +.B print +at the beginning and end of each pool call. +If +.B logstack +is not nil, +it will be called as well. +This provides a mechanism for external programs to search for leaks. +(See +.IR leak (1) +for one such program.) +.PP +The pool routines are strict about the amount of space callers use. +If even a single byte is written past the end of the allotted space of a block, they +will notice when that block is next used in a call to +.I poolrealloc +or +.I free +(or at the next entry into the allocator, when +.B POOL_PARANOIA +is set), +and +.B panic +will be called. +Since forgetting to allocate space for the +terminating NUL on strings is such a common error, +if +.B POOL_TOLERANCE +is set and a single NUL is found written past the end of a block, +.B print +will be called with a notification, but +.B panic +will not be. +.PP +When +.B POOL_NOREUSE +is set, +.B poolfree +fills the passed block with garbage rather than +return it to the free pool. +.SH SOURCE +.B /sys/src/libc/port/pool.c +.SH SEE ALSO +.IR malloc (2), +.IR brk (2) +.PP +.B /sys/src/libc/port/malloc.c +is a complete example. diff --git a/static/plan9-4e/man2/postnote.2 b/static/plan9-4e/man2/postnote.2 new file mode 100644 index 00000000..6b4de1d4 --- /dev/null +++ b/static/plan9-4e/man2/postnote.2 @@ -0,0 +1,49 @@ +.TH POSTNOTE 2 +.SH NAME +postnote \- send a note to a process or process group +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +int postnote(int who, int pid, char *note) +.fi +.SH DESCRIPTION +.I Postnote +sends a note to a process or process group. +If +.I who +is +.BR PNPROC , +then +.I note +is written to +.BI /proc/ pid /note\f1. +If +.I who +is +.BI PNGROUP , +the note is delivered to the +process group by writing +.I note +to +.BI /proc/ pid /notepg\f1. +For +.B PNGROUP +only, if the calling process is in the target group, the note is +.I not +delivered to that process. +.PP +If the write is successful, zero is returned. +Otherwise \-1 is returned. +.SH SOURCE +.B /sys/src/libc/9sys/postnote.c +.SH "SEE ALSO" +.IR notify (2), +.IR intro (2), +.IR proc (3) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/prime.2 b/static/plan9-4e/man2/prime.2 new file mode 100644 index 00000000..13afd872 --- /dev/null +++ b/static/plan9-4e/man2/prime.2 @@ -0,0 +1,104 @@ +.TH PRIME 2 +.SH NAME +genprime, gensafeprime, genstrongprime, DSAprimes, probably_prime, smallprimetest \- prime number generation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +int smallprimetest(mpint *p) +.PP +.B +int probably_prime(mpint *p, int nrep) +.PP +.B +void genprime(mpint *p, int n, int nrep) +.PP +.B +void gensafeprime(mpint *p, mpint *alpha, int n, int accuracy) +.PP +.B +void genstrongprime(mpint *p, int n, int nrep) +.PP +.B +void DSAprimes(mpint *q, mpint *p, uchar seed[SHA1dlen]) +.SH DESCRIPTION +.PP +Public key algorithms abound in prime numbers. The following routines +generate primes or test numbers for primality. +.PP +.I Smallprimetest +checks for divisibility by the first 10000 primes. It returns 0 +if +.I p +is not divisible by the primes and \-1 if it is. +.PP +.I Probably_prime +uses the Miller-Rabin test to test +.IR p . +It returns non-zero if +.I P +is probably prime. The probability of it not being prime is +1/4**\fInrep\fR. +.PP +.I Genprime +generates a random +.I n +bit prime. Since it uses the Miller-Rabin test, +.I nrep +is the repetition count passed to +.IR probably_prime . +.I Gensafegprime +generates an +.IR n -bit +prime +.I p +and a generator +.I alpha +of the multiplicative group of integers mod \fIp\fR; +there is a prime \fIq\fR such that \fIp-1=2*q\fR. +.I Genstrongprime +generates a prime, +.IR p , +with the following properties: +.IP \- +.IR p -1 +has a large prime factor, +.IR p '. +A large factor is one close to 1/2 +the bit length of +.IR p . +.IP \- +.IR p '-1 +has a large prime factor +.IP \- +.IR p +1 +has a large prime factor +.IP \- +(\fIp\fR-1)/2 is prime +.PP +.I DSAprimes +generates two primes, +.I q +and +.IR p, +using the NIST recommended algorithm for DSA primes. +.I q +divides +.IR p -1. +The random seed used is also returned, so that skeptics +can later confirm the computation. Be patient; this is a +slow algorithm. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR aes (2) +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rsa (2), diff --git a/static/plan9-4e/man2/print.2 b/static/plan9-4e/man2/print.2 new file mode 100644 index 00000000..881b8dee --- /dev/null +++ b/static/plan9-4e/man2/print.2 @@ -0,0 +1,445 @@ +.TH PRINT 2 +.SH NAME +print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* 'u +.B +int print(char *format, ...) +.PP +.B +int fprint(int fd, char *format, ...) +.PP +.B +int sprint(char *s, char *format, ...) +.PP +.B +int snprint(char *s, int len, char *format, ...) +.PP +.B +char* seprint(char *s, char *e, char *format, ...) +.PP +.B +char* smprint(char *format, ...) +.PP +.B +int runesprint(Rune *s, char *format, ...) +.PP +.B +int runesnprint(Rune *s, int len, char *format, ...) +.PP +.B +Rune* runeseprint(Rune *s, Rune *e, char *format, ...) +.PP +.B +Rune* runesmprint(char *format, ...) +.PP +.B +int vfprint(int fd, char *format, va_list v) +.PP +.B +int vsnprint(char *s, int len, char *format, va_list v) +.PP +.B +char* vseprint(char *s, char *e, char *format, va_list v) +.PP +.B +char* vsmprint(char *format, va_list v) +.PP +.B +int runevsnprint(Rune *s, int len, char *format, va_list v) +.PP +.B +Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) +.PP +.B +Rune* runevsmprint(Rune *format, va_list v) +.PP +.B +.SH DESCRIPTION +.I Print +writes text to the standard output. +.I Fprint +writes to the named output +file descriptor; +a buffered form +is described in +.IR bio (2). +.I Sprint +places text +followed by the NUL character +.RB ( \e0 ) +in consecutive bytes starting at +.IR s ; +it is the user's responsibility to ensure that +enough storage is available. +Each function returns the number of bytes +transmitted (not including the NUL +in the case of +.IR sprint ), +or +a negative value if an output error was encountered. +.PP +.I Snprint +is like +.IR sprint , +but will not place more than +.I len +bytes in +.IR s . +Its result is always NUL-terminated and holds the maximal +number of complete UTF-8 characters that can fit. +.I Seprint +is like +.IR snprint , +except that the end is indicated by a pointer +.I e +rather than a count and the return value points to the terminating NUL of the +resulting string. +.I Smprint +is like +.IR sprint , +except that it prints into and returns a string of the required length, which is +allocated by +.IR malloc (2). +.PP +The routines +.IR runesprint , +.IR runesnprint , +.IR runeseprint , +and +.I runesmprint +are the same as +.IR sprint , +.IR snprint , +.IR seprint +and +.I smprint +except that their output is rune strings instead of byte strings. +.PP +Finally, the routines +.IR vfprint , +.IR vsnprint , +.IR vseprint , +.IR vsmprint , +.IR runevsnprint , +.IR runevseprint , +and +.IR runevsmprint +are like their +.BR v-less +relatives except they take as arguments a +.B va_list +parameter, so they can be called within a variadic function. +The Example section shows a representative usage. +.PP +Each of these functions +converts, formats, and prints its +trailing arguments +under control of a +.IR format +string. +The +format +contains two types of objects: +plain characters, which are simply copied to the +output stream, +and conversion specifications, +each of which results in fetching of +zero or more +arguments. +The results are undefined if there are arguments of the +wrong type or too few +arguments for the format. +If the format is exhausted while +arguments remain, the excess +is ignored. +.PP +Each conversion specification has the following format: +.IP +.B "% [flags] verb +.PP +The verb is a single character and each flag is a single character or a +(decimal) numeric string. +Up to two numeric strings may be used; +the first is called +.IR width , +the second +.IR precision . +A period can be used to separate them, and if the period is +present then +.I width +and +.I precision +are taken to be zero if missing, otherwise they are `omitted'. +Either or both of the numbers may be replaced with the character +.BR * , +meaning that the actual number will be obtained from the argument list +as an integer. +The flags and numbers are arguments to +the +.I verb +described below. +.PP +The numeric verbs +.BR d , +.BR o , +.BR b , +.BR x , +and +.B X +format their arguments in decimal, +octal, binary, hexadecimal, and upper case hexadecimal. +Each interprets the flags +.BR 0 , +.BR h , +.BR hh , +.BR l , +.BR u , +.BR + , +.BR - , +.BR , , +and +.B # +to mean pad with zeros, +short, byte, long, unsigned, always print a sign, left justified, commas every three digits, +and alternate format. +Also, a space character in the flag +position is like +.BR + , +but prints a space instead of a plus sign for non-negative values. +If neither +short nor long is specified, +then the argument is an +.BR int . +If unsigned is specified, +then the argument is interpreted as a +positive number and no sign is output. +If two +.B l +flags are given, +then the argument is interpreted as a +.B vlong +(usually an 8-byte, sometimes a 4-byte integer). +If +.I precision +is not omitted, the number is padded on the left with zeros +until at least +.I precision +digits appear. +Then, if alternate format is specified, +for +.B o +conversion, the number is preceded by a +.B 0 +if it doesn't already begin with one; +for +.B x +conversion, the number is preceded by +.BR 0x ; +for +.B X +conversion, the number is preceded by +.BR 0X . +Finally, if +.I width +is not omitted, the number is padded on the left (or right, if +left justification is specified) with enough blanks to +make the field at least +.I width +characters long. +.PP +The floating point verbs +.BR f , +.BR e , +.BR E , +.BR g , +and +.B G +take a +.B double +argument. +Each interprets the flags +.BR + , +.BR - , +and +.B # +to mean +always print a sign, +left justified, +and +alternate format. +.I Width +is the minimum field width and, +if the converted value takes up less than +.I width +characters, it is padded on the left (or right, if `left justified') +with spaces. +.I Precision +is the number of digits that are converted after the decimal place for +.BR e , +.BR E , +and +.B f +conversions, +and +.I precision +is the maximum number of significant digits for +.B g +and +.B G +conversions. +The +.B f +verb produces output of the form +.RB [ - ] digits [ .digits\fR]. +.B E +conversion appends an exponent +.BR E [ - ] digits , +and +.B e +conversion appends an exponent +.BR e [ - ] digits . +The +.B g +verb will output the argument in either +.B e +or +.B f +with the goal of producing the smallest output. +Also, trailing zeros are omitted from the fraction part of +the output, and a trailing decimal point appears only if it is followed +by a digit. +The +.B G +verb is similar, but uses +.B E +format instead of +.BR e . +When alternate format is specified, the result will always contain a decimal point, +and for +.B g +and +.B G +conversions, trailing zeros are not removed. +.PP +The +.B s +verb copies a string +(pointer to +.BR char ) +to the output. +The number of characters copied +.RI ( n ) +is the minimum +of the size of the string and +.IR precision . +These +.I n +characters are justified within a field of +.I width +characters as described above. +The +.B S +verb is similar, but it interprets its pointer as an array +of runes (see +.IR utf (6)); +the runes are converted to +.SM UTF +before output. +.PP +The +.B c +verb copies a single +.B char +(promoted to +.BR int ) +justified within a field of +.I width +characters as described above. +The +.B C +verb is similar, but works on runes. +.PP +The +.B p +verb formats a pointer value. +At the moment, it is a synonym for +.BR ux , +but that will change once pointers and integers are different sizes. +.PP +The +.B r +verb takes no arguments; it copies the error string returned by a call to +.IR errstr (2). +.PP +Custom verbs may be installed using +.IR fmtinstall (2). +.SH EXAMPLE +This function prints an error message with a variable +number of arguments and then quits. +.IP +.EX +.ta 6n +6n +6n +void fatal(char *msg, ...) +{ + char buf[1024], *out; + va_list arg; + + out = vseprint(buf, buf+sizeof(buf), "Fatal error: "); + va_start(arg, msg); + out = vseprint(out, buf+sizeof(buf), msg, arg); + va_end(arg); + write(2, buf, out-buf); + exits("fatal error"); +} +.EE +.SH SOURCE +.B /sys/src/libc/fmt +.SH SEE ALSO +.IR fmtinstall (2), +.IR fprintf (2), +.IR utf (6), +.IR errstr (2) +.SH DIAGNOSTICS +Routines that write to a file descriptor or call +.IR malloc +set +.IR errstr . +.SH BUGS +The formatting is close to that specified for ANSI +.IR fprintf (2); +the main difference is that +.B b +is not in ANSI and +.B u +is a flag here instead of a verb. +Also, and distinctly not a bug, +.I print +and friends generate +.SM UTF +rather than +.SM ASCII. +.PP +There is no +.BR runeprint , +.BR runefprint , +etc. because runes are byte-order dependent and should not be written directly to a file; use the +UTF output of +.I print +or +.I fprint +instead. +Also, +.I sprint +is deprecated for safety reasons; use +.IR snprint , +.IR seprint , +or +.I smprint +instead. +Safety also precludes the existence of +.IR runesprint . diff --git a/static/plan9-4e/man2/privalloc.2 b/static/plan9-4e/man2/privalloc.2 new file mode 100644 index 00000000..20dd0bf2 --- /dev/null +++ b/static/plan9-4e/man2/privalloc.2 @@ -0,0 +1,36 @@ +.TH PRIVALLOC 2 +.SH NAME +privalloc, privfree \- per-process private storage management +.SH SYNOPSIS +.B #include +.br +.B #include +.ta \w'voidmmm'u +.PP +.B +void** privalloc(void) +.PP +.B +void privfree(void **p) +.SH DESCRIPTION +.I Privalloc +returns a pointer to a per-process private storage location. +The location is not shared among processes, +even if they share the same data segments. +It returns +.B nil +if there are no free slots available. +.PP +.I Privfree +releases a location allocated with +.IR privalloc . +It is legal to call +.I privfree +with +.I p +set to +.BR nil . +.SH SOURCE +.B /sys/src/libc/9sys/privalloc.c +.SH SEE ALSO +.IR exec (2) diff --git a/static/plan9-4e/man2/proto.2 b/static/plan9-4e/man2/proto.2 new file mode 100644 index 00000000..563a1917 --- /dev/null +++ b/static/plan9-4e/man2/proto.2 @@ -0,0 +1,131 @@ +.TH PROTO 2 +.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 /sys/src/libdisk/proto.c +.SH SEE ALSO +.IR mk9660 (8), +.IR mkfs (8) diff --git a/static/plan9-4e/man2/pushssl.2 b/static/plan9-4e/man2/pushssl.2 new file mode 100644 index 00000000..efd55294 --- /dev/null +++ b/static/plan9-4e/man2/pushssl.2 @@ -0,0 +1,45 @@ +.TH PUSHSSL 2 +.SH NAME +pushssl \- attach SSL version 2 encryption to a communication channel +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int pushssl(int fd, char *alg, char *secin, char *secout, int *cfd) +.SH DESCRIPTION +.I Pushssl +opens an +.IR ssl (3) +device, connects it to the communications channel +.IR fd , +and starts up encryption and message authentication as specified +in +.IR alg . +The algorithms are separated by a space and either can be first. +See +.IR ssl (3) +for the possible algorithms. +.I Secin +and +.I secout +contain the encryption keys for the two directions. +If either is nil, the other is used in both directions. +If +.I cfd +is non-nil, the SSL control channel is opened and its fd +returned. +.PP +.I Pushssl +returns a file descriptor for the SSL data channel. Anything written to this +descriptor will get encrypted and authenticated and then written to the +file descriptor, +.IR fd . +.SH SOURCE +.B /sys/src/libc/9sys +.SH "SEE ALSO" +.IR dial (2), +.IR ssl (3), +.SH DIAGNOSTICS +return \-1 on failure. diff --git a/static/plan9-4e/man2/pushtls.2 b/static/plan9-4e/man2/pushtls.2 new file mode 100644 index 00000000..0671e7c7 --- /dev/null +++ b/static/plan9-4e/man2/pushtls.2 @@ -0,0 +1,177 @@ +.TH PUSHTLS 2 +.SH NAME +pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert \- 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 +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 +.IR tls (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, ...); + } 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 (2)). +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, for example by +.EX + auth/secretpem key.pem > /mnt/factotum/ctl +.EE +.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, maintained manually +.SH SOURCE +.B /sys/src/libc/9sys/pushtls.c +.br +.B /sys/src/libsec/port +.SH "SEE ALSO" +.IR dial (2), +.IR tls (3), +.IR factotum (4), +.IR thumbprint (6) +.SH DIAGNOSTICS +return \-1 on failure. +.SH BUGS +.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/static/plan9-4e/man2/qball.2 b/static/plan9-4e/man2/qball.2 new file mode 100644 index 00000000..1e919708 --- /dev/null +++ b/static/plan9-4e/man2/qball.2 @@ -0,0 +1,76 @@ +.TH QBALL 2 +.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 /sys/src/libgeometry/qball.c +.SH SEE ALSO +.IR quaternion (2) +.br +Ken Shoemake, +``Animating Rotation with Quaternion Curves'', +.I +SIGGRAPH '85 Conference Proceedings. diff --git a/static/plan9-4e/man2/qsort.2 b/static/plan9-4e/man2/qsort.2 new file mode 100644 index 00000000..9f0aedae --- /dev/null +++ b/static/plan9-4e/man2/qsort.2 @@ -0,0 +1,33 @@ +.TH QSORT 2 +.SH NAME +qsort \- quicker sort +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +.nf +void qsort(void *base, long nel, long width, +.B + int (*compar)(void*, void*)) +.fi +.SH DESCRIPTION +.I Qsort +(quicker sort) +sorts an array into nondecreasing order. +The first argument is a pointer to the base of the data; +the second is the number of elements; +the third is the width of an element +in bytes; +the last is the name of a comparison routine +to be called with pointers +to elements being compared. +The routine must return +an integer less than, equal to, or greater than 0 +according as the first argument is to be considered +less than, equal to, or greater than the second. +.SH SOURCE +.B /sys/src/libc/port/qsort.c +.SH "SEE ALSO" +.IR sort (1) diff --git a/static/plan9-4e/man2/quaternion.2 b/static/plan9-4e/man2/quaternion.2 new file mode 100644 index 00000000..3e3de98d --- /dev/null +++ b/static/plan9-4e/man2/quaternion.2 @@ -0,0 +1,152 @@ +.TH QUATERNION 2 +.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 (2)) +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 /sys/src/libgeometry/quaternion.c +.SH SEE ALSO +.IR matrix (2), +.IR qball (2) diff --git a/static/plan9-4e/man2/quote.2 b/static/plan9-4e/man2/quote.2 new file mode 100644 index 00000000..8b223dd0 --- /dev/null +++ b/static/plan9-4e/man2/quote.2 @@ -0,0 +1,159 @@ +.TH QUOTE 2 +.SH NAME +quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote \- quoted character strings +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +char *quotestrdup(char *s) +.PP +.B +Rune *quoterunestrdup(Rune *s) +.PP +.B +char *unquotestrdup(char *s) +.PP +.B +Rune *unquoterunestrdup(Rune *s) +.PP +.B +int quotestrfmt(Fmt*) +.PP +.B +int quoterunestrfmt(Fmt*) +.PP +.B +void quotefmtinstall(void) +.PP +.B +int (*doquote)(int c) +.PP +.SH DESCRIPTION +These routines manipulate character strings, either adding or removing +quotes as necessary. +In the quoted form, the strings are in the style of +.IR rc (1) , +with single quotes surrounding the string. +Embedded single quotes are indicated by a doubled single quote. +For instance, +.IP +.EX +Don't worry! +.EE +.PP +when quoted becomes +.IP +.EX +\&'Don''t worry!' +.EE +.PP +The empty string is represented by two quotes, +.BR '' . +.PP +The first four functions act as variants of +.B strdup +(see +.IR strcat (2)). +Each returns a +freshly allocated copy of the string, created using +.IR malloc (2). +.I Quotestrdup +returns a quoted copy of +.IR s , +while +.I unquotestrdup +returns a copy of +.IR s +with the quotes evaluated. +The +.I rune +versions of these functions do the same for +.CW Rune +strings (see +.IR runestrcat (2)). +.PP +The string returned by +.I quotestrdup +or +.I quoterunestrdup +has the following properties: +.TP +1. +If the original string +.IR s +is empty, the returned string is +.BR '' . +.TP +2. +If +.I s +contains no quotes, blanks, or control characters, +the returned string is identical to +.IR s . +.TP +3. +If +.I s +needs quotes to be added, the first character of the returned +string will be a quote. +For example, +.B hello\ world +becomes +.B \&'hello\ world' +not +.BR hello'\ 'world . +.PP +The function pointer +.I doquote +is +.B nil +by default. +If it is non-nil, characters are passed to that function to see if they should +be quoted. +This mechanism allows programs to specify that +characters other than blanks, control characters, or quotes be quoted. +Regardless of the return value of +.IR *doquote , +blanks, control characters, and quotes are always quoted. +.PP +.I Quotestrfmt +and +.I quoterunestrfmt +are +.IR print (2) +formatting routines that produce quoted strings as output. +They may be installed by hand, but +.I quotefmtinstall +installs them under the standard format characters +.B q +and +.BR Q . +(They are not installed automatically.) +If the format string includes the alternate format character +.BR # , +for example +.BR %#q , +the printed string will always be quoted; otherwise quotes will only be provided if necessary +to avoid ambiguity. +In +.B +there are +.B #pragma +statements so the compiler can type-check uses of +.B %q +and +.B %Q +in +.IR print (2) +format strings. +.SH SOURCE +.B /sys/src/libc/port/quote.c +.br +.B /sys/src/libc/fmt/fmtquote.c +.SH "SEE ALSO +.IR rc (1), +.IR malloc (2), +.IR print (2), +.IR strcat (2) diff --git a/static/plan9-4e/man2/rand.2 b/static/plan9-4e/man2/rand.2 new file mode 100644 index 00000000..2f46885a --- /dev/null +++ b/static/plan9-4e/man2/rand.2 @@ -0,0 +1,172 @@ +.TH RAND 2 +.SH NAME +rand, lrand, frand, nrand, lnrand, srand, truerand, ntruerand, fastrand, nfastrand \- random number generator +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLdouble 'u +.B +int rand(void) +.PP +.B +long lrand(void) +.PP +.B +double frand(void) +.PP +.B +int nrand(int val) +.PP +.B +long lnrand(long val) +.PP +.B +void srand(long seed) +.PP +.B +ulong truerand(void) +.PP +.B +ulong ntruerand(ulong val) +.PP +.B +ulong fastrand(void) +.PP +.B +ulong nfastrand(ulong val) +.sp +.B #include +.br +.B #include +.PP +.B +void genrandom(uchar *buf, int nbytes) +.PP +.B +void prng(uchar *buf, int nbytes) +.SH DESCRIPTION +.I Rand +returns a uniform pseudo-random +number +.IR x , +.RI 0≤ x <2\u\s715\s10\d. +.PP +.I Lrand +returns a uniform +.B long +.IR x , +.RI 0≤ x <2\u\s731\s10\d. +.PP +.I Frand +returns a uniform +.B double +.IR x , +.RI 0.0≤ x <1.0, +This function calls +.I lrand +twice to generate a number with as many as 62 significant bits of mantissa. +.PP +.I Nrand +returns a uniform integer +.IR x , +.RI 0≤ x < val. +.I Lnrand +is the same, but returns a +.BR long . +.PP +The algorithm is additive feedback with: +.IP +x[n] = (x[n\(mi273] + x[n\(mi607]) mod +.if t 2\u\s731\s0\d +.if n 2^31 +.LP +giving a period of +.if t 2\u\s730\s10\d \(mu (2\u\s7607\s10\d \- 1). +.if n 2^30 × (2^607 - 1). +.PP +The generators are initialized by calling +.I srand +with whatever you like as argument. +To get a different starting value each time, +.IP +.L +srand(time(0)) +.LP +will work as long as it is not called more often +than once per second. +Calling +.IP +.L +srand(1) +.LP +will initialize the generators to their +starting state. +.PP +.I Truerand +returns a random unsigned long read from +.BR /dev/random . +Due to the nature of +.BR /dev/random , +truerand can only return a few hundred bits a +second. +.PP +.I Ntruerand +returns a uniform random integer +.IR x , +.RI 0≤ x < val ≤ 2\u\s732\s10\d-1. +.PP +.I Fastrand +is a pseudo random number generator which is seeded +and periodically scrambled using +.IR truerand . +It returns a uniform random integer +.IR x , +.RI 0≤ x < 2\u\s731\s10\d-1. +It is approximately 1000 times faster than +.I truerand +and is intended for security software that requires a +larger stream of unguessable data. +.PP +.I Nfastrand +returns a uniform pseudo random integer +.IR x , +.RI 0≤ x < val ≤ 2\u\s731\s10\d-1, +using +.IR fastrand . +.PP +.I Genrandom +fills a buffer with bytes from the X9.17 pseudo-random +number generator. The X9.17 generator is seeded by 24 +truly random bytes read from +.BR /dev/random . +.PP +.I Prng +uses the native +.IR rand (2) +pseudo-random number generator to fill the buffer. Used with +.IR srand , +this function can produce a reproducible stream of pseudo random +numbers useful in testing. +.PP +Both functions may be passed to +.I mprand +(see +.IR mp (2)). +.SH SOURCE +.B /sys/src/libc/port/rand.c +.br +.B /sys/src/libc/9sys/truerand.c +.br +.B /sys/src/libsec/port/genrandom.c +.br +.B /sys/src/libsec/port/prng.c +.SH "SEE ALSO +.IR cons (3), +.IR mp (2), +.SH BUGS +.I Truerand +and +.I ntruerand +maintain a static file descriptor. diff --git a/static/plan9-4e/man2/rc4.2 b/static/plan9-4e/man2/rc4.2 new file mode 100644 index 00000000..c450c73c --- /dev/null +++ b/static/plan9-4e/man2/rc4.2 @@ -0,0 +1,54 @@ +.TH RC4 2 +.SH NAME +setupRC4state, rc4, rc4skip, rc4back - alleged rc4 encryption +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +void setupRC4state(RC4state *s, uchar *seed, int slen) +.PP +.B +void rc4(RC4state *s, uchar *data, int dlen) +.PP +.B +void rc4skip(RC4state *s, int nbytes) +.PP +.B +void rc4back(RC4state *s, int nbytes) +.SH DESCRIPTION +.PP +This is an algorithm alleged to be Rivest's RC4 encryption function. It is +a pseudo-random number generator with a 256 byte state and a long +cycle. The input buffer is XOR'd with the output of the +generator both to encrypt and to decrypt. The seed, entered +using +.IR setupRC4state , +can be any length. The generator can be run forward using +.IR rc4 , +skip over bytes using +.I rc4skip +to account lost transmissions, +or run backwards using +.I rc4back +to cover retransmitted data. +The +.I RC4state +structure keeps track of the algorithm. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rsa (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/read.2 b/static/plan9-4e/man2/read.2 new file mode 100644 index 00000000..6c207e70 --- /dev/null +++ b/static/plan9-4e/man2/read.2 @@ -0,0 +1,95 @@ +.TH READ 2 +.SH NAME +read, readn, write, pread, pwrite \- read or write file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long read(int fd, void *buf, long nbytes) +.PP +.B +long readn(int fd, void *buf, long nbytes) +.PP +.B +long write(int fd, void *buf, long nbytes) +.PP +.B +long pread(int fd, void *buf, long nbytes, vlong offset) +.PP +.B +long pwrite(int fd, void *buf, long nbytes, vlong offset) +.SH DESCRIPTION +.I Read +reads +.I nbytes +bytes of data +from the offset in the file associated with +.I fd +into memory at +.IR buf . +The offset is advanced by the number of bytes read. +It is not guaranteed +that all +.I nbytes +bytes will be read; for example +if the file refers to the console, at most one line +will be returned. +In any event the number of bytes read is returned. +A return value of +0 is conventionally interpreted as end of file. +.PP +.I Readn +is just like read, but does successive +.I read +calls until +.I nbytes +have been read, or a read system call +returns a non-positive count. +.PP +.I Write +writes +.I nbytes +bytes of data starting at +.I buf +to the file associated with +.I fd +at the file offset. +The offset is advanced by the number of bytes written. +The number of characters actually written is returned. +It should be regarded as an error +if this is not the same as requested. +.PP +.I Pread +and +.I Pwrite +equivalent to a +.IR seek (2) +to +.I offset +followed by a +.I read +or +.IR write . +By combining the operations in a single atomic call, they more closely +match the 9P protocol +(see +.IR intro (5)) +and, more important, +permit multiprocess programs to execute multiple concurrent +read and write operations on the same file descriptor +without interference. +.SH SOURCE +.B /sys/src/libc/9syscall +.br +.B /sys/src/libc/port/readn.c +.SH SEE ALSO +.IR intro (2), +.IR open (2), +.IR dup (2), +.IR pipe (2), +.IR readv (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/static/plan9-4e/man2/readcolmap.2 b/static/plan9-4e/man2/readcolmap.2 new file mode 100644 index 00000000..5ea74cb3 --- /dev/null +++ b/static/plan9-4e/man2/readcolmap.2 @@ -0,0 +1,76 @@ +.TH READCOLMAP 2 +.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 (2) +operator to convert between +mapped and true color or greyscale images, +which is described in +.IR color (6). +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR graphics (2), +.IR draw (3), +.IR color (6) diff --git a/static/plan9-4e/man2/readv.2 b/static/plan9-4e/man2/readv.2 new file mode 100644 index 00000000..31dcb884 --- /dev/null +++ b/static/plan9-4e/man2/readv.2 @@ -0,0 +1,82 @@ +.TH READV 2 +.SH NAME +readv, writev, preadv, pwritev \- scatter/gather read and write +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.ft L +typedef +struct IOchunk +{ + void *addr; + ulong len; +} IOchunk; +.fi +.PP +.B +long readv(int fd, IOchunk *io, int nio) +.PP +.B +long preadv(int fd, IOchunk *io, int nio, vlong off) +.PP +.B +long writev(int fd, IOchunk *io, int nio) +.PP +.B +long pwritev(int fd, IOchunk *io, int nio, vlong off) +.SH DESCRIPTION +These functions supplement the standard read and write operations of +.IR read (2) +with facilities for scatter/gather I/O. +The set of I/O buffers is collected into an array of +.B IOchunk +structures passed as an argument. +.PP +.I Readv +reads data from +.I fd +and returns the total number of bytes received. +The received data is stored in the successive +.I nio +elements of the +.B IOchunk +array, storing +.IB io [0].len +bytes at +.IB io [0].addr\f1, +the next +.IB io [1].len +at +.IB io [1].addr\f1, +and so on. +.I Preadv +does the same, but implicitly seeks to I/O offset +.I off +by analogy with +.IR readv . +.PP +.I Writev +and +.I pwritev +are the analogous write routines. +.SH SOURCE +.B /sys/src/libc/9sys/readv.c +.br +.B /sys/src/libc/9sys/writev.c +.SH SEE ALSO +.IR intro (2), +.IR read (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . +.SH BUGS +The implementations use +.IR malloc (2) +to build a single buffer for a standard call to +.B read +or +.BR write . +They are placeholders for possible future system calls. diff --git a/static/plan9-4e/man2/regexp.2 b/static/plan9-4e/man2/regexp.2 new file mode 100644 index 00000000..6558dc71 --- /dev/null +++ b/static/plan9-4e/man2/regexp.2 @@ -0,0 +1,212 @@ +.TH REGEXP 2 +.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 (2) +and may be released by +.IR free . +Regular expressions are exactly as in +.IR regexp (6). +.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 /sys/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/static/plan9-4e/man2/remove.2 b/static/plan9-4e/man2/remove.2 new file mode 100644 index 00000000..7547e46a --- /dev/null +++ b/static/plan9-4e/man2/remove.2 @@ -0,0 +1,31 @@ +.TH REMOVE 2 +.SH NAME +remove \- remove a file +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int remove(char *file) +.SH DESCRIPTION +.I Remove +removes +.I file +from the directory containing it and discards the contents of the file. +The user must have write permission in the containing directory. +If +.I file +is a directory, it must be empty. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR remove (5), +the description of +.B ORCLOSE +in +.IR open (2). +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/rendezvous.2 b/static/plan9-4e/man2/rendezvous.2 new file mode 100644 index 00000000..70564d97 --- /dev/null +++ b/static/plan9-4e/man2/rendezvous.2 @@ -0,0 +1,57 @@ +.TH RENDEZVOUS 2 +.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 (2) +and +.IR fork (2)), +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 (2). +.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 /sys/src/libc/9syscall +.SH SEE ALSO +.IR segattach (2), +.IR fork (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/rsa.2 b/static/plan9-4e/man2/rsa.2 new file mode 100644 index 00000000..a67dbb40 --- /dev/null +++ b/static/plan9-4e/man2/rsa.2 @@ -0,0 +1,149 @@ +.TH RSA 2 +.SH NAME + - +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +RSApriv* rsagen(int nlen, int elen, int nrep) +.PP +.B +mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out) +.PP +.B +mpint* rsadecrypt(RSApriv *k, mpint *in, mpint *out) +.PP +.B +RSApub* rsapuballoc(void) +.PP +.B +void rsapubfree(RSApub*) +.PP +.B +RSApriv* rsaprivalloc(void) +.PP +.B +void rsaprivfree(RSApriv*) +.PP +.B +RSApub* rsaprivtopub(RSApriv*) +.PP +.B +RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname) +.PP +.B +RSApriv* asn1toRSApriv(uchar *priv, int npriv) +.PP +.B +uchar* decodepem(char *s, char *type, uchar *len) +.SH DESCRIPTION +.PP +RSA is a public key encryption algorithm. The owner of a key publishes +the public part of the key: +.EX + struct RSApub + { + mpint *n; // modulus + mpint *ek; // exp (encryption key) + }; +.EE +This part can be used for encrypting data (with +.IR rsaencrypt ) +to be sent to the owner. +The owner decrypts (with +.IR rsadecrypt ) +using his private key: +.EX + struct RSApriv + { + RSApub pub; + mpint *dk; // exp (decryption key) + + // precomputed crt values + mpint *p; + mpint *q; + mpint *kp; // k mod p-1 + mpint *kq; // k mod q-1 + mpint *c2; // for converting residues to number + }; +.EE +.PP +Keys are generated using +.IR rsagen . +.I Rsagen +takes both bit length of the modulus, the bit length of the +public key exponent, and the number of repetitions of the Miller-Rabin +primality test to run. If the latter is 0, it does the default number +of rounds. +.I Rsagen +returns a newly allocated structure containing both +public and private keys. +.I Rsaprivtopub +returns a newly allocated copy of the public key +corresponding to the private key. +.PP +The routines +.IR rsaalloc , +.IR rsafree , +.IR rsapuballoc , +.IR rsapubfree , +.IR rsaprivalloc , +and +.I rsaprivfree +are provided to aid in user provided key I/O. +.PP +Given a binary X.509 +.IR cert , +the routine +.I X509toRSApub +returns the public key and, if +.I name +is not nil, the CN part of the Distinguished Name of the +certificate's Subject. +(This is conventionally a userid or a host DNS name.) +No verification is done of the certificate signature; the +caller should check the fingerprint, +.IR sha1(cert) , +against a table or check the certificate by other means. +X.509 certificates are often stored in PEM format; use +.I dec64 +to convert to binary before computing the fingerprint or calling +.IR X509toRSApub . +.PP +.I Asn1toRSApriv +converts an ASN1 formatted RSA private key into the corresponding +.B RSApriv +structure. +.PP +.I Decodepem +takes a zero terminated string, +.IR s , +and decodes the PEM (privacy-enhanced mail) formatted section for +.I type +within it. +If successful, it returns the decoded section and sets +.BI * len +to its decoded length. +If not, it returns +.BR nil , +and +.BI * len +is undefined. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR mp (2), +.IR aes (2), +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rc4 (2), +.IR sechash (2), +.IR prime (2), +.IR rand (2) diff --git a/static/plan9-4e/man2/rune.2 b/static/plan9-4e/man2/rune.2 new file mode 100644 index 00000000..a1643858 --- /dev/null +++ b/static/plan9-4e/man2/rune.2 @@ -0,0 +1,190 @@ +.TH RUNE 2 +.SH NAME +runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf \- rune/UTF conversion +.SH SYNOPSIS +.ta \w'\fLchar*xx'u +.B #include +.br +.B #include +.PP +.B +int runetochar(char *s, Rune *r) +.PP +.B +int chartorune(Rune *r, char *s) +.PP +.B +int runelen(long r) +.PP +.B +int runenlen(Rune *r, int n) +.PP +.B +int fullrune(char *s, int n) +.PP +.B +char* utfecpy(char *s1, char *es1, char *s2) +.PP +.B +int utflen(char *s) +.PP +.B +int utfnlen(char *s, long n) +.PP +.B +char* utfrune(char *s, long c) +.PP +.B +char* utfrrune(char *s, long c) +.PP +.B +char* utfutf(char *s1, char *s2) +.SH DESCRIPTION +These routines convert to and from a +.SM UTF +byte stream and runes. +.PP +.I Runetochar +copies one rune at +.I r +to at most +.B UTFmax +bytes starting at +.I s +and returns the number of bytes copied. +.BR UTFmax , +defined as +.B 3 +in +.BR , +is the maximum number of bytes required to represent a rune. +.PP +.I Chartorune +copies at most +.B UTFmax +bytes starting at +.I s +to one rune at +.I r +and returns the number of bytes copied. +If the input is not exactly in +.SM UTF +format, +.I chartorune +will convert to 0x80 and return 1. +.PP +.I Runelen +returns the number of bytes +required to convert +.I r +into +.SM UTF. +.PP +.I Runenlen +returns the number of bytes +required to convert the +.I n +runes pointed to by +.I r +into +.SM UTF. +.PP +.I Fullrune +returns 1 if the string +.I s +of length +.I n +is long enough to be decoded by +.I chartorune +and 0 otherwise. +This does not guarantee that the string +contains a legal +.SM UTF +encoding. +This routine is used by programs that +obtain input a byte at +a time and need to know when a full rune +has arrived. +.PP +The following routines are analogous to the +corresponding string routines with +.B utf +substituted for +.B str +and +.B rune +substituted for +.BR chr . +.PP +.I Utfecpy +copies UTF sequences until a null sequence has been copied, but writes no +sequences beyond +.IR es1 . +If any sequences are copied, +.I s1 +is terminated by a null sequence, and a pointer to that sequence is returned. +Otherwise, the original +.I s1 +is returned. +.PP +.I Utflen +returns the number of runes that +are represented by the +.SM UTF +string +.IR s . +.PP +.I Utfnlen +returns the number of complete runes that +are represented by the first +.I n +bytes of +.SM UTF +string +.IR s . +If the last few bytes of the string contain an incompletely coded rune, +.I utfnlen +will not count them; in this way, it differs from +.IR utflen , +which includes every byte of the string. +.PP +.I Utfrune +.RI ( utfrrune ) +returns a pointer to the first (last) +occurrence of rune +.I c +in the +.SM UTF +string +.IR s , +or 0 if +.I c +does not occur in the string. +The NUL byte terminating a string is considered to +be part of the string +.IR s . +.PP +.I Utfutf +returns a pointer to the first occurrence of +the +.SM UTF +string +.I s2 +as a +.SM UTF +substring of +.IR s1 , +or 0 if there is none. +If +.I s2 +is the null string, +.I utfutf +returns +.IR s1 . +.SH SOURCE +.B /sys/src/libc/port/rune.c +.br +.B /sys/src/libc/port/utfrune.c +.SH SEE ALSO +.IR utf (6), +.IR tcs (1) diff --git a/static/plan9-4e/man2/runestrcat.2 b/static/plan9-4e/man2/runestrcat.2 new file mode 100644 index 00000000..043de093 --- /dev/null +++ b/static/plan9-4e/man2/runestrcat.2 @@ -0,0 +1,67 @@ +.TH RUNESTRCAT 2 +.SH NAME +runestrcat, +runestrncat, +runestrcmp, +runestrncmp, +runestrcpy, +runestrncpy, +runestrecpy, +runestrlen, +runestrchr, +runestrrchr, +runestrdup, +runestrstr \- rune string operations +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLRune* \fP'u +.B +Rune* runestrcat(Rune *s1, Rune *s2) +.PP +.B +Rune* runestrncat(Rune *s1, Rune *s2, long n) +.PP +.B +int runestrcmp(Rune *s1, Rune *s2) +.PP +.B +int runestrncmp(Rune *s1, Rune *s2, long n) +.PP +.B +Rune* runestrcpy(Rune *s1, Rune *s2) +.PP +.B +Rune* runestrncpy(Rune *s1, Rune *s2, long n) +.PP +.B +Rune* runestrecpy(Rune *s1, Rune *es1, Rune *s2) +.PP +.B +long runestrlen(Rune *s) +.PP +.B +Rune* runestrchr(Rune *s, Rune c) +.PP +.B +Rune* runestrrchr(Rune *s, Rune c) +.PP +.B +Rune* runestrdup(Rune *s) +.PP +.B +Rune* runestrstr(Rune *s1, Rune *s2) +.SH DESCRIPTION +These functions are rune string analogues of +the corresponding functions in +.IR strcat (2). +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR memory (2), +.IR rune (2), +.IR strcat (2) +.SH BUGS +The outcome of overlapping moves varies among implementations. diff --git a/static/plan9-4e/man2/scribble.2 b/static/plan9-4e/man2/scribble.2 new file mode 100644 index 00000000..6f394add --- /dev/null +++ b/static/plan9-4e/man2/scribble.2 @@ -0,0 +1,162 @@ +.TH SCRIBBLE 2 +.SH NAME +scribblealloc, +recognize \- character recognition +.SH SYNOPSIS +.PP +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +#include +#include +#include +#include + +Scribble *scribblealloc(void); +Rune recognize(Scribble *); +.EE +.SH DESCRIPTION +.PP +The scribble library implements simple character recognition. +All characters are drawn using a single stroke of the pen (mouse button 1) +as on a palmtop computer. +A reference card is in +.BR /sys/src/libscribble/quickref.gif . +.PP +The library is not really intended for standalone use. Its primary +use is by the scribble graphical control (see +.IR control (2)). +.PP +.B Scribblealloc +allocates and returns an appropriately initialized +.B Scribble +structure: +.IP +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n +#define CS_LETTERS 0 +#define CS_DIGITS 1 +#define CS_PUNCTUATION 2 + +struct Scribble { + /* private state */ + Point *pt; + int ppasize; + Stroke ps; + Graffiti *graf; + int capsLock; + int puncShift; + int tmpShift; + int ctrlShift; + int curCharSet; +}; +.EE +.PP +This structure encodes the points making up the stroke +to be recognized, as well as the \f2character group\fP in which +the stroke should be searched. +.PP +There are three such groups: +.IR letters , +.IR digits , +and +.IR punctuation . +The current group is encoded in the +.B curCharSet +field of the +.B Scribble +structure. +Special strokes are recognized to switch between groups. +In addition, the charater recognized is influenced by +.I mode +parameters and modifies them. +These are identified by the +.BR capsLock , +.BR puncShift , +.BR tmpShift , +and +.B ctrlShift +fields of the +.B Scribble +structure. +When +.B puncShift +is non-zero, the character is recognized in the punctuation +character set. +Similarly, +when the character recognized is printable and +.B ctrlShift +is set, the associated control character is returned as if the +control key were depressed, +and when the character is a letter and +.B capsLock +or +.B tmpShift +is set, the upper-case version is returned. +The +.B puncShift +and +.B tmpShift +flags are turned off +once a character has been recognized; the others are left set. +.PP +The character to be recognized is encoded as an array of pen_points in the +.B ps +field. +To allow easy drawing of the stroke as it is drawn, +the +.I pt +and +.I ppasize +fields are available to the application code for storing an array +of points for a call to +.B poly +(see +.IR draw (2)). +.PP +.I Recognize +recognizes the character provided in the +.B ps +field of the +.B Scribble +structure; it +returns the rune or zero if nothing was recognized. +.SH FILES +.B /sys/src/libscribble/quickref.gif +serves as a quick reference card. +.PP +.B /sys/lib/scribble/classifiers +contains the stroke definitions. +.SH SOURCE +.B /sys/src/libscribble +.PP +This library is adapted from software reproduced by permission: +.PP +.B Graffiti.c +is based on the file +.B Scribble.c +copyrighted +by Keith Packard: +.IP +Copyright © 1999 Keith Packard +.PP +Permission to use, copy, modify, distribute, and sell this software and its +documentation for any purpose is hereby granted without fee, provided that +the above copyright notice appear in all copies and that both that +copyright notice and this permission notice appear in supporting +documentation, and that the name of Keith Packard not be used in +advertising or publicity pertaining to distribution of the software without +specific, written prior permission. Keith Packard makes no +representations about the suitability of this software for any purpose. It +is provided "as is" without express or implied warranty. +.PP +Portions of the software Copyright © 1994 by Sun Microsystems Computer Company. +.PP +Portions of the software Copyright © 2000 by Compaq Computer Corporation. +.SH SEE ALSO +.B Keyboard +and +.B prompter +in +.IR bitsyload (1), +.IR draw (2), +.IR control (2) diff --git a/static/plan9-4e/man2/scsi.2 b/static/plan9-4e/man2/scsi.2 new file mode 100644 index 00000000..081fe7a7 --- /dev/null +++ b/static/plan9-4e/man2/scsi.2 @@ -0,0 +1,184 @@ +.TH SCSI 2 +.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 +.IR sd (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 /sys/src/libdisk/scsi.c +.SH SEE ALSO +.IR sd (3), +.IR scuzz (8) diff --git a/static/plan9-4e/man2/sechash.2 b/static/plan9-4e/man2/sechash.2 new file mode 100644 index 00000000..da9f3341 --- /dev/null +++ b/static/plan9-4e/man2/sechash.2 @@ -0,0 +1,150 @@ +.TH SECHASH 2 +.SH NAME +md4, md5, sha1, hmac_md5, hmac_sha1, md5pickle, md5unpickle, sha1pickle, sha1unpickle \- cryptographically secure hashes +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.B +DigestState* md4(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +DigestState* md5(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +char* md5pickle(MD5state *state) +.PP +.B +MD5state* md5unpickle(char *p); +.PP +.B +DigestState* sha1(uchar *data, ulong dlen, uchar *digest, +.B + DigestState *state) +.PP +.B +char* sha1pickle(MD5state *state) +.PP +.B +MD5state* sha1unpickle(char *p); +.PP +.B +DigestState* hmac_md5(uchar *data, ulong dlen, +.br +.B + uchar *key, ulong klen, +.br +.B + uchar *digest, DigestState *state) +.PP +.B +DigestState* hmac_sha1(uchar *data, ulong dlen, +.br +.B + uchar *key, ulong klen, +.br +.B + uchar *digest, DigestState *state) +.SH DESCRIPTION +.PP +We support several secure hash functions. The output of the +hash is called a +.IR digest . +A hash is secure if, given the hashed data and the digest, +it is difficult to predict the change to the digest resulting +from some change to the data without rehashing +the whole data. Therefore, if a secret is part of the hashed +data, the digest can be used as an integrity check of the data by anyone +possessing the secret. +.PP +The routines +.IR md4 , +.IR md5 , +.IR sha1 , +.IR hmac_md5 , +and +.I hmac_sha1 +differ only in the length of the resulting digest +and in the security of the hash. Usage for each is the same. +The first call to the routine should have +.B nil +as the +.I state +parameter. This call returns a state which can be used to chain +subsequent calls. +The last call should have digest non-\fBnil\fR. +.I Digest +must point to a buffer of at least the size of the digest produced. +This last call will free the state and copy the result into +.IR digest . +For example, to hash a single buffer using +.IR md5 : +.EX + + uchar digest[MD5dlen]; + + md5(data, len, digest, nil); +.EE +.PP +To chain a number of buffers together, +bounded on each end by some secret: +.EX + + char buf[256]; + uchar digest[MD5dlen]; + DigestState *s; + + s = md5("my password", 11, nil, nil); + while((n = read(fd, buf, 256)) > 0) + md5(buf, n, nil, s); + md5("drowssap ym", 11, digest, s); +.EE +.PP +The constants +.IR MD4dlen , +.IR MD5dlen , +and +.I SHA1dlen +define the lengths of the digests. +.PP +.I Hmac_md5 +and +.I hmac_sha1 +are used slightly differently. These hash algorithms are keyed and require +a key to be specified on every call. +The digest lengths for these hashes are +.I MD5dlen +and +.I SHA1dlen +respectively. +.PP +The functions +.I md5pickle +and +.I sha1pickle +marshal the state of a digest for transmission. +.I Md5unpickle +and +.I sha1unpickle +unmarshal a pickled digest. +All four routines return a pointer to a newly +.IR malloc (2)'d +object. +.SH SOURCE +.B /sys/src/libsec +.SH SEE ALSO +.IR aes (2) +.IR blowfish (2), +.IR des (2), +.IR elgamal (2), +.IR rc4 (2), +.IR rsa (2) diff --git a/static/plan9-4e/man2/seek.2 b/static/plan9-4e/man2/seek.2 new file mode 100644 index 00000000..8597376e --- /dev/null +++ b/static/plan9-4e/man2/seek.2 @@ -0,0 +1,46 @@ +.TH SEEK 2 +.SH NAME +seek \- change file offset +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +vlong seek(int fd, vlong n, int type) +.SH DESCRIPTION +.I Seek +sets the offset for the file +associated with +.I fd +as follows: +.IP +If +.I type +is 0, the offset is set to +.I n +bytes. +.IP +If +.I type +is 1, the pointer is set to its current location plus +.IR n . +.IP +If +.I type +is 2, the pointer is set to the size of the +file plus +.IR n . +.PP +The new file offset value is returned. +.PP +Seeking in a directory is not allowed. +Seeking in a pipe is a no-op. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2), +.IR open (2) +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/segattach.2 b/static/plan9-4e/man2/segattach.2 new file mode 100644 index 00000000..208ab327 --- /dev/null +++ b/static/plan9-4e/man2/segattach.2 @@ -0,0 +1,173 @@ +.TH SEGATTACH 2 +.SH NAME +segattach, segdetach, segfree \- map/unmap a segment in virtual memory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLlong 'u +.B +long segattach(int attr, char *class, void *va, ulong len) +.PP +.B +int segdetach(void *addr) +.PP +.B +int segfree(void *va, ulong len) +.PP +.SH DESCRIPTION +.I Segattach +creates a new memory segment, adds it +to the calling process's address space, and returns its lowest address (as an integer). +Segments belong to system-dependent classes. +Segment classes +.B memory +(plain memory) +and +.B shared +(shared memory) +are available on all systems. +.PP +Shared segments are inherited by the children of the attaching process +and remain untouched across a +.IR fork (2). +An +.IR exec (2) +will release a shared segment if it overlaps the segments +in the file being +.IR exec'ed ; +otherwise the segment will be inherited. +.PP +Some machines provide a segment class +.BR lock . +Lock segments allow access to special lock hardware provided +by some multiprocessors, in particular the SGI Power Series machines. +.PP +Systems may also provide interfaces to special hardware devices like +frame buffers through the +.I segattach +interface. +Device memory mapped by this method is typically uncached by default. +.PP +If the specified +.I class +is unknown, +.I segattach +draws an error. +.PP +.I Attr +specifies the new segment's attributes. +The only attributes implemented on all classes of segment is +.BR SG_RONLY , +which allows only read access on the segment, and +.BR SG_CEXEC , +which causes the segment to be detached when the process does an +.IR exec (2). +Specific devices may implement +attributes to control caching and allocation, but these will vary +between devices. +.PP +.I Va +and +.I len +specify the position of the segment in the process's address space. +.I Va +is rounded down to the nearest page boundary and +.IB va + len +is rounded up. +The system does not permit segments to overlap. +If +.I va +is zero, the system will choose a suitable address. +.PP +.I Segdetach +removes a segment from a process's address space. Memory used by +the segment is freed. +.I Addr +may be any address within the bounds of the segment. +.PP +The system will not permit the text and stack segments to be detached +from the address space. +.PP +.I Segfree +tells the system that it may free any physical memory within the span +.RI [ va , +.IR va+len ), +but leaves that portion of the process's address space valid. +The system will not free any memory outside that span, +and may not free all or even any of the specified memory. +If free'd memory is later referenced, +it will be initialized as appropriate for the segment type. +For example data and text segments will be read from the executable file, +and bss segments will be filled with zero bytes. +.PP +The MIPS R2000 and R3000 have no hardware instructions +to implement locks. The following method can be used +to build them from software. +First, try to +.I segattach +a segment of class +.BR lock . +If this succeeds, the machine is an SGI Power Series and +the memory contains hardware locks. +Each 4096-byte page has 64 +.B long +words at its beginning; each word implements +a test-and-set semaphore when read; the low bit of the word +is zero on success, one on failure. +If the +.I segattach +fails, there is no hardware support but the operating system +helps: +Any +.B COP3 +instruction will be trapped by the kernel and interpreted +as a test-and-set. +In the trap, +.B R1 +points to a +.BR long ; +on return, +.B R1 +is greater or equal zero on success, negative on failure. +The following assembly language implements such a test-and-set. +.IP +.EX +.ta 8n +8n +8n +8n +8n +8n +8n +/* + * MIPS test and set + */ + TEXT tas(SB), $0 + MOVW R1, sema+0(FP) /* save arg on stack */ +btas: + MOVW sema+0(FP), R1 + MOVB R0, 1(R1) + NOR R0, R0, R0 /* NOP */ + WORD $(023<<26) /* MFC3 R0, R0 */ + BLTZ R1, btas + RET +.EE +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR lock (2), +.IR segbrk (2), +.IR segflush (2) +.br +.BR /proc/*/segment +.SH DIAGNOSTICS +These functions set +.IR errstr . +.SH BUGS +The return type of +.I segattach +is peculiar. +Also, +.I segattach +returns -1 on error; +beware that on some systems other negative +values might be legal addresses. +.br +There is a small fixed limit on the number of segments that may be attached, +as well as a maximum segment size. diff --git a/static/plan9-4e/man2/segbrk.2 b/static/plan9-4e/man2/segbrk.2 new file mode 100644 index 00000000..b6cf3bac --- /dev/null +++ b/static/plan9-4e/man2/segbrk.2 @@ -0,0 +1,43 @@ +.TH SEGBRK 2 +.SH NAME +segbrk \- change memory allocation +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid* 'u +.B +int segbrk(void *saddr, void *addr) +.PP +.SH DESCRIPTION +.I Segbrk +sets the system's idea of the lowest unused location of a segment +to +.I addr +rounded up to the next multiple of a page size, typically 4096 bytes. +The segment is identified by +.I saddr +which may be any valid address within the segment. +.PP +A call to +.I segbrk +with a zero +.I addr +argument returns the address +of the top of bss. +.PP +The system will prevent segments from overlapping and will not allow the +length of the +text, data, or stack segment to be altered. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR brk (2), +.IR segattach (2), +.IR segflush (2) +.br +.BR /proc/*/segment +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/segflush.2 b/static/plan9-4e/man2/segflush.2 new file mode 100644 index 00000000..53682548 --- /dev/null +++ b/static/plan9-4e/man2/segflush.2 @@ -0,0 +1,42 @@ +.TH SEGFLUSH 2 +.SH NAME +segflush \- flush instruction and data caches +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int segflush(void *va, ulong len) +.PP +.SH DESCRIPTION +.I Segflush +invalidates any instruction cache and writes back any data +cache associated with pages contained in a segment. +All subsequent new pages in the segment will also be flushed when first referenced. +.PP +.I Va +is an address within the segment to be flushed; +it is rounded down to the nearest page boundary. +.I Len +specifies the length in bytes of +the memory to flush; +.IB va + len +is rounded up to the nearest page boundary. +.I Segflush +works correctly when the memory straddles multiple segments. +.PP +Correct use of +.I segflush +depends on an understanding of the cache architecture of the specific +machine. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR segattach (2), +.IR segbrk (2) +.br +.BR /proc/*/segment +.SH DIAGNOSTICS +Sets +.IR errstr . diff --git a/static/plan9-4e/man2/setjmp.2 b/static/plan9-4e/man2/setjmp.2 new file mode 100644 index 00000000..4baa67f5 --- /dev/null +++ b/static/plan9-4e/man2/setjmp.2 @@ -0,0 +1,98 @@ +.TH SETJMP 2 +.SH NAME +setjmp, longjmp, notejmp \- non-local goto +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLvoid 'u +.B +int setjmp(jmp_buf env) +.PP +.B +void longjmp(jmp_buf env, int val) +.PP +.B +void notejmp(void *uregs, jmp_buf env, int val) +.SH DESCRIPTION +These routines are useful for dealing with errors +and interrupts encountered in +a low-level subroutine of a program. +.PP +.I Setjmp +saves its stack environment in +.I env +for later use by +.IR longjmp . +It returns value 0. +.PP +.I Longjmp +restores the environment saved by the last call of +.IR setjmp . +It then causes execution to +continue as if the call of +.I setjmp +had just returned with value +.IR val . +The invoker of +.I setjmp +must not itself have returned in the interim. +All accessible data have values as of the time +.I longjmp +was called. +.PP +.I Notejmp +is the same as +.I longjmp +except that it is to be called from within a note handler (see +.IR notify (2)). +The +.I uregs +argument should be the first argument passed to the note handler. +.PP +.I Setjmp +and +.I longjmp +can also be used to switch stacks. +Defined in +.B +are several macros that can be used to build +.B jmp_bufs +by hand. The following code establishes a +.B jmp_buf +.i label +that may be called by +.I longjmp +to begin execution in a function +.BR f +with 1024 bytes of stack: +.IP +.EX +#include +#include + +jmp_buf label; +#define NSTACK 1024 +char stack[NSTACK]; + +void +setlabel(void) +{ + label[JMPBUFPC] = ((ulong)f+JMPBUFDPC); + /* -2 leaves room for old pc and new pc in frame */ + label[JMPBUFSP = + (ulong)(&stack[NSTACK-2*sizeof(ulong*)]); +} +.EE +.SH SOURCE +.B /sys/src/libc/$objtype/setjmp.s +.br +.B /sys/src/libc/$objtype/notejmp.c +.SH SEE ALSO +.IR notify (2) +.SH BUGS +.PP +.I Notejmp +cannot recover from an address trap or bus error (page fault) on the 680x0 +architectures. diff --git a/static/plan9-4e/man2/sin.2 b/static/plan9-4e/man2/sin.2 new file mode 100644 index 00000000..ac2c2c50 --- /dev/null +++ b/static/plan9-4e/man2/sin.2 @@ -0,0 +1,64 @@ +.TH SIN 2 +.SH NAME +sin, cos, tan, asin, acos, atan, atan2 \- trigonometric functions +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +double sin(double x) +.PP +.B +double cos(double x) +.PP +.B +double tan(double x) +.PP +.B +double asin(double x) +.PP +.B +double acos(double x) +.PP +.B +double atan(double x) +.PP +.B +double atan2(double y, double x) +.SH DESCRIPTION +.I Sin, cos +and +.I tan +return trigonometric functions of radian arguments. +The magnitude of the argument should be checked +by the caller to make sure the result is meaningful. +.PP +.I Asin +returns the arc sine in the range +\-π/2 to π/2. +.PP +.I Acos +returns the arc cosine in the range +0 to π. +.PP +.I Atan +returns the arc tangent in the range +\-π/2 to π/2. +.PP +.I Atan2 +returns the arc tangent of +.I y/x +in the range +\-π to π. +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR intro (2) +.SH BUGS +The value of +.I tan +for arguments greater than about +.if t 2\u\s-231\s+2\d +.if n 2^31 +is garbage. diff --git a/static/plan9-4e/man2/sinh.2 b/static/plan9-4e/man2/sinh.2 new file mode 100644 index 00000000..7dd4184b --- /dev/null +++ b/static/plan9-4e/man2/sinh.2 @@ -0,0 +1,23 @@ +.TH SINH 2 +.SH NAME +sinh, cosh, tanh \- hyperbolic functions +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +double sinh(double x) +.PP +.B +double cosh(double x) +.PP +.B +double tanh(double x) +.SH DESCRIPTION +These functions compute the designated hyperbolic functions +for real arguments. +.SH SOURCE +.B /sys/src/libc/port +.SH SEE ALSO +.IR intro (2) diff --git a/static/plan9-4e/man2/sleep.2 b/static/plan9-4e/man2/sleep.2 new file mode 100644 index 00000000..013df3c5 --- /dev/null +++ b/static/plan9-4e/man2/sleep.2 @@ -0,0 +1,45 @@ +.TH SLEEP 2 +.SH NAME +sleep, alarm \- delay, ask for delayed note +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int sleep(long millisecs) +.PP +.B +long alarm(unsigned long millisecs) +.SH DESCRIPTION +.I Sleep +suspends the current process for the number +of milliseconds specified by the argument. +The actual suspension time may be a little more or less than +the requested time. If +.I millisecs +is 0, the process +gives up the CPU if another process is waiting to run, returning +immediately if not. +Sleep returns \-1 if interrupted, 0 otherwise. +.PP +.I Alarm +causes an +.B alarm +note (see +.IR notify (2)) +to be sent to the invoking process after the number of milliseconds +given by the argument. +Successive calls to +.I alarm +reset the alarm clock. +A zero argument clears the alarm. +The return value is the amount of time previously remaining in +the alarm clock. +.SH SOURCE +.B /sys/src/libc/9syscall +.SH SEE ALSO +.IR intro (2) +.SH DIAGNOSTICS +These functions set +.IR errstr . diff --git a/static/plan9-4e/man2/stat.2 b/static/plan9-4e/man2/stat.2 new file mode 100644 index 00000000..26823e10 --- /dev/null +++ b/static/plan9-4e/man2/stat.2 @@ -0,0 +1,326 @@ +.TH STAT 2 +.SH NAME +stat, fstat, wstat, fwstat, dirstat, dirfstat, dirwstat, dirfwstat, nulldir \- get and put file status +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +int stat(char *name, uchar *edir, int nedir) +.PP +.B +int fstat(int fd, uchar *edir, int nedir) +.PP +.B +int wstat(char *name, uchar *edir, int nedir) +.PP +.B +int fwstat(int fd, uchar *edir, int nedir) +.PP +.B +Dir* dirstat(char *name) +.PP +.B +Dir* dirfstat(int fd) +.PP +.B +int dirwstat(char *name, Dir *dir) +.PP +.B +int dirfwstat(int fd, Dir *dir) +.PP +.B +void nulldir(Dir *d) +.SH DESCRIPTION +Given a file's +.IR name , +or an open file descriptor +.IR fd , +these routines retrieve or modify file status information. +.IR Stat , +.IR fstat , +.IR wstat , +and +.I fwstat +are the system calls; they deal with machine-independent +.IR "directory entries" . +Their format is defined by +.IR stat (5). +.I Stat +and +.I fstat +retrieve information about +.I name +or +.I fd +into +.IR edir , +a buffer of length +.IR nedir , +defined in +.BR . +.I Wstat +and +.I fwstat +write information back, thus changing file attributes according to the contents of +.IR edir . +The data returned from the kernel includes its leading 16-bit length field +as described in +.IR intro (5). +For symmetry, this field must also be present when passing data to the kernel in a call to +.I wstat +and +.IR fwstat , +but its value is ignored. +.PP +.IR Dirstat , +.IR dirfstat , +.IR dirwstat , +and +.I dirfwstat +are similar to their counterparts, except that they +operate on +.I Dir +structures: +.IP +.EX +.ta 6n +\w'ulong 'u +\w'mtime; 'u +typedef +struct Dir { + /* system-modified data */ + uint type; /* server type */ + uint dev; /* server subtype */ + /* file data */ + Qid qid; /* unique id from server */ + ulong mode; /* permissions */ + ulong atime; /* last read time */ + ulong mtime; /* last write time */ + vlong length; /* file length: see */ + char *name; /* last element of path */ + char *uid; /* owner name */ + char *gid; /* group name */ + char *muid; /* last modifier name */ +} Dir; +.EE +.PP +The returned structure is allocated by +.IR malloc (2); +freeing it also frees the associated strings. +.PP +This structure and +the +.B Qid +structure +are defined in +.BR . +If the file resides on permanent storage and is not a directory, +the length returned by +.I stat +is the number of bytes in the file. +For directories, the length returned is zero. +For files that are streams (e.g., pipes and network connections), +the length is the number of bytes that can be read without blocking. +.PP +Each file is the responsibility of some +.IR server : +it could be a file server, a kernel device, or a user process. +.B Type +identifies the server type, and +.B dev +says which of a group of servers of the same type is the one +responsible for this file. +.B Qid +is a structure containing +.B path +and +.B vers +fields: +.B path +is guaranteed to be +unique among all path names currently on the file server, and +.B vers +changes each time the file is modified. +The +.B path +is a +.B long +.B long +(64 bits, +.BR vlong ) +and the +.B vers +is an +.B unsigned long +(32 bits, +.BR ulong ). +Thus, if two files have the same +.BR type , +.BR dev , +and +.B qid +they are the same file. +.PP +The bits in +.B mode +are defined by +.PP +.ta 6n +\w'\fL0x80000000 'u +.nf +\fL 0x80000000\fP directory +\fL 0x40000000\fP append only +\fL 0x20000000\fP exclusive use (locked) + +\fL 0400\fP read permission by owner +\fL 0200\fP write permission by owner +\fL 0100\fP execute permission (search on directory) by owner +\fL 0070\fP read, write, execute (search) by group +\fL 0007\fP read, write, execute (search) by others +.fi +.PP +There are constants defined in +.B +for these bits: +.BR DMDIR , +.BR DMAPPEND , +and +.B DMEXCL +for the first three; and +.BR DMREAD , +.BR DMWRITE , +and +.B DMEXEC +for the read, write, and execute bits for others. +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +.B Mtime +is the time of the last change of content. +Similarly, +.B atime +is set whenever the contents are accessed; +also, it is set whenever +.B mtime +is set. +.PP +.B Uid +and +.B gid +are the names of the owner and group of the file; +.B muid +is the name of the user that last modified the file (setting +.BR mtime ). +Groups are also users, but each server is free to associate +a list of users with any user name +.IR g , +and that list is the +set of users in the group +.IR g . +When an initial attachment is made to a server, +the user string in the process group is communicated to the server. +Thus, the server knows, for any given file access, whether the accessing +process is the owner of, or in the group of, the file. +This selects which sets of three bits in +.B mode +is used to check permissions. +.PP +Only some of the fields may be changed with the +.I wstat +calls. +The +.B name +can be changed by anyone with write permission in the parent directory. +The +.B mode +and +.B mtime +can be changed by the owner or the group leader of the file's current +group. +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 (5) +for more information about permissions and +.IR users (6) +for 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). +.PP +Special values in the fields of the +.B Dir +passed to +.I wstat +indicate that the field is not intended to be changed by the call. +The values are the maximum unsigned integer of appropriate size +for integral values (usually +.BR ~0 , +but beware of conversions and size mismatches +when comparing values) and the empty or nil string for string values. +The routine +.I nulldir +initializes all the elements of +.I d +to these ``don't care'' values. +Thus one may change the mode, for example, by using +.I nulldir +to initialize a +.BR Dir , +then setting the mode, and then doing +.IR wstat ; +it is not necessary to use +.I stat +to retrieve the initial values first. +.SH SOURCE +.TF /sys/src/libc/9syscall +.TP +.B /sys/src/libc/9syscall +for the +.RB non- dir +routines +.TP +.B /sys/src/libc/9sys +for the routines prefixed +.B dir +.SH SEE ALSO +.IR intro (2), +.IR fcall (2), +.IR dirread (2), +.IR stat (5) +.SH DIAGNOSTICS +The +.I dir +functions return a pointer to the data for a successful call, or +.B nil +on error. +The others +return the number of bytes copied on success, or \-1 on error. +All set +.IR errstr . +.PP +If the buffer for +.I stat +or +.I fstat +is too short for the returned data, the return value will be +.B BIT16SZ +(see +.IR fcall (2)) +and the two bytes +returned will contain the initial count field of the +returned data; +retrying with +.B nedir +equal to +that value plus +.B BIT16SZ +(for the count itself) should succeed. diff --git a/static/plan9-4e/man2/strcat.2 b/static/plan9-4e/man2/strcat.2 new file mode 100644 index 00000000..22ba8fb0 --- /dev/null +++ b/static/plan9-4e/man2/strcat.2 @@ -0,0 +1,268 @@ +.TH STRCAT 2 +.SH NAME +strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr \- string operations +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.ta \w'\fLchar* \fP'u +.B +char* strcat(char *s1, char *s2) +.PP +.B +char* strncat(char *s1, char *s2, long n) +.PP +.B +int strcmp(char *s1, char *s2) +.PP +.B +int strncmp(char *s1, char *s2, long n) +.PP +.B +int cistrcmp(char *s1, char *s2) +.PP +.B +int cistrncmp(char *s1, char *s2, long n) +.PP +.B +char* strcpy(char *s1, char *s2) +.PP +.B +char* strecpy(char *s1, char *es1, char *s2) +.PP +.B +char* strncpy(char *s1, char *s2, long n) +.PP +.B +long strlen(char *s) +.PP +.B +char* strchr(char *s, char c) +.PP +.B +char* strrchr(char *s, char c) +.PP +.B +char* strpbrk(char *s1, char *s2) +.PP +.B +long strspn(char *s1, char *s2) +.PP +.B +long strcspn(char *s1, char *s2) +.PP +.B +char* strtok(char *s1, char *s2) +.PP +.B +char* strdup(char *s) +.PP +.B +char* strstr(char *s1, char *s2) +.PP +.B +char* cistrstr(char *s1, char *s2) +.SH DESCRIPTION +The arguments +.I s1, s2 +and +.I s +point to null-terminated strings. +The functions +.IR strcat , +.IR strncat , +.IR strcpy , +.IR strecpy , +and +.I strncpy +all alter +.IR s1 . +.I Strcat +and +.I strcpy +do not check for overflow of +the array pointed to by +.IR s1 . +.PP +.I Strcat +appends a copy of string +.I s2 +to the end of string +.IR s1 . +.I Strncat +appends at most +.I n +bytes. +Each returns a pointer to the null-terminated result. +.PP +.I Strcmp +compares its arguments 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 . +.I Strncmp +makes the same comparison but examines at most +.I n +bytes. +.I Cistrcmp +and +.I cistrncmp +ignore ASCII case distictions when comparing strings. +The comparisons are made with unsigned bytes. +.PP +.I Strcpy +copies string +.I s2 +to +.IR s1 , +stopping after the null byte has been copied. +.I Strncpy +copies exactly +.I n +bytes, +truncating +.I s2 +or adding +null bytes to +.I s1 +if necessary. +The result will not be null-terminated if the length +of +.I s2 +is +.I n +or more. +Each function returns +.IR s1 . +.PP +.I Strecpy +copies bytes until a null byte has been copied, but writes no bytes beyond +.IR es1 . +If any bytes are copied, +.I s1 +is terminated by a null byte, and a pointer to that byte is returned. +Otherwise, the original +.I s1 +is returned. +.PP +.I Strlen +returns the number of bytes in +.IR s , +not including the terminating null byte. +.PP +.I Strchr +.RI ( strrchr ) +returns a pointer to the first (last) +occurrence of byte +.I c +in string +.IR s , +or +.L 0 +if +.I c +does not occur in the string. +The null byte terminating a string is considered to +be part of the string. +.PP +.I Strpbrk +returns a pointer to the first occurrence in string +.I s1 +of any byte from string +.IR s2 , +.L 0 +if no byte from +.I s2 +exists in +.IR s1 . +.PP +.I Strspn +.RI ( strcspn ) +returns the length of the initial segment of string +.I s1 +which consists entirely of bytes from (not from) string +.IR s2 . +.PP +.I Strtok +considers the string +.I s1 +to consist of a sequence of zero or more text tokens separated +by spans of one or more bytes from the separator string +.IR s2 . +The first call, with pointer +.I s1 +specified, returns a pointer to the first byte of the first +token, and will have written a +null byte into +.I s1 +immediately following the returned token. +The function +keeps track of its position in the string +between separate calls; subsequent calls, +signified by +.I s1 +being +.LR 0 , +will work through the string +.I s1 +immediately following that token. +The separator string +.I s2 +may be different from call to call. +When no token remains in +.IR s1 , +.L 0 +is returned. +.PP +.I Strdup +returns a pointer to a distinct copy of the null-terminated string +.I s +in space obtained from +.IR malloc (2) +or +.L 0 +if no space can be obtained. +.PP +.I Strstr +returns a pointer to the first occurrence of +.I s2 +as a substring of +.IR s1 , +or 0 if there is none. +If +.I s2 +is the null string, +.I strstr +returns +.IR s1 . +.I Cistrstr +operates analogously, but ignores ASCII case differences when comparing strings. +.SH SOURCE +All these routines have portable C implementations in +.BR /sys/src/libc/port . +Many also have machine-dependent assembly language +implementations in +.BR /sys/src/libc/$objtype . +.SH SEE ALSO +.IR memory (2), +.IR rune (2), +.IR runestrcat (2) +.SH BUGS +These routines know nothing about +.SM UTF. +Use the routines in +.IR rune (2) +as appropriate. +Note, however, that the definition of +.SM UTF +guarantees that +.I strcmp +compares +.SM UTF +strings correctly. +.PP +The outcome of overlapping moves varies among implementations. diff --git a/static/plan9-4e/man2/string.2 b/static/plan9-4e/man2/string.2 new file mode 100644 index 00000000..a69103b3 --- /dev/null +++ b/static/plan9-4e/man2/string.2 @@ -0,0 +1,231 @@ +.TH STRING 2 +.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 +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B +String* s_new(void) +.br +.B +void s_free(String *s) +.br +.B +String* s_newalloc(int n) +.br +.B +String* s_array(char *p, int n) +.br +.B +String* s_grow(String *s, int n) +.PP +.B +void s_putc(String *s, int c) +.br +.B +void s_terminate(String *s) +.br +.B +String* s_reset(String *s) +.br +.B +String* s_restart(String *s) +.br +.B +String* s_append(String *s, char *p) +.br +.B +String* s_nappend(String *s, char *p, int n) +.br +.B +String* s_memappend(String *s, char *p, int n) +.br +.B +String* s_copy(char *p) +.br +.B +String* s_parse(String *s1, String *s2) +.br +.PP +.B +void s_tolower(String *s) +.PP +.B +String* s_incref(String *s) +.br +.B +String* s_unique(String *s) +.PP +.B +#include +.PP +.B +int s_read(Biobuf *b, String *s, int n) +.br +.B +char* s_read_line(Biobuf *b, String *s) +.br +.B +char* s_getline(Biobuf *b, String *s) +.SH DESCRIPTION +.PP +These routines manipulate extensible strings. +The basic type is +.BR String , +which points to an array of characters. The string +maintains pointers to the beginning and end of the allocated +array. In addition a finger pointer keeps track of where +parsing will start (for +.IR s_parse ) +or new characters will be added (for +.IR s_putc , +.IR s_append , +and +.IR s_nappend ). +The structure, and a few useful macros are: +.sp +.EX +typedef struct String { + Lock; + char *base; /* base of String */ + char *end; /* end of allocated space+1 */ + char *ptr; /* ptr into String */ + ... +} String; + +#define s_to_c(s) ((s)->base) +#define s_len(s) ((s)->ptr-(s)->base) +#define s_clone(s) s_copy((s)->base) +.EE +.PP +.I S_to_c +is used when code needs a reference to the character array. +Using +.B s->base +directly is frowned upon since it exposes too much of the implementation. +.SS "allocation and freeing +.PP +A string must be allocated before it can be used. +One normally does this using +.IR s_new , +giving the string an initial allocation of +128 bytes. +If you know that the string will need to grow much +longer, you can use +.I s_newalloc +instead, specifying the number of bytes in the +initial allocation. +.PP +.I S_free +causes both the string and its character array to be freed. +.PP +.I S_grow +grows a string's allocation by a fixed amount. It is useful if +you are reading directly into a string's character array but should +be avoided if possible. +.PP +.I S_array +is used to create a constant array, that is, one whose contents +won't change. It points directly to the character array +given as an argument. Tread lightly when using this call. +.SS "Filling the string +After its initial allocation, the string points to the beginning +of an allocated array of characters starting with +.SM NUL. +.PP +.I S_putc +writes a character into the string at the +pointer and advances the pointer to point after it. +.PP +.I S_terminate +writes a +.SM NUL +at the pointer but doesn't advance it. +.PP +.I S_restart +resets the pointer to the begining of the string but doesn't change the contents. +.PP +.I S_reset +is equivalent to +.I s_restart +followed by +.IR s_terminate . +.PP +.I S_append +and +.I s_nappend +copy characters into the string at the pointer and +advance the pointer. They also write a +.SM NUL +at +the pointer without advancing the pointer beyond it. +Both routines stop copying on encountering a +.SM NUL. +.I S_memappend +is like +.I s_nappend +but doesn't stop at a +.SM NUL. +.PP +If you know the initial character array to be copied into a string, +you can allocate a string and copy in the bytes using +.IR s_copy . +This is the equivalent of a +.I s_new +followed by an +.IR s_append . +.PP +.I S_parse +copies the next white space terminated token from +.I s1 +to +the end of +.IR s2 . +White space is defined as space, tab, +and newline. Both single and double quoted strings are treated as +a single token. The bounding quotes are not copied. +There is no escape mechanism. +.PP +.I S_tolower +converts all +.SM ASCII +characters in the string to lower case. +.SS Multithreading +.PP +.I S_incref +is used by multithreaded programs to avoid having the string memory +released until the last user of the string performs an +.IR s_free . +.I S_unique +returns a unique copy of the string: if the reference count it +1 it returns the string, otherwise it returns an +.I s_clone +of the string. +.SS "Bio interaction +.PP +.I S_read +reads the requested number of characters through a +.I Biobuf +into a string. The string is grown as necessary. +An eof or error terminates the read. +The number of bytes read is returned. +The string is null terminated. +.PP +.I S_read_line +reads up to and including the next newline and returns +a pointer to the beginning of the bytes read. +An eof or error terminates the read. +The string is null terminated. +.PP +.I S_getline +reads up to the next newline and returns +a pointer to the beginning of the bytes read. Leading +spaces and tabs and the trailing newline are all discarded. +.SH SOURCE +.B /sys/src/libString +.SH SEE ALSO +.IR bio (2) diff --git a/static/plan9-4e/man2/stringsize.2 b/static/plan9-4e/man2/stringsize.2 new file mode 100644 index 00000000..12852815 --- /dev/null +++ b/static/plan9-4e/man2/stringsize.2 @@ -0,0 +1,69 @@ +.TH STRINGSIZE 2 +.SH NAME +stringsize, stringwidth, stringnwidth, runestringsize, runestringwidth, runestringnwidth \- graphical size of strings +.SH SYNOPSIS +.nf +.PP +.ft L +#include +#include +#include +.ft P +.ta \w'\fLPoint 'u +.PP +.B +Point stringsize(Font *f, char *s) +.PP +.B +int stringwidth(Font *f, char *s) +.PP +.B +int stringnwidth(Font *f, char *s, int n) +.PP +.B +Point runestringsize(Font *f, Rune *s) +.PP +.B +int runestringwidth(Font *f, Rune *s) +.PP +.B +int runestringnwidth(Font *f, Rune *s, int n) +.SH DESCRIPTION +These routines compute the geometrical extent of character strings when drawn on the display. The most straightforward, +.BR stringsize , +returns a +.B Point +representing the vector from upper left to lower right of the NUL-terminated string +.I s +drawn in font +.IR f . +.B Stringwidth +returns just the +.I x +component. +.B Stringnwidth +returns the width of the first +.I n +characters of +.IR s . +.PP +The routines beginning with +.B rune +are analogous, but accept an array of runes rather than +.SM UTF\c +-encoded bytes. +.SH FILES +.BR /lib/font/bit " directory of fonts +.SH SOURCE +.B /sys/src/libdraw +.SH "SEE ALSO" +.IR addpt (2), +.IR cachechars (2), +.IR subfont (2), +.IR draw (2), +.IR draw (3), +.IR image (6), +.IR font (6) +.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/static/plan9-4e/man2/subfont.2 b/static/plan9-4e/man2/subfont.2 new file mode 100644 index 00000000..fb43b2a3 --- /dev/null +++ b/static/plan9-4e/man2/subfont.2 @@ -0,0 +1,235 @@ +.TH SUBFONT 2 +.SH NAME +allocsubfont, freesubfont, installsubfont, lookupsubfont, uninstallsubfont, subfontname, readsubfont, readsubfonti, writesubfont, stringsubfont, strsubfontwidth, mkfont \- subfont manipulation +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLSubfont* 'u +.B +Subfont* allocsubfont(char *name, int n, int height, int ascent, +.br +.B + Fontchar *info, Image *i) +.PP +.B +void freesubfont(Subfont *f) +.PP +.B +void installsubfont(char *name, Subfont *f) +.PP +.B +Subfont* lookupsubfont(Subfont *f) +.PP +.B +void uninstallsubfont(Subfont *f) +.PP +.B +Subfont* readsubfont(Display *d, char *name, int fd, int dolock) +.PP +.B +Subfont* readsubfonti(Display *d, char *name, int fd, Image *im, +.br +.B + int dolock) +.PP +.B +int writesubfont(int fd, Subfont *f) +.PP +.B +Point stringsubfont(Image *dst, Point p, Image *src, +.br +.B + Subfont *f, char *str) +.PP +.B +Point strsubfontwidth(Subfont *f, char *s) +.PP +.B +Font* mkfont(Subfont *f, Rune min) +.SH DESCRIPTION +Subfonts are the components of fonts that hold the character images. +A font comprises an array of subfonts; see +.IR cachechars (2). +A new +.B Subfont +is allocated and initialized with +.IR allocsubfont . +See +.IR cachechars (2) +for the meaning of +.IR n , +.IR height , +.IR ascent , +and +.IR info , +and the arrangement of characters in +image +.IR i . +The +.I name +is used to identify the subfont in the subfont cache; see the descriptions +.I lookupsubfont +and +.IR installsubfont +.RI ( q.v. ). +The appropriate fields of the returned +.B Subfont +structure are set to +the passed arguments, and the image is registered as a subfont +with the graphics device +.IR draw (3). +.I Allocsubfont +returns 0 on failure. +.PP +.I Freesubfont +frees a subfont and all its associated structure including the +associated image. +Since +.I freesbufont +calls +.I free +on +.BR f->info , +if +.B f->info +was not allocated by +.IR malloc (2) +it should be zeroed before calling +.IR subffree . +.PP +A number of subfonts are kept in external files. +The convention for naming subfont files is: +.IP +.B /lib/font/bit/\fIname\fP/\fIclass\fP.\fIsize\fP.\fIdepth +.PD +.PP +where +.I size +is approximately the height in pixels of the lower case letters +(without ascenders or descenders). +If there is only one version of the subfont, the +.BI \&. depth +extension is elided. +.I Class +describes the range of runes encoded in the subfont: +.BR ascii , +.BR latin1 , +.BR greek , +etc. +.PP +Subfonts are cached within the program, so a subfont shared between fonts will be loaded only once. +.I Installsubfont +stores subfont +.I f +under the given +.IR name , +typically the file name from which it was read. +.I Uninstallsubfont +removes the subfont from the cache. +Finally, +.I lookupsubfont +searches for a subfont with the given +.I name +in the cache and returns it, or nil if no such subfont exists. +.PP +.I Subfontname +is used to locate subfonts given their names within the fonts. +The default version constructs a name given the +.IR cfname , +its name within the font, +.IR fname , +the name of the font, and the maximum depth suitable for this subfont. +This interface allows a partially specified name within a font to be resolved +at run-time to the name of a file holding a suitable subfont. +Although it is principally a routine internal to the library, +.I subfontname +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). +Briefly, it contains a image with all the characters in it, +followed by a subfont header, followed by character information. +.I Readsubfont +reads a subfont from the file descriptor +.IR fd . +The +.I name +is used to identify the font in the cache. +The +.I dolock +argument specifies whether the routine should synchronize +use of the +.I Display +with other processes; for single-threaded applications it may +always be zero. +.I Readsubfonti +does the same for a subfont whose associated image is already in memory; it is passed as the +argument +.IR im . +In other words, +.I readsubfonti +reads only the header and character information from the file descriptor. +.PP +.I Writesubfont +writes on +.I fd +the part of a subfont file that comes after the image. It should be preceded by +a call to +.IR writeimage +(see +.IR allocimage (2)). +.PP +.I Stringsubfont +is analogous to +.B string +(see +.IR draw (2)) +for subfonts. Rather than use the underlying font caching primitives, +it calls +.B draw +for each character. +It is intended for stand-alone environments such as operating system kernels. +.I Strsubfontwidth +returns the width of the string +.I s +in +as it would appear if drawn with +.I stringsubfont +in +.B Subfont +.BR f . +.PP +.I Mkfont +takes as argument a +.B Subfont +.I s +and returns a pointer to a +.B Font +that maps the character images in +.I s +into the +.B Runes +.I min +to +.IB min + s ->n-1\f1. +.SH FILES +.TF /lib/font/bit +.TP +.B /lib/font/bit +bitmap font file tree +.SH SOURCE +.B /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR allocimage (2), +.IR draw (2), +.IR cachechars (2), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +All of the functions use the graphics error function (see +.IR graphics (2)). diff --git a/static/plan9-4e/man2/symbol.2 b/static/plan9-4e/man2/symbol.2 new file mode 100644 index 00000000..a25e7359 --- /dev/null +++ b/static/plan9-4e/man2/symbol.2 @@ -0,0 +1,436 @@ +.TH SYMBOL 2 +.SH NAME +syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal, +getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym, +fileline, fnbound \- symbol table access functions +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int syminit(int fd, Fhdr *fp) +.PP +.B +Sym *getsym(int index) +.PP +.B +Sym *symbase(long *nsyms) +.PP +.B +int fileelem(Sym **fp, uchar *encname, char *buf, int n) +.PP +.B +int filesym(int index, char *buf, int n) +.PP +.B +long pc2sp(ulong pc) +.PP +.B +long pc2line(ulong pc) +.PP +.B +void textseg(ulong base, Fhdr *fp) +.PP +.B +long line2addr(ulong line, ulong basepc) +.PP +.B +int lookup(char *fn, char *var, Symbol *s) +.PP +.B +int findlocal(Symbol *s1, char *name, Symbol *s2) +.PP +.B +int getauto(Symbol *s1, int off, int class, Symbol *s2) +.PP +.B +int findsym(long addr, int class, Symbol *s) +.PP +.B +int localsym(Symbol *s, int index) +.PP +.B +int globalsym(Symbol *s, int index) +.PP +.B +int textsym(Symbol *s, int index) +.PP +.B +long file2pc(char *file, ulong line) +.PP +.B +int fileline(char *str, int n, ulong addr) +.PP +.B +int fnbound(long addr, ulong *bounds) +.SH DESCRIPTION +These functions provide machine-independent access to the +symbol table of an executable file or executing process. +The latter is accessible by opening the device +.B /proc/\fIpid\fP/text +as described in +.IR proc (3). +.IR Mach (2) +and +.IR object (2) +describe additional library functions +for processing executable and object files. +.PP +.IR Syminit , +.IR getsym , +.IR symbase , +.IR fileelem , +.IR pc2sp , +.IR pc2line , +and +.I line2addr +process the symbol table contained in an executable file +or the +.B text +image of an executing program. +The symbol table is stored internally as an array of +.B Sym +data structures as defined in +.IR a.out (6). +.PP +.I Syminit +uses the data in the +.B Fhdr +structure filled by +.I crackhdr +(see +.IR mach (2)) +to read the raw symbol tables from the open file descriptor +.IR fd . +It returns the count of the number of symbols +or \-1 if an error occurs. +.PP +.I Getsym +returns the address of the +.IR i th +.B Sym +structure or zero if +.I index +is out of range. +.PP +.I Symbase +returns the address of the first +.B Sym +structure in the symbol table. The number of +entries in the symbol table is returned in +.IR nsyms . +.PP +.I Fileelem +converts a file name, encoded as described in +.IR a.out (6), +to a character string. +.I Fp +is the base of +an array of pointers to file path components ordered by path index. +.I Encname +is the address of an array of encoded +file path components in the form of a +.B z +symbol table entry. +.I Buf +and +.I n +specify the +address of a receiving character buffer and its length. +.I Fileelem +returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +.PP +.I Filesym +is a higher-level interface to +.IR fileelem . +It fills +.I buf +with the name of the +.IR i th +file and returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +File names are retrieved in no particular order, although +the order of retrieval does not vary from one pass to the next. +A zero is returned when +.I index +is too large or too small or an error occurs during file name +conversion. +.PP +.I Pc2sp +returns an offset associated with +a given value of the program counter. Adding this offset +to the current value of the stack pointer gives the address +of the current stack frame. This approach only applies +to the 68020 architecture; other architectures +use a fixed stack frame offset by a constant contained +in a dummy local variable (called +.BR .frame ) +in the symbol table. +.PP +.I Pc2line +returns the line number of the statement associated +with the instruction address +.IR pc . +The +line number is the absolute line number in the +source file as seen by the compiler after pre-processing; the +original line number in the source file may be derived from this +value using the history stacks contained in the symbol table. +.PP +.I Pc2sp +and +.I pc2line +must know the start and end addresses of the text segment +for proper operation. These values are calculated from the +file header by function +.IR syminit . +If the text segment address is changed, the application +program must invoke +.I textseg +to recalculate the boundaries of the segment. +.I Base +is the new base address of the text segment and +.I fp +points to the +.I Fhdr +data structure filled by +.IR crackhdr . +.PP +.I Line2addr +converts a line number to an instruction address. The +first argument is the absolute line number in +a file. Since a line number does not uniquely identify +an instruction location (e.g., every source file has line 1), +a second argument specifies a text address +from which the search begins. Usually this +is the address of the first function in the file of interest. +.PP +.IR Pc2sp , +.IR pc2line , +and +.I line2addr +return \-1 in the case of an error. +.PP +.IR Lookup , +.IR findlocal , +.IR getauto , +.IR findsym , +.IR localsym , +.IR globalsym , +.IR textsym , +.IR file2pc , +and +.I fileline +operate on data structures riding above the raw symbol table. +These data structures occupy memory +and impose a startup penalty but speed retrievals +and provide higher-level access to the basic symbol +table data. +.I Syminit +must be called +prior to using these functions. +The +.B Symbol +data structure: +.IP +.EX +typedef struct { + void *handle; /* private */ + struct { + char *name; + long value; + char type; + char class; + }; +} Symbol; +.EE +.LP +describes a symbol table entry. +The +.B value +field contains the offset of the symbol within its +address space: global variables relative to the beginning +of the data segment, text beyond the start of the text +segment, and automatic variables and parameters relative +to the stack frame. The +.B type +field contains the type of the symbol as defined in +.IR a.out (6). +The +.B class +field assigns the symbol to a general class; +.BR CTEXT , +.BR CDATA , +.BR CAUTO , +and +.B CPARAM +are the most popular. +.PP +.I Lookup +fills a +.B Symbol +structure with symbol table information. Global variables +and functions are represented by a single name; local variables +and parameters are uniquely specified by a function and +variable name pair. Arguments +.I fn +and +.I var +contain the +name of a function and variable, respectively. +If both +are non-zero, the symbol table is searched for a parameter +or automatic variable. If only +.I var +is +zero, the text symbol table is searched for function +.IR fn . +If only +.I fn +is zero, the global variable table +is searched for +.IR var . +.PP +.I Findlocal +fills +.I s2 +with the symbol table data of the automatic variable +or parameter matching +.IR name . +.I S1 +is a +.B Symbol +data structure describing a function or a local variable; +the latter resolves to its owning function. +.PP +.I Getauto +searches the local symbols associated with function +.I s1 +for an automatic variable or parameter located at stack +offset +.IR off . +.I Class +selects the class of +variable: +.B CAUTO +or +.BR CPARAM . +.I S2 +is the address of a +.B Symbol +data structure to receive the symbol table information +of the desired symbol. +.PP +.I Findsym +returns the symbol table entry of type +.I class +stored near +.IR addr . +The selected symbol is a global variable or function +with address nearest to and less than or equal to +.IR addr . +Class specification +.B CDATA +searches only the global variable symbol table; class +.B CTEXT +limits the search to the text symbol table. +Class specification +.B CANY +searches the text table first, then the global table. +.PP +.I Localsym +returns the +.IR i th +local variable in the function +associated with +.IR s . +.I S +may reference a function or a local variable; the latter +resolves to its owning function. +If the +.IR i th +local symbol exists, +.I s +is filled with the data describing it. +.PP +.I Globalsym +loads +.I s +with the symbol table information of the +.IR i th +global variable. +.PP +.I Textsym +loads +.I s +with the symbol table information of the +.IR i th +text symbol. The text symbols are ordered +by increasing address. +.PP +.I File2pc +returns a text address associated with +.I line +in file +.IR file , +or -1 on an error. +.PP +.I Fileline +converts text address +.I addr +to its equivalent +line number in a source file. The result, +a null terminated character string of +the form +.LR file:line , +is placed in buffer +.I str +of +.I n +bytes. +.PP +.I Fnbound +returns the start and end addresses of the function containing +the text address supplied as the first argument. The second +argument is an array of two unsigned longs; +.I fnbound +places the bounding addresses of the function in the first +and second elements of this array. The start address is the +address of the first instruction of the function; the end +address is the address of the start of the next function +in memory, so it is beyond the end of the target function. +.I Fnbound +returns 1 if the address is within a text function, or zero +if the address selects no function. +.PP +Functions +.I file2pc +and +.I fileline +may produce inaccurate results when applied to +optimized code. +.PP +Unless otherwise specified, all functions return 1 +on success, or 0 on error. When an error occurs, +a message describing it is stored in the system +error buffer where it is available via +.IR errstr . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) diff --git a/static/plan9-4e/man2/thread.2 b/static/plan9-4e/man2/thread.2 new file mode 100644 index 00000000..b37870df --- /dev/null +++ b/static/plan9-4e/man2/thread.2 @@ -0,0 +1,578 @@ +.TH THREAD 2 +.SH NAME +alt, +chancreate, +chanfree, +chaninit, +chanprint, +mainstacksize, +proccreate, +procdata, +procexec, +procexecl, +procrfork, +recv, +recvp, +recvul, +send, +sendp, +sendul, +nbrecv, +nbrecvp, +nbrecvul, +nbsend, +nbsendp, +nbsendul, +threadcreate, +threaddata, +threadexits, +threadexitsall, +threadgetgrp, +threadgetname, +threadint, +threadintgrp, +threadkill, +threadkillgrp, +threadmain, +threadnotify, +threadid, +threadpid, +threadprint, +threadsetgrp, +threadsetname, +threadwaitchan, +yield \- thread and proc management +.SH SYNOPSIS +.PP +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +#include +#include +#include +.sp +#define CHANEND 0 +#define CHANSND 1 +#define CHANRCV 2 +#define CHANNOP 3 +#define CHANNOBLK 4 +.sp +.ta \w' 'u +\w'Channel 'u +typedef struct Alt Alt; +struct Alt { + Channel *c; + void *v; + int op; + Channel **tag; + int entryno; +}; +.fi +.de XX +.ift .sp 0.5 +.ifn .sp +.. +.PP +.nf +.ft L +.ta \w'\fLChannel* 'u +4n +4n +4n +4n +void threadmain(int argc, char *argv[]) +int mainstacksize +int proccreate(void (*fn)(void*), void *arg, uint stacksize) +int procrfork(void (*fn)(void*), void *arg, uint stacksize, + int rforkflag) +int threadcreate(void (*fn)(void*), void *arg, uint stacksize) +void threadexits(char *status) +void threadexitsall(char *status) +void yield(void) +.XX +int threadid(void) +int threadgrp(void) +int threadsetgrp(int group) +int threadpid(int id) +.XX +int threadint(int id) +int threadintgrp(int group) +int threadkill(int id) +int threadkillgrp(int group) +.XX +void threadsetname(char *name) +char* threadgetname(void) +.XX +void** threaddata(void) +void** procdata(void) +.XX +int chaninit(Channel *c, int elsize, int nel) +Channel* chancreate(int elsize, int nel) +void chanfree(Channel *c) +.XX +int alt(Alt *alts) +int recv(Channel *c, void *v) +void* recvp(Channel *c) +ulong recvul(Channel *c) +int nbrecv(Channel *c, void *v) +void* nbrecvp(Channel *c) +ulong nbrecvul(Channel *c) +int send(Channel *c, void *v) +int sendp(Channel *c, void *v) +int sendul(Channel *c, ulong v) +int nbsend(Channel *c, void *v) +int nbsendp(Channel *c, void *v) +int nbsendul(Channel *c, ulong v) +int chanprint(Channel *c, char *fmt, ...) +.XX +void procexecl(Channel *cpid, char *file, ...) +void procexec(Channel *cpid, char *file, char *args[]) +Channel* threadwaitchan(void) +.XX +int threadnotify(int (*f)(void*, char*), int in) +.EE +.SH DESCRIPTION +.PP +The thread library provides parallel programming support similar to that +of the languages +Alef and Newsqueak. +Threads +and +procs +occupy a shared address space, +communicating and synchronizing through +.I channels +and shared variables. +.PP +A +.I proc +is a Plan 9 process that contains one or more cooperatively scheduled +.IR threads . +Programs using threads must replace +.I main +by +.IR threadmain . +The thread library provides a +.I main +function that sets up a proc with a single thread executing +.I threadmain +on a stack of size +.I mainstacksize +(default eight kilobytes). +To set +.IR mainstacksize , +declare a global variable +initialized to the desired value +.RI ( e.g. , +.B int +.B mainstacksize +.B = +.BR 1024 ). +.PP +.I Threadcreate +creates a new thread in the calling proc, returning a unique integer +identifying the thread; the thread +executes +.I fn(arg) +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 +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 (2)) +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 +are scheduled. +Because of this, +.I arg +should not point to data on the stack of a function that could +return before the new process is scheduled. +.PP +.I Threadexits +terminates the calling thread. +If the thread is the last in its proc, +.I threadexits +also terminates the proc, using +.I status +as the exit status. +.I Threadexitsall +terminates all procs in the program, +using +.I status +as the exit status. +.PP +The threads in a proc are coroutines, scheduled nonpreemptively +in a round-robin fashion. +A thread must explicitly relinquish control of the processor +before another thread in the same proc is run. +Calls that do this are +.IR yield , +.IR proccreate , +.IR procexec , +.IR procexecl , +.IR threadexits , +.IR alt , +.IR send , +and +.I recv +(and the calls related to +.I send +and +.IR recv \(emsee +their descriptions further on). +Procs are scheduled by the operating system. +Therefore, threads in different procs can preempt one another +in arbitrary ways and should synchronize their +actions using +.B qlocks +(see +.IR lock (2)) +or channel communication. +System calls such as +.IR read (2) +block the entire proc; +all threads in a proc block until the system call finishes. +.PP +As mentioned above, each thread has a unique integer thread id. +Thread ids are not reused; they are unique across the life of the program. +.I Threadid +returns the id for the current thread. +Each thread also has a thread group id. +The initial thread has a group id of zero. +Each new thread inherits the group id of +the thread that created it. +.I Threadgrp +returns the group id for the current thread; +.I threadsetgrp +sets it. +.I Threadpid +returns the pid of the Plan 9 process containing +the thread identified by +.IR id , +or \-1 +if no such thread is found. +.PP +.I Threadint +interrupts a thread that is blocked in a channel operation +or system call. +.I Threadintgrp +interrupts all threads with the given group id. +.I Threadkill +marks a thread to die when it next relinquishes the processor +(via one of the calls listed above). +If the thread is blocked in a channel operation or system call, +it is also interrupted. +.I Threadkillgrp +kills all threads with the given group id. +Note that +.I threadkill +and +.I threadkillgrp +will not terminate a thread that never relinquishes +the processor. +.PP +Primarily for debugging +(see +.IR XXXacidthread ), +threads can have string names associated with them. +.I Threadgetname +returns the current thread's name; +.I threadsetname +sets it. +The pointer returned by +.I threadgetname +is only valid until the next call to +.IR threadsetname . +.PP +.I Threaddata +returns a pointer to a per-thread pointer +that may be modified by threaded programs for +per-thread storage. +Similarly, +.I procdata +returns a pointer to a per-proc pointer. +.PP +.I Procexecl +and +.I procexec +are threaded analogues of +.I exec +and +.I execl +(see +.IR exec (2)); +on success, +they replace the calling thread (which must be the only thread in its proc) +and invoke the external program. +On error, they return \-1. +If +.I cpid +is not null, the pid of the invoked program +will be sent along +.I cpid +once the program has been started, or \-1 will be sent if an +error occurs. +.I Procexec +and +.I procexecl +will not access their arguments after sending a result +along +.IR cpid . +Thus, programs that malloc the +.I argv +passed to +.I procexec +can safely free it once they have +received the +.I cpid +response. +.I Threadwaitchan +returns a channel of pointers to +.B Waitmsg +structures (see +.IR wait (2)). +When an exec'ed process exits, a pointer to a +.B Waitmsg +is sent to this channel. +These +.B Waitmsg +structures have been allocated with +.IR malloc (2) +and should be freed after use. +.PP +A +.B Channel +is a buffered or unbuffered queue for fixed-size messages. +Procs and threads +.I send +messages into the channel and +.I recv +messages from the channel. If the channel is unbuffered, a +.I send +operation blocks until the corresponding +.I recv +operation occurs and +.IR "vice versa" . +.I Chaninit +initializes a +.B Channel +for messages of size +.I elsize +and with a buffer holding +.I nel +messages. +If +.I nel +is zero, the channel is unbuffered. +.IR Chancreate +allocates a new channel and initializes it. +.I Chanfree +frees a channel that is no longer used. +.I Chanfree +can be called by either sender or receiver after the last item has been +sent or received. Freeing the channel will be delayed if there is a thread +blocked on it until that thread unblocks (but +.I chanfree +returns immediately). +.PP +.I Send +sends the element pointed at by +.I v +to the channel +.IR c . +If +.I v +is null, zeros are sent. +.I Recv +receives an element from +.I c +and stores it in +.IR v . +If +.I v +is null, +the received value is discarded. +.I Send +and +.I recv +return 1 on success, \-1 if interrupted. +.I Nbsend +and +.I nbrecv +behave similarly, but return 0 rather than blocking. +.PP +.IR Sendp , +.IR nbsendp , +.IR sendul , +and +.I nbsendul +send a pointer or an unsigned long; the channel must +have been initialized with the appropriate +.IR elsize . +.IR Recvp , +.IR nbrecvp , +.IR recvul , +and +.I nbrecvul +receive a pointer or an unsigned long; +they return zero when a zero is received, +when interrupted, or +(for +.I nbrecvp +and +.IR nbrecvul ) +when the operation would have blocked. +To distinguish between these three cases, +use +.I recv +or +.IR nbrecv . +.PP +.I Alt +can be used to recv from or send to one of a number of channels, +as directed by an array of +.B Alt +structures, +each of which describes a potential send or receive operation. +In an +.B Alt +structure, +.B c +is the channel; +.B v +the value pointer (which may be null); and +.B op +the operation: +.B CHANSND +for a send operation, +.B CHANRECV +for a recv operation; +.B CHANNOP +for no operation +(useful +when +.I alt +is called with a varying set of operations). +The array of +.B Alt +structures is terminated by an entry with +.I op +.B CHANEND +or +.BR CHANNOBLK . +If at least one +.B Alt +structure can proceed, one of them is +chosen at random to be executed. +.I Alt +returns the index of the chosen structure. +If no operations can proceed and the list is terminated with +.BR CHANNOBLK , +.I alt +returns the index of the terminating +.B CHANNOBLK +structure. +Otherwise, +.I alt +blocks until one of the operations can proceed, +eventually returning the index of the structure executes. +.I Alt +returns \-1 when interrupted. +The +.B tag +and +.B entryno +fields in the +.B Alt +structure are used internally by +.I alt +and need not be initialized. +They are not used between +.I alt +calls. +.PP +.I Chanprint +formats its arguments in the manner of +.IR print (2) +and sends the result to the channel +.IR c. +The string delivered by +.I chanprint +is allocated with +.IR malloc (2) +and should be freed upon receipt. +.PP +Thread library functions do not return on failure; +if errors occur, the entire program is aborted. +.PP +Threaded programs should use +.I threadnotify +in place of +.I atnotify +(see +.IR notify (2)). +.PP +It is safe to use +.B sysfatal +(see +.IR perror (2)) +in threaded programs. +.I Sysfatal +will print the error string and call +.IR threadexitsall . +.PP +It is safe to use +.IR rfork +(see +.IR fork (2)) +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 /sys/lib/acid/thread +contains useful +.IR acid (1) +functions for debugging threaded programs. +.PP +.B /sys/src/libthread/example.c +contains a full example program. +.SH SOURCE +.B /sys/src/libthread +.SH SEE ALSO +.IR intro (2) diff --git a/static/plan9-4e/man2/time.2 b/static/plan9-4e/man2/time.2 new file mode 100644 index 00000000..d99ba672 --- /dev/null +++ b/static/plan9-4e/man2/time.2 @@ -0,0 +1,45 @@ +.TH TIME 2 +.SH NAME +time, nsec \- time in seconds and nanoseconds since epoch +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.nf +.B +long time(long *tp) +.PP +.B +vlong nsec(void) +.SH DESCRIPTION +Both +.I time +and +.I nsec +return the time since the epoch 00:00:00 GMT, Jan. 1, 1970. +The return value of the former is in seconds and the latter in nanoseconds. +For +.IR time , +if +.I tp +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 /sys/src/libc/9sys/time.c +.br +.B /sys/src/libc/9sys/nsec.c +.SH SEE ALSO +.IR cons (3) +.SH DIAGNOSTICS +Sets +.IR errstr . +.SH BUGS +These routines maintain a static file descriptor. diff --git a/static/plan9-4e/man2/tmpfile.2 b/static/plan9-4e/man2/tmpfile.2 new file mode 100644 index 00000000..25729542 --- /dev/null +++ b/static/plan9-4e/man2/tmpfile.2 @@ -0,0 +1,58 @@ +.TH TMPFILE 2 +.SH NAME +tmpfile, tmpnam \- Stdio temporary files +.SH SYNOPSIS +.B #include +.PP +.ta \w'\fLFILE 'u +.B +FILE *tmpfile(void) +.PP +.B +char *tmpnam(char *s) +.SH DESCRIPTION +.I Tmpfile +creates a temporary file that will automatically +be removed when the file is closed or the program exits. +The return value is a Stdio +.B FILE* +opened in update mode (see +.IR fopen (2)). +.PP +.I Tmpnam +generates a string that is a valid file name and that is not +the same as the name of an existing file. +If +.I s +is zero, it returns a pointer to a string which may be overwritten by +subsequent calls to +.IR tmpnam . +If +.I s +is non-zero, it should point to an array of at least +.B L_tmpnam +(defined in +.BR ) +characters, and the answer will be copied there. +.SH FILES +.TF /tmp/tf000000000000 +.TP +.B /tmp/tf000000000000 +template for +.I tmpfile +file names. +.TP +.B /tmp/tn000000000000 +template for +.I tmpnam +file names. +.SH SOURCE +.B /sys/src/libstdio +.SH BUGS +The files created by +.I tmpfile +are not removed until +.IR exits (2) +is executed; in particular, they are not removed on +.I fclose +or if the program terminates abnormally. diff --git a/static/plan9-4e/man2/wait.2 b/static/plan9-4e/man2/wait.2 new file mode 100644 index 00000000..b932f2b7 --- /dev/null +++ b/static/plan9-4e/man2/wait.2 @@ -0,0 +1,117 @@ +.TH WAIT 2 +.SH NAME +await, wait, waitpid \- wait for a process to exit +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +Waitmsg* wait(void) +.PP +.B +int waitpid(void) +.PP +.B +int await(char *s, int n) +.SH DESCRIPTION +.I Wait +causes a process to wait for any child process (see +.IR fork (2)) +to exit. +It returns a +.B Waitmsg +holding +information about the exited child. +A +.B Waitmsg +has this structure: +.IP +.EX +.ta 6n +\w'long 'u +\w'msg[ERRLEN]; 'u +typedef +struct Waitmsg +{ + int pid; /* of loved one */ + ulong time[3]; /* of loved one & descendants */ + char *msg; +} Waitmsg; +.EE +.PP +.B Pid +is the child's +process id. +The +.B time +array contains the time the child and its descendants spent in user code, +the time spent in system calls, and the child's elapsed real time, +all in units of milliseconds. +.B Msg +contains the message that the child specified in +.IR exits (2). +For a normal exit, +.B msg[0] +is zero, +otherwise +.B msg +is the exit string +prefixed by the process name, a blank, the process id, and a colon. +.PP +If there are no more children to wait for, +.I wait +returns immediately, with return value nil. +.PP +The +.B Waitmsg +structure is allocated by +.IR malloc (2) +and should be freed after use. +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 +.IR await , +which fills in the 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 +may be parsed (after appending a NUL) using +.IR tokenize +(see +.IR getfields (2)); +the resulting fields are, in order, pid, the three times, and the exit string, +which will be +.B '' +for normal exit. +If the representation is longer than +.I n +bytes, it is truncated but, if possible, properly formatted. +The information that does not fit in the buffer is discarded, so +a subsequent call to +.I await +will return the information about the next exiting child, not the remainder +of the truncated message. +In other words, each call to +.I await +returns the information about one child, blocking if necessary if no child has exited. +If the calling process has no living children, +.I await +returns +.BR -1 . +.SH SOURCE +.B /sys/src/libc/9syscall +.SH "SEE ALSO" +.IR fork (2), +.IR exits (2), +the +.B wait +file in +.IR proc (3) +.SH DIAGNOSTICS +These routines set +.IR errstr . diff --git a/static/plan9-4e/man2/window.2 b/static/plan9-4e/man2/window.2 new file mode 100644 index 00000000..5fe2b2bf --- /dev/null +++ b/static/plan9-4e/man2/window.2 @@ -0,0 +1,244 @@ +.TH WINDOW 2 +.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 (2)). +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 (2)), +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 /sys/src/libdraw +.SH SEE ALSO +.IR graphics (2), +.IR draw (2), +.IR cachechars (2), +.IR draw (3) +.SH BUGS +The refresh method +.B Refmesg +should be finished. diff --git a/static/plan9-4e/man3/0intro.3 b/static/plan9-4e/man3/0intro.3 new file mode 100644 index 00000000..a1b30193 --- /dev/null +++ b/static/plan9-4e/man3/0intro.3 @@ -0,0 +1,92 @@ +.TH INTRO 3 +.SH NAME +intro \- introduction to the Plan 9 devices +.SH DESCRIPTION +A Plan 9 +.I device +implements a file tree for client processes. +A file name beginning with a pound sign, such as +.LR #c , +names the root of a file tree implemented by +a particular +.IR "kernel device driver" +identified by the character after the pound sign. +Such names are usually bound to conventional locations +in the name space. +For example, after +.IP +.EX +bind("#c", "/dev", MREPL) +.EE +.LP +an +.IR ls (1) +of +.B /dev +will list the files provided by the +.I console +device. +.PP +A kernel device driver is a +.I server +in the sense of the Plan 9 File Protocol, 9P (see Section 5), +but with the messages implemented by local +rather than remote procedure calls. +Also, several of the messages +.RI ( Nop , +.IR Session , +.IR Flush , +and +.IR Error ) +have no subroutine equivalents. +.PP +When a system call is passed a file name beginning with +.L "#" +it looks at the next character, and if that is a valid +.I device character +it performs an +.IR attach (5) +on the corresponding device to get a channel representing the +root of that device's file tree. +If there are any characters after the device character but +before the next +.L "/" +or end of string, those characters are passed as parameter +.I aname +to the attach. For example, +.IP +.EX +#I2 +.EE +.PP +identifies the number 2 IP protocol stack +(see +.IR ip (3)). +.PP +Each kernel device has a conventional place at which to be bound +to the name space. +The +.I SYNOPSIS +sections of the following pages includes a +.I bind +command to put the device in the conventional place. +Most of these binds are done automatically by +.IR init (8) +using +.B newns +(see +.IR auth (2)) +on the file +.B /lib/namespace +(see +.IR namespace (6)). +When typed to +.IR rc (1), +the +.I bind +commands will need quotes to protect the +.B # +characters. +.SH SEE ALSO +.IR intro (5), +.IR intro (2) diff --git a/static/plan9-4e/man3/INDEX.3 b/static/plan9-4e/man3/INDEX.3 new file mode 100644 index 00000000..2cdb56b1 --- /dev/null +++ b/static/plan9-4e/man3/INDEX.3 @@ -0,0 +1,35 @@ +0intro 0intro +intro 0intro +apm apm +arch arch +audio audio +cap cap +cons cons +draw draw +dup dup +env env +ether ether +floppy floppy +i82365 i82365 +ip ip +kprof kprof +loopback loopback +lpt lpt +mnt mnt +cursor mouse +mouse mouse +pipe pipe +pnp pnp +proc proc +realtime realtime +root root +rtc rtc +sd sd +segment segment +srv srv +ssl ssl +tls tls +eia uart +uart uart +usb usb +vga vga diff --git a/static/plan9-4e/man3/INDEX.html.3 b/static/plan9-4e/man3/INDEX.html.3 new file mode 100644 index 00000000..8d7d5352 --- /dev/null +++ b/static/plan9-4e/man3/INDEX.html.3 @@ -0,0 +1,137 @@ + +plan 9 man section 3 + + +[manual index] +

Plan 9 from Bell Labs - Section 3 - Devices

+
+
+
0intro +- introduction to the Plan 9 devices +
intro + +
apm +- Advanced Power Management 1.2 BIOS interface +
apm + +
arch +- architecture-specific information and control +
arch + +
audio +- SoundBlaster audio controller +
audio + +
cap +- capabilities for setting the user id of processes +
cap + +
cons +- console, clocks, process/process group ids, user, null, reboot, etc. +
cons + +
draw +- screen graphics +
draw + +
dup +- dups of open files +
dup + +
env +- environment variables +
env + +
ether +- Ethernet device +
ether + +
floppy +- floppy disk interface +
floppy + +
i82365 +- Personal Computer Memory Card Interface Association (PCMCIA) device +
i82365 + +
ip +- network protocols over IP +
ip + +
kprof +- kernel profiling +
kprof + +
loopback +- network link simulation +
loopback + +
lpt +- parallel port interface for PC's +
lpt + +
mnt +- attach to 9P servers +
mnt + +
mouse +- kernel mouse interface +
mouse, cursor + +
pipe +- two-way interprocess communication +
pipe + +
pnp +- Plug 'n' Play ISA and PCI Interfaces +
pnp + +
proc +- running processes +
proc + +
realtime +- real time scheduling +
realtime + +
root +- the root file system +
root + +
rtc +- real-time clock and non-volatile RAM +
rtc + +
sd +- storage device interface +
sd + +
segment +- long lived memory segments +
segment + +
srv +- server registry +
srv + +
ssl +- SSL record layer +
ssl + +
tls +- TLS1 and SSL3 record layer +
tls + +
uart +- serial communication control +
uart, eia + +
usb +- USB Host Controller Interface +
usb + +
vga +- VGA controller device +
vga + +
diff --git a/static/plan9-4e/man3/Makefile b/static/plan9-4e/man3/Makefile new file mode 100644 index 00000000..c070e829 --- /dev/null +++ b/static/plan9-4e/man3/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.3) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man3/apm.3 b/static/plan9-4e/man3/apm.3 new file mode 100644 index 00000000..36809ea5 --- /dev/null +++ b/static/plan9-4e/man3/apm.3 @@ -0,0 +1,60 @@ +.TH APM 3 +.SH NAME +apm \- Advanced Power Management 1.2 BIOS interface +.SH SYNOPSIS +.nf +.B bind -a #P /dev + +.B /dev/apm +.SH DESCRIPTION +.PP +This device presents a low-level interface to +the APM 1.2 bios calls. +It is enabled by adding the line +.RB `` apm0= '' +to +.IR plan9.ini . +(The value after the equals sign is ignored; the presence of +the line at all enables the driver.) +It is only available on uniprocessor PCs. +Writing a 386 +.B Ureg +structure and then reading it back executes an APM call: +the written registers are passed to the call, +and the read registers are those returned by the call. +.\" .PP +.\" In addition, the following strings may be +.\" written to +.\" .B /dev/apm +.\" to negotiate with other kernel devices about +.\" suspension of the system. +.\" .TP +.\" .B "vote suspend +.\" Poll kernel devices for objections to suspending the system. +.\" The write succeeds only when no device objected. +.\" .TP +.\" .B "abort suspend +.\" Notify kernel devices that the vote failed and the +.\" suspension will not happen. +.\" .TP +.\" .B "commit suspend +.\" Notify kernel devices that the vote succeeded and +.\" suspension will happen. The devices +.\" may take measures such as disabling PCMCIA cards. +.\" .TP +.\" .B "resume suspend +.\" Notify kernel devices that the system has come back +.\" after a suspension. +.\" The devices may take measures such as reenabling PCMCIA cards. +.\" .PD +.\" A similar set of messages governs entrance into +.\" .B standby +.\" mode. +.PP +This device is intended to enable more user-friendly +interfaces such as +.IR apm (8). +.SH SOURCE +.B /sys/src/9/pc/apm.c +.br +.B /sys/src/9/pc/apmjump.s diff --git a/static/plan9-4e/man3/arch.3 b/static/plan9-4e/man3/arch.3 new file mode 100644 index 00000000..25a5331a --- /dev/null +++ b/static/plan9-4e/man3/arch.3 @@ -0,0 +1,65 @@ +.TH ARCH 3 +.SH NAME +arch \- architecture-specific information and control +.SH SYNOPSIS +.nf +.B bind -a #P /dev + +.B /dev/cputype +.B /dev/ioalloc +.B /dev/iob +.B /dev/iol +.B /dev/iow +.B /dev/irqalloc +.SH DESCRIPTION +.PP +This device presents textual information about PC hardware and allows +user-level control of the I/O ports on x86-class and DEC Alpha machines. +.PP +Reads from +.I cputype +recover the processor type and clock rate. +.PP +Reads from +.I ioalloc +return I/O ranges used by each device, one line +per range. Each line contains three fields separated by white space: first address +in hexadecimal, +last address, name of device. +.PP +Reads from +.I irqalloc +return the enabled interrupts, one line per +interrupt. Each line contains three fields separated by white space: +the trap number, the IRQ it is assigned to, and the name of +the device using it. +.PP +Reads and writes to +.IR iob , +.IR iow , +and +.I iol +cause 8-bit wide, 16-bit wide, and 32-bit wide requests to +I/O ports. +The port accessed is determined by the byte offset of the +file descriptor. +.SH EXAMPLE +The following code reads from an x86 byte I/O port. +.IP +.EX +uchar +inportb(long port) +{ + uchar data; + + if(iobfd == -1) + iobfd = open("#P/iob", ORDWR); + + seek(iobfd, port, 0); + if(read(iobfd, &data, sizeof(data)) != sizeof(data)) + sysfatal("inportb(0x%4.4x): %r\en", port); + return data; +} +.EE +.SH SOURCE +.B /sys/src/9/pc/devarch.c diff --git a/static/plan9-4e/man3/audio.3 b/static/plan9-4e/man3/audio.3 new file mode 100644 index 00000000..caceffdb --- /dev/null +++ b/static/plan9-4e/man3/audio.3 @@ -0,0 +1,129 @@ +.TH AUDIO 3 +.SH NAME +audio \- SoundBlaster audio controller +.SH SYNOPSIS +.nf +.B bind -a #A /dev + +.B /dev/audio +.B /dev/volume +.fi +.SH DESCRIPTION +.PP +The audio device serves a one-level directory, +giving access to the stereo audio ports. +.B Audio +is the data file, which can be read or written to use the port. +Audio data is a sequence of stereo samples, left sample first. +Each sample is a 16 bit little-endian two's complement integer; +the default sampling rate is 44.1 kHz. +Some implementations only support audio output +and return a zero length when read. +.PP +The length of the +.B audio +file as returned by +.IR stat (2) +represents the number of bytes buffered for input or output. +This provides some control over record or playback latency. +.PP +The file +.B audiostat +provides additional timing and latency control. When read, it returns +lines of the form +.br +.B "bufsize \f2s\fP buffered \f2b\fP offset \f2o\fP time \f2t\fP +.br +reporting number of bytes +.I s +used for DMA operations (i.e., the minimum useful size for reads and writes), +the number of bytes +.I b +currently buffered, and the time +.I t +at which offset +.I o +was reached. Using +.I t +and +.IR o , +it is possible to calculate at what time a byte with a different offset will +be recorded or played back. See also +.IR usb (4). +.PP +.B Volume +is the control file associated with the audio port. +Each input and output source has an associated stereo volume control, +ranging from 0 (quiet) to 100 (loud). +In addition, there are controls for the sampling rate of the D/A and A/D converters +and for any tone controls. +Reads +return lines of the form +.IP +.I source +.B in left +.I value +.B right +.I value +.B out left +.I value +.B right +.I value +.PP +possibly abbreviated if the values are shared or non-existent. +For example, if all of the values are shared, the form degenerates to +.RI ` source +.IR value '. +Valid sources depend on the particular audio device, +though all devices have a +.B audio +stereo source, which controls the output volume from the D/A converter +connected to +.BR audio . +.PP +Writes accept the same format with same abbreviations. +Writing the string +.B reset +sets all of the attributes to their default value, +and if no attribute is supplied, +.B audio +is assumed. +.PP +The Sound Blaster 16 (or MCD) is half-duplex and accepts the following controls on its +.B volume +file, +in the format shown above for reads. +.TP +.B audio out +Data written to audio. +.TP +.B synth in out +MIDI synthesizer. +.TP +.B cd in out +CD player. +.TP +.B line in out +Line-level input. +.TP +.B mic in out +Monaural microphone input. +.TP +.B speaker in out +Monaural internal speaker connection. +.TP +.B treb out +Stereo treble tone control. +Values less than 50 decrease the treble, +those greater increase it. +.TP +.B bass out +Stereo bass tone control. +.TP +.B speed in out +Sampling rate for the D/A and A/D converters, +expressed in Hz. +Defaults to 44100. +.PP +.SH SOURCE +.B /sys/src/9/port/devaudio.c diff --git a/static/plan9-4e/man3/cap.3 b/static/plan9-4e/man3/cap.3 new file mode 100644 index 00000000..5d6bffba --- /dev/null +++ b/static/plan9-4e/man3/cap.3 @@ -0,0 +1,81 @@ +.TH CAP 3 +.SH NAME +cap \- capabilities for setting the user id of processes +.SH SYNOPSIS +.B bind #¤ +.I dir +.nf + +.IB dir /caphash +.IB dir /capuse +.fi +.SH DESCRIPTION +.PP +This device enables a trusted process to +create a capability that another process +may then use to change its user id. The intent is to allow +server processes, for example +.B telnetd +(see +.IR ipserv (8)), +to change their user id after having proved +to a trusted process, such as +.IR factotum (4), +that they are indeed executing +on behalf of a user. +A trusted process is one running with the user id +of the host owner (see +.B /dev/hostowner +in +.IR cons (3)). +.PP +A capability is a null terminated string consisting of the concatenation of +an old user name, an ``@'', a new user name, an ``@'', and a string of randomly +generated characters called the key. +The trusted process enables the kernel to authenticate +capabilities passed to it by writing to +.I caphash +a secure hash of the capability. +The hash is 20 bytes long and generated by the following call: +.EX + + hmac_sha1(old_at_new, strlen(old_at_new), key, strlen(key), + hash, nil); + +.EE +The kernel maintains a list of hashes, freeing them after the +corresponding capability is used or after a minute has passed +since the write to +.IR caphash . +.PP +The trusted process may then pass the capability to any process +running as the old user. That process may then +use the capability to change identity to the new user. +A process uses a capability by writing it to +.IR capuse . +The kernel computes the same hash using the supplied capability +and searches its list of hashes for a match. If one is found, +the kernel sets the process's user id to that in the capability. +.SH DIAGNOSTICS +.PP +Errors generated by reading and writing +.I caphash +and +.I capuse +can be obtained using +.IR errstr (2). +A read of +.I caphash +with a length of less than 20 +or a write to +.I capuse +that doesn't contain two @ characters +generates the error ``read or write too small''. +A write to +.I capuse +that has no matching hash generates the error +``invalid capability''. +.SH SOURCE +.B /sys/src/9/port/devcap.c +.SH "SEE ALSO" +.IR sechash (2) diff --git a/static/plan9-4e/man3/cons.3 b/static/plan9-4e/man3/cons.3 new file mode 100644 index 00000000..0d4de988 --- /dev/null +++ b/static/plan9-4e/man3/cons.3 @@ -0,0 +1,346 @@ +.TH CONS 3 +.SH NAME +cons \- console, clocks, process/process group ids, user, null, reboot, etc. +.SH SYNOPSIS +.nf +.B bind #c /dev + +.B /dev/bintime +.B /dev/cons +.B /dev/consctl +.B /dev/cputime +.B /dev/drivers +.B /dev/hostdomain +.B /dev/hostowner +.B /dev/kprint +.B /dev/null +.B /dev/osversion +.B /dev/pgrpid +.B /dev/pid +.B /dev/ppid +.B /dev/random +.B /dev/reboot +.B /dev/swap +.B /dev/sysname +.B /dev/sysstat +.B /dev/time +.B /dev/user +.B /dev/zero +.fi +.SH DESCRIPTION +The console device serves a one-level directory +giving access to the console and +miscellaneous information. +.PP +Reading the +.B cons +file returns characters typed on the keyboard. +Normally, characters are buffered to enable erase and kill processing. +A control-U, +.LR ^U , +typed at the keyboard +.I kills +the current input line (removes all characters +from the buffer of characters +not yet read via +.BR cons ), +and a backspace +.I erases +the previous non-kill, non-erase character from the input buffer. +Killing and erasing only delete characters back to, but not including, +the last newline. +Characters typed at the keyboard actually produce 16-bit runes (see +.IR utf (6)), +but the runes are translated into the variable-length +.SM UTF +encoding (see +.IR utf (6)) +before putting them into the buffer. +A +.IR read (2) +of length greater than zero causes the process to wait until a +newline or a +.L ^D +ends the buffer, and then returns as much of the buffer as the argument +to +.B read +allows, but only up to one complete line. +A terminating +.L ^D +is not put into the buffer. +If part of the line remains, the next +.B read +will return bytes from that remainder and not part of any new line +that has been typed since. +.PP +If +the string +.B rawon +has been written to the +.B consctl +file and the file is still open, +.B cons +is in +.IR "raw mode" : +characters are not echoed as they are typed, +backspace and +.L ^D +are not treated specially, +and characters are available to +.I read +as soon as they are typed. +Ordinary mode is reentered when +.B rawoff +is written to +.B consctl +or this file is closed. +.PP +A +.I write +(see +.IR read (2)) +to +.B cons +causes the characters to be printed on the console screen. +.PP +The +.B osversion +file contains a textual representation of the operating system's version and parameters. +At the moment, it contains one field: the 9P protocol version, currently +.BR 2000 . +.PP +The +.B kprint +file may be read to receive a copy of the data written +to the console by the kernel's print statements or by processes +writing to +.BR /dev/cons . +Only data written after the file is opened is available. +If the machine's console is a serial line, the data is sent both to the +console and to +.BR kprint ; +if its console is a graphics screen, the data is sent either to the +display or to +.BR kprint , +but not both. +(It is advisable not to open +.B kprint +on terminals until you have started +.IR rio (1).) +.PP +The +.B null +file throws away anything written to it +and always returns zero bytes when read. +.PP +The +.B zero +file is a read-only file that produces an infinite stream of zero-valued bytes when read. +.PP +The +.B drivers +file contains, one per line, a listing of the drivers configured in the kernel, in the format +.IP +.EX +#c cons +.EE +.PP +The +.B hostdomain +file contains the name of the authentication domain that +this host belongs to; see +.IR authsrv (6). +Only the user named in +.B /dev/hostowner +may write this. +.PP +The +.B hostowner +file contains the name of the user that owns the console device files. +The hostowner also has group permissions for any local devices. +.PP +Reads from +.B random +return a stream of random numbers. The numbers are +generated by a low priority kernel process that loops +incrementing a variable. Each clock tick the variable +is sampled and, if it has changed sufficiently, the last +few bits are appended to a buffer. This process is inefficient +at best producing at most a few hundred bits a second. +Therefore, +.B random +should be treated as a seed to +pseudo-random number generators which can produce a faster +rate stream. +.PP +Writing the string +.B reboot +to +.B reboot +causes the system to shutdown and, if +possible, restart. +Writing the string +.B reboot +.I kernelpath +loads the named kernel image and restarts, +preserving the kernel configuration in +.BR #ec , +except that the +.B bootfile +variable is set to +.IR kernelpath . +Only the host +owner has the ability to open this file. +.PP +.B Bintime +is a binary interface that provides +the same information as +.B time +.RI ( q.v. ), +in binary form, +and also controls clock frequency and clock trim. +All integers read or written from +.B bintime +are in big endian order. +Unlike the other files, reads and writes do not affect +the offset. Therefore, there is no need for a seek +back to zero between subsequent accesses. +A read of +.B bintime +returns 24 bytes, three 8 byte numbers, representing nanoseconds +since start of epoch, clock ticks, and clock frequency. +.PP +A write to +.B bintime +is a message with one of 3 formats: +.IP "\f5n\fP<8-byte \f2time\fP>" 1.2i +set the nanoseconds since epoch to the given +.IR time . +.IP "\f5d\fP<8-byte \f2delta\fP><4-byte \f2period\fP>" 1.2i +trim the nanoseconds since epoch by +.I delta +over the next +.I period +seconds. +.IP "\f5f\fP<8-byte \f2freq\fP>" 1.2i +Set the frequency for interpreting clock ticks to be +.I freq +ticks per second. +.PP +The rest of the files contain (mostly) read-only strings. +Each string has a fixed length: a +.IR read (2) +of more than that gives a result of that fixed length (the result does not +include a terminating zero byte); +a +.I read +of less than that length leaves the file offset so the +rest of the string (but no more) will be read the next time. +To reread the file without closing it, +.I seek +must be used to reset the offset. +When the file contains numeric data +each number is formatted in decimal. +If the binary number fits in 32 bits, it is formatted as an +11 digit decimal number with +leading blanks and one trailing blank; totaling 12 bytes. +Otherwise, it +is formatted as 21 digit decimal numbers with leading blanks and one +trailing blank; totaling 22 bytes. +.PP +The +.B cputime +file holds six 32-bit numbers, containing the time in milliseconds +that the current process has spent in user mode, system calls, +real elapsed time, and then the time spent, by exited children and their descendants, +in user mode, system calls, and real elapsed time. +.PP +The +.B time +file holds one 32-bit number representing the seconds since start of epoch +and three 64-bit numbers, representing nanoseconds since +start of epoch, clock ticks, and clock frequency. +.PP +A write of a decimal number to +.B time +will set the seconds since epoch. +.PP +The +.B sysname +file holds the textual name of the machine, e.g. +.BR kremvax , +if known. +.PP +The +.B sysstat +file holds 8 numbers: +processor number, context switches, interrupts, system calls, page faults, +TLB faults, TLB purges, and load average. +The load average is in units of milli-CPUs and is decayed over time; +the others are total counts from boot time. +If the machine is a multiprocessor, +.B sysstat +holds one line per processor. +Writing anything to +.B sysstat +resets all of the counts on all processors. +.PP +The +.B swap +device holds a string of the form +.IP +.IB m1 / m2 +.B memory +.IB s1 / s2 +.B swap +.PP +These give, for each of +internal memory and the swapping area, +the number of pages used and the total available. +These numbers are not blank padded. +To turn on swapping, write to +.B swap +the textual file descriptor number of a file or device on which to swap. +See +.IR swap (8). +.PP +The other files served by the +.I cons +device are all single numbers: +.TP 10 +.B pgrpid +process group number +.TP +.B pid +process number +.TP +.B ppid +parent's process number +.SH SEE ALSO +.IR draw (3), +.IR keyboard (6), +.IR authsrv (6), +.IR utf (6), +.IR swap (8) +.SH SOURCE +.B /sys/src/9/port/devcons.c +.SH BUGS +For debugging, two control-T's followed by a letter +generate console output and manage debugging: +.L ^T^Td +toggles whether the console debugger will be run if the system fails. +.L ^T^TD +starts the console debugger immediately. +.L ^T^Tk +kills the largest process; use with care. +.L ^T^Tp +prints data about processes. +.L ^T^Tq +prints the run queue for processor 0. +.L ^T^Ts +prints the kernel stack. +.L ^T^Tx +prints data about kernel memory allocation. +.PP +The system can be rebooted by typing +.LR ^T^Tr . diff --git a/static/plan9-4e/man3/draw.3 b/static/plan9-4e/man3/draw.3 new file mode 100644 index 00000000..89a6c196 --- /dev/null +++ b/static/plan9-4e/man3/draw.3 @@ -0,0 +1,782 @@ +.TH DRAW 3 +.SH NAME +draw \- screen graphics +.SH SYNOPSIS +.nf +.B bind -a #i /dev + +.B /dev/draw/new + +.BI /dev/draw/ n /ctl +.BI /dev/draw/ n /data +.BI /dev/draw/ n /colormap +.BI /dev/draw/ n /refresh + +.ft L +#include +#include + +.ta \w'ushort 'u +ushort BGSHORT(uchar *p) +ulong BGLONG(uchar *p) +void BPSHORT(uchar *p, ushort v) +void BPLONG(uchar *p, ulong v) +.ft P +.fi +.SH DESCRIPTION +The +.I draw +device serves a three-level file system +providing an interface to the graphics facilities of the system. +Each client of the device connects by opening +.B /dev/draw/new +and reading 12 strings, each 11 characters wide followed by a blank: +the connection number +.RI ( n ), +the image id +.RI ( q.v. ) +of the display image (always zero), +the +channel format +of the image, +the +.BR min.x , +.BR min.y , +.BR max.x , +and +.B max.y +of the display image, +and the +.BR min.x , +.BR min.y , +.BR max.x , +and +.B max.y +of the clipping rectangle. +The channel format string is described in +.IR image (6), +and the other fields are decimal numbers. +.PP +The client can then open the directory +.BI /dev/draw/ n / +to access the +.BR ctl , +.BR data , +.BR colormap , +and +.B refresh +files associated with the connection. +.PP +Via the +.B ctl +and +.B draw +files, the +.I draw +device provides access to +images and font caches +in its private storage, +as described in +.IR graphics (2). +Each image is identified by a 4-byte integer, its +.IR id . +.PP +Reading the +.B ctl +file yields 12 strings formatted as in +.BR /dev/draw/new , +but for the current image rather +than the display image. +The current image may be set by writing a +binary image id to the +.B ctl +file. +.PP +A process can write messages to +.B data +to allocate and free images, fonts, and subfonts; +read or write portions of the images; +and draw line segments and character +strings in the images. +All graphics requests are clipped to their images. +Some messages return a response to be recovered by +reading the +.B data +file. +.PP +The format of messages written to +.B data +is a single letter +followed by binary parameters; +multibyte integers are transmitted with the low order byte first. +The +.B BPSHORT +and +.B BPLONG +macros place correctly formatted two- and four-byte integers into a character +buffer. +.B BGSHORT +and +.B BGLONG +retrieve values from a character buffer. +Points are two four-byte numbers: +.IR x , +.IR y . +Rectangles are four four-byte numbers: min +.IR x , +min +.IR y , +max +.IR x , +and max +.IR y . +Images, screens, and fonts have 32-bit identifiers. +In the discussion of the protocol below, +the distinction between identifier and actual image, screen, or font +is not made, so that +``the object +.IR id '' +should be interpreted as +``the object with identifier +.IR id ''. +The definitions of constants used in the description below can be found in +.BR draw.h . +.PP +The following requests are accepted by the +.B data +file. +The numbers in brackets give the length in bytes of the parameters. +.HP .5i +.B A +.IR id [4] +.IR imageid [4] +.IR fillid [4] +.IR public [1] +.br +Allocate a new +.B Screen +(see +.IR window (2)) +with +screen identifier +.I id +using +backing store image +.IR imageid , +filling it initially +with data from image +.IR fillid . +If the +.I public +byte is non-zero, the screen can +be accessed from other processes +using the +.B publicscreen +interface. +.HP +.B b +.IR id [4] +.IR screenid [4] +.IR refresh [1] +.IR chan [4] +.IR repl [1] +.IR r [4*4] +.IR clipr [4*4] +.IR color [4] +.br +Allocate an image with a given +.I id +on the +screen named by +.IR screenid . +The image will have rectangle +.I r +and clipping rectangle +.IR clipr . +If +.I repl +is non-zero, the image's replicate +bit will be set (see +.IR draw (2)). +.IP +.I Refresh +specifies the method to be used to draw the window +when it is uncovered. +.B Refbackup +causes the server to maintain a backing store, +.B Refnone +does not refresh the image, +and +.B Refmesg +causes a message to be sent via +the +.B refresh +file +.RI ( q.v. ). +.IP +The image format is described by +.IR chan , +a binary version of the channel format string. +Specifically, the image format is the catenation of up to four +8-bit numbers, each describing a particular image channel. +Each of these 8-bit numbers contains a channel type in its +high nibble and a bit count in its low nibble. +The channel type is one of +.BR CRed , +.BR CGreen , +.BR CBlue , +.BR CGrey , +.BR CAlpha , +.BR CMap , +and +.BR CIgnore . +See +.IR image (6). +.IP +.I Color +is the catenation of four 8-bit numbers +specifying the red, green, blue, and alpha +channels of the color that the new image should +be initially filled with. +The red channel is in the highest 8 bits, and +the alpha in the lowest. +Note that color is always in this format, independent of +the image format. +.HP +.B c +.IR dstid [4] +.IR repl [1] +.IR clipr [4*4] +.br +Change the replicate bit and clipping rectangle of the +image +.IR dstid . +This overrides whatever settings were specified in +the allocate message. +.HP +.B d +.IR dstid [4] +.IR srcid [4] +.IR maskid [4] +.IR dstr [4*4] +.IR srcp [2*4] +.IR maskp [2*4] +.br +Use the +.B draw +operator to combine the rectangle +.I dstr +of +image +.I dstid +with a +rectangle of image +.IR srcid , +using a rectangle of image +.IR maskid +as an alpha mask to further control blending. +The three rectangles are congruent and aligned such that +the upper left corner +.I dstr +in image +.I dstid +corresponds to +the point +.I srcp +in image +.I srcid +and +the point +.I maskp +in image +.IR maskid . +See +.IR draw (2). +.HP +.B D +.IR debugon [1] +.br +If +.I debugon +is non-zero, enable debugging output. +If zero, disable it. +The meaning of ``debugging output'' is implementation dependent. +.HP +.B e +.IR dstid [4] +.IR srcid [4] +.IR c [2*4] +.IR a [4] +.IR b [4] +.IR thick [4] +.IR sp [2*4] +.IR alpha [4] +.IR phi [4] +.br +Draw an ellipse in image +.I dst +centered on the point +.I c +with horizontal and vertical semiaxes +.I a +and +.IR b . +The ellipse is drawn using the image +.IR src , +with +the point +.I sp +in +.I src +aligned with +.I c +in +.IR dst . +The ellipse is drawn with thickness +.RI 1+2× thick . +.IP +If the high bit of +.I alpha +is set, +only the arc of the ellipse from degree angles +.I alpha +to +.I phi +is drawn. +For the purposes of drawing the arc, +.I alpha +is treated as a signed 31-bit number +by ignoring its high bit. +.HP +.B E +.IR dstid [4] +.IR srcid [4] +.IR center [2*4] +.IR a [4] +.IR b [4] +.IR thick [4] +.IR sp [2*4] +.IR alpha [4] +.IR phi [4] +.br +Draws an ellipse or arc as the +.B e +message, but rather than outlining it, fills +the corresponding sector using the image +.IR srcid . +The +.I thick +field is ignored, but must be non-negative. +.HP +.B f +.IR id [4] +.br +Free the resources associated with the image +.IR id . +.HP +.B F +.IR id [4] +.br +Free the the screen with the specified +.IR id . +Windows on the screen must be freed separately. +.HP +.B i +.IR id [4] +.IR n [4] +.IR ascent [1] +.br +Treat the image +.I id +as a font cache of +.I n +character cells, each with +ascent +.IR ascent . +.HP +.B l +.IR cacheid [4] +.IR srcid [4] +.IR index [2] +.IR r [4*4] +.IR sp [2*4] +.IR left [1] +.IR width [1] +.br +Load a character into the font cache associated with image +.I cacheid +at cache position +.IR index . +The character data is drawn in rectangle +.I r +of the font cache image +and is fetched from +the congruent rectangle in image +.I srcid +with upper left corner +.IR sp . +.I Width +specifies the width of the character\(emthe spacing from this character to the next\(emwhile +.I left +specifies +the horizontal distance from the left side +of the character to the left side of the cache image. +The dimensions of the image of the character are defined by +.IR r . +.HP +.B L +.IR dstid [4] +.IR p0 [2*4] +.IR p1 [2*4] +.IR end0 [4] +.IR end1 [4] +.IR thick [4] +.IR srcid [4] +.IR sp [2*4] +.br +Draw a line of thickness +.RI 1+2× thick +in image +.I dstid +from point +.I p0 +to +.IR p1 . +The line is drawn using the image +.IR srcid , +translated so that point +.I sp +in +.I srcid +aligns with +.I p0 +in +.IR dstid . +The +.I end0 +and +.I end1 +fields specify whether the corresponding +line end should be a square, a disc, +or an arrow head. +See +.I line +in +.IR draw (2) +for more details. +.HP +.B N +.IR id [4] +.IR in [1] +.IR j [1] +.IR name [ j ] +.br +If +.I in +is non-zero, associate the image +.I id +with the string +.IR name . +If +.I in +is zero and +.I name +already corresponds to the +image +.IR id , +the association is deleted. +.HP +.B n +.IR id [4] +.IR j [1] +.IR name [ j ] +.br +Introduce the identifier +.I id +to correspond to the image named +by the string +.IR name . +.HP +.B o +.IR id [4] +.IR r.min [2*4] +.IR scr [2*4] +.br +Position the window +.I id +so that its upper left corner is at the +point +.I scr +on its screen. +Simultaneously change its internal (logical) coordinate system +so that the point +.I log +corresponds to the upper left corner of the window. +.HP +.B p +.IR dstid [4] +.IR n [2] +.IR end0 [4] +.IR end1 [4] +.IR thick [4] +.IR srcid [4] +.IR sp [2*4] +.IR dp [2*2*(n+1)] +.br +Draw a polygon of thickness +.RI 1+2× thick . +It is conceptually equivalent to a series of +.I n +line-drawing messages (see +.B L +above) +joining adjacent points in the list of points +.IR dp . +The source image +.I srcid +is translated so that the point +.I sp +in +.I srcid +aligns with the first point +in the list +.IR dp . +The polygon need not be closed: +.I end0 +and +.I end1 +specify the line endings for the first and +last point on the polygon. +All interior lines have rounded ends +to make smooth joins. +.HP +.B P +.IR dstid [4] +.IR n [2] +.IR wind [4] +.IR ignore [2*4] +.IR srcid [4] +.IR sp [2*4] +.IR dp [2*2*(n+1)] +.br +Draw a polygon as the +.B p +message, but +fill it rather than outlining it. +The winding rule parameter +.I wind +resolves ambiguities about what to fill if the polygon is self-intersecting. +If +.I wind +is +.BR ~0 , +a pixel is inside the polygon if the polygon's winding number about the point +is non-zero. +If +.I wind +is +.BR 1 , +a pixel is inside if the winding number is odd. +Complementary values (0 or ~1) cause outside pixels to be filled. +The meaning of other values is undefined. +The polygon is closed with a line if necessary. +.HP +.B r +.IR id [4] +.IR r [4*4] +.br +Cause the next read of the +.B data +file to return the image pixel data corresponding to the +rectangle +.I r +in image +.IR id . +.HP +.B s +.IR dstid [4] +.IR srcid [4] +.IR fontid [4] +.IR p [2*4] +.IR clipr [4*4] +.IR sp [2*4] +.IR n [2] +.IR n*(index [2]) +.br +Draw in the image +.I dstid +the text string specified by the +.I n +cache +.I indices +into font +.IR fontid , +starting with the upper left corner at point +.I p +in image +.IR dstid . +The image drawn is taken from image +.IR srcid , +translated to align +.I sp +in +.I srcid +with +.I dp +in +.IR dstid. +All drawing is confined to the clipping rectangle +.I clipr +in +.IR dstid . +.HP +.B x +.IR dstid [4] +.IR srcid [4] +.IR fontid [4] +.IR dp [2*4] +.IR clipr [4*4] +.IR sp [2*4] +.IR n [2] +.IR bgid [4] +.IR bp [2*4] +.IR n*(index [2]) +.br +Like the string drawing +.B s +command, but fill the background of each character +with pixels from image +.IR bgid . +The image +.I bgid +is translated so that the point +.I bp +aligns with the +point +.I dp +in +.IR dstid . +.HP +.B S +.IR id [4] +.IR chan [4] +Attach to the public screen with the specified +.IR id . +It is an error if the screen does not exist, is not public, or does not +have the channel descriptor +.I chan +for its associated image. +.HP +.B t +.IR top [1] +.IR n [2] +.IR n*id [4] +.br +Send +.I n +windows to the top (if +.I t +is non-zero) or bottom (if +.I t +is zero) of the window stack. +The window is specified by the list of +.I n +image +.IR id s +are moved as a group, maintaining their own order within the stack. +.HP +.B v +.br +Flush changes from a soft screen, if any, to the display buffer. +.HP +.B y +.IR id [4] +.IR r [4*4] +.IR buf [x*1] +.br +.ti -0.5i +.B Y +.IR id [4] +.IR r [4*4] +.IR buf [x*1] +.br +Replace the rectangle +.I r +of pixels in image +.I id +with the pixel data in +.IR buf . +The pixel data must be in the format dictated by +.IR id 's +image channel descriptor (see +.IR image (6)). +The +.B y +message uses uncompressed data, +while the +.B Y +message uses compressed data. +In either case, +it is an error to include more data than necessary. +.PP +Reading the +.B colormap +returns the system color map used on 8-bit displays. +Each color map entry consists of a single line containing +four space-separated decimal strings. +The first is an index into the map, and the remaining three are +the red, green, and blue values associated with that index. +The color map can be changed by writing entries in the +above format to +the +.B colormap +file. +Note that changing the system color map +does not change the color map used for +calculations involving +.B m8 +images, which is immutable. +.PP +The +.B refresh +file is read-only. +As windows owned by the client are uncovered, +if they cannot be refreshed by the server (such as when they have +refresh functions associated with them), a message is made available +on the +.B refresh +file reporting what needs to be repainted by the client. +The message has five decimal integers formatted as in the +.B ctl +message: the image id of the window and the coordinates of the rectangle +that should be refreshed. +.SH SOURCE +.B /sys/src/9/port/devdraw.c +.br +.B /sys/src/libmemdraw +.SH DIAGNOSTICS +Most messages to +.B draw +can return errors; +these can be detected by a system call error +on the +.IR write (see +.IR read (2)) +of the data containing the erroneous message. +The most common error is a failure to allocate +because of insufficient free resources. Most other errors occur +only when the protocol is mishandled by the application. +.IR Errstr (2) +will report details. +.SH BUGS +The +.B Refmesg +refresh method is not fully implemented. +.br +The +.B colormap +files only reference the system color map, and as +such should be called +.B /dev/colormap +rather than +.BI /dev/draw/ n /colormap\f1. diff --git a/static/plan9-4e/man3/dup.3 b/static/plan9-4e/man3/dup.3 new file mode 100644 index 00000000..6ce855e9 --- /dev/null +++ b/static/plan9-4e/man3/dup.3 @@ -0,0 +1,58 @@ +.TH DUP 3 +.SH NAME +dup \- dups of open files +.SH SYNOPSIS +.nf +.B bind #d /fd + +.B /fd/0 +.B /fd/0ctl +.B /fd/1 +.B /fd/1ctl +\&... +.fi +.SH DESCRIPTION +The +.I dup +device serves a one-level directory containing files whose +names are decimal numbers. +Each such file also has an associated control file. +A file of name +.I n +corresponds to open file descriptor +.I n +in the current process. +.PP +An +.IR open (2) +of file +.I n +results in a file descriptor identical to +what would be returned from a system call +.IB dup ( n , +.BR -1) . +Note that the result is no longer a file in the +.I dup +device. +.PP +The +.I stat +operation returns information about the device file, not the open file it points to. +A stat of +.BI #d/ n +will contain +.I n +for the name, 0 for the length, and 0400, 0200, or 0600 +for the mode, depending on whether the dup target is open +for reading, writing, or both. +.PP +A file of name +.IB n ctl +may be read to discover the properties of the associated file descriptor, in format identical to that of the +.B fd +file in +.IR proc (3). +.SH SEE ALSO +.IR dup (2) +.SH SOURCE +.B /sys/src/9/port/devdup.c diff --git a/static/plan9-4e/man3/env.3 b/static/plan9-4e/man3/env.3 new file mode 100644 index 00000000..2724f2ac --- /dev/null +++ b/static/plan9-4e/man3/env.3 @@ -0,0 +1,64 @@ +.TH ENV 3 +.SH NAME +env \- environment variables +.SH SYNOPSIS +.nf +.B bind #e /env + +.BI /env/ var1 +.BI /env/ var2 + ... +.fi +.SH DESCRIPTION +The +.I env +device serves a one-level directory containing files with arbitrary names +and contents. +The intention is that the file name is the name of an +.I environment variable +(see +.IR rc (1)), +and the content is the variable's current value. +.PP +When a +.IR fork (2) +system call creates a new process, both the parent and the +child continue to see exactly the same files in the +.I env +device: changes made in either process can be noticed by the other. +In contrast, an +.B rfork +system call with the +.B RFENVG +bit set (see +.IR fork (2)) +causes a split: initially both process groups see the +same environment files, but any changes made in one process group +cannot be noticed by the other. +An +.B rfork +with +.B RFCENVG +splits and then clears the environment. +.PP +The special global environment +.B #ec +contains kernel configuration variables, +such as those set in +.IR plan9.ini (8). +All processes see the same +.BR #ec ; +its contents are writable only by the host owner. +[XXX actually everything is world writable; that's a mistake.] +.SH SEE ALSO +.IR rc (1), +.IR fork (2), +.B #c/reboot +in +.IR cons (3), +.IR plan9.ini (8) +.SH SOURCE +.B /sys/src/9/port/devenv.c +.SH BUGS +A write starting at an offset after the current extent of a file +yields an error instead of zero filling. diff --git a/static/plan9-4e/man3/ether.3 b/static/plan9-4e/man3/ether.3 new file mode 100644 index 00000000..05aa6c76 --- /dev/null +++ b/static/plan9-4e/man3/ether.3 @@ -0,0 +1,96 @@ +.TH ETHER 3 +.SH NAME +ether \- Ethernet device +.SH SYNOPSIS +.nf +.B bind -a #l /net + +.BI /net/ether n /clone +.BI /net/ether n /[0-7] +.BI /net/ether n /[0-7]/data +.BI /net/ether n /[0-7]/ctl +.BI /net/ether n /[0-7]/ifstats +.BI /net/ether n /[0-7]/stats +.BI /net/ether n /[0-7]/type + +.fi +.SH DESCRIPTION +The Ethernet interface, +.BI /net/ether n\f1, +is a directory +containing subdirectories, one for each distinct Ethernet packet type, +and a +.B clone +file. +The number +.I n +is the device number of the card, permitting multiple cards to be used on a single machine. +.PP +Each directory contains files to control the associated connection, +receive and send data, +and supply statistics. +Incoming Ethernet packets are demultiplexed by packet type and passed up +the corresponding open connection. +Reading from the +.B data +file reads packets of that type arriving from the network. +A read will terminate at packet boundaries. +Each write to the +.B data +file causes a packet to be sent. +The Ethernet address of the interface is inserted into +the packet header as the source address. +.PP +A connection is assigned to a packet type by opening its +.B ctl +file and +writing +.B connect +.I n +where +.I n +is a decimal integer constant identifying the Ethernet packet type. +A type of \-1 enables the connection to receive copies of packets of +all types. A type of \-2 enables the connection to receive copies of +the first 64 bytes of packets of all types. +If multiple connections are assigned to a given packet type +a copy of each packet is passed up each connection. +.PP +Some interfaces also accept unique options when written to the +.I ctl +(or +.IR clone ) +file; see the description of +.I wavelan +in +.IR plan9.ini (8). +.PP +Reading the +.B ctl +file returns the decimal index of the associated connection, 0 through 7. +Reading the +.B type +file returns the decimal value of the assigned Ethernet packet type. +Reading the +.B stats +file returns status information such as the Ethernet address of the +card and general statistics, independent of the interface; +.B ifstats +contains device-specific data and statistics about the card. +.PP +An interface normally receives only those packets whose +destination address is that of the interface or is the +broadcast address, +.BR ff:ff:ff:ff:ff:ff . +The interface can be made to receive all packets on the +network by writing the string +.B promiscuous +to the +.B ctl +file. +The interface remains promiscuous until the control file is +closed. +The extra packets are passed up connections only of types \-1 +and \-2. +.SH SOURCE +.B /sys/src/9/*/devether.c diff --git a/static/plan9-4e/man3/floppy.3 b/static/plan9-4e/man3/floppy.3 new file mode 100644 index 00000000..f1b35466 --- /dev/null +++ b/static/plan9-4e/man3/floppy.3 @@ -0,0 +1,54 @@ +.TH FLOPPY 3 +.SH NAME +floppy \- floppy disk interface +.SH SYNOPSIS +.nf +.B bind -a #f /dev + +.B /dev/fd0disk +.B /dev/fd0ctl +.B /dev/fd1disk +.B /dev/fd1ctl +.B /dev/fd2disk +.B /dev/fd2ctl +.B /dev/fd3disk +.B /dev/fd3ctl +.fi +.SH DESCRIPTION +.PP +The floppy disk interface serves a one-level directory giving access to up +to four floppy disk drives. +Each drive is represented by a data and control file. +There are no partitions. +.PP +Messages accepted by the +.B ctl +file include: +.TF format +.TP +.B eject +Eject the floppy, if possible. +.TP +.B reset +Reset the drive. +.TP +.BI format " type +Format the floppy. The +.I type +sets the density and +type of disk to be formatted; see +.B format +in +.IR prep (8). +.PD +.PP +A read of the +.B ctl +file returns a string describing the form factor of the disk, one of +.BR 3½DD , +.BR 3½HD , +.BR 5¼DD , +or +.BR 5¼HD . +.SH SOURCE +.B /sys/src/9/*/devfloppy.c diff --git a/static/plan9-4e/man3/i82365.3 b/static/plan9-4e/man3/i82365.3 new file mode 100644 index 00000000..d0e90d2a --- /dev/null +++ b/static/plan9-4e/man3/i82365.3 @@ -0,0 +1,41 @@ +.TH I82365 3 +.SH NAME +i82365 \- Personal Computer Memory Card Interface Association (PCMCIA) device +.SH SYNOPSIS +.nf +.B bind -a #y /dev + +.B /dev/pcm0attr +.B /dev/pcm0ctl +.B /dev/pcm0mem +.B /dev/pcm1attr +.B /dev/pcm1ctl +.B /dev/pcm1mem +.fi +.SH DESCRIPTION +The +.I i82365 +driver provides an interface to an Intel +82365-compatible PCMCIA interface chip. +This chip supports up to 2 PCMCIA slots, 0 +and 1. +Reading +.B pcm[01]attr +returns the contents of attribute memory. +Reading or writing +.B pcm[01]mem +reads or writes RAM on the card. +Reading +.B pcm[01]ctl +returns the card's status. +.PP +This driver must be included to use PCMCIA +devices such as the NE4100 Ethernet card. +The individual card drivers make calls to routines +in the PCMCIA driver. +.SH SOURCE +.B /sys/src/9/pc/devi82365.c +.SH "SEE ALSO" +.IR plan9.ini (8) +.SH BUGS +There is no driver for the Databook PCMCIA interface chip. diff --git a/static/plan9-4e/man3/ip.3 b/static/plan9-4e/man3/ip.3 new file mode 100644 index 00000000..84be502f --- /dev/null +++ b/static/plan9-4e/man3/ip.3 @@ -0,0 +1,926 @@ +.TH IP 3 +.SH NAME +ip \- network protocols over IP +.SH SYNOPSIS +.nf +.B bind -a #I\fIspec\fP /net + +.B /net/ipifc +.B /net/ipifc/clone +.B /net/ipifc/stats +.BI /net/ipifc/ n +.BI /net/ipifc/ n /status +.BI /net/ipifc/ n /ctl +\&... + +.B /net/arp +.B /net/log +.B /net/ndb +.B /net/iproute +.B /net/ipselftab + +.B /net/esp +.B /net/gre +.B /net/icmp +.B /net/il +.B /net/ipmux +.B /net/rudp +.B /net/tcp +.B /net/udp + +.B /net/tcp/clone +.B /net/tcp/stats +.BI /net/tcp/ n +.BI /net/tcp/ n /data +.BI /net/tcp/ n /ctl +.BI /net/tcp/ n /local +.BI /net/tcp/ n /remote +.BI /net/tcp/ n /status +.BI /net/tcp/ n /listen +\&... +.fi +.SH DESCRIPTION +The IP device provides the interface to Internet protocol stacks. +.I Spec +is an integer from 0 to 15 identifying a stack. +Each stack is physically independent of all others: +the only information transfer between them is via programs that +mount multiple stacks. +Normally a system uses only one stack. +However multiple stacks can be used for debugging +new IP networks or implementing firewalls or proxy +services. +.PP +All addresses used are 16-byte IPv6 addresses. Though +we currently implement only IPv4, the IPv6 format is intended to +prepare the way for an IPv6 implementation. IPv4 addresses +are a subset of the IPv6 addresses and both standard +.SM ASCII +formats +are accepted. In binary, all v4 addresses start with the +12 bytes: +.EX + 00 00 00 00 00 00 00 00 00 00 ff ff +.EE +.SS "Configuring interfaces +.PP +Each stack may have multiple interfaces and each interface +may have multiple addresses. +The +.B /net/ipifc +directory contains a +.B clone +file, a +.B stats +file, and numbered subdirectories for each physical interface. +.PP +Opening the +.B clone +file reserves an interface. +The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated interface. +Reading +.B ctl +returns a text string representing the number of the interface. +Writing +.B ctl +alters aspects of the interface. +The possible +.I ctl +messages are: +.TP +.BI "bind ether " path +Treat the device mounted at +.I path +as an Ethernet medium carrying IP and ARP packets +and associate it with this interface. +The kernel will +.IR dial (2) +.IR path !0x800 +and +.IR path !0x806 +and use the two connections for IP and +ARP respectively. +.TP +.B "bind pkt +Treat this interface as a packet interface. Assume +a user program will read and write the +.I data +file to receive and transmit IP packets to the kernel. +This is used by programs such as +.IR ppp (8) +to mediate IP packet transfer between the kernel and +a PPP encoded device. +.TP +.BI "bind netdev " path +Treat this interface as a packet interface. +The kernel will open +.I path +and read and write the resulting file descriptor +to receive and transmit IP packets. +.TP +.BI "bind loopback " +Treat this interface as a local loopback. Anything +written to it will be looped back. +.TP +.B "unbind +Disassociate the physical device from an IP interface. +.TP +.BI add\ "local mask remote mtu " proxy +Add a local IP address to the interface. The +.IR mask , +.IR remote , +.IR mtu , +and +.B proxy +arguments are all optional. The default mask is +the class mask for the local address. The default +remote address is +.I local +ANDed with +.IR mask . +The default mtu is 1514 for Ethernet and 4096 for packet +media. +.IR Proxy , +if specified, means that this machine should answer +ARP requests for the remote address. +.IR Ppp (8) +does this to make remote machines appear +to be connected to the local Ethernet. +.TP +.BI remove\ "local mask" +Remove a local IP address from an interface. +.TP +.BI mtu\ n +Set the maximum transfer unit for this device to +.IR n . +The mtu is the maximum size of the packet including any +medium-specific headers. +.TP +.BI reassemble +Reassemble IP fragments before forwarding to this interface +.TP +.BI iprouting\ n +Allow +.RI ( n is missing +or non-zero) or disallow +.RI ( n +is 0) forwarding packets between this interface and +others. +.TP +.BI addmulti\ addr +Treat the multicast +.I addr +on this interface as a local address. +.TP +.BI remmulti\ addr +Remove the multicast address +.I addr +from this interface. +.PP +Reading the interface's +.I status +file returns information about the interface, one line for each +local address on that interface. The first line +has 9 white-space-separated fields: device, mtu, local address, +mask, remote or network address, packets in, packets out, input errors, +output errors. Each subsequent line contains all but the device and mtu. +See +.B readipifc +in +.IR ip (2). +.SS "Routing +.PP +The file +.I iproute +controls information about IP routing. +When read, it returns one line per routing entry. +Each line contains six white-space-separated fields: +target address, target mask, address of next hop, flags, +tag, and interface number. +The entry used for routing an IP packet is the one with +the longest mask for which destination address ANDed with +target mask equals the target address. +The one character flags are: +.TP +.B 4 +IPv4 route +.TP +.B 6 +IPv6 route +.TP +.B i +local interface +.TP +.B b +broadcast address +.TP +.B u +local unicast address +.TP +.B m +multicast route +.TP +.B p +point-to-point route +.PP +The tag is an arbitrary, up to 4 character, string. It is normally used to +indicate what routing protocol originated the route. +.PP +Writing to +.B /net/iproute +changes the route table. The messages are: +.TP +.B flush +Remove all routes. +.TP +.BI tag\ string +Associate the tag, +.IR string , +with all subsequent routes added via this file descriptor. +.TP +.BI add\ "target mask nexthop" +Add the route to the table. If one already exists with the +same target and mask, replace it. +.TP +.BI remove\ "target mask" +Remove a route with a matching target and mask. +.SS "Address resolution +.PP +The file +.B /net/arp +controls information about address resolution. +The kernel automatically updates the ARP information for Ethernet +interfaces. +When read, the file returns one line per address containing the +type of medium, the status of the entry (OK, WAIT), the IP +address, and the medium address. +Writing to +.B /net/arp +administers the ARP information. The control messages are: +.TP +.B flush +Remove all entries. +.TP +.BI add\ "type IP-addr Media-addr" +Add an entry or replace an existing one for the +same IP address. +.PP +ARP entries do not time out. The ARP table is a +cache with an LRU replacement policy. The IP stack +listens for all ARP requests and, if the requester is in +the table, the entry is updated. +Also, whenever a new address is configured onto an +Ethernet, an ARP request is sent to help +update the table on other systems. +.PP +Currently, the only medium type is +.BR ether . +.SS "Debugging and stack information +.PP +If any process is holding +.B /net/log +open, the IP stack queues debugging information to it. +This is intended primarily for debugging the IP stack. +The information provided is implementation-defined; +see the source for details. Generally, what is returned is error messages +about bad packets. +.PP +Writing to +.B /net/log +controls debugging. The control messages +are: +.TP +.BI set\ arglist +.I Arglist +is a space-separated list of items for which to enable debugging. +The possible items are: +.BR ppp , +.BR ip , +.BR fs , +.BR tcp , +.BR il , +.BR icmp , +.BR udb , +.BR compress , +.BR ilmsg , +.BR gre , +.BR tcpmsg , +.BR udpmsg , +.BR ipmsg , +and +.BR esp . +.TP +.BI clear\ arglist +.I Arglist +is a space-separated list of items for which to disable debugging. +.TP +.BI only\ addr +If +.I addr +is non-zero, restrict debugging to only those +packets whose source or destination is that +address. +.PP +The file +.B /net/ndb +can be read or written by +programs. It is normally used by +.IR ipconfig (8) +to leave configuration information for other programs +such as +.B dns +and +.B cs +(see +.IR ndb (8)). +.B /net/ndb +may contain up tp 1024 bytes. +.PP +The file +.B /net/ipselftab +is a read-only file containing all the IP addresses +considered local. Each line in the file contains +three white-space-separated fields: IP address, usage count, +and flags. The usage count is the number of interfaces to which +the address applies. The flags are the same as for routing +entries. +.SS "Protocol directories +.PP +The +.I ip +device +supports IP as well as several protocols that run over it: +TCP, IL, UDP, GRE, ESP, ICMP, and RUDP. +TCP and UDP provide the standard Internet +protocols for reliable stream and unreliable datagram +communication. +IL provides a reliable datagram service for communication +between Plan 9 machines. +GRE is a general encapsulation protocol. +ESP is the encapsulation protocol for IPSEC. +ICMP is IP's catch-all control protocol used to send +low level error messages and to implement +.IR ping (8). +RUDP is a locally developed reliable datagram protocol based on +UDP. +.PP +Each protocol is a subdirectory of the IP stack. +The top level directory of each protocol contains a +.B clone +file, a +.B stats +file, and subdirectories numbered from zero to the number of connections +opened for this protocol. +.PP +Opening the +.B clone +file reserves a connection. The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated connection. +Reading +.B ctl +returns a text +string representing the number of the +connection. +Connections may be used either to listen for incoming calls +or to initiate calls to other machines. +.PP +A connection is controlled by writing text strings to the associated +.B ctl +file. +After a connection has been established data may be read from +and written to +.BR data . +A connection can be actively established using the +.B connect +message (see also +.IR dial (2)). +A connection can be established passively by first +using an +.B announce +message (see +.IR dial (2)) +to bind to a local port and then +opening the +.B listen +file (see +.IR dial (2)) +to receive incoming calls. +.PP +The following control messages are supported: +.TP +.BI connect\ ipaddress ! port "!r " local +Establish a connection to the remote address +.I ipaddress +and remote port +.IR port . +If +.I local +is specified, it is used as the local port number. +If +.I local +is not specified but +.B !r +is, the system will allocate +a restricted port number (less than 1024) for the connection to allow communication +with Unix +.B login +and +.B exec +services. +Otherwise a free port number starting at 5000 is chosen. +The connect fails if the combination of local and remote address/port pairs +are already assigned to another port. +.TP +.BI announce\ X +.I X +is a decimal port number or +.LR * . +Set the local port +number to +.I X +and accept calls to +.IR X . +If +.I X +is +.LR * , +accept +calls for any port that no process has explicitly announced. +The local IP address cannot be set. +.B Announce +fails if the connection is already announced or connected. +.TP +.BI bind\ X +.I X +is a decimal port number or +.LR * . +Set the local port number to +.IR X . +This exists to support emulation +of BSD sockets by the APE libraries (see +.IR pcc (1)) +and is not otherwise used. +.TP +.BI backlog\ n +Set the maximum number of unanswered (queued) incoming +connections to an announced port to +.IR n . +By default +.I n +is set to five. If more than +.I n +connections are pending, +further requests for a service will be rejected. +.TP +.BI ttl\ n +Set the time to live IP field in outgoing packets to +.IR n . +.TP +.BI tos\ n +Set the service type IP field in outgoing packets to +.IR n . +.PP +Port numbers must be in the range 1 to 32767. +.PP +Several files report the status of a +connection. +The +.B remote +and +.B local +files contain the IP address and port number for the remote and local side of the +connection. The +.B status +file contains protocol-dependent information to help debug network connections. +On receiving and error or EOF reading or writing the +.B data +file, the +.B err +file contains the reason for error. +.PP +A process may accept incoming connections by +.IR open (2)ing +the +.B listen +file. +The +.B open +will block until a new connection request arrives. +Then +.B open +will return an open file descriptor which points to the control file of the +newly accepted connection. +This procedure will accept all calls for the +given protocol. +See +.IR dial (2). +.SS TCP +.PP +TCP connections are reliable point-to-point byte streams; there are no +message delimiters. +A connection is determined by the address and port numbers of the two +ends. +TCP +.B ctl +files support the following additional messages: +.TP +.B hangup +close down a TCP connection +.TP +.BI keepalive \ n +turn on keep alive messages. +.IR N , +if given, is the milliseconds between keepalives +(default 30000). +.SS UDP +.PP +UDP connections carry unreliable and unordered datagrams. A read from +.B data +will return the next datagram, discarding anything +that doesn't fit in the read buffer. +A write is sent as a single datagram. +.PP +By default, a UDP connection is a point-to-point link. +Either a +.B connect +establishes a local and remote address/port pair or +after an +.BR announce , +each datagram coming from a different remote address/port pair +establishes a new incoming connection. +However, many-to-one semantics is also possible. +.PP +If, after an +.BR announce , +one of the following messages is written to +.BR ctl , +then all messages sent to the announced port +are received on the announced connection prefixed with the given structure. +.TP +.B headers4 +.EX +typedef struct Udphdr4 Udphdr4; +struct Udphdr +{ + uchar raddr[4]; /* v4 remote address and port */ + uchar laddr[4]; /* v4 local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.EE +.TP +.B headers +.EX +typedef struct Udphdr Udphdr; +struct Udphdr +{ + uchar raddr[16]; /* v6 remote address and port */ + uchar laddr[16]; /* v6 local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.EE +.PP +The only difference in the two is the type of address, IPv4 or IPv6. +Before a write, a user must prefix a similar structure to each message. +The system overrides the user specified local port with the announced +one. If the user specifies an address that isn't a unicast address in +.BR /net/ipselftab , +that too is overridden. +Since the prefixed structure is the same in read and write, it is relatively +easy to write a server that responds to client requests by just copying new +data into the message body and then writing back the same buffer that was +written. +.SS RUDP +.PP +RUDP is a reliable datagram protocol based on UDP. +Packets are delivered in order. +RUDP does not support +.BR listen . +One must use either +.B connect +or +.B announce +followed immediately by +.B headers +or +.BR headers4 . +.PP +Unlike IL or TCP, the reboot of one end of a connection does +not force a closing of the connection. Communications will +resume when the rebooted machine resumes talking. Any unacknowledged +packets queued before the reboot will be lost. A reboot can +be detected by reading the +.B err +file. It will have the message +.IP +.BI hangup\ address ! port +.PP +where +.I address +and +.I port +are of the far side of the connection. +Retransmitting a datagram more than 10 times +is treated like a reboot: +all queued messages are dropped, an error is queued to the +.B err +file, and the conversation resumes. +.SS IL +.PP +IL is a reliable point-to-point datagram protocol. Like TCP, IL delivers datagrams +reliably and in order. Also like TCP, a connection is +determined by the address and port numbers of the two ends. +Like UDP, each read and write transfers a single datagram. +.PP +IL is efficient for LANs but doesn't have the +congestion control features needed for use through +the Internet. +.SS GRE +.PP +GRE is the encapsulation protocol used by PPTP. +The kernel implements just enough of the protocol +to multiplex it. +.B Announce +is not allowed in GRE, only +.BR connect . +Since GRE has no port numbers, the port number in the connect +is actually the 16 bit +.B eproto +field in the GRE header. +.PP +Reads and writes transfer a +GRE datagram starting at the GRE header. +On write, the kernel fills in the +.B eproto +field with the port number specified +in the connect message. +.SS ESP +.PP +ESP is the Encapsulating Security Payload (RFC 1827). +It is used to set up an encrypted tunnel between machines. +Like GRE, ESP has no port numbers. Instead, the +port number in the +.B connect +message is the SPI (Security Association Identifier (sic)). +IP packets are written to and read from +.BR data . +The kernel encrypts any packets written to +.BR data , +appends a MAC, and prefixes an ESP header before +sending to the other end of the tunnel. +Received packets are checked against their MAC's, +decrypted, and queued for reading from +.BR data . +The control messages are: +.TP +.BI esp\ "alg secret +Encrypt with the algorithm, +.IR alg , +using +.I secret +as the key. +Possible algorithms are: +.BR null , +.BR des_56_cbc , +and +.BR rc4_128 . +.TP +.BI ah\ "alg secret +Use the hash algorithm, +.IR alg , +with +.I secret +as the key for generating the MAC. +Possible algorithms are: +.BR null , +.BR hmac_sha1_96 , +and +.BR hmac_md5_96 . +.TP +.B header +Turn on header mode. Every buffer read from +.B data +starts with 4 unsued bytes, and the first 4 bytes +of every buffer written to +.B data +are ignored. +.TP +.B noheader +Turn off header mode. +.SS "IP packet filter +.PP +The directory +.B /net/ipmux +looks like another protocol directory. +It is a packet filter built on top of IP. Each numbered +subdirectory represents a different filter. +The connect messages written to the +.I ctl +file describe the filter. Packets matching the filter can be read on the +.B data +file. Packets written to the +.B data +file are routed to an interface and transmitted. +.PP +A filter is a semicolon-separated list of +relations. Each relation describes a portion +of a packet to match. The possible relations are: +.TP +.BI proto= n +the IP protocol number must be +.IR n . +.TP +.BI dat[ n : m ]= expr +bytes +.I n +through +.I m +following the IP packet must match +.IR expr . +.TP +.BI ifc= expr +the packet must have been received on an interface whose address +matches +.IR expr . +.TP +.BI src= expr +The source address in the packet must match +.IR expr . +.TP +.BI dst= expr +The destination address in the packet must match +.IR expr . +.PP +.I Expr +is of the form: +.TP +.I \ value +.TP +.IB \ value | value | ... +.TP +.IB \ value & mask +.TP +.IB \ value | value & mask +.PP +If a mask is given, the relevant field is first ANDed with +the mask. The result is compared against the value or list +of values for a match. In the case of +.BR ifc , +.BR dst , +and +.B src +the value is a dot-formatted IP address and the mask is a dot-formatted +IP mask. In the case of +.BR dat , +both value and mask are strings of 2 character hexadecimal digits representing +8 bit values. +.PP +A packet is delivered to only one filter. +The filters are merged into a single comparison tree. +If two filters match the same packet, the following +rules apply in order (here '>' means is preferred to): +.IP 1) +protocol > data > source > destination > interface +.IP 2) +lower data offsets > higher data offsets +.IP 3) +longer matches > shorter matches +.IP 4) +older > younger +.PP +So far this has just been used to implement a version of +OSPF in Inferno. +.SS Statistics +.PP +The +.B stats +files are read only and contain statistics useful to network +monitoring. +.PP +Reading +.B /net/ipifc/stats +returns a list of 19 tagged and new line separated fields representing: +.EX +.ft 1 + forwarding status (0 and 2 mean forwarding off, 1 means on) + default TTL + input packets + input header errors + input address errors + packets forwarded + input packets for unknown protocols + input packets discarded + input packets delivered to higher level protocols + output packets + output packets discarded + output packets with no route + timed out fragments in reassembly queue + requested reassemblies + successful reassemblies + failed reassemblies + successful fragmentations + unsuccessful fragmentations + fragments created +.ft +.EE +.PP +Reading +.B /net/icmp/stats +returns a list of 25 tagged and new line separated fields representing: +.EX +.ft 1 + messages received + bad received messages + unreachables received + time exceededs received + input parameter problems received + source quenches received + redirects received + echo requests received + echo replies received + timestamps received + timestamp replies received + address mask requests received + address mask replies received + messages sent + transmission errors + unreachables sent + time exceededs sent + input parameter problems sent + source quenches sent + redirects sent + echo requests sent + echo replies sent + timestamps sent + timestamp replies sent + address mask requests sent + address mask replies sent +.EE +.PP +Reading +.B /net/tcp/stats +returns a list of 11 tagged and new line separated fields representing: +.EX +.ft 1 + maximum number of connections + total outgoing calls + total incoming calls + number of established connections to be reset + number of currently established connections + segments received + segments sent + segments retransmitted + retransmit timeouts + bad received segments + transmission failures +.EE +.PP +Reading +.B /net/udp/stats +returns a list of 4 tagged and new line separated fields representing: +.EX +.ft 1 + datagrams received + datagrams received for bad ports + malformed datagrams received + datagrams sent +.EE +.PP +Reading +.B /net/il/stats +returns a list of 7 tagged and new line separated fields representing: +.EX +.ft 1 + checksum errors + header length errors + out of order messages + retransmitted messages + duplicate messages + duplicate bytes +.EE +.PP +Reading +.B /net/gre/stats +returns a list of 1 tagged number representing: +.EX +.ft 1 + header length errors +.EE +.SH "SEE ALSO" +.IR listen (8), +.IR dial (2), +.IR ndb (6) +.SH SOURCE +.B /sys/src/9/ip +.SH BUGS +.I Ipmux +has not been heavily used and should be considered experimental. +It may disappear in favor of a more traditional packet filter in the future. diff --git a/static/plan9-4e/man3/kprof.3 b/static/plan9-4e/man3/kprof.3 new file mode 100644 index 00000000..4d3f9999 --- /dev/null +++ b/static/plan9-4e/man3/kprof.3 @@ -0,0 +1,66 @@ +.TH KPROF 3 +.SH NAME +kprof \- kernel profiling +.SH SYNOPSIS +.nf +.B bind -a #K /dev +.sp +.B /dev/kpctl +.B /dev/kpdata +.fi +.SH DESCRIPTION +The +.I kprof +device provides simple profiling +data for the operating system kernel. The data accumulates by +recording the program counter of the kernel at each `tick' of the +system clock. +.PP +The file +.B kpdata +holds the accumulated counts as 4-byte integers in big-endian +byte order. +The size of the file depends on the size of kernel text. +The first count +holds the total number of clock ticks during profiling; +the second the number of ticks that occurred while the kernel +was running. The rest each hold the number of ticks +the kernel program counter was within the +corresponding 8-byte range of kernel text, starting from the base +of kernel text. +.PP +The file +.B kpctl +controls profiling. +Writing the string +.B start +to +.B kpctl +begins profiling; +.B stop +terminates it. The message +.B startclr +restarts profiling after zeroing the array of counts. +.PP +The program +.I kprof +(see +.IR prof (1)) +formats the data for presentation. +.SH EXAMPLE +The following +.IR rc (1) +script runs a test program while profiling the kernel +and reports the results. +.sp +.EX + bind -a '#K' /dev + echo start > /dev/kpctl + runtest + echo stop > /dev/kpctl + kprof /386/9pcdisk /dev/kpdata +.EE +.SH SOURCE +.B /sys/src/9/port/devkprof.c +.SH SEE ALSO +.IR prof (1) diff --git a/static/plan9-4e/man3/loopback.3 b/static/plan9-4e/man3/loopback.3 new file mode 100644 index 00000000..066827a7 --- /dev/null +++ b/static/plan9-4e/man3/loopback.3 @@ -0,0 +1,88 @@ +.TH LOOPBACK 3 +.SH NAME +loopback \- network link simulation +.SH SYNOPSIS +.nf +.B bind -a #X /net + +.BI /net/loopback n /[0-1] +.BI /net/loopback n /[0-1]/data +.BI /net/loopback n /[0-1]/ctl +.BI /net/loopback n /[0-1]/status +.BI /net/loopback n /[0-1]/stats + +.fi +.SH DESCRIPTION +The loopback interface, +.BI /net/loopback n\f1, +is a directory containing two subdirectories, +one for each end of a simulated network link. +The number +.I n +is the device number of the link, permitting multiple links to be used on a single machine. +.PP +Each directory contains files to control the associated connection, +receive and send data, +monitor the simulation parameters, +and supply statistics. +.PP +The +.B data +files for the two directories are cross-connected. +Writes to one are divided into packets of at most a certain size, +typically 32768 bytes, +written to a flow-controlled output queue, +transferred across the link, +and put into an input queue where it is readable from the other +.B data +file. +.PP +Options are set by writing to the +.B ctl +file for the receiving end of the link, +and are reported in the same format by reading +.BR status . +The following options are supported. +.TP +.BI delay \ latency\ bytedelay +Control the time a packet takes in the link. +A packet +.B n +bytes long takes +.I bytedelay +.B * +.B n +nanoseconds to exit the output queue and +is available for reading +.I latency +nanoseconds later. +.TP +.BI droprate \ n +Randomly drop approximately one out of +.B n +packets. +If zero drop no packets. +.TP +.BR indrop \ [01] +Disallow or allow packets to be dropped if the input queue overflows. +.TP +.BI limit \ n +Set the input and output queues to hold at most +.I n +bytes. +.TP +.B reset +Clear all of the statistics recorded for the link. +.PP +Reading +.B stats +returns a list of 4 tagged numbers representing: +.EX +.ft 1 + packets sent to this receiver + bytes sent to this receiver + packets dropped due to droprate + packets dropped due to input queue overflows +.EE +.SH SOURCE +.B /sys/src/9/port/devloopback.c diff --git a/static/plan9-4e/man3/lpt.3 b/static/plan9-4e/man3/lpt.3 new file mode 100644 index 00000000..a8df37dd --- /dev/null +++ b/static/plan9-4e/man3/lpt.3 @@ -0,0 +1,43 @@ +.TH LPT 3 +.SH NAME +lpt \- parallel port interface for PC's +.SH SYNOPSIS +.nf +.B bind -a #L[123] /dev + +.B /dev/lpt[123]data +.B /dev/lpt[123]dlr +.B /dev/lpt[123]pcr +.B /dev/lpt[123]psr +.fi +.SH DESCRIPTION +The +.I lpt +driver provides an interface to the parallel +interface normally used for printers. +The specifiers +.BR 1 , +.BR 2 , +and +.BR 3 +correspond to +the parallel interfaces at PC ports 0x3bc, 0x378, and 0x278 +respectively. +.PP +.B Lpt?data +is write only. +Writing to it sends data to the interface. +This file is sufficient for communicating with most printers. +.PP +.BR Lpt?dlr , +.BR lpt?pcr , +and +.B lpt?psr +are used for fine control of the parallel port. +Reading or writing these files corresponds to +reading and writing the data latch register, +printer control register, and printer status +register. +These are used by programs to drive special devices. +.SH SOURCE +.B /sys/src/9/pc/devlpt.c diff --git a/static/plan9-4e/man3/mnt.3 b/static/plan9-4e/man3/mnt.3 new file mode 100644 index 00000000..c92c4370 --- /dev/null +++ b/static/plan9-4e/man3/mnt.3 @@ -0,0 +1,72 @@ +.TH MNT 3 +.SH NAME +mnt \- attach to 9P servers +.SH SYNOPSIS +.nf +.B #M +.fi +.SH DESCRIPTION +The +.I mount driver +is used by the +.B mount +system call +(but not +.BR bind ; +see +.IR bind (2)) +to connect the name space of a process to +the service provided by a 9P server over a communications channel. +After the +.BR mount , +system calls involving files in that portion of the name space will +be converted by the mount driver into the appropriate +9P messages to the server. +.PP +The +.I mount +system call issues +.I session +and +.IR attach (5) +messages to the server to identify and validate the user of the connection. +Each distinct user of a connection must mount it separately; +the mount driver multiplexes the access of the various users and their +processes to the service. +.PP +File-oriented system calls are converted by the kernel into messages in the 9P protocol. +Within the kernel, 9P is implemented by procedure calls to the +various kernel device drivers. +The mount driver translates these procedure calls into remote procedure calls +to be transmitted as messages over the communication channel to the server. +Each message is implemented by a write +of the corresponding protocol message to the server channel +followed by a read on the server channel to get the reply. +Errors in the reply message are turned into system call error returns. +.PP +A +.IR read (2) +or +.IR write +system call on a file served by the mount driver +may be translated +into more than one +message, +since there is a maximum data size for a 9P message. +The system call +will return when the specified number of bytes have been transferred +or a short reply is returned. +.PP +The string +.L #M +is an illegal file name, +so this device can only be accessed directly by the kernel. +.SH "SEE ALSO" +.IR bind (2) +.SH SOURCE +.B /sys/src/9/port/devmnt.c +.SH BUGS +When mounting a service through the mount driver, +that is, when the channel being multiplexed is itself +a file being served by the mount driver, +large messages may be broken in two. diff --git a/static/plan9-4e/man3/mouse.3 b/static/plan9-4e/man3/mouse.3 new file mode 100644 index 00000000..f2bd33d8 --- /dev/null +++ b/static/plan9-4e/man3/mouse.3 @@ -0,0 +1,213 @@ +.TH MOUSE 3 +.SH NAME +mouse, cursor \- kernel mouse interface +.SH SYNOPSIS +.nf +.B bind -a #m /dev + +.B /dev/mouse +.B /dev/mousein +.B /dev/mousectl +.B /dev/cursor +.fi +.SH DESCRIPTION +The +.I mouse +device provides an interface to the mouse. +There is also a cursor associated with the screen; +it is always displayed at the current mouse position. +.PP +Reading the +.B mouse +file returns the mouse status: its position and button state. +The read blocks until the state has changed since the last read. +The read returns 49 bytes: the letter +.B m +followed by four decimal strings, each 11 characters +wide followed by a blank: +.I x +and +.IR y , +coordinates of the mouse position in the screen image; +.IR buttons , +a bitmask with the +1, 2, and 4 bits set when the +mouse's left, middle, and right buttons, +respectively, are down; +and +.IR msec , +a time stamp, in units of milliseconds. +.PP +Writing the +.B mouse +file, in the same format, +causes the mouse cursor to move to the position specified by the +.I x +and +.I y +coordinates of the message. +The +.I buttons +and +.I msec +fields are ignored and may be omitted. +.PP +Writes to the +.B mousein +file are processed as if they were generated by the +mouse hardware itself, +as extra mouse events to be processed and passed back via +the +.B mouse +file. +The +.B mousein +file, which is exclusive-use, is intended for controlling devices, such as USB mice, +that are managed by user-level software. +Each event should consist of +the letter +.B m +followed by delta +.IR x , +delta +.IR y , +and +.IR buttons +as space-separated decimal numbers. +.PP +Writing to the +.B mousectl +file configures and controls the mouse. +The messages are: +.TF ps2intellimouse +.TP +.B serial\fI n\fR +sets serial port +.I n +to be the mouse port. +.TP +.B ps2 +sets the PS2 port to be the mouse port. +.TP +.B intellimouse +uses the wheel on a Microsoft Intellimouse +as the middle button. +.TP +.B ps2intellimouse +is equivalent to a write of +.B ps2 +followed by a write of +.BR intellimouse . +.TP +.B accelerated +turns on mouse acceleration. +.TP +.B linear +turns off mouse acceleration +.TP +.B res \fIn\fR +sets mouse resolution to a setting between 0 and +3 inclusive. +.TP +.B hwaccel \fIon/off\fR +sets whether acceleration is done in hardware or +software. +By default, PS2 mice use hardware and serial mice use +software. +Some laptops (notably the IBM Thinkpad T23) don't +implement hardware acceleration for external mice. +.TP +.B swap +swaps the left and right buttons on the mouse. +.TP +.B buttonmap \fIxyz\fR +numbers the left, middle, and right mouse buttons +.IR x , +.IR y , +and +.IR z , +respectively. +If +.I xyz +is omitted, the default map, 123, is used. +Thus in the default state writing +.B "buttonmap 321 +swaps left and right buttons +and writing +.B "buttonmap 123 +or just +.B buttonmap +restores their usual meaning. +Note that +.B buttonmap +messages are idempotent, +unlike +.BR swap . +.TP +.B reset +clears the mouse +to its default state. +.PD +.PP +Not all mice interpret all messages; with some devices, +some of the messages may be no-ops. +.PP +Cursors are described in +.IR graphics (2). +When read or written from or to the +.B cursor +file, they are represented in a 72-byte binary format. +The first and second four bytes are little endian +32-bit numbers specifying the +.I x +and +.I y +coordinates of the cursor +.IR offset ; +the next 32 bytes are the +.B clr +bitmask, +and the last 32 bytes the +.B set +bitmask. +.PP +Reading from the +.B cursor +file returns the current cursor information. +Writing to the +.B cursor +file sets the current cursor information. +A write of fewer than 72 bytes sets the +cursor to the default, an arrow. +.PP +The +.B mouse +and +.B cursor +files are multiplexed by +.IR rio (1) +to give the illusion of a private mouse to each of its clients. +The semantics are otherwise the same except that notification +of a window resize is passed to the application using a +.B mouse +message beginning with +.B r +rather than +.BR m ; +see +.IR rio (4) +for details. +.PP +To cope with pointing devices with only two buttons, when the +shift key is pressed, the right mouse button generates middle-button events. +.SH SOURCE +.B /sys/src/9/port/devmouse.c +.SH "SEE ALSO +.IR rio (4) +.SH BUGS +The cursor format is big endian while the +rest of the graphics interface is little endian. +.PP +The +.B mousein +file is disabled. diff --git a/static/plan9-4e/man3/pipe.3 b/static/plan9-4e/man3/pipe.3 new file mode 100644 index 00000000..fb93fa4d --- /dev/null +++ b/static/plan9-4e/man3/pipe.3 @@ -0,0 +1,59 @@ +.TH PIPE 3 +.SH NAME +pipe \- two-way interprocess communication +.SH SYNOPSIS +.B bind #| +.I dir +.nf + +.IB dir /data +.IB dir /ctl +.IB dir /data1 +.IB dir /ctl1 +.fi +.SH DESCRIPTION +.PP +An +.IR attach (5) +of this device allocates two new cross-connected I/O streams. +.B X/data +and +.B x/ctl +are the data and control channels of one stream and +.B x/data1 +and +.B x/ctl1 +are the data and control channels of the other stream. +.PP +Data written to one channel becomes available for reading at +the other. +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 +Writes are atomic up to a certain size, typically 32768 bytes, +that is, each write will be delivered in a single read by the +recipient, provided the receiving buffer is large enough. +.PP +If there are multiple writers, each +.I write +is guaranteed to be available in a contiguous piece at the other +end of the pipe. +If there are multiple readers, each read will return data from only +one write. +.PP +The +.IR pipe (2) +system call performs an +.I attach +of this device and returns file descriptors to the new pipe's +.B data +and +.B data1 +files. +The files are open with mode +.BR ORDWR . +.SH "SEE ALSO" +.IR pipe (2) +.SH SOURCE +.B /sys/src/9/port/devpipe.c diff --git a/static/plan9-4e/man3/pnp.3 b/static/plan9-4e/man3/pnp.3 new file mode 100644 index 00000000..4ad193a5 --- /dev/null +++ b/static/plan9-4e/man3/pnp.3 @@ -0,0 +1,146 @@ +.TH PNP 3 +.SH NAME +pnp \- Plug 'n' Play ISA and PCI Interfaces +.SH SYNOPSIS +.nf +.B bind -a '#$' /dev + +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn ctl +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn raw + +.BI /dev/pnp/ctl +.BI /dev/pnp/csn n ctl +.BI /dev/pnp/csn n raw +\&... + +.fi +.SH DESCRIPTION +.PP +This device provides a limited interface to the PCI bus and +Plug 'n' Play ISA devices. +.SS PCI Interface +.PP +PCI devices are addressed logically by a bus number, +a device number on that bus, and a function number +within the device. +The set of all such device functions may be enumerated +by traversing the +.B /dev/pci +directory; the driver serves two files for each function. +These are a control file +.RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPctl ) +which may be read for a textual summary of the device function, +and a `raw' file +.RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPraw ) +which may be read to obtain the raw contents of PCI configuration space. +.PP +The first field of a PCI control file contains the class, sub-class and +programming interface values for the device function, expressed +as 2-digit hexadecimal values, and separated by periods. +The second field yields the vendor ID and device ID, each as 4-digit +hex numbers, separated by a slash. +The third field is the associated interrupt line in decimal. +The remainder of the line enumerates any valid base address +registers for the function, using two fields for each. +In the first field, the index of the register is followed by +a colon, and then the value of the register itself. +The following field gives the associated size of the memory +(or I/O space) that is mapped by the register. +.SS Plug 'n' Play +.PP +Plug 'n' Play ISA devices are discovered by sending a fixed `unlock' sequence +over an I/O port, and then reading back data from another port. +An arbitration algorithm is used to separate out the individual +cards and enumerate them in turn. +Each card is assigned a unique number, called a CSN, in the range 1-255 as a +result of enumeration. +Cards also have a fixed 64 bit identification number, set by the +manufacturer, which is used by the arbitration algorithm to +resolve conflicts. +The first 32 bits describe the type of the card, and the second +32 bits form a serial number for the particular instance of that card type. +When formatted textually, it appears as 3 upper-case letters +(typically representing the manufacturer), +followed by 4 hex digits, then a period, then 8 hex digits. +The substring before the period is the card type, and the substring +after the period is the serial number. +.PP +The enumeration algorithm needs to be enabled by specifying the +port number to write the unlock sequence out on. +This can be configured to take place at boot time by adding a line +like the following to +.IR plan9.ini : +.IP +.EX +pnp0=port=0x203 +.EE +.PP +Here +.B port +should be chosen to not conflict with any existing devices. +It must be in the range +.BR 0x203-0x3ff . +Alternatively, one can use the following command: +.IP +.EX +echo port 0x203 >/dev/pnp/ctl +.EE +.PP +Note that a side-effect of PnP enumeration is to reset the configuration +state of all such cards; any settings made by a Plug and Play BIOS will be lost. +Reading the file +.B /dev/pnp/ctl +returns one of the strings +.B "enabled\fI port\fP" +or +.BR "disabled" . +.PP +For each enumerated card, two files are served in +.BR /dev/pnp . +A control file +.RL ( /dev/pnp/csn\fIn\fPctl ) +may be read to determine the ID of the card, and a raw file +.RL ( /dev/pnp/csn\fIn\fPraw ) +may be read to obtain the configuration data associated with the card. +It is intended that the control file should take commands which set the +various configurable resources of the card, but this has not been +implemented yet. +.PP +A mechanism is provided for configuring cards via +.IR plan9.ini (8). +A line of the form +.BI pnp n = "idstring ..." +will cause the driver to look for the card named by +.I idstring +and, if found, assign it the CSN +.IR n . +The intention is that +any additional text after the idstring is interpreted as if it +was written to the card's +.B ctl +file, but this is not yet implemented. +.SH EXAMPLES +.PP +To list all PCI functions: +.IP +.EX +cat /dev/pci/*ctl +.EE +.PP +To find just the PCI video card (class 3): +.IP +.EX +grep '^03' /dev/pci/*ctl +.EE +.SH SOURCE +.B /sys/src/9/port/devpnp.c +.SH BUGS +There is currently no way to write to PCI configuration space, +or to perform reads of less than 32 bits. +Access to the I/O and memory regions of a PCI device is not provided. +.PP +The ability to set a Plug 'n' Play card's configurable settings has not been +implemented. +.PP +There should be a user program for identifying and configuring +Plug 'n' Play cards. diff --git a/static/plan9-4e/man3/proc.3 b/static/plan9-4e/man3/proc.3 new file mode 100644 index 00000000..45d5d40e --- /dev/null +++ b/static/plan9-4e/man3/proc.3 @@ -0,0 +1,328 @@ +.TH PROC 3 +.SH NAME +proc \- running processes +.SH SYNOPSIS +.nf +.B bind #p /proc + +.BI /proc/ n /args +.BI /proc/ n /ctl +.BI /proc/ n /fd +.BI /proc/ n /fpregs +.BI /proc/ n /kregs +.BI /proc/ n /mem +.BI /proc/ n /note +.BI /proc/ n /noteid +.BI /proc/ n /notepg +.BI /proc/ n /ns +.BI /proc/ n /proc +.BI /proc/ n /profile +.BI /proc/ n /regs +.BI /proc/ n /segment +.BI /proc/ n /status +.BI /proc/ n /text +.BI /proc/ n /wait +\&... +.fi +.SH DESCRIPTION +The +.I proc +device serves a two-level directory structure. +The first level contains numbered directories +corresponding to pids of live processes; +each such directory contains a set of files +representing the corresponding process. +.PP +The +.B mem +file contains the current memory image of the process. +A read or write at offset +.IR o , +which must be a valid virtual address, +accesses bytes from address +.IR o +up to the end of the memory segment containing +.IR o . +Kernel virtual memory, including the kernel stack for the process and +saved user registers (whose addresses are machine-dependent), +can be accessed through +.BR mem . +Writes are permitted only while the process is in the +.B Stopped +state and only to user addresses or registers. +.PP +The read-only +.B proc +file contains the kernel per-process +structure. +Its main use is to recover the kernel stack and program counter +for kernel debugging. +.PP +The files +.BR regs , +.BR fpregs , +and +.BR kregs +hold representations of the user-level registers, floating-point registers, +and kernel registers in machine-dependent form. +The +.B kregs +file is read-only. +.PP +The read-only +.B fd +file lists the open file descriptors of the process. +The first line of the file is its current directory; subsequent lines list, one per line, +the open files, giving the decimal file descriptor number; whether the file is open for read +.RB ( r ), +write, +.RB ( w ), +or both +.RB ( rw ); +the type, device number, and qid of the file; its I/O unit (the amount of data +that may be transferred on the file as a contiguous piece; see +.IR iounit (2)), +its I/O offset; and its name at the time it was opened. +.PP +The read-only +.B ns +file contains a textual representation of the process's file name space, in the format of +.IR namespace (6) +accepted by +.B newns +(see +.IR auth (2)). +The last line of the file identifies the current working directory of the process, in the form of a +.B cd +command +(see +.IR rc (1)). +The information in this file is based on the names files had when the name space was assembled, +so the names it contains may be inaccessible if the files have been subsequently renamed or rearranged. +.PP +The read-only +.B segment +file contains a textual display of the memory segments +attached to the process. Each line has multiple fields: +the type of segment (\c +.BR Stack , +.BR Text , +.BR Data , +.BR Bss , +etc.); one-letter flags such as +.B R +for read-only, if any; +starting virtual address, in hexadecimal; +ending virtual address, and reference count. +.PP +The read-only +.B status +file contains a string with twelve fields, each followed by a space. +The fields are: +.IP \- +the process name and user name, each 27 characters left justified +.IP \- +the process state, 11 characters left justified (see +.IR ps (1)) +.IP \- +the six 11-character numbers also held in the process's +.B #c/cputime +file +.IP \- +the amount of memory used by the process, except its stack, +in units of 1024 bytes +.IP \- +the base and current scheduling priority, each 11 character numbers +.PP +The read-only +.B args +file contains the arguments of the program when it was created by +.IR exec (2). +If the program was not created by +.BR exec , +such as by +.IR fork (2), +its +.B args +file will be empty. +The format of the file is a list of quoted strings suitable for +.BR tokenize ; +see +.IR getfields (2). +.PP +The +.B text +file is a pseudonym for the file +from which the process was executed; +its main use is to recover the symbol table of the process. +.PP +The +.B wait +file may be read to recover +records from the exiting children of the process in the format of +.B await +(see +.IR wait (2)). +If the process has no extant children, living or exited, +a read of +.B wait +will block. +It is an error for a process to attempt to read its own +.B wait +file when it has no children. +When a process's +.B wait +file is being read, +the process will draw an error +if it attempts an +.B await +system call; similarly, if a process is in an +.B await +system call, its +.B wait +file cannot be read by any process. +.PP +Textual messages written to the +.B ctl +file control the execution of the process. +Some require that the process is in a particular state +and return an error if it is not. +.TP 10n +.B stop +Suspend execution of the process, putting it in the +.B Stopped +state. +.TP 10n +.B start +Resume execution of a +.B Stopped +process. +.TP 10n +.B waitstop +Do not affect the process directly but, like all other messages ending with +.BR stop , +block the process writing the +.B ctl +file until the target process is in the +.B Stopped +state or exits. +Also like other +.B stop +control messages, +if the target process would receive a note while the message is pending, +it is instead stopped and the debugging process is resumed. +.TP 10n +.B startstop +Allow a +.B Stopped +process to resume, and then do a +.B waitstop +action. +.TP 10n +.B hang +Set a bit in the process so that, +when it completes an +.IR exec (2) +system call, it will enter the +.B Stopped +state before returning to user mode. +This bit is inherited across +.IR fork (2) +and +.IR exec (2). +.TP 10n +.B "close\ \fIn +Close file descriptor +.I n +in the process. +.TP 10n +.B closefiles +Close all open file descriptors in the process. +.TP 10n +.B nohang +Clear the hang bit. +.TP 10n +.B kill +Kill the process the next time it crosses the user/kernel boundary. +.TP 10n +.B private +Make it impossible to read the process's user memory. +This property is inherited on fork, cleared on +.IR exec (2), +and is not otherwise resettable. +.TP 10n +.B "pri\ \fIn +Set the base priority for the process to the integer +.IR n . +.TP 10n +.B "wire\ \fIn +Wire the process to processor +.IR n . +.PD +.PP +The priority is interpreted by Plan 9's multilevel process scheduler. +Priorities run from 0 to 19, with higher +numbers representing higher priorities. +A process has a base priority and +a running priority which is less than or equal to the base priority. +As a process uses up more of its allocated time, its priority is lowered. +Unless +explicitly set, user processes have base priority 10, kernel processes +13. +Children inherit the parent's base priority. +.PP +The read-only +.B profile +file contains the instruction frequency count information used for multiprocess profiling; see +.B tprof +in +.IR prof (1). +The information is gleaned by sampling the program's user-level program counter +at interrupt time. +.PP +Strings written to the +.B note +file will be posted as a note to the process +(see +.IR notify (2)). +The note should be less than +.B ERRLEN-1 +characters long; +the last character is reserved for a terminating NUL character. +A read of at least +.B ERRLEN +characters will retrieve the oldest note posted to the +process and prevent its delivery to the process. +The +.B notepg +file is similar, but the note will be delivered to all the +processes in the target process's +.I note group +(see +.IR fork (2)). +However, if the process doing the write is in the group, +it will not receive the note. +The +.B notepg +file is write-only. +.PP +The textual +.B noteid +file may be read to recover an integer identifying the note group of the process +(see +.B RFNOTEG +in +.IR fork (2)). +The file may be written to cause the process to change to another note group, +provided the group exists and is owned by the same user. +.SH FILES +.nf +.B /sys/src/9/*/mem.h +.B /sys/src/9/*/dat.h +.fi +.SH SEE ALSO +.IR debugger (2), +.IR mach (2), +.IR cons (3) +.SH SOURCE +.B /sys/src/9/port/devproc.c diff --git a/static/plan9-4e/man3/realtime.3 b/static/plan9-4e/man3/realtime.3 new file mode 100644 index 00000000..b9bcc7f7 --- /dev/null +++ b/static/plan9-4e/man3/realtime.3 @@ -0,0 +1,316 @@ +.TH REALTIME 3 +.EQ +delim $$ +.EN +.SH NAME +realtime \- real time scheduling +.SH SYNOPSIS +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +.B bind -a #R /dev +.ift .sp 0.5 +.ifn .sp +/dev/realtime/clone +/dev/realtime/debug +/dev/realtime/log +/dev/realtime/nblog +/dev/realtime/resources +/dev/realtime/task/0 +/dev/realtime/task/1 +/dev/realtime/task/... +/dev/realtime/time +.sp +#include /sys/src/port/9/devrealtime.h +.ift .sp 0.5 +.ifn .sp +enum SEvent { + SAdmit, /* new proc arrives*/ + SRelease, /* released, but not yet scheduled */ + SRun, /* one of this task's procs started running */ + SPreempt, /* the running task was preempted */ + SBlock, /* the last of the runnable procs in a task blocked */ + SResume, /* task was scheduled after blocking */ + SDeadline, /* proc's deadline (reported ahead of time) */ + SYield, /* proc reached voluntary early deadline */ + SSlice, /* slice exhausted */ + SExpel, /* proc was expelled */ +}; +typedef enum SEvent SEvent; +typedef vlong Time; +typedef struct Schedevent Schedevent; +.ift .sp 0.5 +.ifn .sp +struct Schedevent { + ushort tid; /* Task ID */ + SEvent etype; /* Event type */ + Time ts; /* Event time */ +}; +.EE +.SH DESCRIPTION +The Plan 9 real-time scheduler allows mixing real-time processes and best-effort +processes on a single system. The scheduler is intended for real-time loads well +under 100% CPU utilization with minimum periods in the order of a hundred thousand +instruction times. The precision of the scheduler depends on the precision of the +machine's programmable real-time clock. +.PP +The unit of real-time scheduling is a +.BR task . +A task can contain zero or more processes. The processes in a task share a common +period, deadline and CPU allocation. Tasks allow cooperating processes to collaborate +to achieve a common deadline, for instance, processes receiving, decompressing and +displaying video in a pipeline can share a single task. +.PP +Tasks are scheduled using Earliest-Deadline First (EDF). Each task has three primary +scheduling parameters, a period $T$, a deadline $D$ and a cost $C$, expressed in +nanoseconds (but converted to a machine- and architecture-dependent unit called +.IR ticks ). +Every $T$ nanoseconds, the task is +.I released +— i.e., it becomes schedulable — and it received a +.I slice +of $C$ nsec. +When the task is released, its +.I "release time" +$r$ is set to the current time. +The task's +.I "absolute deadline" +$d$ is set to $r + D$. +(Note the use of capital letters to indicate intervals and lower-case letters to indicate +`points in time'.) +Between release and deadline the task must +be scheduled often enough to be able to consume its slice of $C$ nsec of CPU time. +So, to be schedulable, $C <= D <= T$ must hold. +If $D < T$, tasks are not schedulable (runnable) between their deadline and the next +release. +Tasks are +.I released +from the moment of release until their deadline or their slice runs out, whichever +happens first. Additionally, tasks can voluntarily declare the slice for the current period +empty, allowing other real-time tasks or best-effort tasks the CPU time remaining in +their slice. +.PP +Before they are released for the first time, tasks have to be +.IR admitted +into the system. Before admission, a test is conducted to determine whether the task, +plus the already admitted tasks can all meet their deadlines, given their scheduling +parameters. When a task changes its scheduling parameters, it is temporarily +.I expelled +and will be readmitted if the new scheduling parameters allow all tasks to continue +to meet their deadlines. +.PP +The EDF scheduler schedules the released task with the earliest deadline. When a task +is released, therefore, it can preempt a task that has a later deadline, but was released earlier. +Real-time tasks sharing resources, however, may need to be prevented from preempting +each other. They can do this by declaring a shared resource. The scheduler will not +preempt one task with another that shares a common resource. To do this, the scheduler only +needs to know the names of the sharable resources used by each of the tasks. +.PP +During the admission test, information about shared resources is used to calculate +a secondary deadline for each task, called the +.IR "inherited deadline" , +$Δ$, which is the minimum of the deadlines $D$ of each of the tasks that shares a +resource with the current task. +The scheduler allows a released task $T$ to preempt running task $T'$ iff +$d < d' ^ D < Δ'$; the first half of the condition says that the released task's deadline +must be earlier, the second implies that the released task may not share resources with +the running one. +The admission test takes these limitations into account. Note that, in practice, tasks +rarely share resources. +.PP +Normally, tasks can block (when all their processes are blocked on system calls) during +their release. +The time spent blocking is not accounted against the current slice, but, since the scheduler +has no control over the time spent blocking, there are no guarantees that the deadline +will be made if a task spends any time blocked. +Whether or not tasks actually block, they will normally complete the work to be done +in a period (slightly) before the slice runs out — and before the deadline. To tell the +scheduler that they no longer require the CPU until the next release, tasks can +.I yield +(see below). +.PP +Tasks can also run in another mode where blocking automatically implies immediate +yielding. This mode truly guarantees that deadlines will be made, but programmers +must know more about the (blocking) nature of the system calls used in order to use +this mode. +.sp +.LP +The real-time scheduler is controlled through a file system (naturally), normally +bound to +.BR /dev . +Opening +.B /dev/realtime/clone +for writing (and reading, if desired), causes a new task to be created in the +non-admitted (expelled) state. The new task will be represented by a file in +the +.B /dev/realtime/task +directory whose name is the task's number. +The file descriptor resulting from opening +.B /dev/realtime/clone +provides the equivalent functionality as that resulting from opening +.BI /dev/realtime/task/ n +except for the initial creation of a new task when opening the +.B clone +file. The task file may also be opened read-only. +.PP +The tasks parameters are set or modified by writing one of these files and they +can be examined by reading it. +A parameter is presented in the form +\f2name\fP=\f2value\fP, \f2name\fP+=\f2value\fP, or \f2name\fP-=\f2value\fP. +A command is presented in the form +.IR commandname . +Parameters and commands are separated by white space; quoting conventions apply +(see +.IR quote (2)). +The settable parameters are +.TP +.B T +Sets the period. The value must be given as a number with or without decimal point +and directly followed (no white space) by one of +.I s +for seconds, +.I ms +for milliseconds, +.I µs +or +.I us +for microseconds, +.I ns +or +nothing +for nanoseconds. The +.B += +operator adds to the period already set, the +.B -= +operator subtracts from it. +.TP +.B D +Sets the deadline. Value syntax and operators as above. +.TP +.B C +Sets the cost. Value syntax and operators as above. +.TP +.B resources +Sets the list of resources; resource names are separated by white space and +quoting must be used in this case. A resource name is an arbitrary string. The +.B += +operator adds to the list of resources +.B -= +operator takes away from it. +.TP +.B procs +Sets, adds to, or subtracts from the process membership of a task. Processes +are identified by their +.I pid +or the special value +.B self +identifying the process writing the +.I clone +or +.I task +file. +.TP +.B yieldonblock +When the (integer) value is non-zero, the task is placed in +.I yield-on-block +mode: when all processes in the task are blocked on system calls, the task automatically +declares the current deadline reached and will be released again in the next period. +When the value is zero, the task can block without forfeiting the current release. +However, when the task blocks long, the deadline may be missed. The default value is zero. +.LP +The commands accepted are +.TP +.B verbose +This is for debugging and causes the progression of the admission test to be displayed. +.TP +.B admit +This initiates an admission test. If the test fails, the write containing the +.B admit +command will fail. If the test succeeds the task is admitted and, if it contains +runnable processes, it will be released (almost) immediately. +.TP +.B expel +Expel the task. +.TP +.B remove +Remove the task, the file descriptor will become invalid. +.TP +.B yield +Gives up the processor until the next release. +.LP +.sp +.B /dev/realtime/debug +prints debugging information about the task queues maintained by the scheduler. +This file will go away. +.PP +.B /dev/realtime/log +and +.B /dev/realtime/nblog +are files used by real-time monitoring processes such as +.B rtstats +(see +.IR rtstats (1)). +Reading them produces a stream of +.B Schedevent +structures in the machine representation. These events are +nearly ordered by Time (nanoseconds since boot); some events can +be reported earlier or later than they occur. +.I Tid +corresponds to the file name in the directory +.BR /dev/realtime/task , +.I etype +is one of the events of +.I SEvent +as explained in +.BR /sys/src/9/port/devrealtime.h , +and +.I ts +is the time at which the event occurred (or will occur). +.B Nblog +is a non-blocking version that returns zero bytes each time there is +nothing left to read. +.PP +.B /dev/realtime/resources +is a read-only file listing the resources declared by the current set of tasks. +.PP +.B /dev/realtime/time +returns the number of nanoseconds since boot, the number of ticks since boot and +.IR fasthz , +the number of clock ticks per second, a billion times the ratio between the other two numbers. +Each number is returned as a binary +.I vlong +in architecture-dependent representation. +.SH EXAMPLE +.EX +.ta 4n +4n +4n +4n +4n +4n +4n +char *clonedev = "#R/realtime/clone"; + +void +processvideo(){ + int fd; + + if ((fd = open(clonedev, ORDWR)) < 0) + sysfatal("%s: %r", clonedev); + if (fprint(fd, "T=33ms D=20ms C=8ms procs=self admit") < 0) + sysfatal("%s: admit: %r", clonedev); + for (;;){ + processframe(); + if (fprint(fd, "yield") < 0) + sysfatal("%s: yield: %r", clonedev); + } + if (fprint(fd, "remove") < 0) + sysfatal("%s: remove: %r", clonedev); + close(fd); +} +.EE +.SH "SEE ALSO +.IR rtstats (1) +.SH FILES +.B /usr/sape/src/realtime/edfproc.c +as an example of using the scheduler for a trivial test run. +.SH SOURCE +.B /sys/src/9/port/devrealtime.c +.br +.B /sys/src/9/port/edf.c +.SH BUGS +The admission test does not take multiprocessors into account. The total +real-time load cannot exceed a single-\s-2CPU\s0 load. diff --git a/static/plan9-4e/man3/root.3 b/static/plan9-4e/man3/root.3 new file mode 100644 index 00000000..ff12df61 --- /dev/null +++ b/static/plan9-4e/man3/root.3 @@ -0,0 +1,39 @@ +.TH ROOT 3 +.SH NAME +root \- the root file system +.SH SYNOPSIS +.nf +.B / +.B /boot +.B /dev +.B /env +.B /net +.B /net.alt +.B /proc +.B /root +.B /srv +.fi +.SH DESCRIPTION +The syntax +.L #/ +is illegal, so this device can only be accessed directly by the kernel. +.PP +This device is set up by the kernel to be the root of +the name space. +The names in the one-level tree are mostly just place-holders, +to allow a place to +.IR bind (2) +to. +The exception is +.BR /boot , +which provides executable code when read. +The kernel does an +.IR exec (2) +of +.B /boot +when initializing. +Some kernels are built with other services, such as +.IR kfs (4) , +in the root directory. +.SH SOURCE +.B /sys/src/9/port/devroot.c diff --git a/static/plan9-4e/man3/rtc.3 b/static/plan9-4e/man3/rtc.3 new file mode 100644 index 00000000..da30231f --- /dev/null +++ b/static/plan9-4e/man3/rtc.3 @@ -0,0 +1,40 @@ +.TH RTC 3 +.SH NAME +rtc \- real-time clock and non-volatile RAM +.SH SYNOPSIS +.B bind #r /dev +.PP +.B /dev/rtc +.br +.B /dev/nvram +.SH DESCRIPTION +The +.I rtc +device supports devices +with real-time clocks and non-volatile RAM. +.PP +The +.B rtc +file behaves just like +.BR /dev/time +(see +.IR cons (3)). +The real-time clock is maintained on-board; +.B /dev/time +is set from the file server. Neither is necessarily more accurate. +.PP +The +.B nvram +file provides (if permission allows) +access to the local non-volatile RAM. +For example, +.IR boot (8) +reads the machine's key +from there +(see +.IR auth (8)). +.SH SEE ALSO +.IR auth (8), +.IR boot (8) +.SH SOURCE +.B /sys/src/9/*/devrtc.c diff --git a/static/plan9-4e/man3/sd.3 b/static/plan9-4e/man3/sd.3 new file mode 100644 index 00000000..99b851cd --- /dev/null +++ b/static/plan9-4e/man3/sd.3 @@ -0,0 +1,209 @@ +.TH SD 3 +.SH NAME +sd \- storage device interface +.SH SYNOPSIS +.nf +.B bind #S /dev + +.BI /dev/sd Cu /ctl +.BI /dev/sd Cu /raw +.BI /dev/sd Cu /data +\&... +.fi +.SH DESCRIPTION +.PP +The storage device interface serves a two-level directory +giving access to multiple storage units, +typically ATA(PI) or SCSI discs. +Each unit +is accessed via files in the directory named by the controller +to which it is attached, +.IR C , +and by its unit number +.IR u . +The controller naming convention for ATA(PI) units starts +with the first controller being named +.LR C , +the second +.LR D , +etc. up to a maximum of 4 controllers +.RB ([ C-F ]); +legacy controllers are always 'C' and 'D'. +There can be a maximum of 2 units per ATA(PI) controller +.RB ([ 01 ]). +The controller naming convention for SCSI units starts with +the first controller being named +.LR 0 , +the second +.LR 1 , +etc. up to a maximum of 16 controllers +.RB ([ 0-9a-f ]). +There can be a maximum of 16 units per SCSI controller +.RB ([ 0-9a-f ]). +.PP +Units are not accessed before the first attach. +Units may be individually attached using the attach specifier, +for example +.IP +.EX +bind -a '#SsdD0' /dev +.EE +.PP +An attach without a specifier will cause the driver to scan for all possible +units before processing the rest of the name. +.PP +The subdirectory for each unit contains two files, +.I ctl +and +.IR raw . +In addition, +if the unit is a direct-access disc of some type +it may be split into partitions and +the subdirectory may contain a file per partition. +By default, +the partition +.I data +will exist for such media. +.PP +Partitions are added and deleted by writing to the +.I ctl +file +.IP +.EX +part \f2name start-sector end-sector\fP +delpart \f2name\fP +.EE +.PP +The default +.I data +partition may be deleted. +A partition cannot be deleted if a process has it open. +If a change of removable media is detected, +the new media cannot be opened until all open partitions +on the old media are closed. +.PP +Partitions are usually created using +.I fdisk +and +.IR prep (8); +the convention is to name non-Plan 9 partitions after their corresponding operating systems +(e.g., +.BR /dev/sdC0/dos ) +and Plan 9 partitions according to their function +(e.g., +.BR /dev/sdC0/swap ). +The example in +.IR prep (8) +shows how this is done. +.PP +Reading the +.I ctl +file returns at least one line of textual information about +the unit. +The first line will always be prefixed by +.B inquiry +and will give a manufacturer and model number if possible. +A line prefixed by +.B config +will be returned for appropriate media, +e.g. for ATA(PI) units the remainder of the line contains +configuration information from the device's +.I identify +command (config and capabilities) +and also the available I/O transfer options; +this is a diagnostic aid. +A line prefixed by +.B geometry +will be returned for appropriate media; +at least two numbers will follow, +the first being the number of sectors contained in the unit +and the second the sector size in bytes. +Any remaining information on the +.B geometry +line is unit-dependent, +for instance, head, +cylinder and sector counts for ATA discs. +If any partitions are defined for the media, +their name, start-sector and end-sector will be returned, +prefixed by +.BR part . +.IP +.EX +% cat /dev/sdD0/ctl +inquiry KENWOOD CD-ROM UCR-421 208E10/20/99 7.39 2 M0 +config 85C0 capabilities 0F00 dma 00550004 dmactl 00000000 +geometry 242725 2352 +part data 0 242725 +% +.EE +.PP +The use of DMA and multi-sector read/write commands may be +enabled and disabled on ATA(PI) units by writing to the +.B ctl +file +.B dma +and +.B rwm +respectively followed by +.B on +or +.BR off . +For example, to enable DMA on a unit that supports it: +.IP +.EX +% echo 'dma on'>/dev/sd00/ctl +.EE +.PP +If supported by the unit, +the standby timer may be enabled: +.IP +.EX +% echo 'standby \f2T\fP'>/dev/sdC0/ctl +.EE +.PP +where +.I T +is the standby timer period in seconds. +.I T +must be between 30 and 1200, +or can be 0 to disable the timer. +.PP +The +.B raw +file is used to execute an arbitrary command on the unit at +a low level. +This is used by programs such as +.IR scuzz (8) +to manipulate devices that do not fit the simple storage model +or for maintenance purposes. +The following steps may be used to execute a command +.IP +\- Write the command to the +.I raw +file; +.IP +\- Read or write data associated with the command, according to the direction of the transfer. +.IP +\- Read the +.I raw +file to retrieve the status of the command, +returned as a text integer. +.SH SOURCE +.B /sys/src/9/port/devsd.c +.br +.B /sys/src/9/*/sd*.[hc] +.SH SEE ALSO +.IR scuzz (8) +.SH BUGS +.PP +Still in development. +.PP +No LUNs. +.PP +The 4 controller limit for ATA(PI) is not enforced. +.PP +No account is taken of some buggy ATA PCI controllers +such as the CMD640. +.PP +ATA(PI) units come up with DMA and multi-sector read/write +capability disabled. diff --git a/static/plan9-4e/man3/segment.3 b/static/plan9-4e/man3/segment.3 new file mode 100644 index 00000000..1a8e5e71 --- /dev/null +++ b/static/plan9-4e/man3/segment.3 @@ -0,0 +1,117 @@ +.TH SEGMENT 3 +.SH NAME +segment \- long lived memory segments +.SH SYNOPSIS +.nf +.B bind '#g' /mnt/segment + +.BI #g/ seg1 +.BI #g/ seg1 /ctl +.BI #g/ seg1 /data +.BI #g/ seg2 +.BI #g/ seg2 /ctl +.BI #g/ seg2 /data + ... +.fi +.SH DESCRIPTION +.PP +The +.I segment +device provides a 2-level file system representing +long-lived sharable segments that processes may +.IR segattach (2). +The name of the directory is the +.I class +argument to +.IR segattach . +.PP +New segments are created under the top level +using +.B create +(see +.IR open (2)). +The +.B DMDIR +bit must be set in the permissions. +.IR Remove (2)'ing +the directory makes the segment no longer +available for +.IR segattach . +However, the segment will continue to exist until all +processes using it either exit or +.I segdetach +it. +.PP +Within each segment directory are two files, +.B data +and +.BR ctl . +Reading and writing +.B data +affects the contents of the segment. +Reading and writing +.B ctl +retrieves and sets the segment's properties. +.PP +There is only one control message, which sets the segment's +virtual address and length in bytes: +.EX + va \fIaddress length\fP +.EE +.I Address +is automatically rounded down to a page boundary and +.I length +is rounded up to end the segment at a page boundary. +The segment will reside at the same virtual address in +all processes sharing it. +When the segment +is attached using +.IR segattach, +the address and length arguments are ignored in the call; +they are defined only by the +.B va +control message. +Once the address and length are set, they cannot be reset. +.PP +Reading the control file +returns a message of the same format with the segment's actual +start address and length. +.PP +Opening +.B data +or reading +.B ctl +before setting the virtual address yields the error +``segment not yet allocated''. +.PP +The permissions check when +.IR segattach ing +is equivalent to the one performed when opening +.B data +with mode ORDWR. +.SH EXAMPLE +.PP +Create a one megabyte segment at address 0x10000000: +.EX + % bind '#g' /mnt/segment + % mkdir /mnt/segment/example + % echo 'va 0x10000000 0x100000' > /mnt/segment/example/ctl +.EE +.PP +Put the string ``hi mom'' at the start of the segment: +.EX + % echo -n hi mom > /mnt/segment/example/data +.EE +.PP +Attach the segment to a process: +.EX +{ + ulong va; + + va = segattach(0, "example", 0, 0); +} +.EE +.SH "SEE ALSO +.IR segattach (2) +.SH SOURCE +.B /sys/src/9/port/devsegment.c diff --git a/static/plan9-4e/man3/srv.3 b/static/plan9-4e/man3/srv.3 new file mode 100644 index 00000000..820c849d --- /dev/null +++ b/static/plan9-4e/man3/srv.3 @@ -0,0 +1,74 @@ +.TH SRV 3 +.SH NAME +srv \- server registry +.SH SYNOPSIS +.nf +.B bind #s /srv + +.BI #s/ service1 +.BI #s/ service2 + ... +.fi +.SH DESCRIPTION +The +.I srv +device provides a one-level directory holding +already-open channels to services. +In effect, +.I srv +is a bulletin board on which processes may post open file descriptors +to make them available to other processes. +.PP +To install a channel, create +a new file such as +.B /srv/myserv +and then write a text string (suitable for +.IR strtoul ; +see +.IR atof (2)) +giving the file descriptor number of an open file. +Any process may then open +.B /srv/myserv +to acquire another reference to the open file that was registered. +.PP +An entry in +.I srv +holds a reference to the associated file even if no process has the +file open. Removing the file from +.B /srv +releases that reference. +.PP +It is an error to write more than one number into a server file, +or to create a file with a name that is already being used. +.SH EXAMPLE +To drop one end of a pipe into +.BR /srv , +that is, to create a named pipe: +.IP +.EX +int fd, p[2]; +char buf[32]; + +pipe(p); +fd = create("/srv/namedpipe", OWRITE, 0666); +fprint(fd, "%d", p[0]); +close(fd); +close(p[0]); +fprint(p[1], "hello"); +.EE +.PP +At this point, any process may open and read +.B /srv/namedpipe +to receive the +.B hello +string. Data written to +.B /srv/namedpipe +can be received by executing +.IP +.EX +read(p[1], buf, sizeof buf); +.EE +.PP +in the above process. +.SH SOURCE +.B /sys/src/9/port/devsrv.c diff --git a/static/plan9-4e/man3/ssl.3 b/static/plan9-4e/man3/ssl.3 new file mode 100644 index 00000000..2b3944d1 --- /dev/null +++ b/static/plan9-4e/man3/ssl.3 @@ -0,0 +1,124 @@ +.TH SSL 3 +.SH NAME +ssl \- SSL record layer +.SH SYNOPSIS +.nf +.B bind -a #D /net + +.B /net/ssl/clone +.BI /net/ssl/ n +.BI /net/ssl/ n /ctl +.BI /net/ssl/ n /data +.BI /net/ssl/ n /encalgs +.BI /net/ssl/ n /hashalgs +.BI /net/ssl/ n /secretin +.BI /net/ssl/ n /secretout +.fi +.SH DESCRIPTION +The SSL device provides the interface to the Secure Socket Layer +device implementing the record layer protocol of SSLv2 +(but not the handshake protocol, which is responsible for +mutual authentication and key exchange.) +The +.I ssl +device can be thought of as a filter providing optional encryption +and anti-tampering. +.PP +The top level directory contains a +.B clone +file and subdirectories numbered from zero to the number of connections +configured. +Opening the +.B clone +file reserves a connection. The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated connection. Reading the +.B ctl +file returns a text +string representing the number of the +connection. +.PP +A connection is controlled by writing text strings to the associated +.B ctl +file. After a connection has been established data may be read from +and written to the data file. +.PP +The SSL protocol provides a stream connection that preserves +.BR read / write +boundaries. As long as reads always specify buffers that are +of equal or greater lengths than the writes at the other end of the +connection, one write will correspond to one read. +.PP +Options are set by writing control messages to the +.B ctl +file of the connection. +.PP +The following control messages are supported: +.TP +.BI fd \ open-file-descriptor +Run the SSL protocol over the existing file descriptor. +.TP +.BI alg \ cryptoalgs +Connections start in +.B alg clear +which means no encryption or digesting. +Writing +.B alg sha +to the control file turns on SHA-1 digest authentication +for the data channel. +Similarly, writing +.B alg rc4_128 +enables encryption. +Both can be turned on at once by +.BR "alg sha rc4_128" . +The digest mode +.B sha +may be replaced by +.BR md5 . +The encryption mode +.B rc4_128 +may be replaced by +.BR rc4_40 , +.BR rc4_128 , +.BR rc4_256 , +.BR des_40_ecb , +.BR des_40_cbc , +.BR des_56_ecb , +and +.BR des_56_cbc . +The mode may be changed at any time during the connection. +.TP +.BI secretin \ base64-secret +The secret for decrypting and authenticating incoming messages +can be specified either as a base64 encoded string by writing to the +control file, or as a binary byte string using the interface below. +.TP +.BI secretout \ base64-secret +The secret for encrypting and hashing outgoing messages +can be specified either as a base64 encoded string by writing to the +control file, or as a binary byte string using the interface below. +.PP +Before enabling digesting or encryption, shared secrets must be agreed upon with +the remote side, one for each direction of transmission, +and loaded as shown above or by writing to the files +.I secretin +and +.IR secretout . +If either the incoming or outgoing secret is not specified, the other secret +is assumed to work for both directions. +.PP +The encryption and hash algoritms actually included in the kernel +may be smaller than the set presented here. Reading +.I encalgs +and +.I hashalgs +will give the actual space-separated list of algorithms implemented. +.SH "SEE ALSO" +.IR listen (8), +.IR dial (2) +.SH SOURCE +.B /sys/src/9/port/devssl.c +.SH BUGS +Messages longer than 4096 bytes are truncated. diff --git a/static/plan9-4e/man3/tls.3 b/static/plan9-4e/man3/tls.3 new file mode 100644 index 00000000..f38fe283 --- /dev/null +++ b/static/plan9-4e/man3/tls.3 @@ -0,0 +1,272 @@ +.TH TLS 3 +.SH NAME +tls \- TLS1 and SSL3 record layer +.SH SYNOPSIS +.nf +.B bind -a #a /net + +.B /net/tls/clone +.B /net/tls/encalgs +.B /net/tls/hashalgs +.BI /net/tls/ n +.BI /net/tls/ n /ctl +.BI /net/tls/ n /data +.BI /net/tls/ n /hand +.BI /net/tls/ n /stats +.BI /net/tls/ n /status +.fi +.SH DESCRIPTION +The TLS device implements the record layer protocols +of Transport Layer Security version 1.0 and Secure Sockets Layer version 3.0. +It does not implement the handshake protocols, which are responsible for +mutual authentication and key exchange. +The +.I tls +device can be thought of as filters providing optional encryption and anti-tampering. +.PP +The top level directory contains a +.B clone +file and subdirectories numbered from zero through at least the last active filter. +Opening the +.B clone +file reserves a filter. +The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated filter. +Reading the +.B ctl +file returns a text string containing the number of the filter directory. +.PP +The filter initially cannot be used to pass messages +and will not encrypt or digest messages. +It is configured and controlled by writing commands to +.BR ctl . +.PP +The following commands are supported: +.TP +.BI fd \ open-fd\ vers +Pass record messages over the communications channel +.IR open-fd . +Initially, outgoing messages use version +.I vers +format records, but incoming messages of either version are accepted. +Valid versions are +.B 0x300 +for SSLv3.0 and +.B 0x301 +for TLSv1.0 (which could be known as SSLv3.01.) +This command must be issued before any other command +and before reading or writing any messages; +it may only be executed once. +.TP +.BI version \ vers +Use +.I vers +format records for all future records, +both outgoing and incoming. +This command may only be executed once. +.TP +.BI secret \ hashalg\ encalg\ isclient\ secretdata +Set up the digesting and encryption algorithms and secrets. +.I Hashalg +and +.I encalg +must be algorithm names returned by the corresponding files. +.I Secretdata +is the base-64 encoded (see +.IR encode (2)) +secret data used for the algorithms. +It must contain at least enough data to populate the +secrets for digesting and encrypting. +These secrets are divided into three categories: digest secrets, keys, and initialization vectors. +The secrets are packed in this order, with no extra padding. +Within each category, the secret for data traveling from the client to the server comes first. +The incoming and outgoing secrets are automatically selected by devtls based on the +.I isclient +argument, which must be non-zero for the client of the TLS handshake, +and zero for the server. +.br +This command must be issued after +.BR version , +and may be issued more than once. +At least one new +.I secret +command must be issued before each +.I changecipher +command; similarly, at least one new +.I secret command +must precede each incoming changecipher message. +.TP +.BI changecipher +Enable outgoing encryption and digesting as configured by the previous +.I secret +command. +This command sends a +.I changecipher +message. +.TP +.BI opened +Enable data messages. +This command may be issued any number of times, +although only the first is significant. +It must follow at least one successful +.I changecipher +command. +.TP +.BI alert \ alertno +Send an alert message. +.I Alertno +may be a valid alert code for either SSLv3.0 or TLSv1.0, +and is mapped to an appropriate code for the protocol in use. +If it is a fatal alert, the filter is set into an error state. +.PP +Application messages and handshake messages are communicated using +.I data +and +.IR hand , +respectively. +Only one +.IR open (2) +of +.I hand +is allowed at a time. +.PP +Any record layer headers and trailers are inserted and +stripped automatically, and are not visible from the outside. +The device tries to synchronize record boundaries with reads and writes. +Each read will return data from exactly one record, +and will return all of the data from the record as long as +the buffer is big enough. +Each write will be converted into an integral number of records, +with all but potentially the last being maximal size. +The maximum record length supported is 16384 bytes. +This behavior is not specified in the protocols, +and may not be followed by other implementations. +.PP +If a fatal alert message is received, or a fatal +.I alert +command issued, the filter is set into an error state. +All further correspondence is halted, +although some pending operations may not be terminated. +Operations on +.I data +will fail with a +.BR "'tls error'" , +and operations on +.I hand +will fail with a textual decoding of the alert. +The current non-fatal alert messages are +.BR "'close notify'" , +.BR "'no renegotiation'" , +and +.BR "'handshake canceled by user'" . +Receipt of one of these alerts cause the next read on +.I hand +to terminate with an error. +If the alert is +.BR "'close notify'", +all future reads will terminate with a +.B "tls hungup" +error. +A +.B "'close notify'" +.I alert +command will terminate all future writes or reads from +.I data +with a +.B "'tls hungup'" +error. +.PP +If an error is encountered while reading or writing +the underlying communications channel, the error is returned +to the offending operation. +If the error is not +.BR "'interrupted'" , +the filter is set into the error state. +In this case, all future operations on +.I hand +will fail with a +.BR "'channel error'" . +.PP +When all file descriptors for a filter have been closed, +the session is terminated and the filter reclaimed for future use. +A +.B "'close notify'" +alert will be sent on the underlying communications channel +unless one has already been sent or the filter is in the error state. +.PP +Reading +.I stats +or +.I status +returns information about the filter. +Each datum is returned on a single line of the form +.IB tag ": " data . +.I Stats +returns the number of bytes communicated by the +.B data +and +.B hand +channels. +The four lines returned are tagged by, in order, +.BR DataIn , +.BR DataOut , +.BR HandIn , +and +.BR HandOut . +.I Status +returns lines following tags: +.BR State , +.BR Version , +.BR EncIn , +.BR HashIn , +.BR NewEncIn , +.BR NewHashIn , +.BR EncOut , +.BR HashOut , +.BR NewEncOut , +and +.BR NewHashOut . +.BR State 's +value is a string describing the status of the connection, +and is one of the following: +.BR 'Handshaking' , +.BR 'Established' , +.BR 'RemoteClosed' , +.BR 'LocalClosed' , +.BR 'Alerting' , +.BR 'Errored' , +or +.BR 'Closed' . +.BR Version 's +give the hexadecimal record layer version in use. +The +.B Enc +and +.B Hash +fields return name of the current algorithms in use +or ready to be used, if any. +.PP +Reading +.I encalgs +and +.I hashalgs +will give the space-separated list of algorithms implemented. +This will always include +.BR clear , +meaning no encryption or digesting. +Currently implemented encryption algorithms are +.B 'rc4_128' +and +.BR '3des_ede_cbc' . +Currently implemented hashing algorithms are +.B 'md5' +and +.BR 'sha1' . +.SH "SEE ALSO" +.IR listen (8), +.IR dial (2) +.SH SOURCE +.B /sys/src/9/port/devtls.c diff --git a/static/plan9-4e/man3/uart.3 b/static/plan9-4e/man3/uart.3 new file mode 100644 index 00000000..b4504610 --- /dev/null +++ b/static/plan9-4e/man3/uart.3 @@ -0,0 +1,97 @@ +.TH UART 3 +.SH NAME +uart, eia \- serial communication control +.SH SYNOPSIS +.nf +.B bind -a #t /dev + +.B /dev/eia0 +.B /dev/eia0ctl +.B /dev/eia0status +.B /dev/eia1 +.B /dev/eia1ctl +.B /dev/eia1status +\&... +.fi +.SH DESCRIPTION +.PP +The serial line devices serve a one-level directory, +giving access to the serial ports. +Device +.I n +is accessed through +.BI eia n +(the data file), +.BI eia n ctl +(the control file), and +.BI eia n status +(the read-only status file). +Reads of the data file will block until at least one byte is available. +The +control file +configures the port. +It accepts the following commands: +.TP +.BI b n +Set the baud rate to +.IR n . +.TP +.BI d n +Set DTR if +.I n +is non-zero; +else clear it. +.TP +.BI k n +Send a break lasting +.I n +milliseconds. +.TP +.BI r n +Set RTS if +.I n +is non-zero; +else clear it. +.TP +.BI m n +Obey modem CTS signal if +.I n +is non-zero; +else clear it. +.TP +.BI i n +Enable input FIFO if +.I n +is non-zero; +else disable. +.TP +.BI p c +Set parity to odd if +.I c +is +.BR o , +to even if +.I c +is +.BR e ; +else set no parity. +.TP +.BI s n +Set number of stop bits to +.IR n . +Legal values are 1 or 2. +.TP +.BI l n +Set number of bits per byte to +.IR n . +Legal values are 5, 6, 7, or 8. +.PP +The status +files contain a textual representation of the status of the line, in the format of the +commands used on the +control +file. +.SH SOURCE +.B /sys/src/9/port/devuart.c +.br +.B /sys/src/9/*/uart*.c diff --git a/static/plan9-4e/man3/usb.3 b/static/plan9-4e/man3/usb.3 new file mode 100644 index 00000000..587b7a30 --- /dev/null +++ b/static/plan9-4e/man3/usb.3 @@ -0,0 +1,235 @@ +.TH USB 3 +.SH NAME +usb \- USB Host Controller Interface +.SH SYNOPSIS +.nf +.B bind -a #U /dev + +.BI /dev/usb m +.BI /dev/usb m /new +.BI /dev/usb m /port +.BI /dev/usb m / n +.BI /dev/usb m / n /ctl +.BI /dev/usb m / n /status +.BI /dev/usb m / n /setup +.BI /dev/usb m / n /ep k\fLdata +\&... + +.fi +.SH DESCRIPTION +The Universal Serial Bus is a popular bus for connecting slow and medium speed +devices, such as mice, keyboards, printers, and scanners to a PC. It is +a four-wire tree-shaped bus that provides both communication and (limited) +power to devices. Branching points in the tree are provided by devices +called +.IR hubs . +.PP +Most PCs have a two-slot hub built in, accommodating two USB devices. To +attach more devices, one or more hubs have to be plugged in to the USB +slots of the PC. The topology of the network is a tree with at most +127 nodes, counting both internal and leaf nodes. +.PP +The USB bus is fully controlled by the host; all devices are polled. +Hubs are passive in the sense that they do not poll the devices attached +to them. The host polls those devices and the hubs merely route the +messages. +.PP +When a device is attached, the host queries it to determine its type +and its speed. The querying process is standardized. The first level +of querying is the same for all devices, the next is somewhat specialized +for particular classes of devices (such as mice, keyboards, or audio devices). +Specialization continues as subclasses and subsubclasses are explored. +.PP +For each connected device there is a directory in +.BI #U/usb n\fR. +Reading +.BI #U/usb n /*/status +yields the state, class, subclass and proto of each device in the +first line. The remaining lines give the state of each of the +interfaces. +.PP +To find a mouse, for example, scan the status files for the line +.IP +.EX +.BR "Enabled 0x020103" +.EE +.PP +A mouse belongs to class 3 (in the least significant byte), +.IR "human interface device" , +subclass 1, +.IR boot , +proto 2, +.I mouse +(proto 1 would be the keyboard). +USB class, subclass and proto codes can be found on +.BR www.usb.org . +.PP +The control interface for each device is +.I "``endpoint 0''" +and is named +.BI #U/usb n /*/setup \fR. +The control interface of the device is accessed by reading and writing +this file. +.PP +There is a separate +.I "control interface +named +.BI #U/usb n /*/ctl +which is used to configure the USB device +.IR driver . +By writing to this +file, driver endpoints can be created and configured for communication with a +device's data streams. A mouse, for example, has one control interface +and one data interface. By communicating with the control interface, +one can find out the device type (i.e., `mouse'), power consumption, number +on interfaces, etc. +.IR Usbd (4) +will extract all this information and, in verbose mode, print it. +.PP +By sending an `endpoint message' to the +.I ctl +file, new driver endpoints can be created. The syntax of these messages +is +.PP +.B ep +.I n +.B bulk +.I "mode maxpkt nbuf +.PP +or +.PP +.B ep +.I "n period mode samplesize hz +.PP +The first form configures a non-real-time stream, the second an +.I isochronous +(real-time) stream. +In both forms, +.I n +is the endpoint to be configured, and +.I mode +is +.B r +for read only, or +.B w +for reading and writing. +In the first form, +.I maxpkt +is the maximum packet size to be used (between 1 and 2048), +and +.I nbuf +is the number of buffers to be allocated by the driver. +.PP +In the second form, +.I period +is the number of milliseconds between packets. This number is usually +dictated by the device. It must be between 1 and 1000. +The +.I samplesize +is the size in bytes of the data units making up packets, and +.I hz +is the number of data units transmitted or received per second. +.PP +The data rate is thus +.IR hz × samplesize +bytes per second, and the packet size used will vary between +⌊(\f2period\fP×\f2hz\fP)/1000⌋×\f2samplesize\fP +and +⌈(\f2period\fP×\f2hz\fP)/1000⌉×\f2samplesize\fP. +.PP +The mouse, which produces 3-byte samples, is configured with +.BR "ep 1 bulk r 3 32" : +endpoint 1 is configured for non-real-time read-only 3-byte messages +and allows 32 of them to be outstanding. +.PP +A usb audio output device at 44.1 KHz, 2 channels, 16-bit samples, on endpoint +4 will be configured with +.BR "ep 4 1 w 4 44100" . +.PP +If the configuration is successful, a file named +.BI ep n data +is created which can be read and/or written depending on +configuration. Configuration is not allowed when the data endpoint +is open. +.PP +Forward +.I seek +operations on isochronous endpoints +can be used to start the I/O at a specific time. +The usb status file provides information that can be used to map file +offsets to points in time: For each endpoint, the status file produces a line +of the form: +.PP +.B "4 0x000201 \f2nnn\fP bytes \f2nnn\fP blocks +.PP +The fields are, from left to right, +endpoint number, class/subclass/proto (as a six-digit hex number with class in the +least significant byte), number of bytes read/written, number of blocks read/written. +.PP +For isochronous devices only, an additional line is produced of the +form: +.PP +.B "bufsize \f2s\fP buffered \f2b\fP offset \f2o\fP time \f2t\fP +.PP +.I S +is the size of the DMA operations on the device (i.e., the minimum useful size +for reads and writes), +.I b +is the number of bytes currently buffered for input or output, and +.I o +and +.I t +should be interpreted to mean that byte offset +.I o +was/will be reached at time +.I t +(nanoseconds since the epoch). +.PP +To play or record samples exactly at some predetermined time, use +.I o +and +.I t +with the sampling rate to calculate the offset to seek to. +.PP +The number of bytes buffered can also be obtained using +.IR stat (2) +on the endpoint file. See also +.IR audio (3). +.sp +.SH FILES +.TF "#U/usb n /*/status" +.TP +.BI #U/usb n /*/status +USB device status file, class, subclass and proto are found in line one +.TP +.BI #U/usb n /*/ctl +USB +.I driver +control file, used to create driver endpoints, control debugging, etc. +.TP +.BI #U/usb n /*/setup +USB +.I device +control file, used to exchange messages with a device's control channel. +.B setup +may be viewed as a preconfigured +.B ep0data +file. +.TP +.BI #U/usb n /*/ep k data +USB device data channel for the +.IR k 'th +configuration. +.SH "SEE ALSO" +.IR usb (4), +.IR usbd (4), +.IR plan9.ini (8) +.SH BUGS +OpenHCI USB cards are not yet supported. +.PP +The interface for configuring endpoints is at variance with the standard. +.PP +The notion that the endpoints themselves have a class and subclass +is a distortion of the standard. +It would be better to leave all handling of the notions of class to the +user-level support programs, and remove it from the driver. diff --git a/static/plan9-4e/man3/vga.3 b/static/plan9-4e/man3/vga.3 new file mode 100644 index 00000000..a2fe3dee --- /dev/null +++ b/static/plan9-4e/man3/vga.3 @@ -0,0 +1,209 @@ +.TH VGA 3 +.SH NAME +vga \- VGA controller device +.SH SYNOPSIS +.nf +.B bind #v /dev + +.B /dev/vgactl +.fi +.SH DESCRIPTION +The VGA device allows configuration of a graphics controller +on a PC. +.B Vgactl +allows control over higher-level settings such as display height, width, depth, +controller and hardware-cursor type. +Along with the I/O-port registers +provided by +.IR arch (3), +it is used to implement configuration and setup of VGA controller cards. +This is usually performed by +.IR vga (8). +.PP +Writing strings to +.B vgactl +configures the VGA device. +The following are valid commands. +.TP +.BI size " X" x Y x "Z chan" +Set the size of the screen image to be +.I X +pixels wide +and +.I Y +pixels high. +Each pixel is +.I Z +bits as specified by +.IR chan , +whose format is described in +.IR image (6). +.TP +.BI actualsize " X" x Y +Set the physical size of the display to be +.I X +pixels wide by +.I Y +pixels high. +This message is optional; +it is used to implement panning and to accommodate +displays that require the in-memory screen image +to have certain alignment properties. +For example, a 1400x1050 screen with a 1408x1050 in-memory image +will use +.B "size 1408x1050 +but +.BR "actualsize 1400x1050" . +.TP +.BI panning " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable panning in a virtual screen. +If panning is on and the screen's +.B size +is larger than its +.BR actualsize , +the displayed portion of the screen will pan to follow the mouse. +Setting the panning mode after the first attach of the +.B #i +driver has no effect. +.TP +.BI type " ctlr" +Set the type of VGA controller being used. +.I Ctlr +is one of +.BR ark200pv , +.BR clgd542x , +.BR clgd546x , +.BR ct65545 , +.BR cyber938x , +.BR hiqvideo , +.BR mach64xx , +.BR mga2164w , +.BR neomagic , +.BR s3 , +and +.BR t2r4 . +.IP +Note that this list does not indicate the full set of VGA chips +supported. For example, +.B s3 +includes the 86C801/5, 86C928, Vision864, and Vision964. +It is the job of +.IR vga (8) +to recognize which particular chip is being used and to initialize it +appropriately. +.TP +.BI hwgc " gc" +Set the type of hardware graphics cursor being used. +.I Gc +is one of +.BR ark200pvhwgc , +.BR bt485hwgc , +.BR clgd542xhwgc , +.BR clgd546xhwgc , +.BR ct65545hwgc , +.BR cyber938xhwgc , +.BR hiqvideohwgc , +.BR mach64xxhwgc , +.BR mga2164whwgc , +.BR neomagichwgc , +.BR rgb524hwgc , +.BR s3hwgc , +.BR t2r4hwgc , +.BR tvp3020hwgc , +and +.BR tvp3026hwgc . +A value of +.B off +disables the cursor. +There is no software cursor. +.TP +.BI palettedepth " d" +Set the number of bits of precision used by the +VGA palette to +.IR d , +which must be either +.B 6 +or +.BR 8 . +.TP +.B blank +Blank the screen. +This consists of setting the hardware +color map to all black as well as, on some controllers, setting the +VGA hsync and vsync signals so as to turn off +VESA DPMS-compliant monitors. +The screen also blanks after 30 minutes of inactivity. +The screen can be unblanked by moving the mouse. +.TP +.BI blanktime " minutes" +Set the timeout before the +screen blanks; the default is 30 minutes. +If +.I minutes +is zero, blanking is disabled. +.TP +.BI hwaccel " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable whether hardware acceleration +(currently for rectangle filling and moving) +used by the graphics engine. +The default setting is +.BR on . +.TP +.BI hwblank " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable the use of DPMS blanking +(see +.B blank +above). +.TP +.BI linear " size align" +Use a linear screen aperture of size +.I size +aligned on an +.IR align -byte +boundary. +.TP +.B drawinit +Initialize the graphics hardware. +This must be sent after setting the +.BR type . +.PP +Reading +.B vgactl +returns the current settings, one per line. +.SH EXAMPLES +The following disables hardware acceleration. +.IP +.EX +echo -n 'hwaccel off' >/dev/vgactl +.EE +.SH SOURCE +.B /sys/src/9/pc/devvga.c +.SH SEE ALSO +.IR arch (3), +.IR vga (8) +.SH BUGS +There should be support for the hardware graphics cursor on the +.B clgd54[23]x +VGA controller chips. +.PP +The hardware graphics cursor on the +.B et4000 +does not work in 2x8-bit mode. diff --git a/static/plan9-4e/man4/0intro.4 b/static/plan9-4e/man4/0intro.4 new file mode 100644 index 00000000..8a3a6a3d --- /dev/null +++ b/static/plan9-4e/man4/0intro.4 @@ -0,0 +1,14 @@ +.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 than 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. +.SH SEE ALSO +.IR bind (1) diff --git a/static/plan9-4e/man4/INDEX.4 b/static/plan9-4e/man4/INDEX.4 new file mode 100644 index 00000000..8500fc3d --- /dev/null +++ b/static/plan9-4e/man4/INDEX.4 @@ -0,0 +1,71 @@ +0intro 0intro +intro 0intro +acme acme +archfs archfs +cddb cdfs +cdfs cdfs +cfs cfs +C consolefs +clog consolefs +consolefs consolefs +9660srv dossrv +9fat: dossrv +a: dossrv +b: dossrv +c: dossrv +d: dossrv +dosmnt dossrv +dossrv dossrv +eject dossrv +execnet execnet +exportfs exportfs +srvfs exportfs +factotum factotum +fgui factotum +secretpem factotum +fs fs +ftpfs ftpfs +import import +iostats iostats +keyfs keyfs +warning keyfs +kfs kfs +lnfs lnfs +namespace namespace +nntpfs nntpfs +paqfs paqfs +plumber plumber +ramfs ramfs +ratfs ratfs +rdbfs rdbfs +rio rio +sacfs sacfs +snap snap +snapfs snap +9fs srv +srv srv +srvold9p srv +32vfs tapefs +cpiofs tapefs +tapefs tapefs +tapfs tapefs +tarfs tapefs +tpfs tapefs +v10fs tapefs +v6fs tapefs +fax telco +faxreceive telco +faxsend telco +telco telco +telcodata telco +telcofax telco +u9fs u9fs +usb usb +usbaudio usb +usbmouse usb +usbd usbd +vacfs vacfs +webcookies webcookies +webfs webfs +wikifs wikifs +wikipost wikifs diff --git a/static/plan9-4e/man4/INDEX.html.4 b/static/plan9-4e/man4/INDEX.html.4 new file mode 100644 index 00000000..c191776a --- /dev/null +++ b/static/plan9-4e/man4/INDEX.html.4 @@ -0,0 +1,157 @@ + +plan 9 man section 4 + + +[manual index] +

Plan 9 from Bell Labs - Section 4 - File Servers

+
+
+
0intro +- introduction to file servers +
intro + +
acme +- control files for text windows +
acme + +
archfs +- mount mkfs-style archive +
archfs + +
cdfs +- CD reader and writer file system +
cdfs, cddb + +
cfs +- cache file system +
cfs + +
consolefs +- file system for console access +
consolefs, C, clog + +
dossrv +- DOS and ISO9660 file systems +
dossrv, 9660srv, a:, b:, c:, d:, 9fat:, dosmnt, eject + +
execnet +- network interface to program execution +
execnet + +
exportfs +- network file server plumbing +
exportfs, srvfs + +
factotum +- +
factotum, fgui, secretpem\- authentication agent and its graphics interface + +
fs +- file server, dump +
fs + +
ftpfs +- file transfer protocol (FTP) file system +
ftpfs + +
import +- import a name space from a remote system +
import + +
iostats +- file system to measure I/O +
iostats + +
keyfs +- authentication database files +
keyfs, warning + +
kfs +- disk file system +
kfs + +
lnfs +- long name file system +
lnfs + +
namespace +- structure of conventional file name space +
namespace + +
nntpfs +- network news transport protocol (NNTP) file system +
nntpfs + +
paqfs +- compressed read-only file system +
paqfs + +
plumber +- file system for interprocess messaging +
plumber + +
ramfs +- memory file system +
ramfs + +
ratfs +- mail address ratification file system +
ratfs + +
rdbfs +- remote kernel debugging file system +
rdbfs + +
rio +- window system files +
rio + +
sacfs +- compressed file system +
sacfs + +
snap +- create and mount process snapshots +
snap, snapfs + +
srv +- start network file service +
srv, srvold9p, 9fs + +
tapefs +- mount archival file systems +
32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs + +
telco +- telephone dialer network +
telco, faxreceive, faxsend, fax, telcofax, telcodata + +
u9fs +- serve 9P from Unix +
u9fs + +
usb +- Universal Serial Bus user level device drivers +
usbmouse, usbaudio + +
usbd +- Universal Serial Bus daemon +
usbd + +
vacfs +- a Venti-based file system +
vacfs + +
webcookies +- HTTP cookie manager +
webcookies + +
webfs +- world wide web file system +
webfs + +
wikifs +- wiki file system +
wikifs, wikipost + +
diff --git a/static/plan9-4e/man4/Makefile b/static/plan9-4e/man4/Makefile new file mode 100644 index 00000000..38781aad --- /dev/null +++ b/static/plan9-4e/man4/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.4) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man4/acme.4 b/static/plan9-4e/man4/acme.4 new file mode 100644 index 00000000..bb20cb0f --- /dev/null +++ b/static/plan9-4e/man4/acme.4 @@ -0,0 +1,408 @@ +.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 +.IR cons (3). +(Unlike in +.IR rio (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 /sys/src/cmd/acme +.SH SEE ALSO +.IR rio (1), +.IR acme (1), +.IR cons (3). diff --git a/static/plan9-4e/man4/archfs.4 b/static/plan9-4e/man4/archfs.4 new file mode 100644 index 00000000..0ba744c5 --- /dev/null +++ b/static/plan9-4e/man4/archfs.4 @@ -0,0 +1,46 @@ +.TH ARCHFS 4 +.SH NAME +archfs \- mount mkfs-style archive +.SH SYNOPSIS +.B archfs +[ +.B -abcC +] +[ +.B -m +.I mtpt +] +.I archfile +.SH DESCRIPTION +.I Archfs +mounts at +.I mtpt +(default +.BR /mnt/arch ) +a file system presenting the contents of an +archive in the format produced by +the +.B -a +flag to +.IR mkfs (8). +The +.BR -a , +.BR -b , +.BR -c , +and +.B -C +flags control the flag argument +to the +.B mount +system call +(see +.IR bind (2)) +as in the +.B mount +command +(see +.IR bind (1)). +.SH SOURCE +.B /sys/src/cmd/archfs.c +.SH SEE ALSO +.IR mkfs (8) diff --git a/static/plan9-4e/man4/cdfs.4 b/static/plan9-4e/man4/cdfs.4 new file mode 100644 index 00000000..ad8548a2 --- /dev/null +++ b/static/plan9-4e/man4/cdfs.4 @@ -0,0 +1,172 @@ +.TH CDFS 4 +.SH NAME +cdfs, cddb \- CD reader and writer file system +.SH SYNOPSIS +.B cdfs +[ +.B -d +.I sddev +] +[ +.B -m +.I mtpt +] +.br +.B "grep aux/cddb /mnt/cd/ctl | rc +.SH DESCRIPTION +.I Cdfs +serves a one and a half level directory +mounted at +.I mtpt +(default +.BR /mnt/cd ) +that provides access to the tracks +on CDs placed in the CD reader or writer +named by +.I sddev +(default +.BR /dev/sdD0 , +see +.IR sd (3)). +.PP +The top level directory contains one file +per CD track. +The files are named +.IR cNNN , +where +.I c +is a type character +.RB ( a +for audio tracks +and +.B d +for data tracks) +and +.I NNN +is the track number. +.PP +If the device is capable of writing CDs +and contains a writable CD, the top level +directory also contains two empty +directories +.B wa +and +.BR wd . +Files created in these directories +appear in the top level directory +as new audio or data tracks, regardless of name. +.PP +At any time, any number of tracks +may be open for reading or a single track +may be open for writing. +Writing a CD track is a real-time operation: +the CD writer must be kept saturated with +new data to avoid buffer underruns. +To ensure this, copying from a file system +stored on local disk is recommended. +.PP +To fixate a CD (close a writable CD by writing +its permanent table of contents), simply +remove the +.B wa +or +.B wd +directory. +The directory removed selects whether +the CD is fixated as an audio or data CD; +since each track carries its own type information, +very few readers care which fixation type was used. +.PP +The top level directory +also contains a +.B ctl +file, into which control messages +may be echoed. +The current control messages are: +.TF "\fLquickblank " +.TP +.B blank +Blank the entire rewritable CD in the drive. +.TP +.B quickblank +Blank only the table of contents on the rewritable +CD in the drive. +.TP +.B eject +Eject the CD in the drive. +.TP +.B ingest +Ingest a CD into the drive. +.TP +.B speed \fIkpbs\fR +Set the reading and writing speed to use. +Drives may round down the speed to one they support. +To set reading and writing speeds separately, +prefix the speeds with +.B read +or +.BR write , +as in +.B speed +.B write +.B 8192 +or +.B speed +.B read +.B 16384 +.B write +.BR 8192. +Note that most drives reset the reading and writing speed +each time a new CD is inserted. +.PD +.PP +Reading the +.B ctl +file yields information about the drive. +If the drive contains an audio CD, the first line +will be an +.B aux/cddb +command that can be run to query +an internet CD database +to get a table of contents. +Subsequent lines contain the current and maximum +reading and writing speeds. +.PD +.PP +Only MMC-compliant CD readers and writers +are supported, but it would be easy to add +support for early CD writers if desired. +.SH EXAMPLE +Copy the audio tracks from a CD: +.IP +.EX +cdfs -d /dev/sd05 +mkdir /tmp/songs +cp /mnt/cd/a* /tmp/songs +.EE +.PP +Copy the tracks onto a blank CD inserted in the drive, +and then fixate the disk as an audio CD. +.IP +.EX +cp /tmp/songs/* /mnt/cd/wa +rm /mnt/cd/wa +.EE +.PP +Cut your own 9660 CD-ROM, without +spooling the CD image to a temporary file. +.IP +.EX +disk/mk9660 -9cj -n notice cdproto >/mnt/cd/wd/foo +rm /mnt/cd/wd +.EE +.SH SOURCE +.B /sys/src/cmd/cdfs +.SH SEE ALSO +.IR sd (3), +.I 9660srv +(in +.IR dossrv (4)), +.IR mk9660 (8) +.SH BUGS +There should be support for DVDs. diff --git a/static/plan9-4e/man4/cfs.4 b/static/plan9-4e/man4/cfs.4 new file mode 100644 index 00000000..e7f6d378 --- /dev/null +++ b/static/plan9-4e/man4/cfs.4 @@ -0,0 +1,95 @@ +.TH CFS 4 +.SH NAME +cfs \- cache file system +.SH SYNOPSIS +.B cfs +.B -s +.RB [ -rdS ] +.RB [ -f +.IR partition ] +.PP +.B cfs +.B -a +.I netaddr +.RB [ -rdS ] +.RB [ -f +.IR partition ] +.RI [ mtpt ] +.SH DESCRIPTION +.I Cfs +is a user-level file server that caches information about remote +files onto a local disk. +It is normally started by the kernel at boot time, though users may start +it manually. +.I Cfs +is interposed between the kernel and a network connection to a +remote file server to improve the +efficiency of access across slow network connections such as modem +lines. +On each open of a file +.I cfs +checks the consistency of cached information and discards any old +information for that file. +.PP +.I Cfs +mounts onto +.I mtpt +(default +.BR / ) +after connecting to the file server. +.PP +The options are: +.TP +.B s +the connection to the remote file server is on file +descriptors 0 and 1. +.TP +.BI "a " netaddr +dial the destination +.I netaddr +to connect to a remote file server. +.TP +.B r +reformat the cache disk partition. +.TP +.B d +turn on debugging. +.TP +.B S +turn on statistics gathering. A file called +.B cfsctl +at the root of the caching file system can be read to get +statistics concerning number of calls/bytes on client and server +sides and latencies. +.TP +.BI "f " partition +use file +.I partition +as the cache disk partition. +.PP +All 9P messages except +.BR read , +.BR clone , +and +.B walk +(see +.IR intro (5)) +are passed through +.I cfs +unchanged to the remote server. +A +.B clone +followed immediately by a +.B walk +is converted into a +.BR clwalk . +If possible, a +.B read +is satisfied by cached data. +Otherwise, the file server is queried for any missing data. +.SH FILES +.TP +.B /dev/sdC0/cache +Default file used for storing cached data. +.SH SOURCE +.B /sys/src/cmd/cfs diff --git a/static/plan9-4e/man4/consolefs.4 b/static/plan9-4e/man4/consolefs.4 new file mode 100644 index 00000000..ea246bca --- /dev/null +++ b/static/plan9-4e/man4/consolefs.4 @@ -0,0 +1,216 @@ +.TH CONSOLEFS 4 +.SH NAME +consolefs, C, clog \- file system for console access +.SH SYNOPSIS +.B aux/consolefs +[ +.B -m +.I mntpt +] [ +.B -c +.I consoledb +] +.PP +.B C +.I system +.PP +.B aux/clog +console log +.I system +.SH DESCRIPTION +To ease administration of multiple machines one might attach +many serial console lines to a single computer. +.I Consolefs +is a file system that lets multiple users simultaneously access +these console lines. +The consoles and permissions to access them are defined in the +file +.I consoledb +(default +.BR /lib/ndb/consoledb ). +The format of +.I consoledb +is the same as that of other +.B /lib/ndb +files, +.IR ndb (6). +Consoles are defined by entries of the form: +.PP +.EX + console=dirty dev=/dev/eia205 + uid=bignose + gid=support + speed=56200 + cronly= +.EE +.PP +Each +.IR console / dev +pair represents the name of a console and the serial line device +associated with it. +.I Consolefs +presents a single level directory with two files +per console: +.I console +and +.IB console ctl\f1. +Writes of +.I console +are equivalent to writes of +.I dev +and reads and writes of +.IB console ctl +are equivalent to reads and writes of +.IB dev ctl\f1. +.I Consolefs +broadcasts anything it reads from +.I dev +to all readers of +.IR console . +Therefore, many users can +.IR con (1) +to a +.IR console , +see all output, and enter commands. +.PP +The +.I cronly= +attribute causes newlines typed by the user to be sent to +the console as returns. +The +.I speed=x +attribute/value pair specifies a bit rate for the +console. The default is 9600 baud. +.PP +Access to the console is controlled by the +.I uid +and +.I gid +attributes/value pairs. +The uid values are user account names. +The gid values are the names of groups defined in +.I consolefs +by entries of the form: +.PP +.EX + group=support + uid=bob + uid=carol + uid=ted + uid=alice +.EE +.PP +Groups are used to avoid excessive typing. Using +.I gid=x +is equivalent to including a +.I uid=y +for each user +.I y +that is a member of +.IR x . +.PP +To keep users from inadvertently interfering with one another, +notification is broadcast to all readers whenever a user +opens or closes +.IR name . +For example, if user +.B boris +opens a console that users +.B vlad +and +.B barney +have already opened, all will read the message: +.PP +.EX + [+boris, vlad, barney] +.EE +.PP +If +.B vlad +then closes, +.B boris +and +.B barney +will read: +.PP +.EX + [-vlad, boris, barney] +.EE +.PP +.I Consolefs +posts the client end of its 9P channel in +.BR /srv/consolefs +and mounts this locally in +.I mntpt +(default +.BR /mnt/consoles ); +remote clients must +.B mount +(see +.IR bind (1)) +this file to see the consoles. +.PP +The +.IR rc (1) +script +.B C +automates this procedure. +It uses +.IR import (4) +to connect to +.B /mnt/consoles +on the machine connected to all the consoles, then uses +.IR con (1) +to connect to the console of the machine +.IR system. +The script must be edited at installation +by the local administration to identify the +system that holds +.BR /mnt/consoles . +.PP +.I Aux/clog +opens the file +.I console +and writes every line read from it, prefixed +by the ASCII time to the file +.IR log . +.PP +An example of 2 consoles complete with console logging is: +.IP +.EX +% aux/consolefs +% ls -p /mnt/consoles +bootes +bootesctl +fornax +fornaxctl +% clog /mnt/consoles/fornax /sys/log/fornax & +% clog /mnt/consoles/bootes /sys/log/bootes & +.EE +.SH FILES +.TF /lib/ndb/consoledb +.TP +.B /srv/consoles +Client end of pipe to server. +.TP +.B /mnt/consoles +Default mount point. +.TP +.B /lib/ndb/consoledb +Default user database. +.SH SOURCE +.B /sys/src/cmd/aux/consolefs.c +.br +.B /rc/bin/C +.br +.B /sys/src/cmd/aux/clog.c +.SH BUGS +.PP +Changing the gid's or uid's while +.I consoelfs +is running +is detected by +.IR consolefs . +However, to add new consoles +one must restart +.IR consolefs . diff --git a/static/plan9-4e/man4/dossrv.4 b/static/plan9-4e/man4/dossrv.4 new file mode 100644 index 00000000..40749a08 --- /dev/null +++ b/static/plan9-4e/man4/dossrv.4 @@ -0,0 +1,217 @@ +.TH DOSSRV 4 +.SH NAME +dossrv, 9660srv, a:, b:, c:, d:, 9fat:, dosmnt, eject \- DOS and ISO9660 file systems +.SH SYNOPSIS +.B dossrv +[ +.B -v +] [ +.B -r +] [ +.B -s +] [ +.B -f +.I file +] [ +.I service +] +.PP +.B 9660srv +[ +.B -9J +] [ +.B -v +] [ +.B -s +] [ +.B -f +.I file +] [ +.I service +] +.PP +.B a: +.PP +.B b: +.PP +.B c: +.PP +.B 9fat: +.PP +.B dosmnt +.I n +.I mtpt +.PP +.B eject +[ +.I n +] +.SH DESCRIPTION +.I Dossrv +is a file server that interprets DOS file systems. +A single instance of +.I dossrv +can provide access to multiple DOS disks simultaneously. +.PP +.I Dossrv +posts a file descriptor named +.I service +(default +.BR dos ) +in the +.B /srv +directory. +To access the DOS file system on a device, use +.B mount +with the +.I spec +argument +(see +.IR bind (1)) +the name of the file holding raw DOS file system, typically the disk. +If +.I spec +is undefined in the +.BR mount , +.I dossrv +will use +.I file +as the default name for the device holding the DOS system. +.PP +Normally +.I dossrv +creates a pipe to act as the communications channel between +itself and its clients. +The +.B -s +flag instructs +.I dossrv +to use its standard input and output instead. +The kernels use this option if they are booting from a DOS disk. +This flag also prevents the creation of an explicit service file in +.BR /srv . +.PP +The +.B -v +flag causes verbose output for debugging, while +the +.B -r +flag makes the file system read-only. +.PP +The shell script +.I a: +contains +.IP +.EX +unmount /n/a: >[2] /dev/null +mount -c /srv/dos /n/a: /dev/fd0disk +.EE +.LP +and is therefore a shorthand for mounting a floppy disk in drive A. +The scripts +.I b: +and +.I dosmnt +are similar, +mounting the second floppy disk +and the +.IR n th +non-floppy DOS partition, +respectively. +.I C: +and +.I d: +call +.I dosmnt +in an attempt to name the drives in +the same order that Microsoft operating systems do. +.I 9fat: +provides access to the FAT component of the Plan 9 partition (see +.IR prep (8)). +.PP +The file attribute flags used by the DOS file system +do not map directly to those used by Plan 9. +Since there is no concept of user or group, +permission changes via +.B wstat +(see +.IR stat (2)) +will fail unless the same (read, write, execute) permissions +are specified for user, group, and other. +For example, removing write permission in Plan 9 +corresponds to setting the read-only +attribute in the DOS file system. +Most of the other DOS attributes +are not accessible. +.PP +Setting the exclusive use flag (DMEXCL) +in Plan 9 corresponds to setting the +system use attribute in the DOS file system. +Such files are not actually restricted to exclusive use, +but do merit special treatment that +helps in the creation of boot disks: +when +.I dossrv +allocates a new block for such a file +(caused, say, by a write that fills the file's +last allocated block), it succeeds only if it can +arrange for the file to be stored +contiguously on disk. +.PP +Since other operating systems do not +guarantee that system files are laid +out contiguously, the DMAPPEND mode +bit is set in file stat information +only when the file is currently contiguous. +Attempts to set the DMAPPEND mode bit +explicitly will cause +.I dossrv +to try to make the file contiguous, +succeeding only if this is possible. +.PP +.I 9660srv +is similar to +.I dossrv +in specification, except that it interprets ISO9660 CD-ROM +file systems instead of DOS file systems. +Some CDs contain multiple directory trees describing +the same set of files. +.IR 9660srv 's +first choice in such a case is a standard ISO9660 tree +with Plan 9 system use fields; +the second choice is a Microsoft ``Joliet'' tree, which +allows long file names and Unicode characters; +the third choice is a standard ISO9660 or High Sierra tree. +The +.B -9 +flag causes +.I 9660srv +to ignore the Plan 9 system use fields, +while the +.B -J +flag causes it to +ignore the Joliet tree. +.PP +If the floppy drive has an ejection motor, +.I eject +will spit out the floppy from drive +.IR n , +default 0. +.SH EXAMPLE +Mount a floppy disk with a DOS file system on it. +.IP +.EX +a: +.EE +.SH "SEE ALSO" +.IR kfs (4) +.SH SOURCE +.B /sys/src/cmd/dossrv +.br +.B /sys/src/cmd/9660srv +.br +.B /rc/bin/eject +.SH BUGS +The overloading of the semantics of +the DMEXCL and DMAPPEND +bits can be confusing. diff --git a/static/plan9-4e/man4/execnet.4 b/static/plan9-4e/man4/execnet.4 new file mode 100644 index 00000000..9375a14b --- /dev/null +++ b/static/plan9-4e/man4/execnet.4 @@ -0,0 +1,67 @@ +.TH EXECNET 4 +.SH NAME +execnet \- network interface to program execution +.SH SYNOPSIS +.B execnet +[ +.B -n +.I name +] +[ +.B netdir +] +.SH DESCRIPTION +.I Execnet +presents a network protocol directory +(see, for example, +.IR ip (3)) +called +.IB netdir / name +(default +.BR /net/exec ). +.PP +Once the protocol directory exists, dialing +(see +.IR dial (2)) +strings of +the form +.IB name ! cmd +will connect to a newly executed instance of +.IR cmd . +.SH EXAMPLE +.I Execnet +can be used to connect to instances of +.IR u9fs (4) +running on other hosts: +.EX + g% execnet + g% srv -m 'exec!ssh ny start-u9fs' ny /n/ny +.EE +This example assumes that the remote command +.B start-u9fs +executed on +.B ny +will start +.I u9fs +appropriately. +For example, it might be: +.EX + ny% cat start-u9fs + #!/bin/sh + + u9fs -na none -u $USER -l $HOME/tmp/u9fs.log + ny% +.EE +See the +.IR u9fs (4) +man page for more information. +.SH SOURCE +.B /sys/src/cmd/execnet +.SH "SEE ALSO +.IR dial (2), +.IR ip (3), +.IR u9fs (4) +.SH BUGS +Almost certainly: +.IR execnet +has only been tested as in the example shown. diff --git a/static/plan9-4e/man4/exportfs.4 b/static/plan9-4e/man4/exportfs.4 new file mode 100644 index 00000000..9f867d85 --- /dev/null +++ b/static/plan9-4e/man4/exportfs.4 @@ -0,0 +1,205 @@ +.TH EXPORTFS 4 +.SH NAME +exportfs, srvfs \- network file server plumbing +.SH SYNOPSIS +.B exportfs +[ +.B -ads +] [ +.B -f +.I dbgfile +] [ +.B -m +.I msize +] [ +.B -r +.I root +] [ +.B -S +.I service +] [ +.B -A announce +] +.PP +.B srvfs +[ +.B -d +] +[ +.B -e +.I "'enc auth'" +] +[ +.B -p +.I filter +] +.I name +.I path +.SH DESCRIPTION +.I Exportfs +is a user level file server that allows Plan 9 compute servers, rather +than file servers, to export portions of a name space across networks. +The service is started either by the +.IR cpu (1) +command or by a network listener process. An initial protocol +establishes a root directory for the exported name space. +The +connection to +.I exportfs +is then mounted, typically on +.BR /mnt/term . +.I Exportfs +then acts as a relay file server: operations in the imported file +tree are executed on the remote server and the results returned. This +gives the appearance of exporting a name space from a remote machine +into a local file tree. +.PP +The +.B -r +option bypasses the initial protocol, instead immediately +serving the name space rooted at +.IR root . +The +.B -s +option is equivalent to +.B -r +.BR / , +but predates +.B -r +and remains for compatibility. +.PP +The +.B -S +option also bypasses the initial protocol but +serves the result of mounting +.IR service . +A separate mount is used for each +.IR attach (5) +message, +to correctly handle servers in which each mount +corresponds to a different client +.IR e.g. , ( +.IR rio (4)). +.PP +The +.B -m +option sets the maximum message size that +exportfs should offer to send (see +.IR version (5)); +this helps tunneled +9P connections to avoid unnecessary fragmentation. +.PP +The +.B -a +option instructs +.I exportfs +to authenticate the user, usually because it is +being invoked from a remote machine. +.PP +The +.B -d +option instructs +.I exportfs +to log all 9P traffic to +.I dbgfile +(default +.BR /tmp/exportdb ). +.PP +The +.B -e +option specifies the encryption and authentication algorithms to use for +encrypting the wire traffic. The defaults are +.B rc4_256 +and +.BR sha1 . +The full list of supported protocols in in +.IR ssl (3). +.PP +The +.B cpu +command uses +.I exportfs +to serve device files in the terminal. The +.IR import (4) +command calls +.I exportfs +on a remote machine, permitting users to access arbitrary pieces of +name space on other systems. +Because the kernel disallows reads and writes on mounted pipes +(as might be found in +.BR /srv ), +.I exportfs +calls itself (with appropriate +.B -m +and +.B -S +options) to simulate reads and writes on such files. +.PP +.I Srvfs +invokes +.I exportprog +(default +.BR /bin/exportfs ) +to create a mountable file system from a name space +and posts it at +.BI /srv/ name , +which is created with mode +.I perm +(default 0600). +By default, the name space is the directory tree rooted at +.IR path . +If the +.B -S +option is given, the name space is obtained by +mounting +.B path +(typically a file in +.BR /srv ). +If the +.B -d +option is given, +.I srvfs +passes it to +.I exportprog +to enable debugging. +.PP +The +.B -A +filter specifies an announce string when exportfs is used in combination +with aan. The announce string identifies the network and network +protocol to use for aan connections. +.SH EXAMPLES +Use +.I srvfs +to enable mounting of an FTP file system (see +.IR ftpfs (4)) +in several windows, +or to publish a +.B /proc +(see +.IR proc (3)) +with a broken process so a remote person may debug the program: +.IP +.EX +srvfs ftp /n/ftp +srvfs broke /mnt/term/proc +.EE +.LP +Use +.I srvfs +to obtain a copy of a service to be manipulated directly +by a user program like +.IR nfsserver (8): +.IP +.EX +srvfs nfs.boot /srv/boot +aux/nfsserver -f /srv/nfs.boot +.EE +.SH SOURCE +.B /sys/src/cmd/exportfs +.br +.B /sys/src/cmd/srvfs.c +.SH SEE ALSO +.IR aan (1), +.IR import (4), +.IR exportfs (4) diff --git a/static/plan9-4e/man4/factotum.4 b/static/plan9-4e/man4/factotum.4 new file mode 100644 index 00000000..38d8dfc4 --- /dev/null +++ b/static/plan9-4e/man4/factotum.4 @@ -0,0 +1,679 @@ +.TH FACTOTUM 4 +.SH NAME +factotum, fgui, secretpem\- authentication agent and its graphics interface +.SH SYNOPSIS +.B auth/factotum +[ +.B -DdkSun +] [ +.B -a asaddr +] [ +.B -s +.I srvname +] [ +.B -m +.I mtpt +] +.PP +.B auth/factotum +.B -g +.IB attribute = value +.B ... +.IB attribute ? +.B ... +.PP +.B auth/fgui +.PP +.B auth/secretpem +.I key.pem +.SH DESCRIPTION +.I Factotum +is a user-level file system that +acts as the authentication agent for a user. +It does so by managing a set of +.IR keys . +A key is a collection of information used to authenticate a particular action. +Stored as a list of +.IB attribute = value +pairs, a key typically contains a user, an authentication domain, a protocol, and +some secret data. +.PP +.I Factotum +presents a two level directory. The first +level contains a single directory +.BR factotum , +which in turn contains: +.TF needkey +.TP +.B rpc +each open represents a new private channel to +.I factotum +.TP +.B proto +when read lists the protocols available +.TP +.B confirm +for confiming the use of key +.TP +.B needkey +allows external programs to control the addition of new keys +.TP +.B log +a log of actions +.TP +.B ctl +for maintaining keys; when read, it returns a list of keys (without the secret data) +.PD +.PP +In any authentication, the caller typically acts as a client +and the callee as a server. The server determines +the authentication domain, sometimes after a negotiation with +the client. Authentication always requires the client to +prove its identity to the server. Under some protocols, the +authentication is mutual. +Proof is accomplished using secret information kept by factotum +in conjunction with a cryptographic protocol. +.PP +.I Factotum +can act in the role of client for any process possessing the +same user id as it. For select protocols such as +.B p9sk1 +it can also act as a client for other processes provided +its user id may speak for the other process' user id (see +.IR authsrv (6)). +.I Factotum +can act in the role of server for any process. +.PP +.IR Factotum 's +structure is independent of +any particular authentication protocol. +.I Factotum +supports the following protocols: +.TF sshrsa +.TP +.B p9any +a metaprotocol used to negotiate which actual protocol to use. +.TP +.B p9sk1 +a Plan 9 shared key protocol described in +.IR authsrv (6)'s +``File Service'' section. +.TP +.B p9sk2 +a variant of +.B p9sk1 +described in +.IR authsrv (6)'s +``Remote Execution'' section. +.TP +.B p9cr +a Plan 9 protocol that can use either +.B p9sk1 +keys or SecureID tokens. +.TP +.B apop +the challenge/response protocol used by POP3 mail servers. +.TP +.B cram +the challenge/response protocol also used by POP3 mail servers. +.TP +.B chap +the challenge/response protocols used by PPP and PPTP. +.TP +.B mschap +a proprietary Microsoft protocol also used by PPP and PPTP. +.TP +.B sshrsa +an public key protocol used by ssh. +.TP +.B pass +passwords in the clear. +.TP +.B vnc +.IR vnc (1)'s +challenge/response. +.PD +.PP +The options are: +.TP +.B \-a +supplies the address of the authentication server to use. +Without this option, it will attempt to find an authentication server by +querying the connection server, the file +.BR /ndb , +and finally the network database in +.BR /lib/ndb . +.TP +.B \-m +specifies the mount point to use, by default +.BR /mnt . +.TP +.B \-s +specifies the service name to use. +Without this option, +.I factotum +does not create a service file in +.BR /srv . +.TP +.B \-D +turns on 9P tracing, written to standard error. +.TP +.B \-d +turns on debugging, written to standard error. +.TP +.B \-g +causes the agent to prompt for the key, write it +to the +.B ctl +file, and exit. +The agent will prompt for values for any of the +attributes ending with a question mark +.RB ( ? ) +and will append all the supplied +.I attribute = value +pairs. See the section on key templates below. +.TP +.B \-n +don't look for a secstore. +.TP +.B \-S +indicates that the agent is running on a +cpu server. On starting, it will attempt to get a +.B 9psk1 +key from NVRAM using +.B readnvram +(see +.IR authsrv (2)), +prompting for anything it needs. +It will never subsequently prompt for a +key that it doesn't have. +This option is typically used by +the kernel at boot time. +.TP +.B \-k +causes the NVRAM to be written. +It is only valid with the +.B \-S +option. +This option is typically used by +the kernel at boot time. +.TP +.B \-u +causes the agent to prompt for user +id and writes it to +.BR /dev/hostowner . +It is mutually exclusive with +.B \-k +and +.BR \-S . +This option is typically used by +the kernel at boot time. +.PD +.PP +.I Fgui +is a graphic user interface for confirming key usage and +entering new keys. It hides the window in which it starts +and waits reading requests from +.B confirm +and +.BR needkey . +For each requests, it unhides itself and waits for +user input. +See the sections on key confirmation and key prompting below. +.SS "Key Tuples +.PP +A +.I "key tuple +is a space delimited list of +.IB attribute = value +pairs. An attribute whose name begins with an exclamation point +.RB ( ! ) +does not appear when reading the +.B ctl +file. +The required attributes depend on the authentication protocol. +.PP +.BR P9sk1 , +.BR p9sk2 , +and +.BR p9cr +all require a key with +.BR proto = p9sk1 , +a +.B dom +attribute identifying the authentication domain, a +.B user +name valid in that domain, and either a +.B !password +or +.B !hex +attribute specifying the password or hexadecimal secret +to be used. Here is an example: +.PP +.EX + proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent +.EE +.PP +.BR Apop , +.BR cram , +.BR chap , +.BR mschap , +and +.B vnc +require a key with a +.B proto +attribute whose value matches the protocol, +in addition to +.BR dom , +.BR user , +and +.B !password +attributes; +e.g. +.PP +.EX + proto=apop dom=mit.edu user=rsc !password=nerdsRus +.EE +.PP +.B Pass +requires a key with +.B proto=pass +in addition to +.B user +and +.B !password +attributes; e.g. +.PP +.EX + proto=pass user=tb !password=does.it.matter +.EE +.PP +.B Sshrsa +requires a key with +.B proto=sshrsa +in addition to all the hex attributes defining an RSA key: +.BR ek , +.BR n , +.BR !p , +.BR !q , +.BR !kp , +.BR !kq , +.BR !c2 , +and +.BR !dk . +.PP +All keys can have additional attibutes that act either as comments +or as selectors to distinguish them in the +.IR auth (2) +library calls. +.PP +Any key may have a +.B role +attribute for restricting how it can be used. +If this attribute is missing, the key can be used in any role. +The possible values are: +.TP +.B client +for authenticating outbound calls +.TP +.B server +for authenticating inbound calls +.TP +.B speaksfor +for authenticating processes whose +user id does not match +.IR factotum 's. +.PD +.PP +Whenever +.I factotum +runs as a server, it must have a +.B p9sk1 +key in order to communicate with the authentication +server for validating passwords and challenge/responses of +other users. +.SS "Key Templates +Key templates are used by routines that interface to +.I factotum +such as +.B auth_proxy +and +.B auth_challenge +(see +.IR auth (2)) +to specify which key and protocol to use for an authentication. +Like a key tuple, a key template is also a list of +.IB attribute = value +pairs. +It must specify at least the protocol and enough +other attributes to uniquely identify a key, or set of keys, to use. +The keys chosen are those that match all the attributes specified +in the template. The possible attribute/value formats are: +.TP 1i +.IB attr = val +The attribute +.I attr +must exist in the key and its value must exactly +match +.I val +.TP 1i +.IB attr ? +The attribute +.I attr +must exist in the key but its value doesn't matter. +.TP 1i +.I attr +The attribute +.I attr +must exist in the key with a null value +.PD +.PP +Key templates are also used by factotum to request a key either via +an RPC error or via the +.B needkey +interface. +The possible attribute/value formats are: +.TP 1i +.IB attr = val +This pair must remain unchanged +.TP 1i +.IB attr ? +This attribute needs a value +.TP 1i +.I attr +The pair must remain unchanged +.PD +.SS "Control and Key Management +.PP +A number of messages can be written to the control file. +The mesages are: +.TP +.B "key \fIattribute-value-list\fP +add a new key. This will replace any old key whose +public, i.e. non ! attributes, match. +.TP +.B "delkey \fIattribute-value-list\fP +delete a key whose attributes match those given. +.TP +.B debug +toggle debugging on and off, i.e., the debugging also +turned on by the +.B \-d +option. +.PP +By default when factotum starts it looks for a +.IR secstore (1) +account on $auth for the user and, if one exists, +prompts for a secstore password in order to fetch +the file +.IR factotum , +which should contain control file commands. +An example would be +.EX + key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229 + key proto=sshrsa size=1024 ek=3B !dk=... +.EE +where the first line sets a password for +challenge / response authentication, strong against dictionary +attack by being a long random string, and the second line +sets a public / private keypair for ssh authentication, +generated by +.B ssh_genkey +(see +.IR ssh (1)). +.PD +.SS "Confirming key use +.PP +The +.B confirm +file provides a connection from +.I factotum +to a confirmation server, normally the program +.IR auth/fgui . +Whenever a key with the +.B confirm +attribute is used, +.I factotum +requires confirmation of its use. If no process has +.B confirm +opened, use of the key will be denied. +However, if the file is opened a request can be read from it +with the following format: +.PP +.B confirm +.BI tag= tagno +.I " +.PP +The reply, written back to +.BR confirm , +consists of string: +.PP +.BI tag= tagno +.BI answer= xxx +.PP +If +.I xxx +is the string +.B yes +then the use is confirmed and the authentication will proceed. +Otherwise, it fails. +.PP +.B Confirm +is exclusive open and can only be opened by a process with +the same user id as +.IR factotum . +.SS "Prompting for keys +.PP +The +.B needkey +file provides a connection from +.I factotum +to a key server, normally the program +.IR auth/fgui . +Whenever +.I factotum +needs a new key, it first checks to see if +.B needkey +is opened. If it isn't, it returns a error to its client. +If the file is opened a request can be read from it +with the following format: +.PP +.B needkey +.BI tag= tagno +.I " +.PP +It is up to the reader to then query the user for any missing fields, +write the key tuple into the +.B ctl +file, and then reply by writing into the +.B needkey +file the string: +.PP +.BI tag= tagno +.PP +.B Needkey +is exclusive open and can only be opened by a process with +the same user id as +.IR factotum . +.SS "The RPC Protocol +Authentication is performed by +.IP 1) +opening +.BR rpc +.IP 2) +setting up the protocol and key to be used (see the +.B start +RPC below), +.IP 3) +shuttling messages back and forth between +.IR factotum +and the other party (see the +.B read +and +.B write +RPC's) until done +.IP 4) +if successful, reading back an +.I AuthInfo +structure (see +.IR authsrv (2)). +.PP +The RPC protocol is normally embodied by one of the +routines in +.IR auth (2). +We describe it here should anyone want to extend +the library. +.PP +An RPC consists of writing a request message to +.B rpc +followed by reading a reply message back. +RPC's are strictly ordered; requests and replies of +different RPC's cannot be interleaved. +Messages consist of of a verb, a singe space, and data. +The data format depends on the verb. The request verbs are: +.TP +.B "start \fIattribute-value-list\fP +start a new authentication. +.I Attribute-value-pair-list +must include a +.B proto +attribute, a +.B role +attribute with value +.B client +or +.BR server , +and enough other attibutes to uniquely identify a key to use. +A +.B start +RPC is required before any others. The possible replies are: +.RS +.TP +.B ok +start succeeded. +.TP +.B "error \fIstring\fP +where +.I string +is the reason. +.RE +.PD +.TP +.B read +get data from +.I factotum +to send to the other party. The possible replies are: +.RS +.TP +.B ok +read succeeded, this is zero length message. +.TP +.B "ok \fIdata\fP +read succeeded, the data follows the space and is +unformatted. +.TP +.B "done +authentication has succeeded, no further RPC's are +necessary +.TP +.B "done haveai +authentication has succeeded, an +.B AuthInfo +structure (see +.IR auth (2)) +can be retrieved with an +.B authinfo +RPC +.TP +.B "phase \fIstring\fP +its not your turn to read, get some data from +the other party and return it with a write RPC. +.TP +.B "error \fIstring\fP +authentication failed, +.I string +is the reason. +.TP +.B "protocol not started +a +.B start +RPC needs to be preceed reads and writes +.TP +.B "needkey \fIattribute-value-list\fP +a key matching the argument is needed. This argument +may be passed as an argument to +.I factotum +.B -g +in order to prompt for a key. After that, the +authentication may proceed, i.e., the read restarted. +.PD +.RE +.TP +.B "write \fIdata\fP +send data from the other party to +.IR factotum . +The possible replies are: +.RS +.TP +.B "ok +the write succeeded +.TP +.B "needkey \fIattribute-value-list\fP +see above +.TP +.B "toosmall \fIn\fP +the write is too short, get more data from the +other party and retry the write. +.I n +specifies the maximun total number of bytes. +.TP +.B "phase \fIstring\fP +its not your turn to write, get some data from +.I factotum +first. +.TP +.B "done +see above +.TP +.B "done haveai +see above +.RE +.TP +.B authinfo +retrieve the AuthInfo structure. +The possible replies are: +.RS +.TP +.B "ok \fIdata\fP +.I data +is a marshaled form of the AuthInfo structure. +.TP +.B "error \fIstring\fP +where +.I string +is the reason for the error. +.PD +.RE +.TP +.B attr +retrieve the attributes used in the +.B start +RPC. +The possible replies are: +.RS +.TP +.B "ok \fIattribute-value-list\fP +.TP +.B "error \fIstring\fP +where +.I string +is the reason for the error. +.PD +.RE +.PP +.I Secretpem +copies a PEM-format RSA private key onto standard output in sshrsa key syntax, +suitable for sending to +.IR /mnt/factotum/ctl . +.SH SOURCE +.B /sys/src/cmd/auth/factotum/ diff --git a/static/plan9-4e/man4/fs.4 b/static/plan9-4e/man4/fs.4 new file mode 100644 index 00000000..20a60653 --- /dev/null +++ b/static/plan9-4e/man4/fs.4 @@ -0,0 +1,148 @@ +.TH FS 4 +.SH NAME +fs \- file server, dump +.SH SYNOPSIS +.I none +.SH DESCRIPTION +The file server is the main file system for +Plan 9. +It is a stand-alone system that runs on +a separate computer. +It serves the Plan 9 protocol via the IL/IP +protocols on Ethernets. +The name of the main file server at Murray Hill is +.BR emelie . +.PP +The file server normally requires all users except +.L none +to provide authentication tickets on each +.IR attach (5). +This can be disabled using the +.B noauth +configuration command (see +.IR fsconfig (8)). +.PP +The group numbered 9999, normally called +.BR noworld , +is special +on the file server. Any user belonging to that group has +attenuated access privileges. Specifically, when checking such +a user's access to files, the file's permission bits are first ANDed +with 0770 for normal files or 0771 for directories. The effect is +to deny world access permissions to +.B noworld +users, except +when walking directories. +.PP +The user +.B none +is always allowed to attach to +.B emelie +without authentication but has minimal permissions. +.PP +.B Emelie +maintains three file systems +on a combination of disks and +write-once-read-many (WORM) magneto-optical disks. +.TP +.B other +is a simple disk-based file system similar to +.IR kfs (4) . +.TP +.B main +is a worm-based file system with a disk-based +look-aside cache. +The disk cache holds +modified worm blocks +to overcome the write-once property of the worm. +The cache also holds recently accessed +non-modified blocks to +speed up the effective access time of the worm. +Occasionally +(usually daily at 5AM) the modified blocks in the +disk cache are +.IR dumped . +At this time, +traffic to the file system is halted and the +modified blocks are relabeled to the unwritten +portion of the worm. +After the dump, +the file system traffic is continued and +the relabeled blocks are copied to the worm by +a background process. +.TP +.B dump +Each time the main file system is dumped, +its root is appended to a subdirectory of the dump file system. +Since the dump file system is not mirrored with a disk +cache, +it is read-only. +The name of the newly added root is created from the date +of the dump: +.BI / yyyy / mmdds\f1. +Here +.I yyyy +is the full year, +.I mm +is the month number, +.I dd +is the day number and +.I s +is a sequence number if more than +one dump is done in a day. +For the first dump, +.I s +is null. +For the subsequent dumps +.I s +is 1, 2, 3, etc. +.sp +The root of the main file system +that is frozen on the first dump +of March 1, 1992 +will be named +.B /1992/0301/ +in the dump file system. +.SH EXAMPLES +Place the root of the +.B dump +file system on +.B /n/dump +and show the modified times of the MIPS C compiler +over all dumps in February, 1992: +.IP +.EX +9fs dump +ls -l /n/dump/1992/02??/mips/bin/vc +.EE +.PP +To get only one line of output for each version of the compiler: +.IP +.EX +ls -lp /n/dump/1992/02??/mips/bin/vc | uniq +.EE +.PP +Make the +.B other +file system available in directory +.BR /n/emelieother : +.IP +.EX +mount -c /srv/boot /n/emelieother other +.EE +.SH SOURCE +.B /sys/src/fs +.SH SEE ALSO +.IR yesterday (1), +.IR srv (4), +.IR fs (8) +.br +Sean Quinlan, +``A Cached WORM File System'', +.I +Software \- Practice and Experience, +December, 1991 +.SH BUGS +For the moment, the file server serves both the old (third edition) and new (fourth +edition) versions of 9P, deciding which to serve by sniffing the first packet on each +connection. diff --git a/static/plan9-4e/man4/ftpfs.4 b/static/plan9-4e/man4/ftpfs.4 new file mode 100644 index 00000000..5486746f --- /dev/null +++ b/static/plan9-4e/man4/ftpfs.4 @@ -0,0 +1,173 @@ +.TH FTPFS 4 +.SH NAME +ftpfs \- file transfer protocol (FTP) file system +.SH SYNOPSIS +.B ftpfs +[ +.B -/dqn +] +[ +.B -m +.I mountpoint +] +[ +.B -a +.I password +] +[ +.B -e +.I ext +] +[ +.B -o +.I os +] +[ +.B -r +remoteroot +] +.I system +.SH DESCRIPTION +.I Ftpfs +dials the TCP file transfer protocol (FTP) port, 21, on +.I system +and mounts itself (see +.IR bind (2)) +on +.I mountpoint +(default +.BR /n/ftp ) +to provide access to files on the remote machine. +If required by the remote machine, +.I ftpfs +will prompt for a user name and password. +The user names +.B ftp +and +.B anonymous +conventionally offer guest/read-only access to +machines. +Anonymous FTP may be called without user interaction +by using the +.B -a +option and specifying the +.IR password . +.PP +By default the file seen at the mount point is the user's +remote home directory if he has one. +The option +.B -/ +forces the mount point to correspond to the +remote root. +The option +.B -r +forces the mount point to correspond to the +remote directory +.IR remoteroot . +.PP +To avoid seeing startup messages from the server use option +.BR -q . +To see all messages from the server use option +.BR -d . +.PP +Some systems will hangup an ftp connection that has no activity +for a given period. The +.BR -k +option causes ftp to send a NOP command every 15 seconds to attempt +to keep the connection open. This command can cause some servers to +hangup, so you'll have to feel your way. +.PP +To terminate the connection, +.B unmount +(see +.IR bind (1)) +the mount point. +.PP +Since there is no specified format for metadata retrieved +in response to an FTP directory request, +.I ftpfs +has to apply heuristics to steer the interpretation. Sometimes, +though rarely, these heuristics fail. The following options are +meant as last resorts to try to steer interpretation. +.PP +A major clue to the heuristics is the operating system at the other +end. Normally this can be determined automatically using the +FTP SYST command. However, in some cases the server doesn't implement +the SYST command. The +.B -o +option will force the case by specifying the name of the operating +system. Known system types are are: +.BR Unix , +.BR Sun , +.BR Tops , +.BR Plan9 +.BR VM , +.BR VMS , +.BR MVS , +.BR NetWare , +.BR OS/2 , +.BR TSO , +and +.BR WINDOWS_NT . +.PP +Some systems and/or FTP servers return directory listings that don't +include the file extension. The +.B -e +option allows the user to specify an extension to append to all +remote files (other than directories). +.PP +Finally, there are two FTP commands to retrieve the contents of a +directory, LIST and NLST. LIST is approximately equivalent to +.L ls -l +and NLST to +.LR ls . +.I Ftpfs +normally uses LIST. However, some FTP servers interpret LIST +to mean, give a wordy description of the file. +.I Ftpfs +normally notices this and switches to using NLST. However, in +some rare cases, the user must force the use of NLST with the +.B -n +option. +.SH EXAMPLE +You want anonymous FTP access to the system +.BR export.lcs.mit.edu . +The first +.IR import (4) +command is only necessary if your machine does not have access to the +desired system, but another, called +.B gateway +in this example, does. +.IP +.EX +import gateway /net +ftpfs -a yourname@yourmachine export.lcs.mit.edu +.EE +.SH SOURCE +.B /sys/src/cmd/ip/ftpfs +.SH "SEE ALSO" +.IR bind (2) +.SH BUGS +.PP +Symbolic links on remote Unix systems will always have mode 0777 +and a length of 8. +.PP +After connecting to a TOPS-20 system, the mount point will contain +only one directory, usually +.BR /n/ftp/PS: . +However, walking to any valid directory on that machine will succeed +and cause that directory entry to appear under the mount point. +.PP +.I Ftpfs +caches files and directories. A directory will fall from the cache +after 5 quiescent minutes or if the local user changes the +directory by writing or removing a file. +Otherwise, remote +changes to the directory that occur after the directory has +been cached might not be immediately visible. +.PP +There is no way to issue the appropriate commands to handle special synthetic +FTP file types such as directories +that automatically return a +.B tar +of their contents. diff --git a/static/plan9-4e/man4/import.4 b/static/plan9-4e/man4/import.4 new file mode 100644 index 00000000..c3c3b49c --- /dev/null +++ b/static/plan9-4e/man4/import.4 @@ -0,0 +1,121 @@ +.TH IMPORT 4 +.SH NAME +import \- import a name space from a remote system +.SH SYNOPSIS +.B import +[ +.B -abcC +] [ +.B "-E clear | ssl" +.\" .B "| tls" .\" Not yet implemented +] [ +.B "-e 'enc auth'" +] [ +.B -p +] [ +.B "-s \f2srvname\fP +] +.I system +.I file +[ +.I mountpoint +] +.SH DESCRIPTION +.I Import +allows an arbitrary +.I file +on a remote +.I system +to be imported into the local name space. +Usually +.I file +is a directory, so the complete +file tree under the directory is made available. +.PP +A process is started on the +remote machine, with authority of the user of +.IR import , +to perform work for the local machine using the +.IR exportfs (4) +service. +If +.I mountpoint +is omitted +.I import +uses the name of the remote +.I file +as the local mount point. +.PP +If +.I file +is a directory, +.I import +allows options exactly as in +.I mount +and +.IR bind (1) +to control the construction of union directories. +.PP +The +.B -E +option causes +.I import +to push an authentication protocol on its network connection. +Currently, the protocols supported are +.B clear +(the default) which pushes no protocol, +and +.BR ssl . +There are plans to make +.B tls +available too. +.PP +The +.B -e +option specifies the encryption and authentication algorithms to use for +encrypting the wire traffic. The defaults are +.B rc4_256 +and +.BR sha1 . +The full list of supported protocols in in +.IR ssl (3). +.PP +The +.B -p +option pushes the +.B aan +filter onto the connection. This filter will protect the connection from +temporary network outages; see +.IR aan (1). +.PP +The +.B -s +option posts the connection's mountable file descriptor in +.B /srv +under the given name. +.SH EXAMPLE +Assume a machine +.B kremvax +that has IP interfaces for the company intranet and the global +internet mounted on +.I /net +and +.I /net.alt +respectively. +Any machine inside the company can get telnet out to the global +internet using: +.IP +.EX +import -a kremvax /net.alt +telnet /net.alt/tcp!ucbvax +.EE +.SH SOURCE +.B /sys/src/cmd/import.c +.SH SEE ALSO +.IR bind (1), +.IR aan (1), +.IR exportfs (4), +.IR ssl (3), +.B cs +in +.IR ndb (8) diff --git a/static/plan9-4e/man4/iostats.4 b/static/plan9-4e/man4/iostats.4 new file mode 100644 index 00000000..15371444 --- /dev/null +++ b/static/plan9-4e/man4/iostats.4 @@ -0,0 +1,64 @@ +.TH IOSTATS 4 +.SH NAME +iostats \- file system to measure I/O +.SH SYNOPSIS +.B iostats +[ +.B -d +] +[ +.B -f +.I dbfile +] +.I cmd +[ +.I args... +] +.SH DESCRIPTION +.I Iostats +is a user-level file server that interposes itself between a program +and the regular file server, which +allows it to gather statistics of file system +use at the level of the Plan 9 file system protocol, 9P. +After a program +exits a report is printed on standard error. +.PP +The report consists of three sections. +The first section reports the amount +of user data in +.B read +and +.B write +messages sent by the program and the average rate at +which the data was transferred. +The +.B protocol +line reports the amount +of data sent as message headers, that is, +protocol overhead. +The +.B rpc +line reports the +total number of file system transactions. +.PP +The second section gives +the number of messages, the fastest, slowest, and average turn around +time and the amount of data involved with each 9P +message type. +The final section gives an I/O summary for each file used +by the program in terms of opens, reads and writes. +.PP +If the +.B -d +flag is present, a debugging log including all traffic +is written to +.I dbfile +(default +.BR iostats.out ). +.SH SOURCE +.B /sys/src/cmd/iostats +.SH BUGS +Poor clock resolution means that large amounts of I/O must be done to +get accurate rate figures. +.PP +Can be fooled by programs that do fresh mounts outside its purview. diff --git a/static/plan9-4e/man4/keyfs.4 b/static/plan9-4e/man4/keyfs.4 new file mode 100644 index 00000000..b88b0330 --- /dev/null +++ b/static/plan9-4e/man4/keyfs.4 @@ -0,0 +1,248 @@ +.TH KEYFS 4 +.SH NAME +keyfs, warning \- authentication database files +.SH SYNOPSIS +.B auth/keyfs +[ +.B -p +] +[ +.B -w +.RB [ np ] +] +[ +.BI -m mntpt +] +[ +.I keyfile +] +.PP +.B auth/warning +[ +.B -n +] +[ +.B -p +] +.SH DESCRIPTION +.I Keyfs +serves a two-level file tree for manipulating authentication information. +It runs on the machine providing authentication service for the local +Plan 9 network, which may be a dedicated authentication server or +a CPU server. +The programs described in +.IR auth (8) +use +.I keyfs +as their interface to the authentication database. +.PP +.I Keyfs +reads and decrypts file +.I keyfile +(default +.BR /adm/keys ) +using the DES key, +which is by default read from +.B #r/nvram +(see +.IR rtc (3)). +With option +.BR -p , +.I keyfs +prompts for a password from which the key is derived. +.I Keyfile +holds a 41-byte record for each user in the database. +Each record is encrypted separately +and contains the user's name, +DES key, +status, +host status, +and expiration date. +The name is a +null-terminated +.SM UTF +string +.B NAMELEN +bytes long. +The status is a byte containing +binary 0 if the account is enabled, +1 if it is disabled. +Host status is a byte containing +binary 1 if the user is a host, +0 otherwise. +The expiration date is four-byte little-endian integer +which represents the time in seconds since the epoch +(see +.IR date (1)) +at which the account will expire. +If any changes are made to the database that affect the information stored in +.IR keyfile , +a new version of the file is written. +.PP +There are two authentication databases, +one for Plan 9 user information, +and one for SecureNet user information. +A user need not be installed in both databases +but must be installed in the Plan 9 database to connect to a Plan 9 server. +.PP +.I Keyfs +serves an interpretation of the +.I keyfile +in the file tree rooted at +.I mntpt +(default +.BR /mnt/keys ). +Each user +.I user +in +.I keyfile +is represented as the directory +.IR mntpt / user . +.PP +Making a new directory in +.I mntpt +creates a new user entry in the database. +Removing a directory removes the user entry, +and renaming it changes the name in the entry. +Such changes are reflected immediately in +.IR keyfile . +.I Keyfs +does not allow duplicate names when creating or renaming user entries. +.PP +All files in the user directories except for +.B key +contain +.SM UTF +strings with a trailing newline when read, +and should be written as +.SM UTF +strings with or without a trailing newline. +.B Key +contains the +.BR DESKEYLEN -byte +encryption key for the user. +.PP +The following files appear in the user directories. +.TF expire +.TP +.B key +The authentication key for the user. +If the user's account is disabled or expired, +reading this file returns an error. +Writing +.I key +changes the key in the database. +.TP +.B log +The number of consecutive failed authentication attempts for the user. +Writing the string +.B bad +increments this number; writing +.B good +resets it to 0. +If the number reaches fifty, +.I keyfs +disables the account. +Once the account is disabled, +the only way to enable it is to write the string +.B ok +to +.BR status . +This number is not stored in +.IR keyfile , +and is initialized to 0 when +.I keyfs +starts. +.TP +.B status +The current status of the account, either +.B ok +or +.BR disabled . +Writing +.B ok +enables the account; +writing +.B disabled +disables it. +.TP +.B expire +The expiration time for the account. +When read, it contains either the string +.B never +or the time in seconds since the epoch +that the account will expire. +When written with strings of the same form, +it sets the expiration date for the user. +If the expiration date is reached, +the account is not disabled, +but +.I key +cannot be read without an error. +.PD +.PP +If the +.B -w +option is on, +.I keyfs +runs the command +.I warning +once every 24 hours to mail people about expiring keys. +Warnings are sent 14 days and 7 days prior to expiration. +The argument to +.BR -w , +either +.B p +or +.BR n , +is passed to +.I warning +to restrict the warnings to +the Plan 9 or SecureNet database. +The default for +.I keyfs +is not to call +.I warning +at all; +.I warning's +own default is to warn about both. +The files +.B /adm/netkeys.who +and +.B /adm/keys.who +are used to find the mail addresses to send to. +The first word on each line identifies +a user. +Any subsequent strings on the line delimited '<' and '>' are considered mail +addresses to send warnings to. +If multiple lines match a user, the last in the file is used. +.B Changeuser +(see +.IR auth (8)) +adds lines to these files. +.SH FILES +.TF /adm/netkeys.who +.TP +.B /adm/keys +Encrypted key file for the Plan 9 database. +.TP +.B /adm/netkeys +Encrypted key file for the SecureNet database. +.TP +.B /adm/keys.who +List of users in the Plan 9 database. +.TP +.B /adm/netkeys.who +List of users in the SecureNet database. +.TP +.B #r/nvram +The non-volatile RAM on the server, which holds the key used +to decrypt key files. +.SH SOURCE +.B /sys/src/cmd/auth/keyfs.c +.br +.B /sys/src/cmd/auth/warning.c +.SH "SEE ALSO" +.IR authsrv (6), +.IR namespace (6), +.IR auth (8) diff --git a/static/plan9-4e/man4/kfs.4 b/static/plan9-4e/man4/kfs.4 new file mode 100644 index 00000000..9ea00b5f --- /dev/null +++ b/static/plan9-4e/man4/kfs.4 @@ -0,0 +1,132 @@ +.TH KFS 4 +.SH NAME +kfs \- disk file system +.SH SYNOPSIS +.B disk/kfs +[ +.B -rc +] [ +.B -b +.I n +] [ +.B -f +.I file +] [ +.B -n +.I name +] [ +.B -p +.I perm +] [ +.B -s +] [ +.B -B +.I nbuf +] +.SH DESCRIPTION +.I Kfs +is a local user-level file server for a Plan 9 terminal with a disk. +It maintains a hierarchical Plan 9 file system on the disk +and offers +9P (see +.IR intro (5)) +access to it. +.I Kfs +begins by +checking the file system for consistency, +rebuilding the free list, and placing a file descriptor in +.BI /srv/ name\f1, +where +.I name +is the service name (default +.BR kfs ). +If the file system is inconsistent, +the user is asked for permission to ream +.RI ( q.v. ) +the disk. +The file system is not checked if it is reamed. +.PP +The options are +.TF "n name" +.TP +.BI "b " n +If the file system is reamed, use +.I n +byte blocks. +Larger blocks make the file system faster +and less space efficient. +.B 1024 +and +.B 4096 +are good choices. +.I N +must be a multiple of 512. +.TP +.B c +Do not check the file system. +.TP +.BI "f " file +Use +.I file +as the disk. +The default is +.BR /dev/sdC0/fs . +.TP +.BI "n " name +Use +.RI kfs. name +as the name of the service. +.TP +.BI "p " perm +Use +.I perm +as the initial permissions for the +command channel +.BI /srv/ service .cmd\fR; +the default is 660. +.TP +.B r +Ream the file system, erasing all of the old data +and adding all blocks to the free list. +.TP +.B s +Post file descriptor zero in +.BI /srv/ service +and read and write protocol messages on file descriptor one. +.TP +.B B +Allocate +.I nbuf +in-memory file system blocks. +The default is as many as will fit in 10% of memory +or two megabytes, whichever is smaller. +.PD +.SH EXAMPLES +Create a file system with service name +.I kfs.local +and mount it on +.BR /n/kfs . +.IP +.EX +% kfs -rb4096 -nlocal +% mount -c /srv/kfs.local /n/kfs +.EE +.PP +.SH FILES +.TF /dev/sdC0/fs +.TP +.B /dev/sdC0/fs +Default file holding blocks. +.SH SOURCE +.B /sys/src/cmd/disk/kfs +.SH "SEE ALSO" +.IR kfscmd (8), +.IR mkfs (8), +.IR prep (8), +.IR sd (3) +.SH BUGS +For the moment, +.I kfs +serves both the old (third edition) and new (fourth +edition) versions of 9P, deciding which to serve by sniffing the first packet on each +connection. diff --git a/static/plan9-4e/man4/lnfs.4 b/static/plan9-4e/man4/lnfs.4 new file mode 100644 index 00000000..528001ed --- /dev/null +++ b/static/plan9-4e/man4/lnfs.4 @@ -0,0 +1,55 @@ +.TH LNFS 4 +.SH NAME +lnfs \- long name file system +.SH SYNOPSIS +.B lnfs +[ +.B -r +] +[ +.B -s +.I srvname +] +.I mountpoint +.SH DESCRIPTION +.I Lnfs +starts a process that mounts itself (see +.IR bind (2)) +on +.IR mountpoint . +It presents a filtered view of the files under the mount +point, allowing users to use long file names +on file servers that do not support file names +longer than 27 bytes. +.PP +The names used in the underlying file system are +the base32 encoding of the md5 hash of the longer +file name. The user need not know the mapping +since +.I lnfs +does all the work. +.I Lnfs +maintains a file +.B .longnames +in the directory +.I mountpoint +to record the long file names. +.PP +The options are: +.TP +.B -r +allow only read access to the file system +.TP +.B -s +provide a service name, +.IR srvname , +to post in +.BR /srv . +Without this option, no posting is performed. +.SH FILES +.B .longnames +.SH SOURCE +.B /sys/src/cmd/lnfs.c +.SH BUGS +This exists only to shame us into getting a real long +name file server working. diff --git a/static/plan9-4e/man4/namespace.4 b/static/plan9-4e/man4/namespace.4 new file mode 100644 index 00000000..68963d35 --- /dev/null +++ b/static/plan9-4e/man4/namespace.4 @@ -0,0 +1,384 @@ +.TH NAMESPACE 4 +.SH NAME +namespace \- structure of conventional file name space +.SH SYNOPSIS +none +.SH DESCRIPTION +After a user's profile has run, the file name space should adhere +to a number of conventions if the system is to behave normally. +This manual page documents those conventions by traversing the +file hierarchy and describing the points of interest. +It also serves as a guide to where things reside in the file system proper. +The traversal is far from exhaustive. +.PP +First, here is the appearance of the file server as it appears before +any mounts or bindings. +.TF /sys/src/cmd +.TP +.B / +The root directory. +.TP +.B /adm +The administration directory for the file server. +.TP +.B /adm/users +List of users known to the file server; see +.IR users (6). +.TP +.B /adm/keys +Authentication keys for users. +.TP +.B /adm/netkeys +SecureNet keys for users; see +.IR securenet (8). +.TP +.B /adm/timezone +Directory of timezone files; see +.IR ctime (2). +.TP +.B /adm/timezone/EST.EDT +Time zone description for Eastern Time. Other such files are in this directory too. +.TP +.B /adm/timezone/timezone +Time zone description for the local time zone; a copy of one of the other files in this directory. +.TP +.B /bin +.TP +.B /dev +.TP +.B /env +.TP +.B /fd +.TP +.B /net +.TP +.B /proc +.TP +.B /srv +.TP +.B /tmp +All empty unwritable directories, place holders for mounted services and directories. +.TP +.B /mnt +A directory containing mount points for applications. +.B /mnt/factotum +Mount point for +.IR factotum (4). +.TP +.B /n +A directory containing mount points for file trees imported from +remote systems. +.TP +.B /29000 +.TP +.B /386 +.TP +.B /68000 +.TP +.B /68020 +.TP +.B /960 +.TP +.B /alpha +.TP +.B /arm +.TP +.B /mips +.TP +.B /sparc +Each CPU architecture supported by Plan 9 has a directory in the root containing +architecture-specific files, to be selected according to +.B $objtype +or +.B $cputype +(see +.IR 2c (1) +and +.IR init (8)). +Here we list only those for +.BR /386 . +.TP +.B /386/init +The initialization program used during bootstrapping; see +.IR init (8). +.TP +.B /386/bin +Directory containing binaries for the Intel x86 architecture. +.TP +.B "/386/bin/aux +.TP +.B /386/bin/ip +.TP +etc. +Subdirectories of +.B /386/bin +containing auxiliary tools and collecting related programs. +.TP +.B /386/lib +Directory of object code libraries as used by +.B 8l +(see +.IR 2l (1)). +.TP +.B /386/include +Directory of x86-specific C include files. +.TP +.B /386/9* +The files in +.B /386 +beginning with a +.B 9 +are binaries of the operating system. +.TP +.B /386/mkfile +Selected by +.IR mk (1) +when +.B $objtype +is +.BR 386 , +this file configures +.B mk +to compile for the Intel x86 architecture. +.TP +.B /rc +Isomorphic to the architecture-dependent directories, this holds executables +and libraries for the shell, +.IR rc (1). +.TP +.B /rc/bin +Directory of shell executable files. +.TP +.B /rc/lib +Directory of shell libraries. +.TP +.B /rc/lib/rcmain +Startup code for +.IR rc (1). +.TP +.B /lib +Collections of data, generally not parts of programs. +.TP +.B /lib/mammals +.TP +.B /lib/sky +.TP +etc. +Databases. +.TP +.B /lib/ndb +The network database used by the networking software; see +.IR ndb (6) +and +.IR ndb (8). +.TP +.B /lib/namespace +The file used by +.B newns +(see +.IR auth (2)) +to establish the default name space; see +.IR namespace (6). +.TP +.B /lib/font/bit +Bitmap font files. +.TP +.B /lib/font/hershey +Vector font files. +.TP +.B /sys +System software. +.TP +.B /sys/include +Directory of machine-independent C include files. +.TP +.B /sys/lib +Pieces of programs not easily held in the various +.BR bins . +.TP +.B /sys/lib/acid +Directory of +.IR acid (1) +load modules. +.TP +.B /sys/lib/dist +Software used to assemble the distribution's installation floppy. +.TP +.B /sys/lib/troff +Directory of +.IR troff (1) +font tables and macros. +.TP +.B /sys/lib/yaccpar +The +.IR yacc (1) +parser. +.TP +.B /sys/man +The manual. +.TP +.B /sys/doc +Other system documentation. +.TP +.B /sys/log +Log files created by various system services. +.TP +.B /sys/src +Top-level directory of system sources. +.TP +.B /sys/src/cmd +Source to the commands in the +.B bin +directories. +.TP +.B /sys/src/9 +Source to the operating system for terminals and CPU servers. +.TP +.B /sys/src/fs +Source to the operating system for file servers. +.TP +.B /sys/src/lib* +Source to the libraries. +.TP +.B /mail +Directory of electronic mail; see +.IR mail (1). +.TP +.B /mail/box +Directory of users' mail box files. +.TP +.B /mail/lib +Directory of alias files, etc. +.TP +.B /acme +Directory of tools for +.IR acme (1). +.TP +.B /cron +Directory of files for +.IR cron (8). +.PD +.PP +The following files and directories are modified in the standard +name space, as defined by +.B /lib/namespace +(see +.IR namespace (6)). +.TF /sys/src/cmd +.TP +.B / +The root of the name space. It is a kernel device, +.IR root (3), +serving a number of local mount points such as +.B /bin +and +.B /dev +as well as the bootstrap program +.BR /boot . +Unioned with +.B / +is the root of the main file server. +.TP +.B /boot +Compiled into the operating system kernel, this file establishes +the connection to the main file server and starts +.BR init ; +see +.IR boot (8) +and +.IR init (8). +.TP +.B /bin +Mounted here is a union directory composed of +.BR /$objtype/bin , +.BR /rc/bin , +.BR $home/$objtype/bin , +etc., so +.B /bin +is always the directory containing the appropriate executables +for the current architecture. +.TP +.B /dev +Mounted here is a union directory containing I/O devices such as the +console +.RI ( cons (3)), +the interface to the raster display +.RI ( draw (3)), +etc. +The window system, +.IR rio (1), +prefixes +this directory with its own version, +overriding many device +files with its own, multiplexed simulations of them. +.TP +.B /env +Mounted here is the environment device, +.IR env (3), +which holds environment variables such as +.BR $cputype . +.TP +.B /net +Mounted here is a union directory formed of all the network devices +available. +.TP +.B /net/cs +The communications point for the connection server, +.B ndb/cs +(see +.IR ndb (8)). +.TP +.B /net/dns +The communications point for the Domain Name Server, +.B ndb/dns +(see +.IR ndb (8)). +.TP +.B /net/il +.TP +.B /net/tcp +.TP +.B /net/udp +Directories holding the IP protocol devices +(see +.IR ip (3)). +.TP +.B /proc +Mounted here is the process device, +.IR proc (3), +which provides debugging access to active processes. +.TP +.B /fd +Mounted here is the dup device, +.IR dup (3), +which holds pseudonyms for open file descriptors. +.TP +.B /srv +Mounted here is the service registry, +.IR srv (3), +which holds connections to file servers. +.TP +.B /srv/boot +The communication channel to the main file server for the machine. +.TP +.B /mnt/wsys +Mount point for the window system. +.TP +.B /mnt/term +Mount point for the terminal's name space as seen by the CPU server +after a +.IR cpu (1) +command. +.TP +.B /n/kremvax +A place where machine +.BR kremvax 's +name space may be mounted. +.TP +.B /tmp +Mounted here is each user's private +.B tmp, +.BR $home/tmp . +.SH SEE ALSO +.IR intro (1), +.IR namespace (6) diff --git a/static/plan9-4e/man4/nntpfs.4 b/static/plan9-4e/man4/nntpfs.4 new file mode 100644 index 00000000..d752f8bf --- /dev/null +++ b/static/plan9-4e/man4/nntpfs.4 @@ -0,0 +1,107 @@ +.TH NNTPFS 4 +.SH NAME +nntpfs \- network news transport protocol (NNTP) file system +.SH SYNOPSIS +.B nntpfs +[ +.B -s +.I service +] +[ +.B -m +.I mountpoint +] +.I system +.SH DESCRIPTION +.I Nntpfs +dials the TCP network news transport protocol (NNTP) +port, 119, on +.I system +(default +.BR '$nntp' ) +and presents at +.I mountpoint +(default +.BR /mnt/news ) +a file system corresponding to the +news articles stored on +.IR system . +.PP +The file system contains a directory per newsgroup, +with dots turned into slashes, e.g., +.B comp/os/plan9 +for +.BR comp.os.plan9 . +Each newsgroup directory contains one +numbered directory per article. +The directories follow the numbering used by +the server. +Each article directory contains three files: +.BR article , +.BR header , +and +.BR body . +The +.B article +file contains the full text of the article, +while +.B header +and +.B body +contain only the header or body. +.PP +Each newsgroup directory contains a +write-only +.B post +file that may be used to post news articles. +RFC1036-compliant articles should be written to it. +The +.B post +file will only exist in a given newsgroup directory +if articles are allowed to be posted to it. +Other than that, the +.B post +file is +.I not +tied to its directory's newsgroup. +The groups to which articles are eventually posted +are determined by the +.B newsgroups: +header lines in the posted article, +not by the location of the +.B post +file in the file system. +.PP +The qid version of a newsgroup directory +is the largest numbered article directory it +contains (~0, if there are no articles). +.PP +The modification time on a newsgroup +directory is the last time a new article was recorded +during this +.I nntpfs +session. +To force a check for new articles, +.IR stat (2) +the newsgroup directory. +.PP +To force a check for new newsgroups, +.IR stat (2) +the root directory. +Note that this causes the entire list of groups, +which can be about a megabyte, +to be transferred. +.PP +To terminate the connection, +.B unmount +the mount point. +.PP +.I Nntpfs +makes no effort to send ``keepalives'' so that +servers do not hang up on it. +Instead, it redials as necessary when hangups are detected. +.SH SOURCE +.B /sys/src/cmd/nntpfs.c +.SH BUGS +Directories are presented for deleted articles; +the files in them cannot be opened. diff --git a/static/plan9-4e/man4/paqfs.4 b/static/plan9-4e/man4/paqfs.4 new file mode 100644 index 00000000..0a200694 --- /dev/null +++ b/static/plan9-4e/man4/paqfs.4 @@ -0,0 +1,76 @@ +.TH PAQFS 4 +.SH NAME +paqfs \- compressed read-only file system +.SH SYNOPSIS +.B paqfs +[ +.B -disv +] +[ +.B -c +.I cachesize +] +[ +.B -m +.I mtpt +] +[ +.B -M +.I mesgsize +] +.I paqfile +.SH DESCRIPTION +.I Paqfs +interprets the compressed read-only file system created by +.IR mkpaqfs (8) +and stored in +.I paqfile +so that it can be mounted into a Plan 9 file system. +.I Paqfs +is typically used to create a stand alone file system for +a small persistent storage device, such as a flash ROM. +It does not authenticate its clients and assumes each group +has a single member with the same name. +.PP +Option to +.I paqfs +are: +.TP +.BI -c " cachesize +The number of file system blocks to cache in memory. The default is 20 blocks. +.TP +.B -d +Output various debugging information to +.IR stderr . +.TP +.B -i +Use file descriptors 0 and 1 as the 9P communication channel rather than create a pipe. +.TP +.BI -m " mtpt +The location to mount the file system. The default is +.BR /n/paq . +.TP +.BI -M " mesgsize +The maximum 9P message size. The default is sufficient for 8K byte read message. +.TP +.B -s +Post the 9P channel on #s/paqfs rather than +mounting it on +.IR mtpt . +.TP +.B -v +Verify the integrity of the +.IR paqfile . +Before mounting the file system, the +entire file is parsed and the +.I sha1 +checksum of the file system data is compared to the checksum embedded in the file. +This option enables the use of +.I paqfs +with files that consist of a +.I paq +file system concatenated with additional data. +.SH SOURCE +.B /sys/src/cmd/paqfs/paqfs.c +.SH "SEE ALSO" +.IR mkpaqfs (8) diff --git a/static/plan9-4e/man4/plumber.4 b/static/plan9-4e/man4/plumber.4 new file mode 100644 index 00000000..fbaebe41 --- /dev/null +++ b/static/plan9-4e/man4/plumber.4 @@ -0,0 +1,126 @@ +.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 (6) +messages between programs. +Its behavior is programmed by a +.I plumbing +file (default +.BR /usr/$user/lib/plumbing ) +in the format of +.IR plumb (6). +.PP +Its services are mounted on the directory +.B /mnt/plumb +.RB ( /mnt/term/mnt/plumb +on the CPU server) and consist of two +pre-defined files, +.B send +and +.BR rules , +and a set of output +.I ports +for dispatching messages to applications. +The service is also published as a +.IR srv (4) +file, named in +.BR $plumbsrv , +for mounting elsewhere. +.PP +Programs use +.B write +(see +.IR read (2)) +to deliver messages to the +.B send +file, and +.IR read (2) +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 /mnt/plumb/send ; +.B sam +in turn reads from, by convention, +.B /mnt/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 /mnt/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 /sys/lib/plumb +directory to search for files in +.B include +statements +.TP +.B /mnt/plumb +mount point for +.IR plumber (4). +.SH SOURCE +.B /sys/src/cmd/plumb +.SH "SEE ALSO" +.IR plumb (1), +.IR plumb (2), +.IR plumb (6) +.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/static/plan9-4e/man4/ramfs.4 b/static/plan9-4e/man4/ramfs.4 new file mode 100644 index 00000000..af2dece0 --- /dev/null +++ b/static/plan9-4e/man4/ramfs.4 @@ -0,0 +1,74 @@ +.TH RAMFS 4 +.SH NAME +ramfs \- memory file system +.SH SYNOPSIS +.B ramfs +[ +.B -i +] +[ +.B -s +] +[ +.B -p +] +[ +.B -m +.I mountpoint +] +.SH DESCRIPTION +.I Ramfs +starts a process that mounts itself (see +.IR bind (2)) +on +.I mountpoint +(default +.BR /tmp ). +The +.I ramfs +process implements a file tree rooted at +.IR dir , +keeping all files in memory. +Initially the file tree is empty. +.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. +The +.B -s +flag causes +.I ramfs +to post its channel on +.B /srv/ramfs +rather than mounting it on +.IR mountpoint , +enabling multiple clients to access its files. +However, it does not authenticate its clients and its +implementation of groups is simplistic, so +it should not be used for precious data. +.PP +The +.B -p +flag causes +.I ramfs +to make its memory `private' +(see +.IR proc (3)) +so that its files are not accessible through the debugging interface. +.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 /sys/src/cmd/ramfs.c +.SH "SEE ALSO" +.IR bind (2) diff --git a/static/plan9-4e/man4/ratfs.4 b/static/plan9-4e/man4/ratfs.4 new file mode 100644 index 00000000..2d396f74 --- /dev/null +++ b/static/plan9-4e/man4/ratfs.4 @@ -0,0 +1,174 @@ +.TH RATFS 4 +.SH NAME +ratfs \- mail address ratification file system +.SH SYNOPSIS +.B ratfs +[ +.B -d +] [ +.B -c +.I configuration +] [ +.B -f +.I classification +] [ +.B -m +.I mountpoint +] +.SH DESCRIPTION +.I Ratfs +starts a process that mounts itself (see +.IR bind (2)) +on +.I mountpoint +(default +.BR /mail/ratify ). +.I Ratfs +is a persistent representation of the local network +configuration and spam blocking list. Without it +each instance of +.IR smtpd (6) +would need to reread and parse a multimegabyte list +of addresses and accounts. +.PP +.I Ratfs +serves a control file, +.BR ctl , +and several top level directories: +.BR trusted , +.BR deny , +.BR dial , +.BR block , +.BR delay , +and +.BR allow . +.PP +The control file is write only and accepts three +possible commands: +.TF "debug file +.TP +.B reload +rereads +.I classification +and +.I configuration +.TP +.B debug \fIfile\fP +creates +.I file +and sends debugging output to it. +.TP +.B nodebug +closes the debug file and turns off debugging +.PD +.PP +The directory +.B trusted +serves a file for each IP range from which all mail +is trusted. The names of the files are CIDR blocks; +an IP address or an IP address followed by +.BR #\fIn\fP , +where +.I n +is the number of bits to match. +To check if any IP address falls in a trusted +range, it is sufficient to open the file whose +name is the IP address. +For example, if +.B trusted +contains only the file +.BR 135.104.0.0#16 , +an attempt to open the file 135.104.9.1 will +succeed while opening 10.1.1.1 will fail. +To determine the particular range matched, +.B dirfstat +(see stat (2)) +the open file and the +.B name +field will be the matching CIDR range. +.PP +The trusted ranges come both from the +.B ournet +entries in the file +.I configuration +(default +.BR /mail/lib/blocked ) +and from creates, typically done by +.B imap4d +(see +.IR ipserv (8)) +and +.B pop3 +(see +.IR mail (1)) +whenever they are used to read someone's mail. +.PP +The remaining directories, +.BR allow , +.BR block , +.BR delay , +.BR deny , +and +.BR dial , +represent the contents of the +.I classification +(default +.BR /mail/lib/smtpd.conf ). +Each contains two directories; +.B ip +and +.BR account . +The +.B ip +directory has the same open semantics as the +.B trusted +directory, i.e., to check if an IP address falls +in that category, try to open a file whose +name is the IP address. +The +.B account +directory is similar but is used for matching +strings. Each file in the directory represents +a regular expression. To see if one of the +strings matches one of the regular expressions, +try to open the file whose name is the string. +If it succeeds, then there is a regular expression +that matches. To determine the regular expression, +.B fstat +the open file. The +.B name +field will be the regular expression. +.PP +There is a direct mapping from entries in +.I classification +and files under +.BR allow , +.BR block , +.BR delay , +.BR deny , +and +.BR dial. +A configuration file entry of the form: +.EX + dial 135.104.9.0/24 +.EE +corresponds to the file +.BR dial/ip/135.104.9.0#24 . +An entry of the form +.EX + *block .*!gre +.EE +corresponds to the file +.BR block/account/.*!gre . +.PP +Both the configuration file and control file formats +are described in +.IR smtpd (6). +.SH SOURCE +.B /sys/src/cmd/ratfs +.SH "SEE ALSO" +.IR mail (1) +.IR smtpd (6) +.IR scanmail (8) + + diff --git a/static/plan9-4e/man4/rdbfs.4 b/static/plan9-4e/man4/rdbfs.4 new file mode 100644 index 00000000..383dd26c --- /dev/null +++ b/static/plan9-4e/man4/rdbfs.4 @@ -0,0 +1,67 @@ +.TH RDBFS 4 +.SH NAME +rdbfs \- remote kernel debugging file system +.SH SYNOPSIS +.B rdbfs +[ +.B -d +] +[ +.B -p +.I pid +] +[ +.B -t +.I text +] +[ +.I device +] +.SH DESCRIPTION +.I Rdbfs +presents in +.BI /proc/ pid +(default +.BR /proc/1 ) +a set of process files for debugging +a kernel over the serial line +.I device +(default +.BR /dev/eia0 ). +.PP +The +.B text +file presented is just a copy of +.I text +(default +.BR /386/9pc ). +It can usually be ignored, since +the debuggers open kernel +files directly rather than +using +.BI /proc/ n /text\fR. +.PP +Kernels can be remotely debugged only when they are +suspended and serving +a textual debugging protocol over their serial lines. +Typing +.RB `` ^t^td '' +.RB (control- t ", control-" t ", d)" +at the console will cause the kernel to enter +this mode when it `panics'. +Typing +.RB `` ^t^tD '' +causes the kernel to enter this mode immediately. +.PP +Because the debugging protocol is textual, a console +provided by +.IR consolefs (4) +may be substituted for the serial device. +.SH SOURCE +.B /sys/src/cmd/rdbfs.c +.br +.B /sys/src/9/port/rdb.c +.SH "SEE ALSO" +.IR acid (1), +.IR db (1), +.IR consolefs (4) diff --git a/static/plan9-4e/man4/rio.4 b/static/plan9-4e/man4/rio.4 new file mode 100644 index 00000000..90e3cbe3 --- /dev/null +++ b/static/plan9-4e/man4/rio.4 @@ -0,0 +1,403 @@ +.TH RIO 4 +.SH NAME +rio \- window system files +.SH SYNOPSIS +.B rio +[ +.B -i +.BI ' cmd ' +] +[ +.B -s +] +[ +.B -f +.I font +] +.SH DESCRIPTION +The window system +.I rio +serves a variety of files for reading, writing, and controlling +windows. +Some of them are virtual versions of system files for dealing +with the display, keyboard, and mouse; others control operations +of the window system itself. +.I Rio +posts its service in the +.B /srv +directory, using a +name constructed from a catenation of the user ID +and a process id; the environment variable +.BR $wsys +is set to this service name within processes running under the control +of each invocation of +.IR rio . +Similarly, +.I rio +posts a named pipe to access the window creation features +(see +.B window +in +.IR rio (1)) +from outside +its name space; this is named in +.BR $wctl . +.PP +A +.I mount +(see +.IR bind (1)) +of +.B $wsys +causes +.I rio +to create a new window; the attach specifier in the +.I mount +gives the coordinates of the created window. +The syntax of the specifier is the same as the arguments to +.B window +(see +.IR rio (1)). +By default, the window is sized and placed automatically. +It is always necessary, however, to provide the process id of the +process to whom to deliver notes generated by DEL characters and hangups +in that window. +That pid is specified by including the string +.B -pid +.I pid +in the attach specifier. (See the Examples section +.IR q.v. ) +.PP +When a window is created either by +the +.I window +command +(see +.IR rio (1)) +or by using the menu supplied by +.IR rio , +this server is mounted on +.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 +.IR cons (3), +and the mouse files +.IR mouse (3) +and +.IR cursor , +each specific to the window. +Note that the +.IR draw (3) +device multiplexes itself; +.IR rio +places windows but does not mediate programs' access to the display device. +.PP +Other files are unique to +.IR rio . +.TF window +.TP +.B cons +is a virtual version of the standard terminal file +.IR cons (3). +.I Rio +supplies extra editing features and a scroll bar +(see +.IR rio (1)). +.TP +.B consctl +controls interpretation of keyboard input. +Writing strings to it sets these modes: +.B rawon +turns on raw mode; +.B rawoff +turns off raw mode; +.B holdon +turns on hold mode; +.B holdoff +turns off hold mode. +Closing the file makes the window revert to default state +(raw off, hold off). +.TP +.B cursor +Like +.B mouse +.RI ( q.v. ), +a multiplexed version of the underlying device file, in this case representing the +appearance of the mouse cursor when the mouse is within the corresponding window. +.TP +.B label +initially contains a string with the process ID of the lead process +in the window and the command being executed there. +It may be written and is used as a tag when the window is hidden. +.TP +.B mouse +is a virtual version of the standard mouse file (see +.IR mouse (3)). +Opening it turns off scrolling, editing, and +.IR rio -supplied +menus in the associated +window. +In a standard mouse message, the first character is +.BR m , +but +.I rio +will send an otherwise normal message with the first character +.B r +if the corresponding window has been resized. +The application must then call +.B getwindow +(see +.IR graphics (2)) +to re-establish its state in the newly moved or changed window. +Reading the +.B mouse +file blocks until the mouse moves or a button changes. +Mouse movements or button changes are invisible when the mouse cursor +is located outside the window, except that if the mouse leaves the window +while a button is pressed, it will continue receiving mouse data until the button is released. +.TP +.B screen +is a read-only file reporting the depth, coordinates, and raster image corresponding to the entire +underlying display, +in the uncompressed format defined in +.IR image (6). +.TP +.B snarf +returns the string currently in the snarf buffer. +Writing this file sets the contents of the snarf buffer. +When +.I rio +is run recursively, the inner instance uses the snarf buffer of the parent, rather than +managing its own. +.TP +.B text +returns the full contents of the window. +It may not be written. +.TP +.B wctl +may be read or written. +When read, it returns the location of the window as four decimal integers formatted +in the usual 12-character style: upper left +.I x +and +.IR y , +lower right +.I x +and +.IR y . +Following these numbers are strings describing the window's state: +.B hidden +or +.BR visible ; +.B current +or +.BR notcurrent . +A subsequent read will block until the window changes size, location, or state. +When written to, +.B wctl +accepts messages to change the size or placement of the associated window, +and to create new windows. +The messages are in a command-line like format, with a command name, +possibly followed by options introduced by a minus sign. +The options must be separated by blanks, for example +.B -dx 100 +rather than +.BR -dx100 . +.IP +The commands are +.B resize +(change the size and position of the window), +.B move +(move the window), +.B scroll +(enable scrolling in the window), +.B noscroll +(disable scrolling), +.B set +(change selected properties of the window), +.B top +(move the window to the `top', making it fully visible), +.B bottom +(move the window to the `bottom', perhaps partially or totally obscuring it), +.B hide +(hide the window), +.B unhide +(restore a hidden window), +.B current +(make the window the recipient of keyboard and mouse input), +and +.B new +(make a new window). +The +.B top +and +.B bottom +commands do not change whether the window is current or not; +the others always make the affected window current. +.IP +Neither +.B top +nor +.B bottom +has any options. +The +.BR resize , +.BR move , +and +.B new +commands accept +.B -minx +.IR n , +.B -miny +.IR n , +.B -maxx +.IR n , +and +.BR -maxy +.I n +options to set the position of the corresponding edge of the window. +They also accept an option +.B -r +.I minx miny maxx maxy +to set all four at once. +The +.B resize +and +.B new +commands accept +.B -dx +.I n +and +.B -dy +.I n +to set the width and height of the window. +By default, +.I rio +will choose a convenient geometry automatically. +.IP +Finally, the +.B new +command accepts an optional shell command and argument string, +given as plain strings after any standard options, to run in the window +instead of the default +.B rc +.B -i +(see +.IR rc (1)). +The +.B -pid +.I pid +option to +.B new +identifies the +.I pid +of the process whose `note group' should receive interrupt +and hangup notes generated in the window. +The initial working directory of the new window may be set by a +.B -cd +.I directory +option. +The +.B -hide +option causes the window to be created off-screen, in the hidden state. +.IP +The +.B set +command accepts a set of parameters in the same style; only +.B -pid +.I pid +is implemented. +.IP +So programs outside name spaces controlled by +.I rio +may create windows, +.B wctl +.B new +messages may also be written to the named pipe identified by +.BR $wctl . +.TP +.B wdir +is a read/write text file containing +.IR rio 's +idea of the current working directory of the process running in the window. +It is used to fill in the +.B wdir +field of +.IR plumb (6) +messages +.I rio +generates from the +.B plumb +menu item on button 2. +The file is writable so the program may update it; +.I rio +is otherwise unaware of +.IR chdir (2) +calls its clients make. +In particular, +.IR rc (1) +maintains +.B /dev/wdir +in default +.IR rio (1) +windows. +.TP +.B winid +returns the unique and unchangeable ID for the window; +it is a string of digits. +.TP +.B window +is the virtual version of +.BR /dev/screen . +It contains the depth, coordinates, and +uncompressed raster image corresponding to the associated +window. +.TP +.B wsys +is a directory containing a subdirectory for each window, named +by the unique ID for that window. Within each subdirectory +are entries corresponding to several of the special files associated +with that window: +.BR cons , +.BR consctl , +.BR label , +.BR mouse , +etc. +.SH EXAMPLES +Cause a window to be created in the upper left corner, +and the word +.L hi +to be printed there. +.IP +.EX +mount $riosrv /tmp 'new -r 0 0 128 64 -pid '$pid +echo hi > /tmp/cons +.EE +.PP +Start +.IR sam (1) +in a large horizontal window. +.IP +.EX +echo new -dx 800 -dy 200 -cd /sys/src/cmd sam > /dev/wctl +.EE +.PP +Print the screen image of window with id 123. +.IP +.EX +lp /dev/wsys/123/window +.EE +.SH SOURCE +.B /sys/src/cmd/rio +.SH SEE ALSO +.IR rio (1), +.IR draw (3), +.IR mouse (3), +.IR cons (3), +.IR event (2), +.IR graphics (2). diff --git a/static/plan9-4e/man4/sacfs.4 b/static/plan9-4e/man4/sacfs.4 new file mode 100644 index 00000000..9b966281 --- /dev/null +++ b/static/plan9-4e/man4/sacfs.4 @@ -0,0 +1,59 @@ +.TH SACFS 4 +.SH NAME +sacfs \- compressed file system +.SH SYNOPSIS +.B disk/sacfs +[ +.B -i +.I infd +.I outfd +] +[ +.B -s +] +[ +.B -m +.I mountpoint +] +.I file +.SH DESCRIPTION +Sacfs interprets the compressed, block based file system created by +.IR mksacfs (8) +and stored in +.I file +so that it can be mounted into a Plan 9 file system. +.I Sacfs +is typically used to create a stand alone file system from +a small persistent storage device, such as a flash rom. +It does not authenticate its clients and assumes each group +has a single member with the same name. +.PP +The +.B -s +flag causes +.I sacfs +to post its channel on +.BR #s/sacfs . +The +.B -i +flag causes +.I sacfs +to use file descriptors +.I infd +and +.I outfd +for its communication channel. +If neither +.B -s +nor +.B -i +are given, +.I sacfs +mounts itself on +.IR mountpoint +(default +.BR /n/c: ). +.SH SOURCE +.B /sys/src/cmd/disk/sacfs/sacfs.c +.SH "SEE ALSO" +.IR mksacfs (8) diff --git a/static/plan9-4e/man4/snap.4 b/static/plan9-4e/man4/snap.4 new file mode 100644 index 00000000..d56706c7 --- /dev/null +++ b/static/plan9-4e/man4/snap.4 @@ -0,0 +1,103 @@ +.TH SNAP 4 +.SH NAME +snap, snapfs \- create and mount process snapshots +.SH SYNOPSIS +.B snap +[ +.B -o +.I file +] +.I pid... +.PP +.B snapfs +[ +.B -a +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I service +] +.I file... +.SH DESCRIPTION +.I Snap +and +.I snapfs +allow one to save and restore (static) process images, +usually for debugging +on a different machine or at a different time. +.PP +.I Snap +writes a snapshot +(see +.IR snap (6)) +of the named processes to +.I file +(default standard output). +If +.I proc +is a text string +rather than a process id, +.I snap +will save all processes with +that name that +are owned by the current user. +Both memory and text images are saved. +.PP +.I Snapfs +is a file server that +recreates the +.B /proc +directories for the processes in the snapshot. +By default, it mounts the new directories +into +.B /proc +before the current entries. +The +.B -m +option can be used to specify +an alternate mountpoint, +while +.B -a +will cause it to mount the new directories +after the current entries. +The +.B -s +option causes it to serve requests via +.BI /srv/ service. +.SH EXAMPLE +Suppose +.I page +has hung viewing Postscript on your terminal, but the author is gone for the rest of +the month and you want to make sure the process +is still around for debugging on his return. +You can save the errant processes with +.IP +.EX +snap -o page.snap `{psu | awk '$NF ~ /page|gs/ {print $2}'} +.EE +.PP +When the author returns, he can add the process images to his name space +by running +.IP +.EX +snapfs page.snap +.EE +.PP +and then use a conventional +debugger to debug them. +.SH SOURCE +.B /sys/src/cmd/snap +.SH SEE ALSO +.IR acid (1), +.IR db (1), +.IR proc (3), +.IR snap (6) +.SH BUGS +The snapshots take up about as much disk space +as the processes they contain did memory. +Compressing them when not in use is recommended, +as is storing them on a rewritable disk. diff --git a/static/plan9-4e/man4/srv.4 b/static/plan9-4e/man4/srv.4 new file mode 100644 index 00000000..ab38204e --- /dev/null +++ b/static/plan9-4e/man4/srv.4 @@ -0,0 +1,237 @@ +.TH SRV 4 +.SH NAME +srv, srvold9p, 9fs \- start network file service +.SH SYNOPSIS +.B srv +[ +.B -abcCmq +] +.RI [ net !] system\c +.RI [! service ] +[ +.I srvname +[ +.I mtpt +] ] +.PP +.B 9fs +.RI [ net !] system +.RI [ mountpoint ] +.PP +.B srvold9p +[ +.B -abcCd +] [ +.B -u +.I user +] [ +.B -s +| [ +.B -m +.I mountpoint +] ] [ +.B -x +.I command +| +.B -n +.I network-addr +| +.B -f +.I file +] [ +.B -F +] [ +.B -p +.I servicename +] +.SH DESCRIPTION +.I Srv +dials the given machine and initializes the connection to serve the +9P protocol. +It then creates in +.B /srv +a file named +.IR srvname . +Users can then +.B mount +(see +.IR bind (1)) +the service, typically on a name in +.BR /n , +to access the files provided by the remote machine. +If +.I srvname +is omitted, the first argument to +.B srv +is used. +Option +.B m +directs +.I srv +to mount the service on +.BI /n/ system +or onto +.I mtpt +if it is given. +Option +.B q +suppresses complaints if the +.B /srv +file already exists. +The +.BR a , +.BR b , +.BR c , +and +.B C +flags are used to control the mount flag as in +.IR bind (1). +.PP +The specified +.I service +must serve 9P. Usually +.I service +can be omitted; when calling some +non-Plan 9 systems, a +.I service +such as +.B u9fs +must be mentioned explicitly. +.PP +The +.I 9fs +command does the +.I srv +and the +.I mount +necessary to make available the files of +.I system +on network +.IR net . +The files are mounted on +.IR mountpoint , +if given; +otherwise they are mounted on +.BI /n/ system\f1. +If +.I system +contains +.L / +characters, only the last element of +.I system +is used in the +.B /n +name. +.PP +.I 9fs +recognizes some special names, such as +.B dump +to make the dump file system available on +.BR /n/dump . +.I 9fs +is an +.IR rc (1) +script; examine it to see what local conventions apply. +.PP +.I Srvold9p +is a compatibilty hack to allow Fourth Edition Plan 9 systems +to connect to older 9P servers. +It functions as a variant of +.I srv +that performs a version translation on the 9P messages on the underlying connection. +Some of its options are the same as those of +.IR srv ; +the special ones are: +.TP +.B -d +Enable debuggging +.TP +.BI -u\ user +When connecting to the remote server, log in as +.IR user . +Since +.I srvold9p +does no authentication, and since new kernels cannot authenticate to +old services, the likeliest value of +.I user +is +.BR none . +.TP +.BI -x\ command +Run +.I command +and use its standard input and output as the 9P service connection. +If the +.I command +string contains blanks, it should be quoted. +.TP +.BI -n\ network-addr +Dial +.I network-addr +to establish the connection. +.TP +.BI -f\ file +Use +.I file +(typically an existing +.IR srv (3) +file) as the connection. +.TP +.B -F +Insert a special (internal) filter process to the connection to maintain +message boundaries; usually only needed on TCP connections. +.TP +.BI -p\ servicename +Post the service under +.IR srv (3) +as +.BI /srv/ servicename\f1. +.PP +.I Srvold9p +is run automatically when a +.IR cpu (1) +call is received on the service port for the old protocol. +.SH EXAMPLES +To see kremvax's and deepthought's files in +.B /n/kremvax +and +.BR /n/deepthought : +.IP +.EX +9fs kremvax +9fs hhgttg /n/deepthought +.EE +.PP +To mount as user +.B none +a connection to an older server kgbsun: +.IP +.EX +srvold9p -u none -m /n/kgbsun -p kgbsun -n il!kgbsun +.EE +.PP +Other windows may then mount the connection directly: +.IP +.EX +mount /srv/kgbsun /n/kgbsun +.EE +.SH NOTE +The TCP port used for 9P is 564. +.SH FILES +.TF /srv/* +.TP +.B /srv/* +ports to file systems and servers posted by +.I srv +and +.I 9fs +.SH SOURCE +.B /sys/src/cmd/srv.c +.br +.B /rc/bin/9fs +.br +.SH "SEE ALSO" +.IR bind (1), +.IR dial (2), +.IR srv (3), +.IR ftpfs (4) diff --git a/static/plan9-4e/man4/tapefs.4 b/static/plan9-4e/man4/tapefs.4 new file mode 100644 index 00000000..e6ca73ed --- /dev/null +++ b/static/plan9-4e/man4/tapefs.4 @@ -0,0 +1,100 @@ +.TH TAPEFS 4 +.SH NAME +32vfs, cpiofs, tapfs, tarfs, tpfs, v6fs, v10fs \- mount archival file systems +.SH SYNOPSIS +.B fs/32vfs +[ +.B -m +.I mountpoint +] +[ +.B -p +.I passwd +] +[ +.B -g +.I group +] +.I file +.br +.B fs/cpiofs +.br +.B fs/tapfs +.br +.B fs/tarfs +.br +.B fs/tpfs +.br +.B fs/v6fs +.br +.B fs/v10fs +.br +.SH DESCRIPTION +These commands interpret data from traditional tape or file system formats +stored in +.IR file , +and mount their contents (read-only) into a Plan 9 file system. +The optional +.B -p +and +.B -g +flags specify Unix-format password (respectively group) files +that give the mapping between the numeric user- and group-ID +numbers on the media and the strings reported by Plan 9 status +inquiries. +The +.B -m +flag introduces the name at which the new file system should be +attached; the default is +.BR /n/tapefs . +.PP +.I 32vfs +interprets raw disk images of 32V systems, which are ca. 1978 research Unix systems for +the VAX, and also pre-FFS Berkeley VAX systems (1KB block size). +.PP +.I Cpiofs +interprets +.B cpio +tape images (constructed with +.BI cpio 's +.B c +flag). +.PP +.I Tarfs +interprets +.I tar +tape images. +.PP +.I Tpfs +interprets +.I tp +tapes from the Fifth through Seventh Edition research Unix systems. +.PP +.I Tapfs +interprets +.I tap +tapes from the pre-Fifth Edition era. +.PP +.I V6fs +interprets disk images from the +Fifth and Sixth edition research Unix systems (512B block size). +.PP +.I V10fs +interprets disk images from the +Tenth Edition research Unix systems (4KB block size). +.SH SOURCE +.PP +These commands are constructed in a highly stereotyped +way using the files +.I fs.c +and +.I util.c +in +.BR /sys/src/cmd/tapefs , +which in +turn derive substantially from +.IR ramfs (4). +.SH "SEE ALSO +Section 5 +.IR passim , +.IR ramfs (4). diff --git a/static/plan9-4e/man4/telco.4 b/static/plan9-4e/man4/telco.4 new file mode 100644 index 00000000..f78a9086 --- /dev/null +++ b/static/plan9-4e/man4/telco.4 @@ -0,0 +1,226 @@ +.TH TELCO 4 +.SH NAME +telco, faxreceive, faxsend, fax, telcofax, telcodata \- telephone dialer network +.SH SYNOPSIS +.B telco +[ +.B -p +] [ +.B -i +.I source-id +] [ +.B -v +] +.I dialer-devs +.PP +.B aux/faxsend +.I address +.I page1 +\&... +.PP +.B aux/faxreceive +[ +.B -s +.I spool-dir +] [ +.B -v +] +.PP +.B fax +.I telno +.I recipient +[ +.I files +] +.PP +.B service/telcofax +.PP +.B service/telcodata +.SH DESCRIPTION +.I Telco +is a file server that provides a network interface to +Hayes telephone dialers. +The interface is the same as that provided by +.IR ip (3) +and can be used by any program that makes network connections using +.IR dial (2). +The network addresses used by +.I telco +are telephone +numbers. +.PP +The options are +.TP +.B -p +use pulse dialing +.TP +.B -v +verbose: write to the log file all communications with +the dialer. +.TP +.B -i +specify a +.I source-id +to be used during FAX transfers +.PP +Some control of outgoing calls can be encoded +in the address. +Normally, addresses are of the form +.IB telco ! number\f1, +where +.I number +is a decimal telephone number. +However, commas in the telephone number can be used to insert +pauses in the dialing process. +Dialing options can be added to the end of the address, separated +by +.BR ! 's. +The dialing options are +.TF baudrate +.TP +.B compress +turn on compression (default off) +.TP +.I baudrate +a decimal number representing the highest baud +rate with which to make the call +.TP +.B fax +to make a Class 2 facsimile call (used by programs such as +.IR faxsend ) +.PD +.PP +.I Telco +also answers incoming calls. +Upon receiving a facsimile call, +.I telco +starts the script +.BR /rc/bin/service/telcofax . +For data calls it starts +.BR /rc/bin/service/telcodata . +Each is started with the network connection as both standard +input and standard output and with two arguments, +the file name of the network connection, e.g., +.BR /net/telco/0/data , +and the type of modem. +Currently, the only modem types supported are: +.TF ATT14400 +.TP +.B MT1432 +Multitech's 14400 baud modem +.TP +.B MT2834 +Multitech's 28800 baud modem +.TP +.B ATT14400 +the 14400 baud modem in Safaris +.TP +.B VOCAL +the 14400 baud Vocal modem +.PD +.PP +All other modems are assumed to be compatible with the standard +Hayes command subset. +.PP +.I Faxreceive +is normally started by +.BR /rc/bin/service/telcofax . +It inputs and spools a CCITT Group 3 (G3) encoded FAX, and then starts the +script +.BR /sys/lib/fax/receiverc , +passing it four arguments: the spool file name, +.B Y +(for success) or +.BR N , +the number of pages, and the id string passed by the caller. +This script sends by +.IR mail (1) +notification to a list of recipients kept in the file +.BR /mail/faxqueue/faxrecipients ; +the script and the list +should be edited to match local needs. +.I Faxreceive's +options are: +.TP +.B -s +specify a different spool directory; the default is +.BR /mail/faxqueue . +.TP +.B -v +verbose: write to the log file all communications with +the modem. +.PP +.I Faxsend +transmits a FAX to +.IR address . +.I Page1 +and all arguments that follow +are names of files containing G3 encoded +FAX images, one per page. +.PP +.I Fax +is a shell script that queues +PostScript, G3, or text files to be transmitted to a +FAX machine. +A standard cover sheet, derived from +.BR /sys/lib/fax/h.ps , +is sent before the message. +.I Telno +is the destination telephone number. +.I Recipient +is the name of the recipient to be placed +on the cover sheet. +If no +.I files +are specified, standard input is sent. +.SH EXAMPLE +Start the dialer on a PC, then use +.I con +to phone out. +.IP +.EX +telco /dev/eia1 +con -l telco!18005551212 +.EE +.PP +The connection will be made at the highest +negotiable baud rate. To use the +best negotiable compression scheme as well: +.IP +.EX +con -l telco!18005551212!compress +.EE +.SH FILES +.B /mail/faxqueue/* +.br +.B /rc/bin/service/telcodata +.br +.B /rc/bin/service/telcofax +.br +.B /sys/log/telco +.br +.B /sys/lib/fax/receiverc +.br +.B /mail/faxqueue/faxrecipients +.br +.B /sys/lib/fax/h.ps +.br +.B /sys/log/fax +.SH SOURCE +.B /sys/src/cmd/telco/* +.br +.B /sys/src/cmd/fax/* +.SH "SEE ALSO" +.IR con (1), +.IR ip (3) +.SH BUGS +.PP +These programs require the Class 2 facsimile interface. This means that +.I faxsend +and +.I faxreceive +will not work on most portable computers since they have Class 1 +interfaces. +.PP +The modem specific information is currently built into the source. +This should be in a user modifiable file. diff --git a/static/plan9-4e/man4/u9fs.4 b/static/plan9-4e/man4/u9fs.4 new file mode 100644 index 00000000..6d4d475c --- /dev/null +++ b/static/plan9-4e/man4/u9fs.4 @@ -0,0 +1,250 @@ +.TH U9FS 4 +.SH NAME +u9fs \- serve 9P from Unix +.SH SYNOPSIS +.B u9fs +[ +.B -Dnz +] +[ +.B -a +.I authtype +] +[ +.B -A +.I autharg +] +[ +.B -l +.I logfile +] +[ +.B -m +.I msize +] +[ +.B -u +.I onlyuser +] +.SH DESCRIPTION +.I U9fs +is +.I not +a Plan 9 program. Instead it is a program that +serves Unix files to Plan 9 machines using the 9P protocol +(see +.IR intro (5)). +It is typically invoked on a +Unix machine by +.B inetd +with its standard input and output connected to a +network connection, typically TCP on an Ethernet. +It typically runs as user +.B root +and multiplexes access to multiple Plan 9 clients over the single wire. +It assumes Plan 9 uids match Unix login names, +and changes to the corresponding Unix effective uid when processing requests. +.I U9fs +serves both 9P1 (the 9P protocol as used by +the second and third editions of Plan 9) and 9P2000. +.PP +The options are: +.TP +.B -D +Write very chatty debugging output to the log file (see +.B -l +option below). +.TP +.B -n +Signals that +.I u9fs +is +.I not +being invoked with a network connection +on standard input and output, and thus should +not try to determine the remote address of the connection. +This is useful when +.I u9fs +is not invoked from +.I inetd +(see examples below). +.TP +.B -z +Truncate the log file on startup. This is useful mainly when debugging +with +.BR -D . +.TP +.BI -a " authtype +Sets the authentication method to be used. +.I Authtype +should be +.BR rhosts , +.BR none , +or +.BR 9p1 . +The default is +.BR rhosts , +which uses the +.I ruserok +library call to authenticate users by entries in +.B /etc/hosts.equiv +or +.BR $HOME/.rhosts . +This default is discouraged for all but the most controlled networks. +Specifying +.B none +turns off authentication altogether. +This is useful when +.I u9fs +is not invoked from +.I inetd +(see examples below). +Specifying +.B 9p1 +uses the second and third edition Plan 9 authentication mechanisms. +The file +.BR /etc/u9fs.key , +or +.I autharg +if specified +(see the +.B -A +option), +is consulted for the authentication data. +The file must contain exactly three lines: +the plaintext password, the user id, and +the authentication domain. +.TP +.BI -A " autharg +Used to specify an argument to the authentication method. +See the authentication descriptions above. +.TP +.BI -l " logfile +Specifies the file which should contain debugging output +and other messages. +The out-of-the-box compile-time default is +.BR /tmp/u9fs.log . +.TP +.BI -m " msize +Set +.I msize +for 9P2000 +(see +.IR open (5)). +.TP +.BI -u " user +Treat all attaches as coming from +.IR user . +This is useful in some cases when running without +.IR inetd ; +see the examples. +.SH +EXAMPLES +.PP +Plan 9 calls 9P file service +.B 9fs +with TCP port number 564. +Set up this way on a machine called, say, +.BR kremvax , +.I u9fs +may be connected to the name space of a Plan 9 process by +.IP +.EX +9fs kremvax +.EE +.PP +For more information on this procedure, see +.IR srv (4) +and +.IR bind (1). +.PP +.I U9fs +serves the entire file system of the Unix machine. +It forbids access to devices +because the program is single-threaded and may block unpredictably. +Using the +.B attach +specifier +.B device +connects to a file system identical to the usual system except +it only permits device access (and may block unpredictably): +.IP +.EX +srv tcp!kremvax!9fs +mount -c /srv/tcp!kremvax!9fs /n/kremvax device +.EE +.PP +(The +.B 9fs +command +does not accept an attach specifier.) +Even so, +device access may produce unpredictable +results if the block size of the device is greater than 8192, +the maximum data size of a 9P message. +.PP +The source to +.I u9fs +is in the Plan 9 directory +.BR /sys/src/cmd/unix/u9fs . +To install +.I u9fs +on a Unix system with an ANSI C compiler, copy the source to a directory on that system +and run +.BR make . +Then install the binary in +.BR /usr/etc/u9fs . +Add this line to +.BR inetd.conf : +.IP +.EX +9fs stream tcp nowait root /usr/etc/u9fs u9fs +.EE +.PP +and this to +.BR services : +.IP +.EX +9fs 564/tcp 9fs # Plan 9 fs +.EE +.LP +Due to a bug in their +IP software, some systems will not accept the service name +.BR 9fs , +thinking it +a service number because of the initial digit. +If so, run the service as +.B u9fs +or +.BR 564 . +.PP +On systems where listeners cannot be started, +.IR execnet (4) +is useful for running +.I u9fs +via mechanisms like +.IR ssh . +.SH SOURCE +.B /sys/src/cmd/unix/u9fs +.SH DIAGNOSTICS +Problems are reported to the +log file specified with the +.B -l +option (default +.BR /tmp/u9fs.log ). +The +.B -D +flag enables chatty debugging. +.SH SEE ALSO +.IR bind (1), +.IR execnet (4), +.IR srv (4), +.IR ip (3), +.IR nfsserver (8) +.SH BUGS +The implementation of devices is unsatisfactory. +.LP +Semantics like remove-on-close or the +atomicity of +.B wstat +are hard to provide exactly. diff --git a/static/plan9-4e/man4/usb.4 b/static/plan9-4e/man4/usb.4 new file mode 100644 index 00000000..2f01063b --- /dev/null +++ b/static/plan9-4e/man4/usb.4 @@ -0,0 +1,154 @@ +.TH USB 4 +.SH NAME +usbmouse, +usbaudio +\- Universal Serial Bus user level device drivers +.SH SYNOPSIS +.B usb/usbmouse +[ +.B -f +] [ +.I ctrlno +.I n +] +.PP +.B usb/usbaudio +[ +.B -d +] [ +.B -v +.I volume +] [ +.B -m +.I mountpoint +] [ +.I ctrlno +.I n +] +.PP +.B usbstart +.SH DESCRIPTION +These programs implement support for specific USB device classes. +They should be run after +.IR usbd (4) +has had a chance to locate the devices in question and provide +them with device addresses and minimal configuration. +Dynamic handling of device insertion and removal is currently not supported. +.PP +The script +.B usbstart +checks whether a USB driver is present, and if so, starts usbd +followed by the support programs listed below. +.SS USB MICE +.B Usbmouse +sends mouse events from a USB mouse to +.B #m/mousein +where the Plan 9 kernel processes them like other mice. +.PP +Without arguments, it scans the USB status files to find a mouse +and uses the first one it finds. A pair of numeric arguments overrides this search +with a specific USB controller and device. +.PP +The +.B -f +flag runs +.B usbmouse +in the foreground. +.SS USB AUDIO DEVICES +.B Usbaudio +configures and manages a usb audio device. It implements a file system, +normally mounted in +.BI /dev , +but this can be changed with the +.B \-m +flag, with files +.IR /volume , +.IR /audioctl , +.IR /audio , +and +.IR /audioin . +The names +.I /volume +and +.I /audio +maintain backward compatibility with the soundblaster driver. +.PP +Reading +.I /volume +or +.I /audioctl +yields the device's settings. The data format of +.I /volume +is compatible with the soundblaster and +produces something like +.PP +.EX +audio out 65 +treb out 0 +bass out 0 +speed out 44100 +.EE +.PP +This file can be written using the same syntax. The keyword +.I out +may be omitted. Settings are given as percentages of the range. +.PP +The file +.I /audioctl +provides more information, using up to 6 columns of 12 characters each. +From left to right, the fields are: +.IR "control name" , +.I in +or +.IR out , +.IR "current value" , +.IR "minimum value" , +.IR maximum , +and +.IR resolution . +There are 3, 5, or 6 columns present. +Maxima and resolution are omitted when they are not available or not applicable. +The resolution for +.I speed +is reported as 1 (one) if the sampling frequency is continuously variable. It is absent +if it is settable at a fixed number of discrete values only. +.PP +When all values from +.I /audioctl +have been read, a zero-sized buffer is returned (the usual end-of-file indication). +A new read will then block until one of the settings changes and then report its new value. +.PP +The file +.I /audioctl +can be written like +.IR /volume . +.PP +Audio data is written to +.I /audio +and read from +.IR /audioin . +The data format is little endian, samples ordered primarily by time and +secondarily by channel. Samples occupy the minimum integral number +of bytes. Read and write operations of arbitrary size are allowed. +.SH EXAMPLE +.LP +To use a USB mouse and audio device, put the following in your profile +(replace x by your favorite initial volume setting): +.PP +.EX +.ta 6n +if (test -r '#U'/usb0) { + usb/usbd + usb/usbmouse -a 2 + usb/usbaudio -v x +} +.EE +.PP +Alternatively, just put +.B usbstart +in your profile. +.SH SOURCE +.B /sys/src/cmd/usb +.SH "SEE ALSO" +.IR usb (3), +.IR usbd (4) diff --git a/static/plan9-4e/man4/usbd.4 b/static/plan9-4e/man4/usbd.4 new file mode 100644 index 00000000..154d49c9 --- /dev/null +++ b/static/plan9-4e/man4/usbd.4 @@ -0,0 +1,35 @@ +.TH USBD 4 +.SH NAME +usbd \- Universal Serial Bus daemon +.SH SYNOPSIS +.B usbd +[ +.B -v +] [ +.B -d +] +.SH DESCRIPTION +.I Usbd +manages the USB infrastructure, polls all ports, configures hubs and +provides access to USB devices through a file system in +.BR #U . +It monitors all ports, active or inactive and acts on state changes +by configuring devices when they are plugged in or turned on and +unconfiguring them when they are pulled out or switched off. +.PP +.B Usbd +recognizes the following flags: +.I +.TP +.B v +Verbose; print configuration information and device status as they change. +.TP +.B d +Debug; print the bytes in each message sent or received. +.LP +.sp +.SH SOURCE +.B /sys/src/cmd/usb/usbd +.SH "SEE ALSO" +.IR usb (3), +.IR usb (4) diff --git a/static/plan9-4e/man4/vacfs.4 b/static/plan9-4e/man4/vacfs.4 new file mode 100644 index 00000000..db9c79a6 --- /dev/null +++ b/static/plan9-4e/man4/vacfs.4 @@ -0,0 +1,72 @@ +.TH VACFS 4 +.SH NAME +vacfs \- a Venti-based file system +.SH SYNOPSIS +.B vacfs +[ +.B -dis +] +[ +.B -c +.I cachesize +] +[ +.B -h +.I host +] +[ +.B -m +.I mtpt +] +.I vacfile +.SH DESCRIPTION +.I Vacfs +interprets the file system created by +.IR vac (1) +so that it can be mounted into a Plan 9 file hierarchy. +The data for the file system is stored on +.IR venti (8) +with a root fingerprint specified in +.IR vacfile . +.I Vacfs +is currently rather limited: access is read-only, +clients are not authenticated, and groups are assumed to +contain a single member with the same name. +These restrictions should eventually be removed. +.PP +Options to +.I vacfs +are: +.TP +.BI -c " cachesize +The number of file system blocks to cache in memory. The default is 1000 blocks. +.TP +.B -d +Print debugging information to standard error. +.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 -i +Use file descriptors 0 and 1 as the 9P communication channel rather than create a pipe. +.TP +.BI -m " mtpt +The location to mount the file system. The default is +.BR /n/vac . +.TP +.B -s +Post the 9P channel on #s/vacfs rather than +mounting it on +.IR mtpt . +.SH SOURCE +.B /sys/src/cmd/vac +.SH "SEE ALSO" +.IR vac (1), +.IR venti (8) diff --git a/static/plan9-4e/man4/webcookies.4 b/static/plan9-4e/man4/webcookies.4 new file mode 100644 index 00000000..63842e90 --- /dev/null +++ b/static/plan9-4e/man4/webcookies.4 @@ -0,0 +1,166 @@ +.TH WEBCOOKIES 4 +.SH NAME +webcookies \- HTTP cookie manager +.SH SYNOPSIS +.B webcookies +[ +.B -f +.I cookiefile +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I service +] +.SH DESCRIPTION +.I Webcookies +manages a set of HTTP cookies, which are +used to associate HTTP requests with persistent state +(such as user profiles) on many web servers. +.PP +.I Webcookies +reads +.I cookiefile +(default +.BR $home/lib/webcookies ) +and mounts itself at +.I mtpt +(default +.BR /mnt/webcookies ). +If +.I service +is specified, +.I cookiefs +will post a service file descriptor +in +.BR /srv/\fIservice . +.PP +The cookie file contains one cookie per line; +each cookie comprises some number of +.IB attr = value +pairs. +Cookie attributes are: +.TF \fBnetscapestyle=flag +.TP +.BI name= name +The name of the cookie on the remote server. +.TP +.BI value= value +The value associated with that name on the remote server. +The actual data included when a cookie is sent back +to the server is +.IB \fR``\fIname = value\fR'' +(where, confusingly, +.I name +and +.I value +are the values associated with the +.B name +and +.B value +attributes. +.TP +.BI domain= domain +The domain within which the cookie can be used. +If +.I domain +is an IP address, the cookie can only be used when +connecting to a web server at that IP address. +If +.I domain +is a pattern beginning with a dot, +the cookie can only be used for servers whose name +has +.I domain +as a suffix. +For example, a cookie with +.B domain=.bell-labs.com +may be used on the web sites +.I www.bell-labs.com +and +.IR www.research.bell-labs.com . +.TP +.BI path= path +The cookie can only be used for URLs with a path (the part after +.BI http:// hostname\fR) +beginning with +.IR path . +.TP +.BI version= version +The version of the HTTP cookie specification, specified by the server. +.TP +.BI comment= comment +A comment, specified by the server. +.TP +.BI expire= expire +The cookie expires at time +.IR expire , +which is a decimal number of seconds since the epoch. +.TP +.B secure=1 +The cookie may only be used over secure +.RB ( https ) +connections. +.TP +.B explicitdomain=1 +The domain associated with this cookie was set by +the server (rather than inferred from a URL). +.TP +.B explicitpath=1 +The path associated with this cookie was set by the +server (rather than inferred from a URL). +.TP +.B netscapestyle=1 +The server presented the cookie in ``Netscape style,'' which +does not conform to the cookie standard, RFC2109. +It is assumed that when presenting the cookie to the server, +it must be sent back in Netscape style as well. +.PD +.PP +.I Webcookies +serves a directory containing two files. +The first, +.BR cookies , +is a textual representation of the cookie file, +which can be edited to change the set of cookies +currently held. +The second, +.BR http , +is intended to be used by HTTP clients +to access cookies. +Upon opening +.BR http , +the client must write a full URL to it. +After writing the URL, reading from the file will yield any +HTTP +.B Cookie: +headers that should be included in the +request for this particular URL. +Once the request has been made, any +.B Set-Cookie: +lines in the HTTP response header should +be written to the file to save them for next time. +If +.B cookiefs +decides not to accept the cookie (as outlined in +RFC2109, section 4.3.4), no indication is given. +.PP +.IR Hget (1) +uses +.BR /mnt/webcookies/http , +when it exists, to manage cookie state. +.I Webfs +does not (yet). +.SH SOURCE +.B /sys/src/cmd/webcookies.c +.SH SEE ALSO +.IR hget (1) +.SH BUGS +It's not clear what the relationship between +.I cookiefs +and something like +.I webfs +should be. diff --git a/static/plan9-4e/man4/webfs.4 b/static/plan9-4e/man4/webfs.4 new file mode 100644 index 00000000..e6d57bfa --- /dev/null +++ b/static/plan9-4e/man4/webfs.4 @@ -0,0 +1,307 @@ +.TH WEBFS 4 +.SH NAME +webfs \- world wide web file system +.SH SYNOPSIS +.B webfs +[ +.B -c +.I cookiefile +] +[ +.B -m +.I mtpt +] +[ +.B -s +.I service +] +\&... +.SH DESCRIPTION +.I Webfs +presents a file system interface to the parsing and retrieving +of URLs. +.I Webfs +mounts itself at +.I mtpt +(default +.BR /mnt/web ), +and, if +.I service +is specified, will post a service file descriptor +in +.BR /srv/\fIservice . +.PP +.I Webfs +presents a three-level file system suggestive +of the network protocol hierarchies +.IR ip (3) +and +.IR ether (3). +.PP +The top level contains three files: +.BR ctl , +.BR cookies , +and +.BR clone . +.PP +The +.B ctl +file is used to maintain parameters global to the instance of +.IR webfs . +Reading the +.B ctl +file yields the current values of the parameters. +Writing strings of the form +.RB `` attr " " value '' +sets a particular attribute. +Attributes are: +.TP +.B chatty9p +The +.B chatty9p +flag used by the 9P library, discussed in +.IR 9p (2). +.B 0 +is no debugging, +.B 1 +prints 9P message traces on standard error, +and values above +.B 1 +present more debugging, at the whim of the library. +The default for this and the following debug flags is +.BR 0 . +.TP +.B fsdebug +This variable is the level of debugging output about the file system module. +.TP +.B cookiedebug +This variable is the level of debugging output about the cookie module. +.TP +.B urldebug +This variable is the level of debugging output about URL parsing. +.TP +.B acceptcookies +This flag controls whether to accept cookies presented by remote web servers. +(Cookies are described below, in the discussion of the +.B cookies +file.) +The values +.B on +and +.B off +are synonymous with +.B 1 +and +.BR 0 . +The default is +.BR on . +.TP +.B sendcookies +This flag controls whether to present stored cookies to remote web servers. +The default is +.BR on . +.TP +.B redirectlimit +Web servers can respond to a request with a message +redirecting to another page. +.I Webfs +makes no effort to determine whether it is in an infinite +redirect loop. +Instead, it gives up after this many redirects. +The default is +.BR 10 . +.TP +.B useragent +.I Webfs +sends the value of this attribute in its +.B User-Agent: +header in its HTTP requests. +The default is +.RB `` "webfs/2.0 (plan 9)" .'' +.PD +.PP +The top-level directory also contains +numbered directories corresponding to connections, which +may be used to fetch a single URL. +To allocated a connection, open the +.B clone +file and read a number +.I n +from it. +After opening, the +.B clone +file is equivalent to the file +.IB n /ctl \fR. +A connection is assumed closed once all files in its directory +have been closed, and is then will be reallocated. +.PP +Each connection has its own private set of +.BR acceptcookies , +.BR sendcookies , +.BR redirectlimit , +and +.B useragent +variables, initialized to the defaults set in the +root's +.B ctl +file. The per-connection +.B ctl +file allows editing the variables for this particular connection. +.PP +Each connection also has a URL string variable +.B url +associated with it. +This URL may be an absolute URL such as +.I http://www.lucent.com/index.html +or a relative URL such as +.IR ../index.html . +The +.B baseurl +string variable sets the URL against which relative URLs +are based. +Once the URL has been set, +its pieces can be retrieved via individual files in the +.B parsed +directory. +.I Webfs +parses the following URL syntaxes; names in italics are +the names of files in the +.B parsed +directory. +.IP +\fIscheme\f5:\fIschemedata +.br +\f5http://\fIhost\f5/\fIpath\fR[\f5?\fIquery\fR][\f5#\fIfragment\fR] +.br +\f5ftp://\fR[\fIuser\fR[\f5:\fIpassword\fR]\f5@\fR]\fP\f5\fIhost\f5/\fIpath\fR[\f5;type=\fIftptype\fR] +.br +\f5file:\fIpath +.LP +If there is associated data to be +posted with the request, it can be written to +.BR postbody . +Finally, opening +.B body +initiates the request. +The resulting data may be read from +.B body +as it arrives. +After the request has been executed, the MIME content type +may be read from the +.B contenttype +file. +.PP +The top-level +.B cookies +file contains the internal set of HTTP cookies, which +are used by HTTP servers to associate requests with persistent +state such as user profiles. +It may be edited as an ordinary text file. +Multiple instances of +.I webfs +and +.IR webcookies (4) +share cookies by keeping their internal set +consistent with the +.I cookiefile +(default +.BR $home/lib/webcookies ), +which has the same format. +.PP +These files contain one line per cookie; +each cookie comprises some number of +.IB attr = value +pairs. +Cookie attributes are: +.TP +.BI name= name +The name of the cookie on the remote server. +.TP +.BI value= value +The value associated with that name on the remote server. +The actual data included when a cookie is sent back +to the server is +.IB \fR``\fIname = value\fR'' +(where, confusingly, +.I name +and +.I value +are the values associated with the +.B name +and +.B value +attributes. +.TP +.BI domain= domain +If +.I domain +is an IP address, the cookie can only be used for URLs +with +.I host +equal to that IP address. +Otherwise, +.I domain +must be a pattern beginning with a dot, and +the cookie can only be used for URLs with a +.I host +having +.I domain +as a suffix. +For example, a cookie with +.B domain=.bell-labs.com +may be used on hosts +.I www.bell-labs.com +and +.IR www.research.bell-labs.com +(but not +.IR www.not-bell-labs.com ). +.TP +.BI path= path +The cookie can only be used for URLs with a path +beginning with +.IR path . +.TP +.BI version= version +The version of the HTTP cookie specification, specified by the server. +.TP +.BI comment= comment +A comment, specified by the server. +.TP +.BI expire= expire +The cookie expires at time +.IR expire , +which is a decimal number of seconds since the epoch. +.TP +.B secure=1 +The cookie may only be used over secure +.RB ( https ) +connections. +Secure connections are currently unimplemented. +.TP +.B explicitdomain=1 +The domain associated with this cookie was set by +the server (rather than inferred from a URL). +.TP +.B explicitpath=1 +The path associated with this cookie was set by the +server (rather than inferred from a URL). +.TP +.B netscapestyle=1 +The server presented the cookie in ``Netscape style,'' which +does not conform to the cookie standard, RFC2109. +It is assumed that when presenting the cookie to the server, +it must be sent back in Netscape style as well. +.PD +.PP +.SH SOURCE +.B /sys/src/cmd/webfs +.SH SEE ALSO +.IR hget (1), +.IR webcookies (4). +.SH BUGS +It's not clear what the relationship between +.IR hget , +.I webcookies +and +.I webfs +should be. diff --git a/static/plan9-4e/man4/wikifs.4 b/static/plan9-4e/man4/wikifs.4 new file mode 100644 index 00000000..e99ba361 --- /dev/null +++ b/static/plan9-4e/man4/wikifs.4 @@ -0,0 +1,338 @@ +.TH WIKIFS 4 +.SH NAME +wikifs, wikipost \- wiki file system +.SH SYNOPSIS +.B wikifs +[ +.B -DM +] +[ +.B -a +.I announce +]... +[ +.B -m +.I mtpt +] +[ +.B -p +.I perm +] +[ +.B -s +.I service +] +.I dir +.PP +.B ip/httpd/wikipost +.RB [ -b +.IR inbuf ] +.RB [ -d +.IR domain ] +.RB [ -r +.IR remoteip ] +.RB [ -w +.IR webroot ] +.RB [ -N +.IR netdir ] +.I method version uri +.RI [ search ] +.SH DESCRIPTION +A +.I wiki +is a web server that facilitates easy editing of the pages it contains. +.I Wikifs +presents a wiki in two forms: as web pages to be served +via +.IR httpd (8) +and as text files to be viewed via the +.IR acme (1) +wiki client +(see +.BR /acme/wiki/guide ). +.PP +.I Wikifs +presents a file system interface to the wiki data stored +in +.IR dir . +By default, +.I wikifs +mounts itself at +.BR /mnt/wiki ; +the +.B -m +flag specifies a different mount point, +and the +.B -M +flag causes +.I wikifs +not to mount at all. +.I Wikifs +also announces 9P network services on the addresses +given as arguments to +.B -a +options. +If the +.B -s +option is given, +.I wikifs +will post a service file descriptor in +.BI /srv/ service +with permission +.I perm +(default 600). +The +.B -D +flag causes a transcript of the 9P conversation +to be written to standard error. +.PP +The wiki holds both the current pages and also +all versions of all pages that have ever existed. +All pages have time stamps associated with them. +When a user wants to edit a page, he reads the +current page from the wiki, noting the time stamp +on the page. +When a user writes changes to a page, he includes the time stamp +of the page he started with. If the page has been updated +by someone else while he was editing, the write will fail. +This is called a ``conflicting write.'' +The submission is still saved in the history, so that +the user can compare the page he submitted with the changes +that were made while he was editing. +.PP +Each version of each page is described by a text file containing +one or more metadata lines followed by the page contents. +The metadata lines begin with a capital letter specifying the type of data. +Currently the metadata types are: +.TP +.B D +The date this page was written, in decimal seconds since the epoch. +.TP +.B A +The author of this version of the page. Typically the rest of the line +takes the form +.I name +.IR ip-address . +.TP +.B X +This page's contents were submitted but rejected due to a +conflicting write. +.PD +After the metadata comes the actual page contents; each line of +page contents is prefixed with a +.B # +character. +.PP +The directory +.IB dir /d +contains all the wiki data. Typically it is world-writable +so that +.I wikifs +can run as none. +Each page on the wiki has a unique sequence number +.IR n ; +for each page, the +.B d +directory contains three files +.IR n , +.IB n .hist \fR, +and +.BI L .n \fR. +The file +.I n +holds the current version of the page: the first line of +.I n +is the page title, followed by page metadata and contents as described above. +The append-only file +.IB n .hist +holds the history of the page. +The first line of +.IB n .hist +is the title of the page. +The rest of the file is the metadata and contents of every +version of the page that has been submitted to the wiki. +.BI L .n +is a lock file for the page: it must be +held while reading or writing +.I n +and +.IB n .hist \fR. +The lock files allow multiple instances of +.I wikifs +to coexist peacefully. +Finally, the +.B map +file (with associated lock +.BR L.map ) +provides a mapping from +sequence numbers to +to page titles. +Each map line is a decimal +.IR n , +a single space, +and then the title. +Since titles are presented as names by +.IR wikifs , +they cannot contain slashes. +.PP +.I Wikifs +presents a three-level file system. +The top level contains per-page directories +named by the page titles with spaces turned +into underscores. +Each page also has a number associated with it +(see the discussion of the wiki data files below). +The number corresponding to a page may +also be used to access it, although directory +listings will always present the title. +The +.B new +file is used to add new or revised pages to the wiki: +writes to the file should be in the usual textual format: +a title line, metadata lines, and page contents. +Once all the contents have been written, a final zero-length +message should be written to mark the end of the page. +This last write will return an error if a conflicting +write has occurred. +After writing the file, the client may read from +.B new +to obtain the canonical title for the page, as presented +by the file system. +.PP +The page directories contain subdirectories representing +the history of the page, named +by the decimal time stamp corresponding to each version. +In addition to these history directories, +the page directories contain the following files: +.TP +.B current +The current raw data file for the page. +.TP +.B diff.html +A web page listing the contents of every version of +the page that has ever appeared on the wiki. +The text is grey by default: +differences between versions appear in black. +.TP +.B edit.html +A web form for editing the the current version of the page. +.TP +.B history.html +A web page listing the time stamps of the historical versions of the page. +Each time stamp links to a page showing just +that version. +.TP +.B history.txt +A textual formatting of the history. Each time stamp is prefixed with +the name of the directory corresponding to that version. +.TP +.B index.html +An HTML formatting of the current version of the page. +.TP +.B index.txt +A textual formatting of the current version of the page. +.TP +.B werror.html +An HTML error page to be returned by +.I wikipost +on conflicting writes. +.PD +.LP +The HTML files are generated from the templates with the same names +in +.IR dir , +except that +.B index.html +and +.B index.txt +are generated from the templates +.B page.html +and +.BR page.txt . +.PP +The history directories +are similar to the page directories but only contain +.BR current , +.BR index.html , +and +.BR index.txt . +This +.B index.html +and +.B index.txt +are generated from the templates +.B oldpage.html +and +.BR oldpage.txt . +.PP +The +.IR httpd (8) +helper program +.I wikipost +is used to process editing requests posted +to the web server by users. +It expects the posted form to contain these +(usually hidden) fields: +.BR TITLE , +the title of the page; +.BR VERSION , +the time stamp of the page that is being edited; +.BR service , +the service name associated with this wiki +.RI ( wikipost +looks for +.BI /srv/wiki. service \fR); +and +.BR base , +the base for wiki URLs in the response. +.PP +After mounting the wiki, +.I wikipost +writes a page update request to +.B /mnt/wiki/new +and then returns the contents of one HTML +file in +.BR /mnt/wiki/ title \fR. +If the write succeeds, +.I wikipost +returns +.BR index.html . +if the write fails due to a conflicting write, +.I wikipost +returns +.BR werror.html . +.SH EXAMPLE +The Plan 9 wiki at Bell Labs is started by running: +.EX +.ta +4n + wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/lib/wiki +.EE +.PP +The wiki is mounted for +.IR httpd (8) +by an entry in +.BR /lib/namespace.httpd : +.EX +.ta +4n + # wiki + mount -b #s/wiki.plan9 /usr/web/wiki/plan9 +.EE +Notice that the wiki service was explicitly posted with +mode 666 so that +.I httpd +(running as none) +would be able to mount it. +.PP +In the Plan 9 distribution, the directory +.B /sys/lib/wiki +contains sample files similar to those used +to start the current Plan 9 wiki. +.SH SOURCE +.B /sys/src/cmd/wikifs +.br +.B /sys/src/cmd/ip/httpd/wikipost.c +.SH SEE ALSO +The original wiki, +.B http://c2.com/cgi/wiki?WikiWikiWeb +.br +.B /acme/wiki/guide diff --git a/static/plan9-4e/man5/0intro.5 b/static/plan9-4e/man5/0intro.5 new file mode 100644 index 00000000..523538cd --- /dev/null +++ b/static/plan9-4e/man5/0intro.5 @@ -0,0 +1,603 @@ +.TH INTRO 5 +.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 +inside the kernel; the +.IR proc (3) +.I kernel device +is a part of the Plan 9 kernel that does this. +User programs can also act as servers. +.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. +A server's file tree is attached to a process +group's name space by +.IR bind (2) +and +.I mount +calls; +see +.IR intro (2). +Processes in the group are then clients +of the server: +system calls operating on files are translated into requests +and responses transmitted on the connection to the appropriate service. +.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 (6)). +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 (2) +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 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 [4] +.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 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 (2) +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 eight-byte qid +.IR path , +then the four-byte qid +.IR version . +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 +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 (2)). +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; instead calls to library +routines that access files are +translated by the mount driver, +.IR mnt (3), +into 9P messages. +.SH DIRECTORIES +Directories are created by +.B create +with +.B DMDIR +set in the permissions argument (see +.IR stat (5)). +The members of a directory can be found with +.IR read (5). +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" +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 (5) +and +.IR users (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. +(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 , +and (skipping one bit) +.BR QTAUTH . +The name +.BR QTFILE , +defined to be zero, +identifies the value of the type for a plain file. diff --git a/static/plan9-4e/man5/INDEX.5 b/static/plan9-4e/man5/INDEX.5 new file mode 100644 index 00000000..a3b62ae8 --- /dev/null +++ b/static/plan9-4e/man5/INDEX.5 @@ -0,0 +1,16 @@ +0intro 0intro +intro 0intro +attach attach +auth attach +clunk clunk +error error +flush flush +create open +open open +read read +write read +remove remove +stat stat +wstat stat +version version +walk walk diff --git a/static/plan9-4e/man5/INDEX.html.5 b/static/plan9-4e/man5/INDEX.html.5 new file mode 100644 index 00000000..35d30ca7 --- /dev/null +++ b/static/plan9-4e/man5/INDEX.html.5 @@ -0,0 +1,53 @@ + +plan 9 man section 5 + + +[manual index] +

Plan 9 from Bell Labs - Section 5 - Plan 9 File Protocol, 9P

+
+
+
0intro +- introduction to the Plan 9 File Protocol, 9P +
intro + +
attach +- messages to establish a connection +
attach, auth + +
clunk +- forget about a fid +
clunk + +
error +- return an error +
error + +
flush +- abort a message +
flush + +
open +- prepare a fid for I/O on an existing or new file +
open, create + +
read +- transfer data from and to a file +
read, write + +
remove +- remove a file from a server +
remove + +
stat +- inquire or change file attributes +
stat, wstat + +
version +- negotiate protocol version +
version + +
walk +- descend a directory hierarchy +
walk + +
diff --git a/static/plan9-4e/man5/Makefile b/static/plan9-4e/man5/Makefile new file mode 100644 index 00000000..0a0569ba --- /dev/null +++ b/static/plan9-4e/man5/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.5) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man5/attach.5 b/static/plan9-4e/man5/attach.5 new file mode 100644 index 00000000..dd21c6b6 --- /dev/null +++ b/static/plan9-4e/man5/attach.5 @@ -0,0 +1,159 @@ +.TH ATTACH 5 +.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 (5)) +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 +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 auth (2), +.IR fauth (2), +.IR version (5), +.IR authsrv (6) diff --git a/static/plan9-4e/man5/clunk.5 b/static/plan9-4e/man5/clunk.5 new file mode 100644 index 00000000..6256b3c4 --- /dev/null +++ b/static/plan9-4e/man5/clunk.5 @@ -0,0 +1,43 @@ +.TH CLUNK 5 +.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 +A +.B clunk +message is generated by +.I close +and indirectly by other actions such as failed +.I open +calls. diff --git a/static/plan9-4e/man5/error.5 b/static/plan9-4e/man5/error.5 new file mode 100644 index 00000000..288bfe7f --- /dev/null +++ b/static/plan9-4e/man5/error.5 @@ -0,0 +1,27 @@ +.TH ERROR 5 +.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 255 bytes, +defined as +.B ERRMAX +in +.BR . diff --git a/static/plan9-4e/man5/flush.5 b/static/plan9-4e/man5/flush.5 new file mode 100644 index 00000000..996c2b45 --- /dev/null +++ b/static/plan9-4e/man5/flush.5 @@ -0,0 +1,76 @@ +.TH FLUSH 5 +.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 (2), +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 must 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 +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. diff --git a/static/plan9-4e/man5/open.5 b/static/plan9-4e/man5/open.5 new file mode 100644 index 00000000..6672c694 --- /dev/null +++ b/static/plan9-4e/man5/open.5 @@ -0,0 +1,247 @@ +.TH OPEN 5 +.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 (5)), +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 create +system call +(see +.IR open (2)) +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 (5). +.SH ENTRY POINTS +.I Open +and +.I create +both generate +.B open +messages; only +.I create +generates a +.B create +message. +The +.B iounit +associated with an open file may be discovered by calling +.IR iounit (2). +.PP +For programs that need atomic file creation, without the race +that exists in the +.B open-create +sequence described above, +the kernel does the following. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.B create +system call, +the +.B open +message is not sent; the kernel issues only the +.BR create . +Thus, if the file exists, +.B create +will draw an error, but if it doesn't and the +.B create +system call succeeds, the process issuing the +.B create +is guaranteed to be the one that created the file. + diff --git a/static/plan9-4e/man5/read.5 b/static/plan9-4e/man5/read.5 new file mode 100644 index 00000000..4438ee98 --- /dev/null +++ b/static/plan9-4e/man5/read.5 @@ -0,0 +1,125 @@ +.TH READ 5 +.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 (5)), +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 (see +.IR seek (2)). +.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 (5), +if non-zero, reports the maximum size that is guaranteed +to be transferred atomically. +.SH ENTRY POINTS +.B Read +and +.B write +messages are generated by the corresponding calls. +Because they include an offset, the +.I pread +and +.I pwrite +calls correspond more directly to the 9P messages. +Although +.IR seek (2) +affects the offset, it does not generate a message. diff --git a/static/plan9-4e/man5/remove.5 b/static/plan9-4e/man5/remove.5 new file mode 100644 index 00000000..c6548bb3 --- /dev/null +++ b/static/plan9-4e/man5/remove.5 @@ -0,0 +1,35 @@ +.TH REMOVE 5 +.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. +.SH ENTRY POINTS +.B Remove +messages are generated by +.IR remove . diff --git a/static/plan9-4e/man5/stat.5 b/static/plan9-4e/man5/stat.5 new file mode 100644 index 00000000..90fdb80e --- /dev/null +++ b/static/plan9-4e/man5/stat.5 @@ -0,0 +1,291 @@ +.TH STAT 5 +.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 (2)) +convert between directory entries and a C structure called a +.BR Dir . +.PP +The +.I mode +contains permission bits as described in +.IR intro (5) +and the following: +.B 0x80000000 +.RB ( DMDIR , +this file is a directory), +.B 0x40000000 +.RB ( DMAPPEND , +append only), +.B 0x20000000 +.RB ( DMEXCL , +exclusive use); 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. +.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 (5) +for more information about permissions and +.IR users (6) +for 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 +.IR fsconfig (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 (5)). +.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 fstat +and +.IR stat . +.PP +.B Wstat +messages are generated by +.I fwstat +and +.IR wstat . +.SH BUGS +To make the contents of a directory, such as returned by +.IR read (5), +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/static/plan9-4e/man5/version.5 b/static/plan9-4e/man5/version.5 new file mode 100644 index 00000000..c7236e2e --- /dev/null +++ b/static/plan9-4e/man5/version.5 @@ -0,0 +1,101 @@ +.TH VERSION 5 +.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 +The +.B version +message is generated by the +.B fversion +system call. +It is also generated automatically, if required, by a +.B mount +or +.B fauth +system call on an uninitialized connection. diff --git a/static/plan9-4e/man5/walk.5 b/static/plan9-4e/man5/walk.5 new file mode 100644 index 00000000..61439459 --- /dev/null +++ b/static/plan9-4e/man5/walk.5 @@ -0,0 +1,178 @@ +.TH WALK 5 +.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 (5)). +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 (2). +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 +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. diff --git a/static/plan9-4e/man6/0intro.6 b/static/plan9-4e/man6/0intro.6 new file mode 100644 index 00000000..281f10b6 --- /dev/null +++ b/static/plan9-4e/man6/0intro.6 @@ -0,0 +1,8 @@ +.TH INTRO 6 +.SH NAME +intro \- introduction to file formats +.SH DESCRIPTION +This section of the manual describes file formats +and other miscellany such as +.I troff +macro packages. diff --git a/static/plan9-4e/man6/INDEX.6 b/static/plan9-4e/man6/INDEX.6 new file mode 100644 index 00000000..ca53e4de --- /dev/null +++ b/static/plan9-4e/man6/INDEX.6 @@ -0,0 +1,33 @@ +0intro 0intro +intro 0intro +a.out a.out +ar ar +authsrv authsrv +ticket authsrv +color color +face face +font font +subfont font +image image +keyboard keyboard +man man +map map +mpictures mpictures +ms ms +namespace namespace +ndb ndb +plot plot +plumb plumb +regexp regexp +rewrite rewrite +smtpd smtpd +snap snap +thumbprint thumbprint +users users +ASCII utf +UTF utf +Unicode utf +rune utf +utf utf +venti.conf venti.conf +vgadb vgadb diff --git a/static/plan9-4e/man6/INDEX.html.6 b/static/plan9-4e/man6/INDEX.html.6 new file mode 100644 index 00000000..70a18a72 --- /dev/null +++ b/static/plan9-4e/man6/INDEX.html.6 @@ -0,0 +1,113 @@ + +plan 9 man section 6 + + +[manual index] +

Plan 9 from Bell Labs - Section 6 - File Formats, Misc

+
+
+
0intro +- introduction to file formats +
intro + +
a.out +- object file format +
a.out + +
ar +- archive (library) file format +
ar + +
authsrv +- authentication service +
ticket + +
color +- representation of pixels and colors +
color + +
face +- face files +
face + +
font +- external format for fonts and subfonts +
font, subfont + +
image +- external format for images +
image + +
keyboard +- how to type characters +
keyboard + +
man +- macros to typeset manual +
man + +
map +- digitized map formats +
map + +
mpictures +- picture inclusion macros +
mpictures + +
ms +- macros for formatting manuscripts +
ms + +
namespace +- name space description file +
namespace + +
ndb +- Network database +
ndb + +
plot +- graphics interface +
plot + +
plumb +- format of plumb messages and rules +
plumb + +
regexp +- regular expression notation +
regexp + +
rewrite +- mail rewrite rules +
rewrite + +
smtpd +- SMTP listener configuration +
smtpd + +
snap +- process snapshots +
snap + +
thumbprint +- public key thumbprints +
thumbprint + +
users +- file server user list format +
users + +
utf +- character set and format +
UTF, Unicode, ASCII, rune + +
venti.conf +- a venti configuration file +
venti.conf + +
vgadb +- VGA controller and monitor database +
vgadb + +
diff --git a/static/plan9-4e/man6/Makefile b/static/plan9-4e/man6/Makefile new file mode 100644 index 00000000..cd649fe8 --- /dev/null +++ b/static/plan9-4e/man6/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.6) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man6/a.out.6 b/static/plan9-4e/man6/a.out.6 new file mode 100644 index 00000000..a4fa5db2 --- /dev/null +++ b/static/plan9-4e/man6/a.out.6 @@ -0,0 +1,252 @@ +.TH A.OUT 6 +.SH NAME +a.out \- object file format +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +An executable Plan 9 binary file has up to six sections: +a header, the program text, the data, +a symbol table, a PC/SP offset table (MC68020 only), +and finally a PC/line number table. +The header, given by a structure in +.BR , +contains 4-byte integers in big-endian order: +.PP +.EX +.ta \w'#define 'u +\w'_MAGIC(b) 'u +\w'_MAGIC(10) 'u +4n +4n +4n +4n +typedef struct Exec { + long magic; /* magic number */ + long text; /* size of text segment */ + long data; /* size of initialized data */ + long bss; /* size of uninitialized data */ + long syms; /* size of symbol table */ + long entry; /* entry point */ + long spsz; /* size of pc/sp offset table */ + long pcsz; /* size of pc/line number table */ +} Exec; +#define _MAGIC(b) ((((4*b)+0)*b)+7) +#define A_MAGIC _MAGIC(8) /* 68020 */ +#define I_MAGIC _MAGIC(11) /* intel 386 */ +#define J_MAGIC _MAGIC(12) /* intel 960 */ +#define K_MAGIC _MAGIC(13) /* sparc */ +#define V_MAGIC _MAGIC(16) /* mips 3000 */ +#define X_MAGIC _MAGIC(17) /* att dsp 3210 */ +#define M_MAGIC _MAGIC(18) /* mips 4000 */ +#define D_MAGIC _MAGIC(19) /* amd 29000 */ +#define E_MAGIC _MAGIC(20) /* arm 7-something */ +#define Q_MAGIC _MAGIC(21) /* powerpc */ +#define N_MAGIC _MAGIC(22) /* mips 4000 LE */ +#define L_MAGIC _MAGIC(23) /* dec alpha */ +.EE +.DT +.PP +Sizes are expressed in bytes. +The size of the header is not included in any of the other sizes. +.PP +When a Plan 9 binary file is executed, +a memory image of three segments is +set up: the text segment, the data segment, and the stack. +The text segment begins at a virtual address which is +a multiple of the machine-dependent page size. +The text segment consists of the header and the first +.B text +bytes of the binary file. +The +.B entry +field gives the virtual address of the entry point of the program. +The data segment starts at the first page-rounded virtual address +after the text segment. +It consists of the next +.B data +bytes of the binary file, followed by +.B bss +bytes initialized to zero. +The stack occupies the highest possible locations +in the core image, automatically growing downwards. +The bss segment may be extended by +.IR brk (2). +.PP +The next +.B syms +(possibly zero) +bytes of the file contain symbol table +entries, each laid out as: +.IP +.EX +uchar value[4]; +char type; +char name[\f2n\fP]; /* NUL-terminated */ +.EE +.PP +The +.B value +is in big-endian order and +the size of the +.B name +field is not pre-defined: it is a zero-terminated array of +variable length. +.PP +The +.B type +field is one of the following characters with the high bit set: +.RS +.TP +.B T +text segment symbol +.PD0 +.TP +.B t +static text segment symbol +.TP +.B L +leaf function text segment symbol +.TP +.B l +static leaf function text segment symbol +.TP +.B D +data segment symbol +.TP +.B d +static data segment symbol +.TP +.B B +bss segment symbol +.TP +.B b +static bss segment symbol +.TP +.B a +automatic (local) variable symbol +.TP +.B p +function parameter symbol +.RE +.PD +.PP +A few others are described below. +The symbols in the symbol table appear in the same order +as the program components they describe. +.PP +The Plan 9 compilers implement a virtual stack frame pointer rather +than dedicating a register; +moreover, on the MC680X0 architectures +there is a variable offset between the stack pointer and the +frame pointer. +Following the symbol table, +MC680X0 executable files contain a +.BR spsz -byte +table encoding the offset +of the stack frame pointer as a function of program location; +this section is not present for other architectures. +The PC/SP table is encoded as a byte stream. +By setting the PC to the base of the text segment +and the offset to zero and interpreting the stream, +the offset can be computed for any PC. +A byte value of 0 is followed by four bytes that hold, in big-endian order, +a constant to be added to the offset. +A byte value of 1 to 64 is multiplied by four and added, without sign +extension, to the offset. +A byte value of 65 to 128 is reduced by 64, multiplied by four, and +subtracted from the offset. +A byte value of 129 to 255 is reduced by 129, multiplied by the quantum +of instruction size +(e.g. two on the MC680X0), +and added to the current PC without changing the offset. +After any of these operations, the instruction quantum is added to the PC. +.PP +A similar table, occupying +.BR pcsz -bytes, +is the next section in an executable; it is present for all architectures. +The same algorithm may be run using this table to +recover the absolute source line number from a given program location. +The absolute line number (starting from zero) counts the newlines +in the C-preprocessed source seen by the compiler. +Three symbol types in the main symbol table facilitate conversion of the absolute +number to source file and line number: +.RS +.TP +.B f +source file name components +.TP +.B z +source file name +.TP +.B Z +source file line offset +.RE +.PP +The +.B f +symbol associates an integer (the +.B value +field of the `symbol') with +a unique file path name component (the +.B name +of the `symbol'). +These path components are used by the +.B z +symbol to represent a file name: the +first byte of the name field is always 0; the remaining +bytes hold a zero-terminated array of 16-bit values (in big-endian order) +that represent file name components from +.B f +symbols. +These components, when separated by slashes, form a file name. +The initial slash of a file name is recorded in the symbol table by an +.B f +symbol; when forming file names from +.B z +symbols an initial slash is not to be assumed. +The +.B z +symbols are clustered, one set for each object file in the program, +before any text symbols from that object file. +The set of +.B z +symbols for an object file form a +.I history stack +of the included source files from which the object file was compiled. +The value associated with each +.B z +symbol is the absolute line number at which that file was included in the source; +if the name associated with the +.B z +symbol is null, the symbol represents the end of an included file, that is, +a pop of the history stack. +If the value of the +.B z +symbol is 1 (one), +it represents the start of a new history stack. +To recover the source file and line number for a program location, +find the text symbol containing the location +and then the first history stack preceding the text symbol in the symbol table. +Next, interpret the PC/line offset table to discover the absolute line number +for the program location. +Using the line number, scan the history stack to find the set of source +files open at that location. +The line number within the file can be found using the line numbers +in the history stack. +The +.B Z +symbols correspond to +.B #line +directives in the source; they specify an adjustment to the line number +to be printed by the above algorithm. The offset is associated with the +first previous +.B z +symbol in the symbol table. +.SH "SEE ALSO" +.IR db (1), +.IR acid (1), +.IR 2a (1), +.IR 2l (1), +.IR nm (1), +.IR strip (1), +.IR mach (2), +.IR symbol (2) +.SH BUGS +There is no type information in the symbol table; however, the +.B -a +flags on the compilers will produce symbols for +.IR acid (1). diff --git a/static/plan9-4e/man6/ar.6 b/static/plan9-4e/man6/ar.6 new file mode 100644 index 00000000..669be073 --- /dev/null +++ b/static/plan9-4e/man6/ar.6 @@ -0,0 +1,99 @@ +.TH AR 6 +.SH NAME +ar \- archive (library) file format +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +The archive command +.IR ar (1) +is used to combine several files into +one. +Archives are used mainly as libraries to be searched +by the loaders +.IR 2l (1) +.I et al. +.PP +A file produced by +.I ar +has a magic string at the start, +followed by the constituent files, each preceded by a file header. +The magic number and header layout as described in the +include file are: +.IP +.EX +.ta \w'#define 'u +\w'SAR_HDR 'u +.ec % +#define ARMAG "!\n" +#define SARMAG 8 + +#define ARFMAG "`\n" + +struct ar_hdr { + char name[16]; + char date[12]; + char uid[6]; + char gid[6]; + char mode[8]; + char size[10]; + char fmag[2]; +}; +#define SAR_HDR 60 +.ec \ +.EE +.LP +The +.B name +is a blank-padded string. +The +.L fmag +field contains +.L ARFMAG +to help verify the presence of a header. +The other fields are left-adjusted, blank-padded numbers. +They are decimal except for +.LR mode , +which is octal. +The date is the modification date of the file (see +.IR stat (2)) +at the time of its insertion into the archive. +The mode is the low 9 bits of the file permission mode. +The length of the header is +.LR SAR_HDR . +Because the +.L ar_hdr +structure is padded in an architecture-dependent manner, +the structure should never be read or written as a unit; +instead, each field should be read or written independently. +.PP +Each file begins on an even (0 mod 2) boundary; +a newline is inserted between files if necessary. +Nevertheless +.B size +reflects the +actual size of the file exclusive of padding. +.PP +When all members of an archive are object files of +the same architecture, +.B ar +automatically adds an extra file, named +.BR __.SYMDEF , +as the first member of the archive. This file +contains an index used by the loaders to locate all +externally defined text and data symbols in the archive. +.PP +There is no provision for empty areas in an archive +file. +.SH "SEE ALSO" +.IR ar (1), +.IR 2l (1), +.IR nm (1), +.IR stat (2) +.SH BUGS +The +.B uid +and +.B gid +fields are unused in Plan 9. +They provide compatibility with Unix +.I ar +format. diff --git a/static/plan9-4e/man6/authsrv.6 b/static/plan9-4e/man6/authsrv.6 new file mode 100644 index 00000000..2638f631 --- /dev/null +++ b/static/plan9-4e/man6/authsrv.6 @@ -0,0 +1,373 @@ +.TH AUTHSRV 6 +.SH NAME +ticket \- authentication service +.SH DESCRIPTION +This manual page describes +the protocols used to authorize connections, confirm the identities +of users and machines, and maintain the associated databases. +The machine that provides these services is called the +.I authentication server +(AS). +The AS may be a stand-alone machine or a general-use machine such as a CPU server. +The network database +.IR ndb (6) +holds for each public machine, such as a CPU server or +file server, the name of the authentication server that machine uses. +.PP +Each machine contains three values important to authentication; a 56-bit DES +key, a 28-byte authentication ID, and a 48-byte authentication domain name. +The ID is a user name and identifies who is currently responsible for the +kernel running on that machine. +The domain name identifies the machines across which the ID is valid. +Together, the ID and domain name identify the owner of a key. +.PP +When a terminal boots, the user is prompted for user name and password. +The user name becomes the terminal's authentication ID. +The password is converted using +.I passtokey +(see +.IR auth (2)) +into a 56-bit DES key and saved as the machine's key. +The authentication domain is set to the null string. +If possible, the terminal validates the key with the AS +before saving it. +For Internet machines the correct AS to ask is found using +.IR dhcpd (8). +.PP +When a CPU or file server boots, it reads the key, ID, and domain name from +non-volatile RAM. +This allows servers to reboot without operator intervention. +.PP +The details of any authentication are mixed with the semantics +of the particular service they are authenticating so we describe +them one case at a time. The following definitions will be used +in the descriptions: +.TF nullx +.TP +.I \fICHc\fP +an 8-byte random challenge from a client +.TP +.I CHs +an 8-byte random challenge from a server +.TP +.I \fIKs\fP +server's key +.TP +.I \fIKc\fP +client's key +.TP +.I \fIKn\fP +a nonce key created for a ticket +.TP +.I K\fP\fIm\fP +message m +encrypted with key K +.TP +.I \fIIDs\fP +server's ID +.TP +.I \fIDNs\fP +server's authentication domain name +.TP +.I \fIIDc\fP +client's ID +.TP +.I \fIUIDc\fP +user's name on the client +.TP +.I \fIUIDs\fP +user's name on the server +.PD +.PP +A number of constants defined in +.B auth.h +are also used: +.IR AuthTreq, +.IR AuthChal, +.IR AuthOK, +.IR AuthErr, +.IR AuthTs, +.IR AuthTc, +.IR AuthAs, +and +.IR AuthAc . +.SS "File Service" +File service sessions are long-lived connections between a client host +and a file server. +Processes belonging to different users share the session. +Whenever a user process on the client +.I mounts +a file server +(see +.IR bind (2)), +it must authenticate itself. +There are four players in an authentication: the server, the client kernel, +the user process on the client, and the authentication server. +The goal of the authentication protocol is to convince the server +that the client may validly speak for the user process. +.PP +To reduce the number of messages for each authentication, +common information is exchanged once at the +beginning of the session within a +.I session +message +(see +.IR attach (5)): +.TF "Client→Server" +.TP +.IR Client → Server +Tsession( \fICHc\fP ) +.TP +.IR Server → Client +Rsession( \fICHs\fP, \fIIDs\fP, \fIDNs\fP ) +.PD +.PP +Each time a user mounts a file server connection, an attach +message is sent identifying/authenticating the user: +.TF "Client→Server" +.TP +.IR Client → Server +Tattach( \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, \fIcount\fP } ) +.TP +.IR Server → Client +Rattach( \fIKn\fP{ AuthAs, \fICHc\fP, \fIcount\fP } ) +.PD +.PP +The part of the attach request encrypted with +.BR \fIKs\fP +is called a +.IR ticket . +Since it is encrypted in the server's secret key, this message is guaranteed +to have originated on the AS. +The part encrypted with the +.B \fIKn\fP +found in the ticket is called an +.IR authenticator . +The authenticator is generated by the client kernel and guarantees that +the ticket was not stolen. +The +.I count +is incremented with each mount to make every authenticator unique, +thus foiling replay attacks. +The server is itself authenticated by the authenticator +it sends as a reply to the attach. +.PP +Tickets are created by the AS at the request of a user process. +The AS contains a database of which \fIIDc\fP's may speak for which \fIUIDc\fP's. +If the \fIIDc\fP may speak for the \fIUIDc\fP, two tickets are returned. +.TF "UserProc→AS" +.TP +.IR UserProc → AS +\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP +.TP +.IR AS → UserProc +\fIAuthOK\fP, \fIKc\fP{ \fIAuthTc\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP } +.PD +.PP +Otherwise an error message is returned. +.TF "UserProc→AS" +.TP +.IR AS → UserProc +\fIAuthErr\fP, 64-byte error string +.PD +.PP +The user passes both tickets to the client's kernel using +the +.I fauth +system call +(see +.IR fauth (2)). +The kernel decrypts the ticket encrypted with \fIKc\fP. +If \fIUIDc\fP +matches the user's login ID, the tickets are remembered for +any subsequent attaches by that user of that file server session. +Otherwise, the ticket is assumed stolen and an error is returned. +.SS "Remote Execution" +.PP +A number of applications require a process on one machine to start +a process with the same user ID on a server machine. +Examples are +.IR cpu (1), +.I rx +(see +.IR con (1)), +and +.IR exportfs (4). +The called process replies to the connection with a ticket request. +.TF "Server→UserProc" +.TP +.IR Server → UserProc +\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, xxx, xxx +.PD +.PP +Here +.I xxx +indicates a field whose contents do not matter. +.PP +The calling process adds its machine's \fIIDc\fP and its \fIUIDc\fP to the request +and follows the protocol outlined above to get two tickets from the AS. +The process passes the +\fIKs\fP +encrypted ticket plus an authenticator generated by +.B /dev/authenticator +from the +\fIKc\fP +ticket to the remote server, which writes them to the +kernel to set the user ID (see +.IR cons (3)). +The server replies with its own authenticator which can be written +to the kernel along with the +\fIKc\fP +encrypted ticket to confirm the server's identity (see +.IR cons (3)). +.TF "UserProc→Server" +.TP +.IR UserProc → Server +\fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, 0 } +.TP +.IR Server → UserProc +\fIKn\fP{ \fIAuthAs\fP, \fICHs\fP, 0 } +.PD +.SS "Challenge Box" +A user may also start a process on a CPU server from a non Plan 9 +machine using commands such as +.IR con, +.IR telnet, +or +.I ftp +(see +.IR con (1) +and +.IR ftpfs (4)). +In these situations, the user can authenticate using a hand-held +DES encryptor. +The telnet or FTP daemon first sends a ticket request to the +authentication server. +If the AS has keys for both the \fIIDc\fP and \fIUIDc\fP in the ticket +request it returns a challenge as a hexadecimal number. +.TF "Daemon→AS" +.TP +.IR Daemon → AS +\fIAuthChal\fP, \fICHc\fP, \fIIDc\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP +.TP +.IR AS → Daemon +\fIAuthOK\fP, 16-byte +.SM ASCII +challenge +.PD +.PP +Otherwise, it returns a null-terminated 64-byte error string. +.TF "Daemon→AS" +.TP +.IR AS → Daemon +\fIAuthErr\fP, 64-byte error string +.PD +.PP +The daemon relays the challenge to the calling program, +which displays the challenge on the user's screen. +The user encrypts it and types in the +result, which is relayed back to the AS. +The AS checks it against the expected response and returns +either a ticket or an error. +.TF "Daemon→AS" +.TP +.IR Daemon → AS +16-byte +.SM ASCII +response +.TP +.IR AS → Daemon +\fIAuthOK\fP, \fIKc\fP{ \fIAuthTs\fP, \fICHc\fP, \fIUIDc\fP, \fIUIDc\fP, \fIKn\fP } +.PD +.PP +or +.TF "Daemon→AS" +.TP +.IR AS → Daemon +\fIAuthErr\fP, 64-byte error string +.PD +.PP +Finally, the daemon passes the ticket to the kernel +to set the user ID (see +.IR cons (3)). +.SS "Password Change" +Any user can change the key stored for him or her on the AS. +Once again we start by passing a ticket request to the AS. +Only the user ID in the request is meaningful. +The AS replies with a single ticket (or an error message) +encrypted in the user's personal key. +The user encrypts both the old and new keys with the +\fIKn\fP from the returned ticket and sends that back to the AS. +The AS checks the reply for validity and replies with an +\fIAuthOK\fP byte or an error message. +.TF "UserProc→AS" +.TP +.IR UserProc → AS +\fIAuthPass\fP, xxx, xxx, xxx, xxx, \fIUIDc\fP +.TP +.IR AS → UserProc +\fIAuthOK\fP, \fIKc\fP{ \fIAuthTp\fR, xxx, xxx, xxx, \fIKn\fP } +.TP +.IR UserProc → AS +\fIKn\fP{ \fIAuthPass\fP, "old password", "new password" } +.TP +.IR AS → UserProc +\fIAuthOK\fP +.PD +.PP +or +.TF "UserProc→AS" +.TP +.IR AS → UserProc +\fIAuthErr\fP, 64-byte error string +.PD +.PP +.SS "Data Base" +An +.IR ndb (2) +database file exists for the authentication server. +The attribute types used by the AS are +.B hostid +and +.BR uid . +The value in the +.B hostid +is a client host's ID. +The values in the +.B uid +pairs in the same entry list which users that host ID +make speak for. +A uid value of +.B * +means the host ID may speak for all users. +A uid value of +.BI ! user +means the host ID may not speak for +.IR user . +For example: +.EX +hostid=bootes + uid=!sys uid=!adm uid=* +.EE +.PP +is interpreted as +.B bootes +may speak for any user except +.B sys +and +.BR adm . +.SH FILES +.TF /lib/ndb/auth.*xxx +.TP +.B /lib/ndb/auth +database file +.TP +.B /lib/ndb/auth.* +hash files for +.B /lib/ndb/auth +.SH SEE ALSO +.IR auth (2), +.IR fauth (2), +.IR cons (3), +.IR attach (5), +.IR auth (8) diff --git a/static/plan9-4e/man6/color.6 b/static/plan9-4e/man6/color.6 new file mode 100644 index 00000000..aedaee58 --- /dev/null +++ b/static/plan9-4e/man6/color.6 @@ -0,0 +1,150 @@ +.TH COLOR 6 +.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 (2). +The function +.B setalpha +(see +.IR allocimage (2)) +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 (2). +.SH "SEE ALSO" +.IR color (2), +.IR graphics (2), +.IR draw (2) diff --git a/static/plan9-4e/man6/face.6 b/static/plan9-4e/man6/face.6 new file mode 100644 index 00000000..cfb78565 --- /dev/null +++ b/static/plan9-4e/man6/face.6 @@ -0,0 +1,114 @@ +.TH FACE 6 +.SH NAME +face \- face files +.SH DESCRIPTION +The directory +.B /lib/face +contains a hierarchy of images of people. +In that directory 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 (6)). +The small files are the `icons' displayed by +.B faces +and +.B seemail +(see +.IR faces (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, as recorded in +.BR /sys/log/mail . +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 (6) diff --git a/static/plan9-4e/man6/font.6 b/static/plan9-4e/man6/font.6 new file mode 100644 index 00000000..7b2429a9 --- /dev/null +++ b/static/plan9-4e/man6/font.6 @@ -0,0 +1,87 @@ +.TH FONT 6 +.SH NAME +font, subfont \- external format for fonts and subfonts +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Fonts and subfonts are described in +.IR cachechars (2). +.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 (2)). +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 (2)). +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 (6). +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 (2)) +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 (2), +.IR draw (2), +.IR cachechars (2), +.IR subfont (2) diff --git a/static/plan9-4e/man6/image.6 b/static/plan9-4e/man6/image.6 new file mode 100644 index 00000000..31560891 --- /dev/null +++ b/static/plan9-4e/man6/image.6 @@ -0,0 +1,205 @@ +.TH IMAGE 6 +.SH NAME +image \- external format for images +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Images are described in +.IR graphics (2), +and the definition of pixel values is in +.IR color (6). +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 (2)), or +.B readmemimage +and +.B writememimage +(see +.IR memdraw (2)). +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 (2) +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 (2) +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 (6) +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 +.IR faces (1) +and +.IR face (6)) +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 (2), +.IR draw (2), +.IR allocimage (2), +.IR color (6), +.IR face (6), +.IR font (6) diff --git a/static/plan9-4e/man6/keyboard.6 b/static/plan9-4e/man6/keyboard.6 new file mode 100644 index 00000000..308b9ac2 --- /dev/null +++ b/static/plan9-4e/man6/keyboard.6 @@ -0,0 +1,198 @@ +.TH KEYBOARD 6 +.SH NAME +keyboard \- how to type characters +.SH DESCRIPTION +Keyboards are idiosyncratic. +It should be obvious how to type ordinary +.SM ASCII +characters, +backspace, tab, escape, and newline. +In Plan 9, the key labeled +.B Return +or +.B Enter +generates a newline +.RB ( 0x0A ); +if there is a key labeled +.B Line +.BR Feed , +it generates a carriage return +.RB ( 0x0D ); +Plan 9 eschews CRLFs. +All control characters are typed in the usual way; +in particular, control-J is a line feed and control-M a carriage return. +On the PC and some other machines, the key labeled +.B Caps +.B Lock +acts as an additional control key, +and the key labeled +.B End +acts a line feed key. +.PP +The delete character +.RB ( 0x7F ) +may be generated by a different key, +one near the extreme upper right of the keyboard. +On the Next it is the key labeled +.L * +(not the asterisk above the 8). +On the SLC and Sparcstation 2, delete is labeled +.B Num +.B Lock +(the key above +.B Backspace +labeled +.B Delete +functions as an additional backspace key). +On the other keyboards, the key labeled +.B Del +or +.B Delete +generates the delete character. +.PP +The view character +.RB ( 0x80 ), +used by +.IR rio (1), +.IR acme (1), +and +.IR sam (1), +causes windows to scroll forward. +It is generally somewhere near the lower right of the main key area. +The scroll character is generated by the +.B VIEW +key on the Gnot, the +.B Alt +.B Graph +key on the SLC, and the arrow key ↓ +on the other terminals. +As a convenience for sloppy typists, some programs interpret → and ← keys, +which lie on either side of ↓, as view keys as well. +The arrow key ↑ scrolls backward. +.PP +Characters in Plan 9 are runes (see +.IR utf (6)). +Any 16-bit rune can be typed using a compose key followed by several +other keys. +The compose key is also generally near the lower right of the main key area: +the +.B NUM PAD +key on the Gnot, the +.B Alternate +key on the Next, the +.B Compose +key on the SLC, the +.B Option +key on the Magnum, and either +.B Alt +key on the PC. +After typing the compose key, type a capital +.L X +and exactly four hexadecimal characters (digits and +.L a +to +.LR f ) +to type a single rune with the value represented by +the typed number. +There are shorthands for many characters, comprising +the compose key followed by a two- or three-character sequence. +There are several rules guiding the design of the sequences, as +illustrated by the following examples. +The full list is too long to repeat here, but is contained in the file +.L /lib/keyboard +in a format suitable for +.IR grep (1) +or +.IR look (1). +.IP +A repeated symbol gives a variant of that symbol, e.g., +.B ?? +yields ¿\|. +.IP +.SM ASCII +digraphs for mathematical operators give the corresponding operator, e.g., +.B <= +yields ≤. +.IP +Two letters give the corresponding ligature, e.g., +.B AE +yields Æ. +.IP +Mathematical and other symbols are given by abbreviations for their names, e.g., +.B pg +yields ¶. +.IP +Chess pieces are given by a +.B w +or +.B b +followed by a letter for the piece +.RB ( k +for king, +.B q +for queen, +.B r +for rook, +.B n +for knight, +.B b +for bishop, or +.B p +for pawn), +e.g., +.B wk +for a white king. +.IP +Greek letters are given by an asterisk followed by a corresponding latin letter, +e.g., +.B *d +yields δ. +.IP +Cyrillic letters are given by an at sign followed by a corresponding latin letter or letters, +e.g., +.B @ya +yields я. +.IP +Script letters are given by a dollar sign followed by the corresponding regular letter, +e.g., +.B $F +yields ℱ. +.IP +A digraph of a symbol followed by a letter gives the letter with an accent that looks like the symbol, e.g., +.B ,c +yields ç. +.IP +Two digits give the fraction with that numerator and denominator, e.g., +.B 12 +yields ½. +.IP +The letter s followed by a character gives that character as a superscript, e.g., +.B s1 +yields ⁱ. +These characters are taken from the Unicode block 0x2070; the 1, 2, and 3 +superscripts in the Latin-1 block are available by using a capital S instead of s. +.IP +Sometimes a pair of characters give a symbol related to the superimposition of the characters, e.g., +.B cO +yields ©. +.IP +A mnemonic letter followed by $ gives a currency symbol, e.g., +.B l$ +yields £. +.PP +Note the difference between ß (ss) and µ (micron) and +the Greek β and μ. +.SH FILES +.TF "/lib/keyboard " +.TP +.B /lib/keyboard +sorted table of characters and keyboard sequences +.SH "SEE ALSO" +.IR intro (1), +.IR ascii (1), +.IR tcs (1), +.IR acme (1), +.IR rio (1), +.IR sam (1), +.IR cons (3), +.IR utf (6) diff --git a/static/plan9-4e/man6/man.6 b/static/plan9-4e/man6/man.6 new file mode 100644 index 00000000..09d5455f --- /dev/null +++ b/static/plan9-4e/man6/man.6 @@ -0,0 +1,249 @@ +.TH MAN 6 +.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/static/plan9-4e/man6/map.6 b/static/plan9-4e/man6/map.6 new file mode 100644 index 00000000..d767065a --- /dev/null +++ b/static/plan9-4e/man6/map.6 @@ -0,0 +1,87 @@ +.TH MAP 6 +.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/static/plan9-4e/man6/mpictures.6 b/static/plan9-4e/man6/mpictures.6 new file mode 100644 index 00000000..7100118f --- /dev/null +++ b/static/plan9-4e/man6/mpictures.6 @@ -0,0 +1,151 @@ +.TH MPICTURES 6 +.SH NAME +mpictures \- picture inclusion macros +.SH SYNOPSIS +.B troff -mpictures +[ +.I options +] +.I file ... +.SH DESCRIPTION +.I Mpictures +macros insert PostScript pictures into +.IR troff (1) +documents. +The macros are: +.TP +.BI .BP " source height width position offset flags label +Define a frame and place a picture in it. +Null arguments, represented by \f5""\fR, +are interpreted as defaults. +The arguments are: +.RS +.TP +.I source +Name of a PostScript picture file, optionally +suffixed with +.RI ( n ) +to select page number +.I n +from the file (first page by default). +.PD0 +.TP +.I height +Vertical size of the frame, default +.BR 3.0i . +.TP +.I width +Horizontal size of the frame, current line length by default. +.TP +.I position +.L l +(default), +.LR c , +or +.L r +to left-justify, center, or right-justify the frame. +.TP +.I offset +Move the frame horizontally from the original +.I position +by this amount, default +.BR 0i . +.TP +.I flags +One or more of: +.RS +.PD 0v +.TP +.BI a d +Rotate the picture clockwise +.I d +degrees, default +.IR d =90. +.TP +.B o +Outline the picture with a box. +.TP +.B s +Freely scale both picture dimensions. +.TP +.B w +White out the area to be occupied by the picture. +.TP +.BR l , r , t ,\fPb +Attach the picture to the left right, top, or bottom of the frame. +.RE +.TP +.I label +Place +.I label +at distance +.B 1.5v +below the frame. +.PD +.PP +If there's room, +.B .BP +fills text around the frame. +Everything destined for either side of the frame +goes into a diversion to be retrieved when the accumulated +text sweeps past the trap set by +.B .BP +or when the diversion is explicitly closed +by +.BR .EP . +.RE +.TP +.BI .PI " source height" , width , "yoffset\fB,\fPxoffset flags. +This low-level macro, used by +.BR .BP , +can help do more complex things. +The two arguments not already described are: +.RS +.TP +.I xoffset +Offset the frame from the left margin by this amount, default +.BR 0i . +.PD0 +.TP +.I yoffset +Offset the frame from the current baseline, +measuring positive downward, default +.BR 0i . +.PD +.RE +.TP +.B .EP +End a picture started by +.BR .BP ; +.B .EP +is usually called implicitly by a trap +at frame bottom. +.PP +If a PostScript file lacks page-delimiting comments, +the entire file is included. +If no +.B %%BoundingBox +comment is present, the picture is +assumed to fill an 8.5\(mu11-inch page. +Nothing prevents the picture from being placed off the page. +.SH SEE ALSO +.IR troff (1) +.SH DIAGNOSTICS +A picture file that can't be read by the PostScript +postprocessor is replaced by white space. +.SH BUGS +A picture and associated text silently disappear if +a diversion trap set by +.B .BP +isn't reached. +Call +.B .EP +at the end of the document to retrieve it. +.br +Macros in other packages may break the adjustments +made to the line length and indent when text is being placed +around a picture. +.br +A missing or improper +.B %%BoundingBox +comment may cause the frame to be filled incorrectly. diff --git a/static/plan9-4e/man6/ms.6 b/static/plan9-4e/man6/ms.6 new file mode 100644 index 00000000..66b10395 --- /dev/null +++ b/static/plan9-4e/man6/ms.6 @@ -0,0 +1,308 @@ +.TH MS 6 +.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/static/plan9-4e/man6/namespace.6 b/static/plan9-4e/man6/namespace.6 new file mode 100644 index 00000000..09a0b562 --- /dev/null +++ b/static/plan9-4e/man6/namespace.6 @@ -0,0 +1,82 @@ +.TH NAMESPACE 6 +.SH NAME +namespace \- name space description file +.SH DESCRIPTION +Namespace files describe how to construct a name space from scratch, +an operation normally performed by the +.I newns +subroutine +(see +.IR auth (2)) +which is typically called by +.IR init (8). +Each line specifies one name space operation. +Spaces and tabs separate arguments to operations; +no quotes or escapes are recognized. +Blank lines and lines with +.B # +as the first non-space character are ignored. +Environment variables of the form +.BI $ name +are expanded within arguments, +where +.I name +is a +.SM UTF +string terminated by white space, a +.BR / , +or a +.BR $ . +.PP +The known operations and their arguments are: +.TF 0 +.TP +.BR mount \ [ -abcC ]\ \fIservename\ old " \fR[\fIspec\fR\^\^] +Mount +.I servename +on +.IR old . +.TP +.BR bind \ [ -abcC "] \fInew old +Bind +.I new +on +.IR old . +.TP +.BR import \ [ -abc ]\ \fIhost\fR\ "[\fIremotepath\fR\^\^] \fImountpoint\fR +Import +.I remotepath +from machine +.I server +and attach it to +.IR mountpoint . +.TP +.BI cd \ dir +Change the working directory to +.IR dir . +.TP +.BR unmount \ [ \fInew\fR ]\ \fIold +Unmount +.I new +from +.IR old , +or everything mounted on +.I old +if +.I new +is missing. +.PD +.PP +The options for +.IR bind , +.IR mount , +and +.I import +are interpreted as in +.IR bind (1) +and +.IR import (4). +.SH "SEE ALSO" +.IR bind (1), +.IR namespace (4), +.IR init (8) diff --git a/static/plan9-4e/man6/ndb.6 b/static/plan9-4e/man6/ndb.6 new file mode 100644 index 00000000..00d3821e --- /dev/null +++ b/static/plan9-4e/man6/ndb.6 @@ -0,0 +1,285 @@ +.TH NDB 6 +.SH NAME +ndb \- Network database +.SH DESCRIPTION +.PP +The network database consists of files +describing machines known to the local +installation and machines known publicly. +The files comprise multi-line tuples made up of +attribute/value pairs of the form +.IB attr = value +or sometimes just +.IR attr . +Each line starting without white space starts a new tuple. +Lines starting with +.B # +are comments. +.PP +The file +.B /lib/ndb/local +is the root of the database. +Other files are included in the +database if a tuple with an +attribute-value pair of attribute +.B database +and no value exists in +.BR /lib/ndb/local . +Within the +.B database +tuple, +each pair with attribute +.B file +identifies a file to be included in the database. The files are searched +in the order they appear. +For example: +.IP +.EX +database= + file=/lib/ndb/common + file=/lib/ndb/local + file=/lib/ndb/global +.EE +.PP +declares the database to be composed of the three files +.BR /lib/ndb/common , +.BR /lib/ndb/local , +and +.BR /lib/ndb/global . +By default, +.B /lib/ndb/local +is searched before the others. +However, +.B /lib/ndb/local +may be included in the +.B database +to redefine its ordering. +.PP +Within tuples, pairs on the same line bind tighter than +pairs on different lines. +.PP +Programs search the database directly using the routines in +.IR ndb (2) +or indirectly using +.B ndb/cs +and +.B ndb/dns +(see +.IR ndb (8)). +Both +.B ndb/cs +and the routine +.I ndbipinfo +impose structure on the otherwise flat database by using +knowledge specific to the network. +The internet is made up of networks which can be subnetted +multiple times. A network must have an +.B ipnet +attribute and is uniquely identified by the values of it's +.B ip +and +.B ipmask +attributes. If the +.B ipmask +is missing, the relevant Class A, B or C one is used. +The network is subnetted if one or more +.BR ipsubmask 's +are specified. +A search for an attribute associated with a network or host starts +at the top-level Class A, B, or C network and works it's way down to the +specific entry. The attribute/value chosen is the one lowest down in the +search, i.e, closest to the host. +For example, consider at the following entries: +.IP +.EX +ipnet=murray-hill ip=135.104.0.0 ipmask=255.255.0.0 + ipsubmask=255.255.255.0 + dns=135.104.10.1 + ntp=ntp.cs.bell-labs.com +ipnet=plan9 ip=135.104.9.0 ipmask=255.255.255.0 + ntp=oncore.cs.bell-labs.com + smtp=smtp1.cs.bell-labs.com +ip=135.104.9.6 sys=anna dom=anna.cs.bell-labs.com + smtp=smtp2.cs.bell-labs.com +.EE +.LP +Here +.B anna +is on the subnet +.B plan9 +which is in turn on the class B net +.BR murray-hill . +If one were to search for +.BR anna 's +.B NTP +and +.B SMTP +servers, one would get +.B oncore.cs.bell-labs.com +and +.B smtp2.cs.bell-labs.com +respectively. +.PP +.I Ndb/cs +can be made to perform such network aware +searches by using metanames in the dialstring. +A metaname is a +.I $ +followed by an attribute name. +.I Ndb/cs +looks up the attribute relative to the system it is running +on. Thus, with the above example, if a program called +.IP +.EX + dial("tcp!$smtp!smtp", 0, 0, 0); +.EE +.LP +the dial would connect to the SMTP port of +.BR smtp2.cs.bell-labs.com . +.PP +A number of attributes are meaningful to programs and thus +reserved. +They are: +.TF restricted +.TP +.B sys +system name +.TP +.B dom +Internet domain name +.TP +.B ip +Internet address +.TP +.B ether +Ethernet address +.TP +.B bootf +file to download for initial bootstrap +.TP +.B ipnet +Internet network name +.TP +.B ipmask +Internet network mask +.TP +.B ipsubmask +Internet network mask of this network's subnets +.TP +.B ipgw +Internet gateway +.TP +.B auth +authentication server to be used +.TP +.B fs +file server to be used +.TP +.B tcp +a TCP service name +.TP +.B udp +a UDP service name +.TP +.B il +an IL service name +.TP +.B port +a TCP, UDP, or IL port number +.TP +.B restricted +a TCP service that can be called only by ports numbered +less that 1024 +.TP +.B proto +a protocol supported by a host. +The pair +.B proto=il +is needed by +.I cs +(see +.IR ndb (8)) +in tuples for hosts that support the IL protocol +.TP +.B dnsdomain +a domain name that +.I ndb/dns +adds onto any unrooted names when doing a search +There may be multiple +.B dnsdomain +pairs. +.TP +.B dns +a DNS server to use (for DNS and DHCP) +.TP +.B ntp +an NTP server to use (for DHCP) +.TP +.B smtp +an SMTP server to use (for DHCP) +.TP +.B time +a time server to use (for DHCP) +.TP +.B wins +a Windows name server (for DHCP) +.TP +.B mx +mail exchanger (for DNS and DHCP) +.TP +.B soa +start of area (for DNS) +.sp +.PD +.PP +The file +.B /lib/ndb/auth +is used during authentication to decide who has the power to `speak for' other +users; see +.IR authsrv (6). +.SH EXAMPLES +.LP +A tuple for the CPU server, spindle. +.LP +.EX +sys = spindle + dom=spindle.research.bell-labs.com + bootf=/mips/9powerboot + ip=135.104.117.32 ether=080069020677 + proto=il +.EE +.LP +Entries for the network +.B mh-astro-net +and its subnets. +.LP +.EX +ipnet=mh-astro-net ip=135.104.0.0 ipmask=255.255.255.0 + fs=bootes.research.bell-labs.com + ipgw=r70.research.bell-labs.com + auth=p9auth.research.bell-labs.com +ipnet=unix-room ip=135.104.117.0 + ipgw=135.104.117.1 +ipnet=third-floor ip=135.104.51.0 + ipgw=135.104.51.1 +.EE +.LP +Mappings between TCP service names and port numbers. +.LP +.EX +.ta \w'\fLtcp=sysmonxxxxx'u \w'\fLtcp=sysmonxxxxxport=512xxx'u +tcp=sysmon port=401 +tcp=rexec port=512 restricted +tcp=9fs port=564 +.EE +.SH FILES +.TP +.B /lib/ndb/local +first database file searched +.SH "SEE ALSO" +.IR dial (2), +.IR ndb (2), +.IR ndb (8), +.IR dhcpd (8), +.IR ipconfig (8), +.IR con (1) diff --git a/static/plan9-4e/man6/plot.6 b/static/plan9-4e/man6/plot.6 new file mode 100644 index 00000000..73edcf0e --- /dev/null +++ b/static/plan9-4e/man6/plot.6 @@ -0,0 +1,336 @@ +.TH PLOT 6 +.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/static/plan9-4e/man6/plumb.6 b/static/plan9-4e/man6/plumb.6 new file mode 100644 index 00000000..bc58a506 --- /dev/null +++ b/static/plan9-4e/man6/plumb.6 @@ -0,0 +1,417 @@ +.TH PLUMB 6 +.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 (2) +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 (2)) +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 (2), +.IR plumber (4), +.IR regexp (6) diff --git a/static/plan9-4e/man6/regexp.6 b/static/plan9-4e/man6/regexp.6 new file mode 100644 index 00000000..58cc2ee1 --- /dev/null +++ b/static/plan9-4e/man6/regexp.6 @@ -0,0 +1,129 @@ +.TH REGEXP 6 +.SH NAME +regexp \- regular expression notation +.SH DESCRIPTION +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 awk (1), +.IR ed (1), +.IR grep (1), +.IR sam (1), +.IR sed (1), +.IR regexp (2) diff --git a/static/plan9-4e/man6/rewrite.6 b/static/plan9-4e/man6/rewrite.6 new file mode 100644 index 00000000..c54032c3 --- /dev/null +++ b/static/plan9-4e/man6/rewrite.6 @@ -0,0 +1,154 @@ +.TH REWRITE 6 +.SH NAME +rewrite \- mail rewrite rules +.SH SYNOPSIS +.B /mail/lib/rewrite +.SH DESCRIPTION +.IR Mail (1) +uses rewrite rules to convert mail destinations into +commands used to dispose of the mail. +Each line of the file +.F /mail/lib/rewrite +is a rule. +Blank lines and lines beginning with +.B # +are ignored. +.PP +Each rewriting rule consists of (up to) 4 strings: +.TF pattern +.TP +.I pattern +A regular expression in the style of +.IR regexp (6). +The +.I pattern +is applied to mail destination addresses. +The pattern match is case-insensitive +and must match the entire address. +.TP +.I type +The type of rule; see below. +.TP +.I arg1 +An +.IR ed (1) +style replacement string, with +.BI \e n +standing for the text matched by the +.IR n th +parenthesized subpattern. +.TP +.I arg2 +Another +.IR ed (1) +style replacement string. +.PD +.PP +In each of these fields the substring +.B \es +is replaced by the login id of the +sender and the substring +.B \el +is replaced by the name of the local machine. +.PP +When delivering a message, +.I mail +starts with the first rule and continues down the list until a pattern +matches the destination address. +It then performs one of the following actions depending on the +.I type +of the rule: +.TF alias +.TP +.B >> +Append the mail to the file indicated by expanding +.IR arg1 , +provided that file appears to be a valid mailbox. +.TP +.B | +Pipe the mail through the command formed from concatenating the +expanded +.I arg1 +and +.IR arg2 . +.TP +.B alias +Replace the address by the address(es) specified +by expanding +.I arg1 +and recur. +.TP +.B translate +Replace the address by the address(es) output by the +command formed by expanding +.I arg1 +and recur. +.PD +.PP +.I Mail +expands the addresses recursively until each address has matched a +.B >> +or +.B | +rule or until the recursion depth indicates a rewriting loop +(currently 32). +.PD +.PP +If +.IR mail (1) +is called with more than one address and +several addresses match +.B | +rules and result in the same +expanded +.IR arg1 , +the message is delivered to all those addresses +by a single command, +composed by concatenating the common expanded +.I arg1 +and each expanded +.IR arg2 . +This mail bundling is performed to reduce the number +of times the same message is transmitted across a +network. For example, with the following +rewrite rule +.PP +.EX + ([^!]*\.bell-labs\.com)!(.*) | "/mail/lib/qmail '\es' 'net!\e1'" "'\e2'" +.EE +.PP +if user +.B presotto +runs the command +.PP +.EX + % mail plan9.bell-labs.com!ken plan9.bell-labs.com!rob +.EE +.PP +there will follow only one execution of the command +.PP +.EX + /mail/lib/qmail presotto net!plan9.bell-labs.com ken rob +.EE +.PP +Here +.B /mail/lib/qmail +is an +.IR rc (1) +script used for locally queuing remote mail. +.PP +In the event of an error, the disposition of the mail depends on the name of the +command executing the rewrite. If the command is called +.B mail +and is run by +.BR $user , +the command will print an error and deposit the message in +.BR /mail/box/$user/dead.letter . +If the command is called +.BR rmail , +usually because it was invoked to deliver mail arriving over the network, +the message will be returned to the sender. The returned message will +appear to have been sent by user +.BR postmaster . +.SH "SEE ALSO" +.IR mail (1) diff --git a/static/plan9-4e/man6/smtpd.6 b/static/plan9-4e/man6/smtpd.6 new file mode 100644 index 00000000..687426ce --- /dev/null +++ b/static/plan9-4e/man6/smtpd.6 @@ -0,0 +1,306 @@ +.TH SMTPD 6 +.SH NAME +smtpd \- SMTP listener configuration +.SH DESCRIPTION +The +SMTP +daemon +of +.IR mail (1) +implements the slave side of the SMTP protocol +to accept incoming mail on TCP port 25. +In general, +.IR smtpd 's +default parameters +are sufficient for internal systems +on protected networks, but external or +gateway systems require additional +security mechanisms. +The files +.BR /mail/lib/smtpd.conf , +containing configuration parameters, +and +.BR /mail/lib/blocked , +containing +banished addresses, provide the means to +exercise these facilities. +.SS Input Format +In both files input lines +consist of a verb followed by one or more +parameters. These tokens are separated by white space or +commas and all characters following a +.B # +are comments. A +.B # +cannot be escaped. Continuation lines are +not supported, but verbs that take multiple parameters +can be restated on many lines and the associated +parameters accumulate into a single set. +All token processing is case-insensitive. +.PP +Many parameters are +.IR addresses , +either numeric IP addresses in CIDR notation +or a +.I "sender address" +in UUCP-style format. +.PP +An IP address in CIDR notation has the form +.PP +.EX + aaa.bbb.ccc.ddd/mask +.EE +.PP +consisting of a four octet IP address, a slash, +and a +.I mask length +specifying the number of significant high-order bits. +The lower the mask length, the larger the +range of addresses covered by the CIDR address; +see RFC 1878 for a discussion of mask lengths. +Missing low-order octets are assumed to be zero. +If a mask length is not given, a mask length of +16, 24, or 32 is assumed for addresses containing +two, three, or four octets, respectively. These +mask lengths select a class B, class C or Class D +address block. Notice that this convention differs +from the standard treatment, where the default mask length +depends on the allocation class of the network +block containing the address. +.PP +.I "Sender addresses" +are specified in UUCP notation as +follows: +.PP +.EX + [domain!]...domain!user +.EE +.PP +It is seldom necessary to specify more than one domain. +When +.I domain +is missing or +.BR * , +the address selects the specified user in all domains. +A +.I domain +of the form +.BI *. domain +selects the domain and all of its sub-domains. +For example, +.B example.com!user +only matches the account +.I user +in domain +.BR example.com , +while +.B *.example.com!user +selects that account in +.B example.com +and all of its sub-domains. +When +.I user +is omitted or +.BR * , +the address selects all users in the specified domain. +Finally, when +.B * +is the last character of the user name it is a wild-card +matching all user names beginning with +.IR user . +This limited pattern matching capability should be used with care. +For safety, the sender addresses +.BR * , +.BR ! , +.BR *! , +.B !* +and +.B *!* +are ignored. +.SS /mail/lib/smtpd.conf +This file contains configuration options +and parameters describing the local domain. +Many of the options can also be specified on the command +line; command line options always override the values in +this file. +Configuration options are: +.PD0 +.TP 10 +.BI defaultdomain " domain" +The name of the local domain; it is appended to addresses +lacking a domain qualification. +This is identical to the +.B -h +command line option. +.TP 10 +.BR norelay \ [ on\f1|\fPoff ] +If +.I on +is specified, relaying is prohibited +from unauthorized networks to external domains. +Authorized networks and domains must be specified +by the +.B ournets +and +.B ourdomains +verbs described below. Setting this option on is equivalent to specifying the +.B -f +command line flag, but the list of +networks and domains can only be specified in +this file. +.TP 10 +.BR verifysenderdom \ [ on\f1|\fPoff ] +When +.IR on , +.I smtpd +verifies that the first domain of the sender's address +exists. The test is cursory; it checks only that +there is a DNS delegation for the domain. +Setting the option on is equivalent to specifying the +.B -r +command line option and +is useful for detecting some unreturnable +messages as well as messages with randomly +generated domain names. +.TP 10 +.BR saveblockedmsg \ [ on\f1|\fPoff ] +When +.IR on , +causes copies of blocked messages to be saved +in subdirectories of +.BR /mail/queue.dump . +Directories are named with the date and file names +are random numbers. +If this option is +.I off +blocked messages are discarded. +Setting this option on is equivalent to specifying the +.B -s +command line option. +.TP 10 +.BR ournets " \fIIP address\fP [, \fIIP address\fP, ..., \fIIP address\fP]" +This option specifies trusted +source networks that are allowed to relay mail to external domains. +These are usually the internal networks of the local domain, but they +can also include friendly +external networks. Addresses +are in CIDR notation. +.TP 10 +.BR ourdomains " \fIdomain\fP [, \fIdomain\fP, ..., \fIdomain\fP]" +This option specifies destination domains that are allowed +to receive relayed mail. These are usually the domains +served by a gateway system. +Domain specifications conform to the format +for sender addresses given above. +.PD +.PP +When the +.B norelay +option is enabled or the +.B -f +command line option given, +relaying is allowed only if the source IP address is in +.B ournets +or the destination domain is specified in +.BR ourdomains . +.SS Blocked Addresses +When +.B /mail/lib/blocked +exists and is readable, +.I smtpd +reads a list of banned addresses from it. +Messages received from these addresses are +rejected with a 5\fIxx\fP-series SMTP error code. +There is no option +to turn blocking on or off; if the file is accessible, +blocking is enabled on all +.I smtpd +sessions, including those from trusted networks. +.PP +The command line format and address specifications +conform to the notation described above. If the parameters +of the verb is sender addresses in UUCP format, the line +must begin with an +.B * +character; if the parameters are one or more IP addresses, +the +.B * +must precede the verb. Most +verbs cause messages to be rejected; verbs +of this class generally select different error +messages. The remaining verbs specify addresses that +are always accepted, in effect overriding blocked addresses. +The file is processed in order, so an override must +precede its associated blocked address. +Supported verbs are: +.PD0 +.TP 10 +.BR dial " \fIIP address\fP [,..., \fIIP address\fP]" +The parameters are IP addresses associated with +dial-up ports. The rejection message states +that connections from dial-up ports are not accepted. Copies +of messages are never saved. +.TP 10 +.BR block " \fIaddress\fP [, ... \fIaddress\fP]" +Messages from addresses +matching the parameters +are rejected with an error message saying +that spam is not accepted. The message is saved if +the option is enabled. +.TP 10 +.BR relay " \fIaddress\fP [, ... \fIaddress\fP]" +This verb is identical to +.BR block , +but the error message states that +the message is rejected because the sending +system is being used as a spam relay. +.TP +.BR deny " \fIaddress\fP [, ... \fIaddress\fP]" +The +.B deny +command rejects a message when the +sender address matches one of its parameters. +The rejection message asks the sender to +contact +.BR postmaster @ +.I hostdomain +for further information. +This verb is usually used to block +inadvertently abusive traffic, for example, +mail loops and stuck senders. Messages are +never saved. +.TP +.BR allow " \fIaddress\fP [, ... \fIaddress\fP]" +The +.B allow +verb negates the effect of subsequent blocking commands. +It is useful when a large range of addresses contains +a few legitimate addresses, for example, when +a mail server is in a Class C network block +of modem ports. Rather than enumerate the dial ports, it is +easier to block the entire Class C with a +.B dial +command, and precede it with an override for +the address of the mail server. Similarly, +it is possible to block mail from an entire +domain while accepting mail from a few friendly +senders in the domain. +The verb +.B accept +is a synonym for +.BR allow . +.PD +.PP +.IR Scanmail (8) +describes spam detection +software that works well with +the capabilities described here +and +.IR mail (1) +defines additional +.I smtpd +command line arguments applicable +to exposed systems. +.SH "SEE ALSO" +.IR mail (1), +.IR scanmail (8) diff --git a/static/plan9-4e/man6/snap.6 b/static/plan9-4e/man6/snap.6 new file mode 100644 index 00000000..1553669d --- /dev/null +++ b/static/plan9-4e/man6/snap.6 @@ -0,0 +1,98 @@ +.TH SNAP 6 +.SH NAME +snap \- process snapshots +.SH DESCRIPTION +Process snapshots are used to +save a process image for debugging on +another machine or at another time. +They are like old Unix core dumps but +can hold multiple process images and +are smaller. +.PP +The first line of a snapshot begins with the prefix +``process snapshot'' and often contains +other information as well, such as creation time, +user name, system name, cpu type, and kernel type. +This information is intended for humans, not programs. +Programs reading snapshots should only +check that this line begins with the specified prefix. +.PP +Throughout the rest of the snapshot, decimal strings are +always right-justified, blank-padded to 11 characters, +and followed by a single space character. +.PP +The rest of the snapshot is one or more records, +each of which begins with a one-line header. +This header is a decimal process id followed by +an identification string, which denotes the type of +data in the record. +.PP +Records of type +.BR fd , +.BR fpregs , +.BR kregs , +.BR noteid , +.BR ns , +.BR proc , +.BR regs , +.BR segment , +and +.BR status +are all formatted as a decimal number +.I n +followed by +.I n +bytes of data. +This data is the contents of the file +of the same name found in +.BR /proc . +.PP +The format of the +.B mem +and +.B text +sections is not as simple. +These sections contain one or more page descriptions. +Each describes a one kilobyte page of data. +If the section is not a multiple of a kilobyte in size, +the last page will be shorter. +Each description begins with a one-byte +flag. +If the flag is +.BR r , +then it is followed by +a page of binary data. +If the flag is +.BR z , +then the data is understood to be zeros, +and is omitted. +If the flag is +.B m +or +.BR t , +then it is followed by two decimal strings +.I p +and +.IR o , +indicating that this page is the same +as the page at offset +.I o +of the memory or text +segment for process +.IR p . +This data must have been previously +described in the snapshot, and the offset +must be a multiple of a kilobyte. +.PP +It is not guaranteed that any of the sections +described above be in a process snapshot, +although the snapshot quickly becomes useless when +too much is missing. +.PP +Memory and text images may be incomplete. +The memory or text file for a given process +may be split across multiple disjoint sections +in the snapshot. +.SH SEE ALSO +.IR proc (3), +.IR snap (4). diff --git a/static/plan9-4e/man6/thumbprint.6 b/static/plan9-4e/man6/thumbprint.6 new file mode 100644 index 00000000..63be911a --- /dev/null +++ b/static/plan9-4e/man6/thumbprint.6 @@ -0,0 +1,41 @@ +.TH THUMBPRINT 6 +.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 (2)), +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 (2) diff --git a/static/plan9-4e/man6/users.6 b/static/plan9-4e/man6/users.6 new file mode 100644 index 00000000..f00a8194 --- /dev/null +++ b/static/plan9-4e/man6/users.6 @@ -0,0 +1,69 @@ +.TH USERS 6 +.SH NAME +users \- file server user list format +.SH DESCRIPTION +The permanent file servers each maintain a private list of users +and groups, in +.B /adm/users +by convention. +Each line in the file has the format +.IP +.IB num : name : leader :\fImembers\fP +.PP +where +.I num +is a decimal integer, +.I name +and +.I leader +are printable strings excluding the characters +.LR ? , +.LR = , +.LR + , +.LR - , +.LR / , +and +.LR : , +and +.I members +is a comma-separated list of such strings. +Such a line defines a user and a group with the given +.IR name ; +the group has a group leader given by +.I leader +and group members given by the user names in +.IR members . +The +.I leader +field may be empty, +in which case any group member is a group leader. +The +.I members +field may be empty. +.PP +Lines beginning with +.L # +are ignored. +.PP +The +.I num +in a line is a number used internally by a file server; +there should be no duplicate +.IR num s +in the file. +A negative +.I num +is special: a user with a negative +.I num +cannot attach to the file server. +The file +.B /adm/users +itself is owned by user +.IR adm , +having a negative +.IR num , +and write protected to others, +so it can only be changed via console commands. +.SH "SEE ALSO" +.IR intro (5), +.IR stat (5) diff --git a/static/plan9-4e/man6/utf.6 b/static/plan9-4e/man6/utf.6 new file mode 100644 index 00000000..0f49abf0 --- /dev/null +++ b/static/plan9-4e/man6/utf.6 @@ -0,0 +1,98 @@ +.TH UTF 6 +.SH NAME +UTF, Unicode, ASCII, rune \- character set and format +.SH DESCRIPTION +The Plan 9 character set and representation are +based on the Unicode Standard and on the ISO multibyte +.SM UTF-8 +encoding (Universal Character +Set Transformation Format, 8 bits wide). +The Unicode Standard represents its characters in 16 +bits; +.SM UTF-8 +represents such +values in an 8-bit byte stream. +Throughout this manual, +.SM UTF-8 +is shortened to +.SM UTF. +.PP +In Plan 9, a +.I rune +is a 16-bit quantity representing a Unicode character. +Internally, programs may store characters as runes. +However, any external manifestation of textual information, +in files or at the interface between programs, uses a +machine-independent, byte-stream encoding called +.SM UTF. +.PP +.SM UTF +is designed so the 7-bit +.SM ASCII +set (values hexadecimal 00 to 7F), +appear only as themselves +in the encoding. +Runes with values above 7F appear as sequences of two or more +bytes with values only from 80 to FF. +.PP +The +.SM UTF +encoding of the Unicode Standard is backward compatible with +.SM ASCII\c +: +programs presented only with +.SM ASCII +work on Plan 9 +even if not written to deal with +.SM UTF, +as do +programs that deal with uninterpreted byte streams. +However, programs that perform semantic processing on +.SM ASCII +graphic +characters must convert from +.SM UTF +to runes +in order to work properly with non-\c +.SM ASCII +input. +See +.IR rune (2). +.PP +Letting numbers be binary, +a rune x is converted to a multibyte +.SM UTF +sequence +as follows: +.PP +01. x in [00000000.0bbbbbbb] → 0bbbbbbb +.br +10. x in [00000bbb.bbbbbbbb] → 110bbbbb, 10bbbbbb +.br +11. x in [bbbbbbbb.bbbbbbbb] → 1110bbbb, 10bbbbbb, 10bbbbbb +.br +.PP +Conversion 01 provides a one-byte sequence that spans the +.SM ASCII +character set in a compatible way. +Conversions 10 and 11 represent higher-valued characters +as sequences of two or three bytes with the high bit set. +Plan 9 does not support the 4, 5, and 6 byte sequences proposed by X-Open. +When there are multiple ways to encode a value, for example rune 0, +the shortest encoding is used. +.PP +In the inverse mapping, +any sequence except those described above +is incorrect and is converted to rune hexadecimal 0080. +.SH FILES +.TF "/lib/unicode " +.TP +.B /lib/unicode +table of characters and descriptions, suitable for +.IR look (1). +.SH "SEE ALSO" +.IR ascii (1), +.IR tcs (1), +.IR rune (2), +.IR keyboard (6), +.IR "The Unicode Standard" . diff --git a/static/plan9-4e/man6/venti.conf.6 b/static/plan9-4e/man6/venti.conf.6 new file mode 100644 index 00000000..f8c2d77a --- /dev/null +++ b/static/plan9-4e/man6/venti.conf.6 @@ -0,0 +1,67 @@ +.TH VENTI.CONF 6 +.SH NAME +venti.conf \- a venti configuration file +.SH DESCRIPTION +A venti configuration file enumerates the various index sections and +arenas that constitute a venti system. +The components are indicated by the name of the file, typically +a disk partition, in which they reside. The configuration +file is the only location that file names are used. Internally, +venti uses the names assigned when the components were formatted +with +.IR fmtarenas (8) +or +.IR fmtisect (8). +In particular, by changing the configuration a +component can be copied to a different file. +.PP +The configuration file consists of lines in the form described below. +Lines starting with +.B # +are comments. +.TP +.BI index " name +Names the index for the system. +.TP +.BI arenas " file +.I File +contains a collection of arenas, formatted using +.IR fmtarenas (8). +.TP +.BI isect " file +.I File +contains an index section, formatted using +.IR fmtisect (8). +.PP +After formatting a venti system using +.IR fmtindex (8), +the order of arenas and index sections should not be changed. +Additional arenas can be appended to the configuration. +.SH EXAMPLE +.EX +# a sample venti configuration file +# +# formatted with +# venti/fmtarenas arena. /tmp/disks/arenas +# venti/fmtisect isect0 /tmp/disks/isect0 +# venti/fmtisect isect1 /tmp/disks/isect1 +# venti/fmtindex venti.conf +# +# server is started with +# venti/venti + +# the name of the index +index main + +# the index sections +isect /tmp/disks/isect0 +isect /tmp/disks/isect1 + +# the arenas +arenas /tmp/disks/arenas +.EE +.SH "SEE ALSO" +.IR venti (8), +.IR fmtarenas (8), +.IR fmtisect (8), +.IR fmtindex (8) diff --git a/static/plan9-4e/man6/vgadb.6 b/static/plan9-4e/man6/vgadb.6 new file mode 100644 index 00000000..a6335768 --- /dev/null +++ b/static/plan9-4e/man6/vgadb.6 @@ -0,0 +1,486 @@ +.TH VGADB 6 +.SH NAME +vgadb \- VGA controller and monitor database +.SH DESCRIPTION +.PP +The VGA database, +.BR /lib/vgadb , +consists of two parts, +the first describing how to identify and program a VGA controller +and the second describing the timing parameters for known +monitors to be loaded into a VGA controller to give a particular +resolution and refresh rate. +Conventionally, at system boot, the program +.B aux/vga +(see +.IR vga (8)) +uses the monitor type in +.BR /env/monitor , +the display resolution in +.BR /env/vgasize , +and the VGA controller information in the database to +find a matching monitor entry and initialize the VGA controller accordingly. +.PP +The file comprises multi-line entries made up of +attribute/value pairs of the form +.IB attr = value +or sometimes just +.IR attr . +Each line starting without white space starts a new entry. +Lines starting with +.B # +are comments. +.PP +The first part of the database, the VGA controller identification and +programming information, +consists of a number of entries with attribute +.B ctlr +and no value. +Within one of these entries the following attributes are +meaningful: +.TF 0xC0000 +.TP +.I nnnnn +an offset into the VGA BIOS area. +The value is a string expected to be found there that will +identify the controller. +For example, +.B 0xC0068="#9GXE64 Pro" +would identify a #9GXEpro VGA controller if the string +.B "#9GXE64 Pro" +was found in the BIOS at address 0xC0068. +There may be more than one identifier attribute per controller. +If a match cannot be found, the first few bytes of the BIOS +are printed to help identify the card and create a controller +entry. +.TP +.IB nnnnn - mmmmm +A range of the VGA BIOS area. +The value is a string as above, but the entire range +is searched for that string. +The string must begin at or after +.I nnnnn +and not contain any characters at or after +.IR mmmmm . +For example, +.B 0xC0000-0xC0200="MACH64LP" +identifies a Mach 64 controller with the +string +.B MACH64LP +occurring anywhere in the first 512 bytes of BIOS memory. +.TP +.B ctlr +VGA controller chip type. +This must match one of the VGA controller types +known to +.B /dev/vgactl +(see +.IR vga (3)) +and internally to +.BR aux/vga . +Currently, +.BR ark2000pv , +.BR clgd542x , +.BR ct65540 , +.BR ct65545 , +.BR cyber938x , +.BR et4000 , +.BR hiqvideo , +.BR ibm8514 , +.BR mach32 , +.BR mach64 , +.BR mach64xx , +.BR mga2164w , +.BR neomagic , +.BR s3801 , +.BR s3805 , +.BR s3928 , +.BR t2r4 , +.BR trio64 , +.BR virge , +.BR vision864 , +.BR vision964 , +.BR vision968 , +and +.B w30c516 +are recognized. +.TP +.B ramdac +RAMDAC controller type. +This must match one of the types +known internally to +.BR aux/vga . +Currently +.BR att20c490 , +.BR att20c491 , +.BR att20c492 , +.BR att21c498 , +.BR bt485 , +.BR rgb524mn , +.BR sc15025 , +.BR stg1702 , +.BR tvp3020 , +.BR tvp3025 , +and +.B tvp3026 +are recognized. +.TP +.B clock +clock generator type. +This must match one of the types +known internally to +.BR aux/vga . +Currently +.BR ch9294 , +.BR icd2061a , +.BR ics2494 , +.BR ics2494a , +.BR s3clock , +.BR tvp3025clock , +and +.B tvp3026clock +are recognized. +.TP +.B hwgc +hardware graphics cursor type. +This must match one of the types +known to +.B /dev/vgactl +and internally to +.BR aux/vga . +Currently +.BR ark200pvhwgc , +.BR bt485hwgc , +.BR clgd542xhwgc , +.BR clgd546xhwgc , +.BR ct65545hwgc , +.BR cyber938xhwgc , +.BR hiqvideohwgc , +.BR mach64xxhwgc , +.BR mga2164whwgc , +.BR neomagichwgc , +.BR rgb524hwgc , +.BR s3hwgc , +.BR t2r4hwgc , +.BR tvp3020hwgc , +and +.B tvp3026hwgc +are recognized. +.TP +.B membw +Memory bandwidth in megabytes per second. +.I Vga +chooses the highest refresh rate possible within the constraints +of the monitor (explained below) and the +card's memory bandwidth. +.TP +.B linear +Whether the card supports a large (>64kb) linear memory +window. The value is either +.B 1 +or +.B 0 +(equivalent to unspecified). +The current kernel graphics subsystem +requires a linear window; entries without +.B linear=1 +are of historic value only. +.TP +.B link +This must match one of the types +known internally to +.BR aux/vga . +Currently +.B vga +and +.B ibm8514 +are recognized. +The type +.B vga +handles generic VGA functions and should almost always be included. +The type +.B Ibm8514 +handles basic graphics accelerator initialization on controllers +such as the early S3 family of GUI chips. +.PD +.PP +The +.BR clock , +.BR ctlr , +.BR link , +and +.B ramdac +values can all take an extension following a +.B '-' +that can be used as a speed-grade +or subtype; matching is done without the extension. +For example, +.B ramdac=stg1702-135 +indicates the STG1702 RAMDAC has a maximum clock frequency of 135MHz, +and +.B clock=ics2494a-324 +indicates that the frequency table numbered +324 +should be used for the ICS2494A clock generator. +.PP +The functions internal to +.B aux/vga +corresponding to the +.BR clock , +.BR ctlr , +.BR link , +and +.B ramdac +values will be called in the order given for initialization. +Sometimes the clock should be set before the RAMDAC is initialized, +for example, depending on the components used. +In general, +.BR link=vga +will always be first and, +if appropriate, +.BR link=ibm8514 +will be last. +.PP +The entries in the second part of +.B /lib/vgadb +have as attribute the name of a monitor type +and the value is conventionally a resolution in the form +.IB X x Y\f1, +where +.I X +and +.I Y +are numbers representing width and height in pixels. +The monitor type (i.e. entry) +.B include +has special properties, described below and shown in the examples. +The remainder of the entry contains timing information for +the desired resolution. +Within one of these entries the following attributes are +meaningful: +.TF interlace +.TP +.B clock +the video dot-clock frequency in MHz required for this resolution. +The value 25.175 is known internally to +.IR vga (8) +as the baseline VGA clock rate. +.B defaultclock +the default video dot-clock frequency in MHz used +for this resolution when no +memory bandwidth is specified for the card +or when +.I vga +cannot determine the maximum clock frequency of the card. +.TP +.B shb +start horizontal blanking, in character clocks. +.TP +.B ehb +end horizontal blanking, in character clocks. +.TP +.B ht +horizontal total, in character clocks. +.TP +.B vrs +vertical refresh start, in character clocks. +.TP +.B vre +vertical refresh end, in character clocks. +.TP +.B vt +vertical total, in character clocks. +.TP +.B hsync +horizontal sync polarity. +Value must be +.B + +or +.BR - . +.TP +.B vsync +vertical sync polarity. +Value must be +.B + +or +.BR - . +.TP +.B interlace +interlaced mode. +Only value +.B v +is recognized. +.TP +.B alias +continue, replacing the +.B alias +line by the contents of the entry whose attribute is given as +.IR value . +.TP +.B include +continue, replacing this +.B include +line by the contents of the previously defined +.B include +monitor type with matching +.IR value . +(See the examples.) +Any non-zero attributes already set will not be overwritten. +This is used to save duplication of timing information. +Note that +.I value +is not parsed, it is only used as a string +to identify the previous +.BI include= value +monitor type entry. +.PD +.PP +The values given for +.BR shb , +.BR ehb , +.BR ht , +.BR vrs , +.BR vre , +.BR vt , +.BR hsync , +and +.B vsync +are beyond the +scope of this manual page. +See the book by +Ferraro +for details. +.SH EXAMPLES +Basic +.B ctlr +entry for a laptop with a Chips and Technology 65550 +controller: +.EX +ctlr # NEC Versa 6030X/6200MX + 0xC0090="CHIPS 65550 PCI & VL Accelerated VGA BIOS" + link=vga + ctlr=hiqvideo linear=1 + hwgc=hiqvideohwgc +.EE +A more complex entry. Note the extensions on the +.BR clock , +.BR ctlr , +and +.B ramdac +attributes. The order here is important: the RAMDAC clock input must be +initialized before the RAMDAC itself. The clock frequency is selected by +the +.B ET4000 +chip. +.EX +ctlr # Hercules Dynamite Power + 0xC0076="Tseng Laboratories, Inc. 03/04/94 V8.00N" + link=vga + clock=ics2494a-324 + ctlr=et4000-w32p + ramdac=stg1702-135 +.EE +Monitor entry for type +.B vga +(the default monitor type used by +.IR vga (8)) +and resolution 640x480x[18]. +.EX +include = 640x480@60Hz # 60Hz, 31.5KHz + clock=25.175 + shb=664 ehb=760 ht=800 + vrs=491 vre=493 vt=525 + +vga = 640x480 # 60Hz, 31.5KHz + include=640x480@60Hz +.EE +Entries for multisync monitors with video bandwidth up to 65MHz. +.EX +# +# Multisync monitors with video bandwidth up to 65MHz. +# +multisync65 = 1024x768 # 60Hz, 48.4KHz + include=1024x768@60Hz +multisync65 = 1024x768i # 87Hz, 35.5KHz (interlaced) + include=1024x768i@87Hz +multisync65 + alias=vga +.EE +Note how this builds on the existing +.B vga +entries. +.SH FILES +.TP +.B /lib/vgadb +.SH "SEE ALSO" +.IR ndb (2), +.IR vga (3), +.IR ndb (6), +.IR 9load (8), +.IR vga (8) +.br +Richard E. Ferraro, +.I +Programming Guide to the EGA, VGA and Super VGA Cards, +Third Edition +.SH BUGS +The database should provide a way +to use the PCI bus +as well as BIOS memory to identify cards. +.SH "ADDING A NEW MONITOR" +Adding a new monitor is usually fairly straightforward, as most modern monitors +are multisync and the only interesting parameter is the +maximum video bandwidth. +Once the timing parameters are worked out for a particular maximum +video bandwidth as in the example above, an entry for a new monitor +with that limit is simply +.EX +# +# Sony CPD-1304 +# Horizontal timing: +# Allowable frequency range: 28-50KHz +# Vertical timing: +# Allowable frequency range: 50-87Hz +# +cpd-1304 + alias=multisync65 +.EE +Even this is not necessary, as the monitor type could simply be +given as +.BR multisync65 . +.SH "ADDING A NEW VGA CONTROLLER" +While the use of this database formalizes the steps needed to +program a VGA controller, +unless you are lucky and all the important components on +a new VGA controller card are interconnected in the same way as an +existing entry, adding a new entry requires adding new internal +types to +.IR vga (8). +Fortunately, the unit of variety +has, for the most part, shifted from +individual components to entire +video chipsets. +Thus in lucky cases all that is necessary +is the addition of another +.B 0xNNNNN= +line to the entry for the controller. +This is particularly true in the case +of the ATI Mach 64 and the S3 Virge. +.PP +If you need to actually add support +for a controller with a different chipset, +you will need the data sheets for the VGA controller +as well as any RAMDAC or clock generator +(these are commonly integrated into the controller). +You will also need to know how these components interact. +For example, a common combination is an S3 86C928 VGA chip with +an ICD2061A clock generator. The ICD2061A is usually loaded by clocking +a serial bit-stream out of one of the 86C928 registers. +Similarly, the RAMDAC may have an internal clock-doubler and/or +pixel-multiplexing modes, in which case both the clock generator and +VGA chip must be programmed accordingly. +Hardware acceleration for rectangle fills +and block copies is provided in the kernel; +writing code to handle this is necessary +to achieve reasonable performance at high +pixel depths. diff --git a/static/plan9-4e/man7/0intro.7 b/static/plan9-4e/man7/0intro.7 new file mode 100644 index 00000000..754feac3 --- /dev/null +++ b/static/plan9-4e/man7/0intro.7 @@ -0,0 +1,8 @@ +.TH INTRO 7 +.SH NAME +intro \- introduction to databases +.SH DESCRIPTION +This manual section describes databases available on Plan 9 +and the commands that access them. +Some of them involve proprietary data that is not distributed outside +Bell Laboratories. diff --git a/static/plan9-4e/man7/INDEX.7 b/static/plan9-4e/man7/INDEX.7 new file mode 100644 index 00000000..d296e59e --- /dev/null +++ b/static/plan9-4e/man7/INDEX.7 @@ -0,0 +1,8 @@ +0intro 0intro +intro 0intro +astro astro +dict dict +juke juke +map map +mapdemo map +scat scat diff --git a/static/plan9-4e/man7/INDEX.html.7 b/static/plan9-4e/man7/INDEX.html.7 new file mode 100644 index 00000000..b87c21d6 --- /dev/null +++ b/static/plan9-4e/man7/INDEX.html.7 @@ -0,0 +1,33 @@ + +plan 9 man section 7 + + +[manual index] +

Plan 9 from Bell Labs - Section 7 - Databases

+
+
+
0intro +- introduction to databases +
intro + +
astro +- print astronomical information +
astro + +
dict +- dictionary browser +
dict + +
juke +- CDROM juke box +
juke + +
map +- draw maps on various projections +
map, mapdemo + +
scat +- sky catalogue and Digitized Sky Survey +
scat + +
diff --git a/static/plan9-4e/man7/Makefile b/static/plan9-4e/man7/Makefile new file mode 100644 index 00000000..57ec7ecb --- /dev/null +++ b/static/plan9-4e/man7/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.7) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man7/astro.7 b/static/plan9-4e/man7/astro.7 new file mode 100644 index 00000000..9d19e81b --- /dev/null +++ b/static/plan9-4e/man7/astro.7 @@ -0,0 +1,122 @@ +.TH ASTRO 7 +.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 /sys/src/cmd/astro +.SH SEE ALSO +.IR scat (7) +.SH BUGS +The +.B k +option reverts to GMT outside of 1970-2036. diff --git a/static/plan9-4e/man7/dict.7 b/static/plan9-4e/man7/dict.7 new file mode 100644 index 00000000..5fc47634 --- /dev/null +++ b/static/plan9-4e/man7/dict.7 @@ -0,0 +1,163 @@ +.TH DICT 7 +.SH NAME +dict \- dictionary browser +.SH SYNOPSIS +.B dict +[ +.B -k +] +[ +.B -d +.I dictname +] +[ +.B -c +.I command +] +[ +.I pattern +] +.SH DESCRIPTION +.I Dict +is a dictionary browser. +If a +.I pattern +is given on the command line, +.I dict +prints all matching entries; +otherwise it repeatedly accepts and executes commands. +The options are +.TF -d\ \fIdictname\fP +.TP +.BI -d " dictname" +Use the given dictionary. +The default is +.BR oed , +the second edition of the Oxford English Dictionary. +A list of available dictionaries is printed by option +.BR -d? . +.TP +.BI -c " command" +Execute one command and quit. +The command syntax is described below. +.TP +.B -k +Print a pronunciation key. +.PD +.PP +Patterns are regular expressions (see +.IR regexp (6)), +with an implicit leading +.L ^ +and trailing +.LR $ . +Patterns are matched against an index of headwords and variants, +to form a `match set'. +By default, both patterns and the index are folded: +upper case characters are mapped into their lower case equivalents, +and Latin accented characters are mapped into their non-accented +equivalents. +In interactive mode, there is always a `current match set' +and a `current entry' within the match set. +Commands can change either or both, as well as print the entries +or information about them. +.PP +Commands have an address followed by a command letter. +Addresses have the form: +.TF /\fIre\fP/.\fIn\fP +.TP +.BI / re / +Set the match set to all entries matching the regular expression +.IR re , +sorted in dictionary order. +Set the current entry to the first of the match set. +.TP +.BI ! re ! +Like +.BI / re / +but use exact matching, i.e., without case and accent folding. +.TP +.I n +An integer +.I n +means change the current entry to the +.IR n th +of the current match set. +.TP +.BI # n +The integer +.I n +is an absolute byte offset into the raw dictionary. +(See the +.B A +command, below.) +.TP +.IB addr + +After setting the match set and current entry according to +.IR addr , +change the match set and current entry to be the next entry +in the dictionary (not necessarily in the match set) after +the current entry. +.TP +.IB addr - +Like +.IB addr + +but go to previous dictionary entry. +.PD +.PP +The command letters come in pairs: a lower case and the +corresponding upper case letter. +The lower case version prints something about the current +entry only, and advances the current entry to the next +in the match set (wrapping around to the beginning after +the last). +The upper case version prints something about all of the +match set and resets the current entry to the beginning of +the set. +.TF \fLa,A\fP +.TP +.BR p , P +Print the whole entry. +.TP +.BR h , H +Print only the headword(s) of the entry. +.TP +.BR a , A +Print the dictionary byte offset of the entry. +.TP +.BR r , R +Print the whole entry in raw format (without translating +special characters, etc.). +.PD +.PP +If no command letter is given for the first command, +.B H +is assumed. +After an +.BR H , +the default command is +.BR p . +Otherwise, the default command is the previous command. +.SH FILES +.B /lib/dict/oed2 +.br +.B /lib/dict/oed2index +.br +Other files in +.BR /lib . +.SH "SEE ALSO" +.IR regexp (6) +.SH SOURCE +.B /sys/src/cmd/dict +.SH BUGS +A font with wide coverage of the Unicode Standard +should be used for best results. +(Try +.BR /lib/font/bit/pelm/unicode.9.font .) +.br +If the +.I pattern +doesn't begin with +a few literal characters, matching takes a long time. +.br +The dictionaries are not distributed outside Bell Labs. diff --git a/static/plan9-4e/man7/juke.7 b/static/plan9-4e/man7/juke.7 new file mode 100644 index 00000000..421d5afe --- /dev/null +++ b/static/plan9-4e/man7/juke.7 @@ -0,0 +1,52 @@ +.TH JUKE 7 +.SH NAME +juke \- +.SM CDROM +juke box +.SH SYNOPSIS +.B 9fs juke +.SH DESCRIPTION +The +.I juke +file system is a stand-alone file server, +.BR jukefs , +that stores copies of +.SM CDROM\c +s +in a simulation of the true juke box that it replaces. +Each `disc' in the juke box appears as a file in +.B /n/juke +or in a subdirectory of +.BR /n/juke . +Here are descriptions of some of them. +.nr zz \w'\f(CWsupercomputing.93\fP'u/1n+2 +.TP \n(zz +.B plan9.1992 +The 1992 Plan 9 release. +.TP +.B plan9.1995 +The 1995 Plan 9 release. +.TP +.B dss/dss.??? +Digitized Sky Survey (102 discs covering the night sky); access with +.IR scat (7). +.TP +.B eg/* +Chess end games. +.PP +To see the contents of a +.SM CDROM\c +, start +.B 9660srv +(see +.IR dossrv (4)) +and mount the service with the file name of the +.SM CDROM +as the attach specifier. +.SH BUGS +There should be a way to access the contents of the +.SM CDROM\c +s +without running +.B 9660srv +locally. diff --git a/static/plan9-4e/man7/map.7 b/static/plan9-4e/man7/map.7 new file mode 100644 index 00000000..abb5b942 --- /dev/null +++ b/static/plan9-4e/man7/map.7 @@ -0,0 +1,676 @@ +.TH MAP 7 +.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 (6)-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 /sys/src/cmd/map +.SH "SEE ALSO" +.IR map (6), +.IR plot (1), +.IR road (7) +.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/static/plan9-4e/man7/scat.7 b/static/plan9-4e/man7/scat.7 new file mode 100644 index 00000000..d9bf8db8 --- /dev/null +++ b/static/plan9-4e/man7/scat.7 @@ -0,0 +1,335 @@ +.TH SCAT 7 +.SH NAME +scat \- sky catalogue and Digitized Sky Survey +.SH SYNOPSIS +.B scat +.SH DESCRIPTION +.I Scat +looks up items in catalogues of objects +outside the solar system +and implements database-like manipulations +on sets of such objects. +It also provides an interface to +.IR astro (7) +to plot the locations of solar system objects. +Finally, it displays images from the +Space Telescope Science Institute's +Digitized Sky Survey, keyed to the catalogues. +.PP +Items are read, one per line, from the standard input +and looked up in the catalogs. +Input is case-insensitive. +The result of the lookup becomes the set of objects available +to the database commands. +After each lookup or command, if more than two objects are +in the set, +.I scat +prints how many objects are in the set; otherwise it +prints the objects' +descriptions or cross-index listings (suitable for input to +.IR scat ). +An item is in one of the following formats: +.TP +.B ngc1234 +Number 1234 in the New General Catalogue of +Nonstellar Objects, NGC2000.0. +The output identifies the type +.RB( Gx =galaxy, +.BR Pl =planetary +nebula, +.BR OC =open +cluster, +.BR Gb =globular +cluster, +.BR Nb =bright +nebula, +.BR C+N =cluster +associated with nebulosity, +.BR Ast =asterism, +.BR Kt =knot +or nebulous region in a galaxy, +.BR *** =triple +star, +.BR D* =double +star, +.BR ? =uncertain, +.BR - =nonexistent, +.BR PD =plate +defect, and +(blank)=unverified or unknown), +its position in 2000.0 coordinates, +its size in minutes of arc, a brief description, and popular names. +.TP +.B ic1234 +Like NGC references, but from the Index Catalog. +.TP +.B sao12345 +Number 12345 in the Smithsonian Astrophysical Star Catalogue. +Output identifies the visual and photographic magnitudes, +2000.0 coordinates, proper motion, spectral type, multiplicity and variability +class, and HD number. +.TP +.B m4 +Catalog number 4 in Messier's catalog. +The output is the NGC number. +.TP +.B abell1701 +Catalog number 1701 in the Abell and Zwicky +catalog of clusters of galaxies. +Output identifies the magnitude of the tenth brightest member of the cluster, +radius of the cluster in degrees, its distance in megaparsecs, +2000.0 coordinates, galactic latitude and longitude, +magnitude range of the cluster (the `distance group'), +number of members (the `richness group'), population +per square degree, and popular names. +.TP +.B planetarynebula +The set of NGC objects of the specified type. +The type may be a compact NGC code or a full name, as above, with no blank. +.TP +\fL"α umi"\fP +Names are provided in double quotes. +Known names are the Greek +letter designations, proper names such as Betelgeuse, bright variable stars, +and some proper names of stars, NGC objects, and Abell clusters. +Greek letters may be spelled out, e.g. +.BR alpha . +Constellation names must be the three-letter abbreviations. +The output +is the SAO number. +For non-Greek names, catalog numbers and names are listed for all objects with +names for which the given name is a prefix. +.TP +.B 12h34m -16 +Coordinates in the sky are translated to the nearest `patch', +approximately one square degree of sky. +The output is the coordinates identifying the patch, +the constellations touching the patch, and the Abell, NGC, and SAO +objects in the patch. +The program prints sky positions in several formats corresponding +to different precisions; any output format is understood as input. +.TP +.B umi +All the patches in the named constellation. +.TP +.B mars +The planets are identified by their names. +The names +.B shadow +and +.B comet +refer to the earth's penumbra at lunar distance and the comet installed in the current +.IR astro (7). +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 . +The positions are current at the start of +.I scat 's +execution; see the +.B astro +command in the next section for more information. +.PP +The commands are: +.TF print +.TP +.BI add " item" +Add the named item to the set. +.TP +.BI keep " class ..." +Flatten the set and cull it, keeping only the specified classes. +The classes may be specific NGC types, +all stars +.RB ( sao ), +all NGC objects +.RB ( ngc ), +all M objects +.RB ( m ), +all Abell clusters +.RB ( abell ), +or a specified brightness range. +Brightness ranges are specified by a leading +.B > +or +.B < +followed by a magnitude. +Remember that brighter objects have lesser magnitudes. +.TP +.BI drop " class ..." +Complement to +.BR keep . +.TP +.BI flat +Some items such as patches represents sets of items. +.I Flat +flattens the set so +.I scat +holds all the information available for the objects in the set. +.TP +.BI print +Print the contents of the set. If the information seems meager, try +flattening the set. +.TP +.BI expand " n" +Flatten the set, +expand the area of the sky covered by the set to be +.I n +degrees wider, and collect all the objects in that area. +If +.I n +is zero, +.I expand +collects all objects in the patches that cover the current set. +.TP +.BI astro " option" +Run +.IR astro (7) +with the specified +.I options +(to which will be appended +.BR -p ), +to discover the positions of the planets. +.BR Astro 's +.B -d +and +.B -l +options can be used to set the time and place; by default, it's right now at the coordinates in +.BR /lib/sky/here . +Running +.B astro +does not change the positions of planets already in the display set, +so +.B astro +may be run multiple times, executing e.g. +.B "add mars" +each time, to plot a series of planetary positions. +.TP +.BI plot " option" +Expand and plot the set in a new window on the screen. +Symbols for NGC objects are as in Sky Atlas 2000.0, except that open clusters +are shown as stippled disks rather than circles. +Abell clusters are plotted as a triangle of ellipses. +The planets are drawn as disks of representative color with the first letter of the name +in the disk (lower case for inferior planets; upper case for superior); +the sun, moon, and earth's shadow are unlabeled disks. +Objects larger than a few pixels are plotted to scale; however, +.I scat +does not have the information necessary to show the correct orientation for galaxies. +.IP +The option +.B nogrid +suppresses the lines of declination and right ascension. +By default, +.I scat +labels NGC objects, Abell clusters, and bright stars; option +.B nolabel +suppresses these while +.B alllabel +labels stars with their SAO number as well. +The default size is 512×512; options +.B dx +.I n +and +.BR dy +.I n +set the +.I x +and +.I y +extent. +The option +.B zenithup +orients the map so it appears as it would in the sky at the time and +location used by the +.B astro +command +.RI ( q.v. ). +.IP +The output is designed to look best on an LCD display. +CRTs have trouble with the thin, grey lines and dim stars. +The option +.B nogrey +uses white instead of grey for these details, improving visibility +at the cost of legibility when plotting on CRTs. +.TP +.B "plate \f1[[\f2ra dec\f1] \f2rasize\f1 [\f2decsize\f1]]" +Display the section of the Digitized Sky Survey (plate scale +approximately 1.7 arcseconds per pixel) centered on the +given right ascension and declination or, if no position is specified, the +current set of objects. The maximum area that will be displayed +is one degree on a side. The horizontal and vertical sizes may +be specified in the usual notation for angles. +If the second size is omitted, a square region is displayed. +If no size is specified, the size is sufficient to display the centers +of all the +objects in the current set. If a single object is in the set, the +500×500 pixel block from the survey containing the center +of the object is displayed. +The survey is stored in the CD-ROM juke box; run +.B 9fs +.B juke +before running +.IR scat . +.TP +.BI gamma " value" +Set the gamma for converting plates to images. Default is \-1.0. +Negative values display white stars, positive black. +The images look best on displays with depth 8 or greater. +.I Scat +does not change the hardware color map, which +should be set externally to a grey scale; try the command +.B getmap gamma +(see +.IR getmap (9.1)) +on an 8-bit color-mapped display. +.PD +.SH EXAMPLES +Plot the Messier objects and naked-eye stars in Orion. +.EX + ori + keep m <6 + plot nogrid +.EE +.PP +Draw a finder chart for Uranus: +.EX + uranus + expand 5 + plot +.EE +.PP +Show a partial lunar eclipse: +.EX + astro -d + 2000 07 16 12 45 + moon + add shadow + expand 2 + plot +.EE +.PP +Draw a map of the Pleiades. +.EX + "alcyone" + expand 1 + plot +.EE +.PP +Show a pretty galaxy. +.EX + ngc1300 + plate 10' +.EE +.SH FILES +.B /lib/sky/*.scat +.SH SOURCE +.B /sys/src/cmd/scat +.SH SEE ALSO +.IR astro (7) +.br +.B /lib/sky/constelnames\ \ +the three-letter abbreviations of the constellation names. +.PP +The data was provided by the Astronomical Data Center at the NASA Goddard +Space Flight Center, except for NGC2000.0, which is Copyright © 1988, Sky +Publishing Corporation, used (but not distributed) by permission. The Digitized Sky Survey, 102 +CD-ROMs, is not distributed with the system. diff --git a/static/plan9-4e/man8/0intro.8 b/static/plan9-4e/man8/0intro.8 new file mode 100644 index 00000000..f96a521b --- /dev/null +++ b/static/plan9-4e/man8/0intro.8 @@ -0,0 +1,8 @@ +.TH INTRO 8 +.SH NAME +intro \- introduction to system administration +.SH DESCRIPTION +This manual section describes commands for system administration +as well as various utility programs necessary for the system +but not routinely invoked +by a user. diff --git a/static/plan9-4e/man8/9load.8 b/static/plan9-4e/man8/9load.8 new file mode 100644 index 00000000..bffcb43c --- /dev/null +++ b/static/plan9-4e/man8/9load.8 @@ -0,0 +1,407 @@ +.TH 9LOAD 8 +.SH NAME +9load, ld \- PC bootstrap program +.SH SYNOPSIS +.I "(Under MS-DOS) +.br +[ +.I drive +:][ +.I path +.RB ] ld +[ +.I 9load +] +.SH DESCRIPTION +.I 9load +and +.I ld +are programs that reside in a FAT file system and bootstrap Plan 9. +.I 9load +loads the kernel, but it cannot be run from DOS; use +.I ld +to bootstrap (by starting +.IR 9load ) +if DOS is running. +.I 9load +is run automatically by the boot procedures described below; +it cannot be run directly by hand. +There are three bootstrap sequences: +.IP \- +BIOS, MBR, disk partition PBS, +.IR 9load , +kernel +.IP \- +BIOS, floppy PBS, +.IR 9load , +kernel +.IP \- +BIOS, MBR, DOS, +.IR ld , +.IR 9load , +kernel. +.PP +Details follow. +.PP +.I 9load +is a bootstrap program that loads and starts a program, +typically the kernel, on a PC. +It is run by the PC partition boot sector program (PBS), +which usually resides in the first +sector of the active partition. +A copy of the Plan 9 PBS is kept in +.BR /386/pbs , +but due to the ``cylinder-head-sector'' (CHS) addressing mode of old BIOSes, it can only +operate up to 8.5GB into the disk. +Plan 9 partitions further into the disk +can only be booted using +.BR /386/pbslba , +and then only if the machine's BIOS supports +linear block addressing (LBA) mode for disk transfers. +.PP +When booting from floppy or hard disk, the BIOS loads the +first sector of the medium at location 0x7C00. In the +case of a floppy, this is the PBS. In the case of a hard +disk it it the master boot record (MBR). +The MBR copies itself to address +.BR 0x600 , +finds the active partition and loads its PBS at address +.BR 0x7C00 . +A copy of the Plan 9 MBR is kept in +.BR /386/mbr ; +some commercial MBRs cannot read sectors +past 2GB. +The Plan 9 MBR can read sectors up to 8.5GB into +the disk, and further if the BIOS supports LBA. +The single file +.B /386/mbr +detects whether the BIOS supports LBA and +acts appropriately, defaulting to CHS mode +when LBA is not present. +The PBSs cannot do this due to code size considerations. +The Plan 9 MBR is suitable for booting non-Plan 9 +operating systems, +and (modulo the large disk constraints just described) +non-Plan 9 MBRs are suitable for booting Plan 9. +.PP +Thus the default sequence is: BIOS, MBR, PBS, +.IR 9load , +kernel. +.PP +Because it contains many device drivers for different +disks and networks, +.I 9load +is larger than 64K and cannot be run as a DOS +.RB `` .com '' +executable. +A stripped-down version that knows about disks but not networks, +called +.I ld +(really +.BR ld.com ), +fits in 64K and can be used under DOS to load and start a program (default +.IR 9load ) +from the FAT16 partition. +Its command line argument is of the same format as the +.I bootfile +specifiers described below. +This profusion of loaders is unfortunate, but at least +.I ld +and +.I 9load +are compiled from the same source. +.PP +.I 9load +begins execution at address +.B 0x80010000 +(64K) and +loads the +.I bootfile +at the entry address specified by the header, +usually +.BR 0x80100020 . +After loading, control is passed to the entry location. +.PP +In summary, +Plan 9 can be booted on a PC two different ways: +either by booting MS-DOS and using +.I ld +to start +.I 9load +in the appropriate directory, +or by booting directly from a Plan 9 boot floppy or disk +partition +prepared using +.B format +to install the appropriate files and bootstrap sectors +(see +.IR prep (8)). +.PP +The +.IR bootfile , +which may be compressed with +.IR gzip (1), +can be specified to +.I 9load +as a +.B bootfile= +entry in +.IR plan9.ini , +or if booting from the ethernet, by a BOOTP server. +If the +.B plan9.ini +file contains multiple +.B bootfile= +entries, +.I 9load +will present a numerical menu of the choices; type +the corresponding number to select an entry. +.PP +The format of the +.I bootfile +name is +.IB device ! file +or +.IB device ! partition ! file\f1. +If +.BI ! file +is omitted, the default for the particular +.I device +is used. +Supported +.I devices +are +.TF \fLethern +.TP +.BI fd n +An MS-DOS floppy disk. +.I N +specifies the floppy drive, either +0 or 1. +The +.I bootfile +is the contents of the MS-DOS +.IR file . +There is no default file. +For compatibility with hard disks, a +.I partition +may be given, but only +.B dos +is recognized: +.BI fd0!dos! file\f1. +.TP +.BI ether n +Ethernet. +.I N +specifies the Ethernet device number. +If a +.I partition +is specified, it is taken to be the name of a host machine +from which to load the kernel. +.I file +is determined by the +.B /lib/ndb +(see +.IR ndb (6)) +entry for this PC. +.TP +.BI sd Cn +Non-floppy disk. +The device name format is described in +.IR sd (3). +A +.I partition +must be given and must +name a partition containing a FAT file system. +The name +.B dos +refers to the first DOS partition on a given device. +It is common for Plan 9 partitions to contain a small +FAT file system for configuration. +By convention, this partition is called +.BR 9fat . +There is no default partition or pathname. +.PD +.PP +When +.I 9load +starts running at physical address 0x10000, +it switches to 32-bit mode. +It then double maps the first 16Mb of physical memory to +virtual addresses 0 and 0x80000000. +Physical memory from 0x300000 upwards is used as data +space. +Next, in order to find configuration information, +.I 9load +searches all units on devices +.BR fd +and +.BI sd Cn \fR, +in that order, for a file called +.B plan9\eplan9.ini +or +.B plan9.ini +(see +.IR plan9.ini (8)) +on a partition named +.B dos +or +.BR 9fat . +If one is found, searching stops and the file is read into memory +at physical address 0x1200 +where it can be found later by any loaded +.IR bootfile . +Some options in +.B plan9.ini +are used by +.IR 9load : +.TF bootfile=manual +.TP +.B console +.TP +.B baud +Specifies the console device and baud rate if not a display. +.TP +.BI ether n +Ethernet interfaces. These can be used to load the +.I bootfile +over a network. +Probing for Ethernet interfaces is too prone to error. +.TP +.BI bootfile= bootfile +Specifies the +.IR bootfile . +This option is overridden by a command-line argument. +.TP +.B bootfile=auto +Default. +.TP +.B bootfile=local +Like +.IR auto , +but do not attempt to load over the network. +.TP +.B bootfile=manual +After determining which devices are available for loading from, +enter prompt mode. +.PD +.PP +When the search for +.B plan9.ini +is done, +.I 9load +proceeds to determine which bootfile to load. +If there was no +.I bootfile +option, +.I 9load +chooses a default +from the following prioritized device list: +.EX + fd sd ether +.EE +.I 9load +then attempts to load the +.I bootfile +unless +the +.B bootfile=manual +option was given, in which case prompt mode is entered immediately. +If the default device is +.BR fd , +.I 9load +will prompt the user for input before proceeding with the +default bootfile load after 5 seconds; +this prompt is omitted if +a command-line argument or +.I bootfile +option +was given. +.PP +.I 9load +prints the list of available +.IR device s +and +enters prompt mode on encountering any error +or if directed to do so by a +.B bootfile=manual +option. +In prompt mode, the user is required to type +a +.IB bootfile +in response to the +.L "Boot from: +prompt. +.PP +.I 9load +parses the master boot record and Plan 9 partition tables +(see +.IR prep (8)), +leaving partitioning information appended to the +in-memory contents of +.I plan9.ini +for the +.IR bootfile . +This is used by +.IR sd (3) +to initialize partitions so that +.IR kfs (4) +file systems can be mounted as the root file system. +A more extensive partitioning is typically done by +.I fdisk +and +.I prep +as part of +.I termrc +or +.I cpurc +(see +.IR cpurc (8)). +.PP +A +control-P +character typed at any time on the console causes +.B 9load +to perform a hardware reset +(Ctrl-Alt-Del can also be used on a PC keyboard). +.PP +When loaded from a PBS (rather than from +.IR ld.com ), +.I 9load +must be contiguously allocated on +the disk. +See +.IR dossrv (4) +for information on ensuring this. +.SH FILES +.RI [ drive :] +[ +.I path +.RB ] 9load +.br +.RI [ drive :] +[ +.I path +.RB ] ld +.br +.IB "FAT filesystem" :\eplan9\eplan9.ini +.br +.IB "FAT filesystem" :\eplan9.ini +.SH SOURCE +.B /sys/src/boot/pc +.SH "SEE ALSO" +.IR plan9.ini (8), +.IR prep (8) +.SH BUGS +.PP +Much of the work done by +.B 9load +is duplicated by the loaded kernel. +.PP +If +.I ld +detects an installed MS-DOS Extended Memory Manager, +it attempts to de-install it, but the technique +used may not always work. +It is safer not to install the Extended Memory Manager before running +.IR ld . diff --git a/static/plan9-4e/man8/9pcon.8 b/static/plan9-4e/man8/9pcon.8 new file mode 100644 index 00000000..23ba23ce --- /dev/null +++ b/static/plan9-4e/man8/9pcon.8 @@ -0,0 +1,160 @@ +.TH 9PCON 8 +.SH NAME +9pcon \- 9P to text translator +.SH SYNOPSIS +.B aux/9pcon +[ +.B -cn +] +[ +.B -m +.I msize +] +.I service +.SH DESCRIPTION +.I 9pcon +provides a textual interface to +.IR service , +a conventional 9P server. +By default, +.I 9pcon +interprets +.I service +as a file to be opened. +The +.B -c +flag causes +.I 9pcon +to interpret +.I service +as a command to run which will carry out a +(binary) 9P +conversation over file descriptors 0 and 1. +The +.B -n +flag +causes +.I 9pcon +to interpret +.I service +as a network address to dial. +.PP +Once the connection is established, +.I 9pcon +prints R-messages as they arrive from the server, +and sends T-messages as they are typed on standard input. +There is no prompt. +Lines beginning with # are ignored. +The syntax for T-messages is one of: +.IP +.B Tversion +.I msize +.I version +.br +.B Tauth +.I afid +.I uname +.I aname +.br +.B Tattach +.I fid +.I afid +.I uname +.I aname +.br +.B Twalk +.I fid +.I newfid +.I wname... +.br +.B Topen +.I fid +.I mode +.br +.B Tcreate +.I fid +.I name +.I perm +.I mode +.br +.B Tread +.I fid +.I offset +.I count +.br +.B Twrite +.I fid +.I offset +.I data +.br +.B Tclunk +.I fid +.br +.B Tremove +.I fid +.br +.B Tstat +.I fid +.br +.B Twstat +.I fid +.I name +.I uid +.I gid +.I mode +.I mtime +.I length +.br +.B Tflush +.I oldtag +.LP +See +.IR intro (5) +for a description of the fields in each message. +For the most part, the syntax mirrors the description +of the messages in section 5. +The exceptions are that +the tags on the T-messages are added automatically; +.BR Twalk 's +.I nwname +count is inferred from the number of +.I wnames +given; +and +.BR Twstat 's +.I dir +is in expanded form rather than being an opaque byte sequence. +Note that since commands are parsed with +.B tokenize +(see +.IR getfields (2)), +it is easy to pass empty strings for absent +.IR name , +.IR uid , +and +.I gid +fields. +To ease specifying default integer fields, the +.B Twstat +message recognizes +.B ~0 +in the +.IR mode , +.IR mtime , +and +.I length +arguments. +For example, +.EX + Twstat 101 '' '' sys ~0 ~0 ~0 +.EE +sends a +.I wstat +message that attempts to change the group id associated with +.SH SOURCE +.B /sys/src/cmd/aux/9pcon.c +.SH SEE ALSO +.IR intro (5) +.SH BUGS +There should be a flag to wait for responses, +to facilitate scripting. diff --git a/static/plan9-4e/man8/INDEX.8 b/static/plan9-4e/man8/INDEX.8 new file mode 100644 index 00000000..6a86e3c4 --- /dev/null +++ b/static/plan9-4e/man8/INDEX.8 @@ -0,0 +1,157 @@ +0intro 0intro +intro 0intro +9load 9load +ld 9load +9pcon 9pcon +apm apm +auth auth +auth.srv auth +changeuser auth +convkeys auth +convkeys2 auth +disable auth +enable auth +guard.srv auth +login auth +printnetkey auth +status auth +wrkey auth +boot boot +booting booting +buildindex buildindex +checkarenas checkarenas +checkindex checkindex +cpurc cpurc +termrc cpurc +cron cron +dhcpd dhcpd +rarpd dhcpd +tftpd dhcpd +drawterm drawterm +fmtarenas fmtarenas +fmtindex fmtindex +fmtisect fmtisect +exsort fs +fs fs +fsconfig fsconfig +echo httpd +httpd httpd +imagemap httpd +man2html httpd +save httpd +init init +ipconfig ipconfig +rip ipconfig +ftpd ipserv +imap4d ipserv +ipserv ipserv +rexexec ipserv +rlogind ipserv +telnetd ipserv +kfscmd kfscmd +ksync kfscmd +il17007 listen +il17008 listen +il17009 listen +il17013 listen +il17031 listen +il19 listen +il565 listen +il566 listen +il7 listen +il9 listen +listen listen +tcp110 listen +tcp113 listen +tcp143 listen +tcp17007 listen +tcp17009 listen +tcp17013 listen +tcp19 listen +tcp21 listen +tcp23 listen +tcp25 listen +tcp513 listen +tcp515 listen +tcp53 listen +tcp564 listen +tcp565 listen +tcp566 listen +tcp567 listen +tcp7 listen +tcp9 listen +tcp993 listen +lp lp +dump9660 mk9660 +mk9660 mk9660 +mkext mkfs +mkfs mkfs +mkpaqfs mkpaqfs +mksacfs mksacfs +aux/accupoint mouse +aux/mouse mouse +mouse mouse +na na +cs ndb +csquery ndb +dns ndb +dnsdebug ndb +dnsquery ndb +ipquery ndb +mkdb ndb +mkhash ndb +mkhosts ndb +ndb ndb +query ndb +newuser newuser +9auth nfsserver +nfsserver nfsserver +pcnfsd nfsserver +portmapper nfsserver +pcmcia pcmcia +gping ping +hogports ping +ping ping +traceroute ping +plan9.ini plan9.ini +ppp ppp +pppoe ppp +pptp ppp +pptpd ppp +fdisk prep +format prep +mbr prep +prep prep +qer qer +runq qer +rdarena rdarena +reboot reboot +applychanges replica +applylog replica +compactdb replica +replica replica +updatedb replica +scanmail scanmail +testscan scanmail +scuzz scuzz +secstore secstore +secstored secstore +secuser secstore +securenet securenet +snoopy snoopy +stats stats +swap swap +timesync timesync +tlssrv tlssrv +udpecho udpecho +bootfloppy update +bootplan9 update +bootwin9x update +bootwinnt update +personalize update +setup.9fat update +setup.disk update +setup.kfs update +update update +venti venti +vga vga diff --git a/static/plan9-4e/man8/INDEX.html.8 b/static/plan9-4e/man8/INDEX.html.8 new file mode 100644 index 00000000..0bb88c67 --- /dev/null +++ b/static/plan9-4e/man8/INDEX.html.8 @@ -0,0 +1,237 @@ + +plan 9 man section 8 + + +[manual index] +

Plan 9 from Bell Labs - Section 8 - System Administration

+
+
+
0intro +- introduction to system administration +
intro + +
9load +- PC bootstrap program +
9load, ld + +
9pcon +- 9P to text translator +
9pcon + +
apm +- Advanced Power Management 1.2 BIOS interface +
apm + +
auth +- maintain authentication databases +
changeuser, wrkey, convkeys, convkeys2, printnetkey, status, auth.srv, guard.srv, login, disable, enable + +
boot +- connect to the root file server +
boot + +
booting +- bootstrapping procedures +
booting + +
buildindex +- rebuild a Venti index +
buildindex + +
checkarenas +- check the integrity, and optionally fix, Venti arenas +
checkarenas + +
checkindex +- check the integrity and optionally fix a Venti index +
checkindex + +
cpurc +- boot script +
cpurc, termrc + +
cron +- clock daemon +
cron + +
dhcpd +- Internet booting +
dhcpd, rarpd, tftpd + +
drawterm +- connect to Plan 9 CPU servers from other operating systems +
drawterm + +
fmtarenas +- format a file into a number of Venti arenas +
fmtarenas + +
fmtindex +- format a Venti index +
fmtindex + +
fmtisect +- format a Venti index section +
fmtisect + +
fs +- file server maintenance +
fs, exsort + +
fsconfig +- configuring a file server +
fsconfig + +
httpd +- HTTP server +
httpd, echo, save, imagemap, man2html + +
init +- initialize machine upon booting +
init + +
ipconfig +- Internet configuration and routing +
ipconfig, rip + +
ipserv +- Internet remote access daemons +
telnetd, rlogind, rexexec, ftpd, imap4d + +
kfscmd +- kfs administration +
kfscmd, ksync + +
listen +- listen for calls on a network device +
listen, il7, il9, il19, il565, il566, il17007, il17008, il17009, il17013, il17031, tcp7, tcp9, tcp19, tcp21, tcp23, tcp25, tcp53, tcp110, tcp113, tcp143, tcp513, tcp515, tcp564, tcp565, tcp566, tcp567, tcp993, tcp17007, tcp17009, tcp17013 + +
lp +- PostScript preprocessors +
lp + +
mk9660 +- create an ISO-9660 CD image +
dump9660, mk9660 + +
mkfs +- archive or update a file system +
mkfs, mkext + +
mkpaqfs +- make a compressed read-only file system +
mkpaqfs + +
mksacfs +- make a compressed file system +
mksacfs + +
mouse +- configure a mouse to a port +
aux/mouse, aux/accupoint + +
na +- assembler for the Symbios Logic PCI-SCSI I/O Processors +
na + +
ndb +- network database +
query, mkhash, mkdb, cs, csquery, dns, dnsquery, ipquery, dnsdebug, mkhosts + +
newuser +- adding a new user +
newuser + +
nfsserver +- NFS service +
nfsserver, portmapper, pcnfsd, 9auth + +
pcmcia +- identify a PCMCIA card +
pcmcia + +
ping +- probe the Internet +
ping, gping, traceroute, hogports + +
plan9.ini +- configuration file for PCs +
plan9.ini + +
ppp +- point to point protocol +
ppp, pppoe, pptp, pptpd + +
prep +- prepare hard and floppy diskettes, flashes +
prep, fdisk, format, mbr + +
qer +- queue management for spooled files +
qer, runq + +
rdarena +- extract a Venti arena +
rdarena + +
reboot +- reboot the system upon loss of remote file server connection +
reboot + +
replica +- simple client-server replica management +
applychanges, applylog, compactdb, updatedb + +
scanmail +- spam filters +
scanmail, testscan + +
scuzz +- SCSI target control +
scuzz + +
secstore +- secstore commands +
secstored, secuser + +
securenet +- Digital Pathways SecureNet Key remote authentication box +
securenet + +
snoopy +- spy on network packets +
snoopy + +
stats +- display graphs of system activity +
stats + +
swap +- establish a swap file +
swap + +
timesync +- synchronize the system clock to a time source +
timesync + +
tlssrv +- TLS server +
tlssrv + +
udpecho +- echo UDP packets +
udpecho + +
update +- administration for local file systems +
bootfloppy, bootplan9, bootwin9x, bootwinnt, personalize, setup.9fat, setup.disk, setup.kfs, update + +
venti +- an archival block storage server +
venti + +
vga +- configure a VGA card +
vga + +
diff --git a/static/plan9-4e/man8/Makefile b/static/plan9-4e/man8/Makefile new file mode 100644 index 00000000..a2af6bc6 --- /dev/null +++ b/static/plan9-4e/man8/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.8) + +include ../../mandoc.mk diff --git a/static/plan9-4e/man8/apm.8 b/static/plan9-4e/man8/apm.8 new file mode 100644 index 00000000..23fdd668 --- /dev/null +++ b/static/plan9-4e/man8/apm.8 @@ -0,0 +1,111 @@ +.TH APM 8 +.SH NAME +apm \- Advanced Power Management 1.2 BIOS interface +.SH SYNOPSIS +.I (in plan9.ini) +.B apm0= +.PP +bind -a '#P' /dev +.PP +.B aux/apm +[ +.B -d +.I device +] +[ +.B -m +.I mountpoint +] +[ +.B -s +.I service +] +.SH DESCRIPTION +.I Aux/apm +presents at +.I mountpoint +(default +.BR /mnt/apm ) +an interface to the APM 1.2 BIOS +(see +.IR apm (3)) +.I device +(the default is to try +.BR /dev/apm , +followed by +.BR #P/apm ). +If a +.I service +is specified, the interface will be +posted at +.BI /srv/ service +as well. +.PP +The directory contains the following files. +.TP +.B battery +Contains one line for each battery in the system. +Each line lists three fields: the status (a string, one of +.BR unknown , +.BR high , +.BR low , +.BR critical , +or +.BR charging ), +the percent charge remaining, and +an estimate of the amount of time left in seconds. +If either or both of the last two are unknown, +the corresponding field will be zero. +.TP +.B ctl +The +.B ctl +file is used to set power management modes for +various parts of the system. +Control messages are of the form +.RI `` device " " verb ,'' +where +.I device +is one of +.BR system , +.BR display , +.BR storage , +.BR lpt , +.BR eia , +.BR network , +and +.BR pcmcia , +and +.I verb is one of +.BR enable , +.BR disable , +.BR standby , +and +.BR on . +.B Enable +and +.B disable +control whether power management is active +for the device, while +.B standby +puts the device into standby mode +and +.B on +brings it back to full power. +.TP +.B event +Reads from this file will block until an APM event +has occurred. +A large enough read is guaranteed to return +an integral number of textual event descriptions, one per line. +.SH SOURCE +.B /sys/src/cmd/aux/apm.c +.br +.B /acme/bin/Battery +.SH BUGS +The verbs +.B suspend +and +.B off +should be supported but doing so requires +nontrivial help from the kernel. diff --git a/static/plan9-4e/man8/auth.8 b/static/plan9-4e/man8/auth.8 new file mode 100644 index 00000000..5aabf0ac --- /dev/null +++ b/static/plan9-4e/man8/auth.8 @@ -0,0 +1,194 @@ +.TH AUTH 8 +.SH NAME +changeuser, wrkey, convkeys, convkeys2, printnetkey, status, auth.srv, guard.srv, login, disable, enable \- maintain authentication databases +.SH SYNOPSIS +.B auth/changeuser +.RB [ -np ] +.I user +.PP +.B auth/wrkey +.PP +.B auth/convkeys +.RB [ -p ] +.I keyfile +.PP +.B auth/convkeys +.RB [ -p ] +.I keyfile +.PP +.B auth/printnetkey +.I user +.PP +.B auth/status +.I user +.PP +.B auth/enable +.I user +.PP +.B auth/disable +.I user +.PP +.B auth/auth.srv +.PP +.B auth/guard.srv +.PP +.B auth/login +.I user +.SH DESCRIPTION +These administrative commands run only on the authentication server. +.IR Changeuser +manipulates an authentication database file system served by +.IR keyfs (4) +and used by file servers. +There are two authentication databases, +one holding information about Plan 9 accounts +and one holding SecureNet keys. +A +.I user +need not be installed in both databases +but must be installed in the Plan 9 database to connect to a Plan 9 service. +.PP +.I Changeuser +installs or changes +.I user +in an authentication database. +It does not install a user on a Plan 9 file server; see +.IR fs (8) +for that. +.PP +Option +.B -p +installs +.I user +in the Plan 9 database. +.I Changeuser +asks twice for a password for the new +.IR user . +If the responses do not match +or the password is too easy to guess +the +.I user +is not installed. +.I Changeuser +also asks for an APOP secret. +This secret is used in the APOP (RFC1939), +CRAM (RFC2195), and +Microsoft challenge/response protocols used for +POP3, IMAP, and VPN access. +.PP +Option +.B -n +installs +.I user +in the SecureNet database and prints out a key for the SecureNet box. +The key is chosen by +.IR changeuser . +.PP +If neither option +.B -p +or option +.B -n +is given, +.I changeuser +installs the +.I user +in the Plan 9 database. +.PP +.I Changeuser +prompts for +biographical information such as email address, +user name, sponsor and department number and +appends it to the file +.B /adm/netkeys.who +or +.BR /adm/keys.who . +.PP +.I Wrkey +prompts for a machine key, host owner, and host domain and stores them in +local non-volatile RAM. +.PP +.I Convkeys +re-encrypts the key file +.IR keyfile . +Re-encryption is performed in place. +Without the +.B -p +option +.I convkeys +uses the key stored in +.B /dev/keys +to decrypt the file, and encrypts it using the new key. +By default, +.I convkeys +prompts twice for the new password. +The +.B -p +forces +.I convkeys +to also prompt for the old password. +The format of +.I keyfile +is described in +.IR keyfs (4). +.PP +The format of the key file changed between Release 2 +and 3 of Plan 9. +.I Convkeys2 +is like +.IR convkeys . +However, in addition to rekeying, it converts from +the previous format to the Release 3 format. +.PP +.I Printnetkey +displays the network key as it should be entered into the +hand-held Securenet box. +.PP +.I Status +is a shell script that prints out everything known about +a user and the user's key status. +.PP +.I Enable/disable +are shell scripts that enable/disable both the Plan 9 and +Netkey keys for individual users. +.PP +.I Auth.srv +is the program, run only on the authentication server, that handles ticket requests +on IL port 566. +It is started +by an incoming call to the server +requesting a conversation ticket; its standard input and output +are the network connection. +.I Auth.srv +executes the authentication server's end of the appropriate protocol as +described in +.IR authsrv (6). +.PP +.I Guard.srv +is similar. It is called whenever a foreign (e.g. Unix) system wants +to do a SecureNet challenge/response authentication. +.PP +.I Login +allows a user to change his authenticated id to +.IR user . +.I Login +sets up a new namespace from +.B /lib/namespace +and exec's +.IR rc (1) +under the new id. +.SH FILES +.TF /sys/lib/httppasswords +.TP +.B /adm/keys.who +List of users in the Plan 9 database. +.TP +.B /adm/netkeys.who +List of users in the SecureNet database. +.TP +.B /sys/lib/httppasswords +List of realms and passwords for HTTP access. +.SH SOURCE +.B /sys/src/cmd/auth +.SH "SEE ALSO" +.IR keyfs (4), +.IR securenet (8) diff --git a/static/plan9-4e/man8/boot.8 b/static/plan9-4e/man8/boot.8 new file mode 100644 index 00000000..65d292cf --- /dev/null +++ b/static/plan9-4e/man8/boot.8 @@ -0,0 +1,258 @@ +.TH BOOT 8 +.SH NAME +boot \- connect to the root file server +.SH SYNOPSIS +.B /boot +[ +.B -fkm +] +[ +.BI -u username +] +[ +.IB method ! fs-addr +] +.SH DESCRIPTION +.PP +.I Boot +is the first program run after a kernel has been loaded. +It connects to the file server that will serve the +root, performs any authentication needed to +connect to that server, and +.IR exec (2)'s +the +.IR init (8) +program. +It is started by the kernel, never run directly by the user. See +.IR booting (8) +for information about the process of loading the kernel (and +.IR boot ) +into memory. +.PP +Once loaded, the kernel initializes its data structures and devices. +It sets the two environment variables +.B /env/cputype +and +.B /env/terminal +to describe the processor. +It then binds a place-holder file server, +.IR root (3), +onto +.B / +and crafts an initial process whose sole function is to +.IR exec (2) +.BR /boot , +a binary which is compiled into +.IR root (3). +.PP +The command line passed depends +on the information passed from boot ROM +to kernel. +Machines that boot directly from ROM (that is, most machines other than PCs) +pass the boot line given to the ROM directly to +.IR boot . +.PP +On the PC, each line in the DOS file +.B plan9.ini +of the form +.IB name = value +is passed to the boot program as an environment +variable with the same name and value. +The command line is +.IP +.B /386/9dos +.IB method ! server +.PP +(The first argument is ignored by +.IR boot .) +.I Boot +must determine the file +.I server +to use +and a +.I method +with which to connect to it. +Typically this will name a file server on the network, +or state that the root file system is on local disk and name the partition. +The complete list of methods is given below. +.PP +.I Boot +must also set a user name to be used +as the owner of devices and all console +processes and an encryption key to be used +when challenged. +.I Boot +will prompt for these. +.PP +Method and address are prompted for first. +The prompt lists all valid methods, with the default in brackets, for example: +.IP +.EX +root is from (il, local!#S/sdC0/fs)[il]: +.EE +.PP +A newline picks the default. +Other possible responses are +.I method +or +.IB method ! address\f1. +To aid in automatic reboot, the default is automatically +taken on CPU servers if nothing is typed within 15 seconds. +.PP +The other interactions depend on whether the system +is a +terminal or a CPU server. +.SS Terminal +.PP +The terminal must have a +.I username +to set. +If none is specified with the +.B -u +option, +.I boot +will prompt for one on the console: +.IP +.EX +user: +.EE +.PP +The user will also be prompted for a password to +be used as an encryption key on each +.IR attach (5): +.IP +.EX +password: +.EE +.PP +With most +.I methods +.I boot +can now connect to the file server. +However, with the serial line +.I methods +.B 9600 +and +.BR 19200 , +the actual mechanics of setting up the complete connection +are too varied to put into the boot program. +Instead +.I boot +lets the user set up the connection. +It prints a prompt on the console and then simulates +a dumb terminal between the user and the serial line: +.IP +.EX +Connect to file system now, type ctrl-d when done. +(Use the view or down arrow key to send a break) +.EE +.PP +The user can now type at the modem to +dial the number. What is typed depends on +the modem and is beyond this discussion. +.PP +When the user types a control-D, +.I boot +stops simulating a terminal and starts the file +system protocol over the serial line. +.PP +Once connected, +.I boot +mounts +the root file system before +.B / +and makes the connection available as +.B #s/boot +for subsequent processes to +.B mount +(see +.IR bind (2)). +.I Boot +completes by +.IR exec (2)'ing +.B /$objtype/init +.BR -t . +If the +.B -m +option is given it is also passed as an option to +.IR init . +.PP +If the kernel has been built with the cache file system, +.IR cfs (4), +the local disk partition +.BI /dev/sd XX /cache +(where +.B XX +is a unit specifier) +exists, and the root file system is from a remote server, +then the kernel will insert a user level cache +process between the remote server and the local namespace +that caches all remote accesses on the local partition. +The +.B -f +flag commands +.B cfs +to reformat the cache partition. +.SS CPU Servers +.PP +The user owning devices and console processes on CPU servers +and that user's domain and encryption key are +read from NVRAM on all machines except PC's. +PC's keep the information in the disk partition +.BI /dev/sd XX /nvram\f1. +If a +.B -k +option is given or if no stored information is found +.I boot +will prompt for all three items and store them. +.IP +.EX +password: +authid: bootes +authdom: research.bell-labs.com +.EE +.PP +The key is used for mutual authentication of the server and its clients. +The domain and id identify the owner of the key. +.PP +Once connected, +.I boot +behaves as on the terminal except for +.IR exec (2)'ing +.B /$objtype/init +.BR -c . +.SS Booting Methods +.PP +The methods available to any system depend on what was +compiled into the kernel. +The complete list of booting methods are listed below. +.TP 8 +.B il +connect via Ethernet using the IL protocol. +.TP 8 +.B tcp +connect via Ethernet using the TCP protocol. +This method is used only if the initial file server +is on a Unix system. +.TP 8 +.B local +connect to the local file system. +.PP +For the +.B il +and +.B tcp +methods, +the address must be a numeric IP address. +If no address is specified, +a file server address will be found from another +system on the network using the BOOTP protocol and +the Plan 9 vendor-specific fields. +.SH FILES +.B #s/boot +.SH SOURCE +.B /sys/src/9/boot +.SH "SEE ALSO" +.IR root (3), +.IR dhcpd (8), +.IR init (8) diff --git a/static/plan9-4e/man8/booting.8 b/static/plan9-4e/man8/booting.8 new file mode 100644 index 00000000..a8dd4fdd --- /dev/null +++ b/static/plan9-4e/man8/booting.8 @@ -0,0 +1,158 @@ +.TH BOOTING 8 +.SH NAME +booting \- bootstrapping procedures +.SH SYNOPSIS +none +.SH DESCRIPTION +This manual page collects the incantations required to bootstrap Plan 9 machines. +Some of the information here is specific to the installation at Bell Labs; +some is generic. +.PP +If a CPU server is up, BOOTP/DHCP and TFTP will run from there; +if not, the necessary files and services must be available on a separate machine, +such as a Unix system, to use these protocols for bootstrapping. +.PP +Be sure to read +.IR boot (8) +to understand what happens after the kernel is loaded. +.SS Terminals +To bootstrap a diskless terminal or a CPU server, a file server must be running. +PCs can boot from a floppy disk or any FAT16 partition. +On all the terminals, typing two control-T's followed by a lower-case +.B r +reboots the machine; +other methods of rebooting are mentioned for some machines. +.SS PCs +To boot a PC, it is necessary to get +.B /386/9load +loaded into memory. +There are many ways to do this. A Plan 9 boot floppy prepared by +.B format +(see +.IR prep (8)) +will load +.B 9load +when the PC is reset or powered on. +Other methods are described in +.IR 9load (8). +.B 9load +then locates and loads a Plan 9 kernel, using configuration information +from the file +.B plan9.ini +stored in the +.B 9fat +configuration partition or on a DOS file system. +See +.IR 9load (8) +for details. +.PP +Once the kernel is booted, it behaves like the others. +See +.IR boot (8) +for details. +.SS Alpha PCs +Alpha PCs must be booted via TFTP using the SRM console. +If the system has ARC firmware instead, SRM may be downloaded from +.IP +.EX +http://www.compaq.com/ +.EE +.PP +You must configure the SRM firmware to load the file +.BR /alpha/bootalphapc . +The following commands may be used (replace +.B ewa0 +with the name of your ethernet device, if different): +.IP +.EX +set boot_reset ON +set boot_file /alpha/bootalphapc +set bootdef_dev ewa0 +set ewa0_inet_init bootp +set ewa0_protocols BOOTP +.EE +.PP +This secondary bootstrap program will first load the file +.BR /alpha/conf/ +(substituting the IP address of the system as obtained via bootp). +This file is expected to be in +.IR plan9.ini (8) +format (the file +.B /alpha/conf/10.0.0.2 +may be used as a template). +It then loads the kernel via tftp, using the value of +.B bootfile +to tell it which file to load; this should be +.B /alpha/9apc +for terminals. +.SS CPU Servers +The Plan 9 CPU servers are multi-user, so they do not request a user name +when booting. +On the CPU servers, typing a control-P on the console reboots the machine. +.SS PC CPU Server +Proceed as for the PC terminal, but load +.B /386/9pccpu +or +.BR /386/9pccpudisk . +.SS Alpha PC CPU Server +Proceed as for the Alpha PC terminal, but use +.B /alpha/9apccpu +as the value of +.BR bootfile . +.SS SGI Challenge multiprocessor CPU Server +The Challenge ROM monitor can boot from the Ethernet. +To boot from the Ethernet, type +.IP +.EX +.B bootp()/mips/9ch +.EE +.PP +or use the ROM command +.B setenv +to set the variable +.B bootfile +to that same string and type +.BR boot . +To load a different file, tell +.B bootp +which file to load, +and to force the download to come from a particular system, +.BR bootp()system:file . +Any arguments after +.B bootp()file +are passed to +.BR /boot . +If you are running a Plan 9 +.SM BOOTP +server (see +.IR dhcpd (8)), +the file name can be omitted and the +file specified by the +.B bootf +parameter for the machine in +.BR /lib/ndb +will be downloaded by default. +.PP +Once the kernel is loaded, +it prompts for the Ethernet +protocol to use to reach the root file server; request the default. +.PP +.SS File servers +The CPU servers and terminals run essentially the same program, but +the Plan 9 file servers run a distinct system. +The file servers accept only the commands described in +.IR fs (8) +on their consoles. +.SS PC File Server +Boot the PC file server like a regular PC, loading the appropriate file system kernel. +.SH "SEE ALSO" +.IR 9load (8), +.IR boot (8), +.IR fs (8), +.IR init (8), +.IR plan9.ini (8) +.SH SOURCE +Sources for the various boot programs are under +.BR /sys/src/boot . +.SH BUGS +The file server should be able to boot from its own disk. diff --git a/static/plan9-4e/man8/buildindex.8 b/static/plan9-4e/man8/buildindex.8 new file mode 100644 index 00000000..43d03e10 --- /dev/null +++ b/static/plan9-4e/man8/buildindex.8 @@ -0,0 +1,62 @@ +.TH BUILDINDEX 8 +.SH NAME +buildindex \- rebuild a Venti index +.SH SYNOPSIS +.B venti/buildindex +[ +.B -B +.I blockcachesize +] +[ +.B -Z +] +.I venti.config +.I tmp +.SH DESCRIPTION +.I Buildindex +populates the index for the Venti system described in +.IR venti.config . +The index must have previously been formatted using +.IR fmtindex (8). +This command is typically used to build a new index for a Venti +system when the old index becomes too small, or to rebuild +an index after media failure. +Small errors in an index can usually be fixed with +.IR checkindex (8). +.PP +The +.I tmp +file, usually a disk partition, must be large enough to store a copy of the index. +This temporary space is used to perform a merge sort of index entries +generated by reading the arenas. +.PP +Options to +.I buildindex +are: +.TP +.BI -B " blockcachesize +The amount of memory, in bytes, to use for caching raw disk accesses while running +.IR buildindex . +(This is not a property of the created index.) +The default is 8k. +The units for the size can be specified by appending +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.TP +.B -Z +Do not zero the index. +This option should only be used when it is known that the index was already zeroed. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8), +.IR checkindex (8), +.IR fmtindex (8), +.IR venti.conf (6) +.SH BUGS +Should allow an individual index section to be rebuilt. +The merge sort could be performed in the space used to store the +index rather than requiring a temporary file. diff --git a/static/plan9-4e/man8/checkarenas.8 b/static/plan9-4e/man8/checkarenas.8 new file mode 100644 index 00000000..e817c9cb --- /dev/null +++ b/static/plan9-4e/man8/checkarenas.8 @@ -0,0 +1,34 @@ +.TH CHECKARENAS 8 +.SH NAME +checkarenas \- check the integrity, and optionally fix, Venti arenas +.SH SYNOPSIS +.B venti/checkarenas +[ +.B -afv +] +.I file +.SH DESCRIPTION +.I Checkarenas +examines the Venti arenas contained in the given +.IR file . +The program detects various error conditions, and optionally attempts +to fix any errors that are found. +.PP +Option to +.I checkarenas +are: +.TP +.B -a +For each arena, scan the entire data section. +If this option is omitted, only the end section of +the arena is examined. +.TP +.B -f +Attempt to fix any errors that are found. +.TP +.B -v +Increase the verbosity of output. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8) diff --git a/static/plan9-4e/man8/checkindex.8 b/static/plan9-4e/man8/checkindex.8 new file mode 100644 index 00000000..2ae21f51 --- /dev/null +++ b/static/plan9-4e/man8/checkindex.8 @@ -0,0 +1,52 @@ +.TH CHECKINDEX 8 +.SH NAME +checkindex \- check the integrity and optionally fix a Venti index +.SH SYNOPSIS +.B venti/checkindex +[ +.B -f +] +[ +.B -B +.I blockcachesize +] +.I venti.config +.I tmp +.SH DESCRIPTION +.I Checkindex +examines the Venti index described in +.IR venti.config . +The program detects various error conditions including: +blocks that are not indexed, index entries for blocks that do not exist, +and duplicate index entries. +If requested, an attempt can be made to fix errors that are found. +.PP +The +.I tmp +file, usually a disk partition, must be large enough to store a copy of the index. +This temporary space is used to perform a merge sort of index entries +generated by reading the arenas. +.PP +Option to +.I checkindex +are: +.TP +.BI -B " blockcachesize +The amount of memory, in bytes, to use for caching raw disk accesses while running +.IR checkindex . +The default is 8k. +The units for the size can be specified by appending +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.TP +.B -f +Attempt to fix any errors that are found. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8), +.IR buildindex (8), +.IR venti.conf (6) diff --git a/static/plan9-4e/man8/cpurc.8 b/static/plan9-4e/man8/cpurc.8 new file mode 100644 index 00000000..13fe0df4 --- /dev/null +++ b/static/plan9-4e/man8/cpurc.8 @@ -0,0 +1,67 @@ +.TH CPURC 8 +.SH NAME +cpurc, termrc \- boot script +.SH SYNOPSIS +.B cpurc +.PP +.B termrc +.SH DESCRIPTION +After the kernel boots, it execs +.B /boot +(see +.IR root (3)), +which in turn execs +.BR /$cputype/init . +.IR Init (8) +sets the +.B $service +environment variable to +.B cpu +or +.BR terminal , +and then invokes the appropriate +.B rc +script to bring the system up. +.PP +Based on the values of +.B $sysname +and +.B $terminal +these scripts start appropriate network processes and +administrative daemons and enable swapping. +.I Cpurc +sets +.B /env/boottime +to the time +.I cpurc +was executed and +.B /env/NPROC +to a value suitable for parallel compilation in +.IR mk (1). +.PP +These files should be edited by local installations +to reflect the configuration of their systems. +If an executable file +.B /sys/lib/sysconfig/termrc/$sysname +exists for the machine named +.BR $sysname , +.I termrc +will execute it as its last act. +This action is suppressed, as is automatic initialization of the mouse and +VGA on a PC, if the user is +.BR none . +.SH FILES +.TF /sys/lib/sysconfig/termrc +.TP +.B /sys/lib/sysconfig/termrc +machine-specific configuration scripts for +.IR termrc . +.SH SOURCE +.B /rc/bin/cpurc +.br +.B /rc/bin/termrc +.SH "SEE ALSO" +.IR srv (4), +.IR namespace (6), +.IR init (8), +.IR listen (8) diff --git a/static/plan9-4e/man8/cron.8 b/static/plan9-4e/man8/cron.8 new file mode 100644 index 00000000..a6fbf40d --- /dev/null +++ b/static/plan9-4e/man8/cron.8 @@ -0,0 +1,111 @@ +.TH CRON 8 +.SH NAME +cron \- clock daemon +.SH SYNOPSIS +.B auth/cron +[ +.B -c +] +.SH DESCRIPTION +.I Cron +executes commands at specified dates and times according +to instructions in the files +.BI /cron/ user /cron\f1. +It runs only on an authentication server. +Option +.B -c +causes +.I cron +to create +.BI /cron/ user +and +.BI /cron/ user /cron +for the current user; +it can be run from any Plan 9 machine. +.PP +Blank lines and lines beginning with +.B # +in these files are ignored. +Entries are lines with fields +.IP +.I +minute hour day month weekday host command +.PP +.I Command +is a string, which may contain spaces, that is passed to an +.IR rc (1) +running on +.I host +for execution. +The first five fields are integer patterns for +.PD0 +.RS +.TP \w'month\ of\ year\ \ 'u +minute +0\-59 +.TP +hour +0\-23 +.TP +day of month +1\-31 +.TP +month of year +1\-12 +.TP +day of week +0\-6; 0=Sunday +.PD +.RE +.PP +The syntax for these patterns is +.IP +.EX +time : '*' + | range +range : number + | number '-' number + | range ',' range +.EE +.PP +Each number must be in the appropriate range. +Hyphens specify inclusive ranges of valid times; +commas specify lists of valid time ranges. +.PP +To run the job, +.I cron +calls +.I host +and authenticates remote execution, equivalent to running +.B rx +.I host +.I command +(see +.IR con (1)). +The user's profile is run with +.B $service +set to +.BR rx . +.PP +.I Cron +is not a reliable service. +It skips commands if it cannot reach +.I host +within two minutes, or if the +.I cron +daemon is +not running at the appropriate time. +.SH EXAMPLES +Here is the job that mails system news. +.IP +.EX +% cat /cron/upas/cron +# send system news +15 8-17, 21 *** helix /mail/lib/mailnews +% +.EE +.SH SOURCE +.B /sys/src/cmd/auth/cron.c +.SH "SEE ALSO" +.IR con (1), +.IR rc (1) diff --git a/static/plan9-4e/man8/dhcpd.8 b/static/plan9-4e/man8/dhcpd.8 new file mode 100644 index 00000000..838a38ed --- /dev/null +++ b/static/plan9-4e/man8/dhcpd.8 @@ -0,0 +1,272 @@ +.TH DHCPD 8 +.SH NAME +dhcpd, rarpd, tftpd \- Internet booting +.SH SYNOPSIS +.PP +.B ip/dhcpd +.RB [ -mdsnp ] +.RB [ -f +.IR ndb-file ] +.RB [ -x +.IR netmtpt ] +.RB [ -M +.IR secs ] +[ +.I address +.I n +]* +.PP +.B ip/rarpd +.RB [ -d ] +.RB [ -e +.IR etherdev ] +.RB [ -x +.IR netmtpt ] +.PP +.B ip/tftpd +.RB [ -dr ] +.RB [ -h +.IR homedir ] +.RB [ -x +.IR netmtpt ] +.SH DESCRIPTION +These programs support booting over the Internet. +They should all be run on the same server to +allow other systems to be booted. +.I Dhcpd +and +.I tftpd +are used to boot everything; +.I rarpd +is an extra piece just for Suns. +.PP +.I Dhcpd +runs the +.SM BOOTP +and +.SM DHCP +protocols. +Clients use these protocols to obtain configuration information. +This information comes from attribute/value pairs in the network database +(see +.IR ndb (6) +and +.IR ndb (8)). +DHCP requests are honored both for static addresses found in +the NDB and for dynamic addresses listed in the command line. +DHCP requests are honored if either: +.br +\- there exists an NDB entry +containing both the ethernet address of the requester and +an IP address on the originating network or subnetwork. +.br +\- a free dynamic address exists on the originating network or subnetwork. +.PP +A BOOTP request is honored it all of the following are true: +.br +\- there exists an NDB entry +containing both the ethernet address of the requester and +an IP address on the originating network or subnetwork. +.br +\- the entry contains a +.B bootf= +attribute +.br +\- the file in the +.B bootf= +attribute is readable. +.PP +Dynamic addresses are specified on the command line as a list +of addresses and number pairs. +For example, +.EX + ip/dhcpd 10.1.1.12 10 10.2.1.70 12 +.EE +directs +.I dhcpd +to return dynamic addresses 10.1.1.12 through 10.1.1.21 inclusive +and 10.2.1.70 through 10.2.1.81 inclusive. +.PP +.I Dhcpd +maintains a record of all dynamic addresses in the directory +.BR /lib/ndb/dhcp , +one file per address. +If multiple servers have access to this common directory, +they will correctly coordinate their actions. +.PP +Attributes come from either the NDB entry for the system, the entry for its +subnet, or the entry for its network. The system entry has precedence, +then the subnet, then the network. +The NDB attributes used are: +.TF ipmask +.TP +.B ip +the IP address +.TP +.B ipmask +the IP mask +.TP +.B ipgw +the default IP gateway +.TP +.B dom +the domain name of the system +.TP +.B fs +the default Plan 9 name server +.TP +.B auth +the default Plan 9 authentication server +.TP +.B dns +a domain name server +.TP +.B ntp +a network time protocol server +.TP +.B time +a time server +.TP +.B wins +a +.SM NETBIOS +name server +.TP +.B www +a World Wide Web proxy +.TP +.B pop3 +a POP3 mail server +.TP +.B smtp +an SMTP mail server +.TP +.B bootf +the default boot file +.PD +.PP +.I Dhcpd +will answer +.SM BOOTP +requests only if it has been specifically targeted or if it +has read access to the boot file for the requester. That means that the requester +must specify a boot file in the request or one has to exist in NDB for +.I dhcpd +to answer. +.I Dhcpd +will answer all +.SM DHCP +requests for which it can associate an IP address with the +requester. +The options are: +.TP +.B d +Print debugging to standard output. +.TP +.B m +Mute: don't reply to requests, just log them and what +.I dhcpd +would have done. +.TP +.B f +Specify a file other than +.B /lib/ndb/local +as the network database. +.TP +.B s +Sleep 2 seconds before answering requests. This is used to make a server +be a backup only. +.TP +.B n +Don't answer +.SM BOOTP +requests. +.TP +.B p +Answer +.SM DHCP +requests from +.SM PPTP +clients only. +.TP +.B x +The IP stack to use is mounted at +.IR netmtpt . +The default is +.BR /net . +.TP +.B M +Use +.I secs +as the minimum lease time. +.PD +.PP +.I Rarpd +performs the Reverse Address Resolution Protocol, translating +Ethernet addresses into IP addresses. +The options are: +.TP +.B d +Print debugging to standard output. +.TP +.B e +Use the Ethernet mounted at +.BI /net/ etherdev\f1. +.TP +.B x +The IP stack to use is mounted at +.IR netmtpt . +The default is +.BR /net . +.PD +.PP +.I Tftpd +transfers files to systems that are booting. +It runs as user +.B none +and can only access files with global read permission. +The options are: +.TP +.B d +Print debugging to standard output. +.TP +.B x +The IP stack to use is mounted at +.IR netmtpt . +The default is +.BR /net . +.TP +.B h +Change directory to +.IR homedir . +The default is +.BR /lib/tftpd . +All requests for files with non-rooted file names are served starting at this +directory with the exception of files of the form +.BR xxxxxxxx.SUNyy . +These are Sparc kernel boot files where +.B xxxxxxxx +is the hex IP address of the machine requesting the kernel and +.B yy +is an architecture identifier. +.I Tftpd +looks up the file in the network database using +.I ipinfo +(see +.IR ndb (2)) +and responds with the boot file specified for that particular +machine. +If no boot file is specified, the transfer fails. +.I Tftpd +supports only octet mode. +.TP +.B r +Restricts access to only those files rooted in the +.IR homedir . +.PD +.SH FILES +.BR /lib/ndb/dhcp " directory of dynamic address files +.SH SOURCE +.B /sys/src/cmd/ip +.SH "SEE ALSO" +.IR ndb (6) diff --git a/static/plan9-4e/man8/drawterm.8 b/static/plan9-4e/man8/drawterm.8 new file mode 100644 index 00000000..2f5a1d50 --- /dev/null +++ b/static/plan9-4e/man8/drawterm.8 @@ -0,0 +1,124 @@ +.TH DRAWTERM 8 +.SH NAME +drawterm \- connect to Plan 9 CPU servers from other operating systems +.SH SYNOPSIS +.B drawterm +[ +.B -a +.I authaddr +] +[ +.B -c +.I cpuaddr +] +[ +.B -d +depth +] +[ +.B -r +root +] +[ +.B -nm +] +.SH DESCRIPTION +.I Drawterm +is +.I not +a Plan 9 program. +It is a program that users of non-Plan 9 systems can use +to establish graphical +.IR cpu (1) +connections with Plan 9 CPU servers. +Just as a real Plan 9 terminal does, +.I drawterm +serves its local name space +as well as some devices (the keyboard, mouse, and screen) +to a remote CPU server, which mounts this name space +on +.B /mnt/term +and starts a shell. +Typically, either explicitly or via the profile, one uses the shell +to start +.IR rio (1). +.PP +By default, +drawterm +uses the CPU server +.B CPUSERV +and the authentication server +.BR AUTHSERV . +The +.B -a +and +.B -c +options specify alternate servers. +(Edit the source to set appropriate local values for the variables +.B AUTHSERV +and +.BR CPUSERV ). +.PP +On Windows systems, the file system served by the +terminal (and mounted on +.BR /mnt/term ) +is the tree rooted at +.BR c:/ . +The +.B -r +option specifies a different file system root. +In Windows, the depth of the virtual screen +provided by +drawterm +matches the depth of the actual screen. +To present a screen with a different depth, use the +.B -d +option. +Both options do nothing on non-Windows systems. +.PP +The +.B -n +option causes +drawterm to prompt for authentication via +.IR netkey -style +challenge/response rather than using +the password-based protocol typically used +by terminals. +.PP +By default, drawterm queues mouse events to +guard against lost events due to network latency. +The +.B -m +option turns this behavior off. +.PP +Drawterm has been ported to +Digital Unix, +Irix, +Linux, +Solaris, +and +Windows. +Binaries are kept in +.BR /sys/src/cmd/unix/drawterm/bin . +.SH SOURCE +.B /sys/src/cmd/unix/drawterm +.SH DIAGNOSTICS +The Unix versions of drawterm print diagnostics +to standard error. +The Windows version displays message boxes. +.SH "SEE ALSO +.IR cpu (1), +.IR rio (1) +.SH BUGS +Although at first +.I drawterm +may seem like a Plan 9 terminal, in fact it is just a way to provide a CPU server +with some terminal devices. +The difference is important because one cannot run terminal-resident programs +when using +.IR drawterm . +The illusion can be improved by delicate adjustments in +.BR /usr/$user/lib/profile . +.PP +It would be nice to be able to change the default servers +without recompiling. diff --git a/static/plan9-4e/man8/fmtarenas.8 b/static/plan9-4e/man8/fmtarenas.8 new file mode 100644 index 00000000..b9f18816 --- /dev/null +++ b/static/plan9-4e/man8/fmtarenas.8 @@ -0,0 +1,64 @@ +.TH FMTARENAS 8 +.SH NAME +fmtarenas \- format a file into a number of Venti arenas +.SH SYNOPSIS +.B venti/fmtarenas +[ +.B -Z +] +[ +.B -a +.I arenasize +] +[ +.B -b +.I blocksize +] +.I name +.I file +.SH DESCRIPTION +.I Fmtarenas +formats the given +.IR file , +typically a disk partition, into a number of +.IR venti (8) +arenas. +The arenas are given names of the form +.IR name%d , +where +.I %d +is replaced with a sequential number starting at 0. +.PP +Option to +.I fmtarenas +are: +.TP +.BI -a " arenasize +The arenas are of +.I arenasize +bytes. The default is 512 megabytes, which was selected to provide a balance +between the number of arenas and the ability to copy an arena to external +media such as recordable CDs and tapes. +.TP +.BI -b " blocksize +The size, in bytes, for read and write operations to the file. +The size is recorded in the file, and is used by applications that access the arenas. +The default is 8k. +.TP +.B -Z +Do not zero the data sections of the arenas. +Using this option reduces the formatting time +but should only be used when it is known that the file was already zeroed. +.PP +The units for the various sizes can be specified by appending +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8), +.IR fmtisect (8), +.IR fmtindex (8) diff --git a/static/plan9-4e/man8/fmtindex.8 b/static/plan9-4e/man8/fmtindex.8 new file mode 100644 index 00000000..ec98f209 --- /dev/null +++ b/static/plan9-4e/man8/fmtindex.8 @@ -0,0 +1,60 @@ +.TH FMTINDEX 8 +.SH NAME +fmtindex \- format a Venti index +.SH SYNOPSIS +.B venti/fmtindex +[ +.B -a +] +.I venti.config +.SH DESCRIPTION +.I Fmtindex +takes the +.IR venti.conf (6) +file +.I venti.config +and initializes the index sections to form a usable index structure. +The arena files and index sections must have previously been formatted +using +.IR fmtarenas (8) +and +.IR fmtisect (8) +respectively. +.PP +The function of a Venti index is to map a Sha1 fingerprint to a location +in the data section of one of the arenas. The index is composed of +blocks, each of which contains the mapping for a fixed range of possible +fingerprint values. +.I Fmtindex +determines the mapping between Sha1 values and the blocks +of the collection of index sections. Once this mapping has been determined, +it cannot be changed without rebuilding the index. +The basic assumption in the current implementation is that the index +structure is sufficiently empty that individual blocks of the index will rarely +overflow. The total size of the index should be about 2% to 10% of +the total size of the arenas, but the exact depends both the index block size +and the compressed size of block stored to Venti. +.PP +.I Fmtindex +also computes a mapping between a linear address space and +the data section of the collection of arenas. The +.B -a +option can be used to add additional arenas to an index. +To use this feature, +add the new arenas to +.I venti.config +after the existing arenas and then run +.I fmtindex +.BR -a . +.PP +A copy of the above mappings is stored in the header for each of the index sections. +These copies enable +.IR buildindex (8) +to restore a single index section without rebuilding the entire index. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8), +.IR fmtarenas (8), +.IR fmtisect (8), +.IR venti.conf (6) diff --git a/static/plan9-4e/man8/fmtisect.8 b/static/plan9-4e/man8/fmtisect.8 new file mode 100644 index 00000000..b82966ba --- /dev/null +++ b/static/plan9-4e/man8/fmtisect.8 @@ -0,0 +1,50 @@ +.TH FMTISECT 8 +.SH NAME +fmtisect \- format a Venti index section +.SH SYNOPSIS +.B venti/fmtisect +[ +.B -Z +] +[ +.B -b +.I blocksize +] +.I name +.I file +.SH DESCRIPTION +.I Fmtisect +formats the given +.IR file , +typically a disk partition, as a Venti index section with the specified +.IR name . +One or more formatted index sections are combined into a Venti +index using +.IR fmtindex (8). +Each of the index sections within an index must have a unique name. +.PP +Options to +.I fmtisect +are: +.TP +.BI -b " blocksize +The size, in bytes, for read and write operations to the file. +All the index sections within a index must have the same block size. +The default is 8k. The units for the size can be specified by appending +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.TP +.B -Z +Do not zero the index. +Using this option reduces the formatting time +but should only be used when it is known that the file was already zeroed. +.PP +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8), +.IR fmtarenas (8), +.IR fmtindex (8) diff --git a/static/plan9-4e/man8/fs.8 b/static/plan9-4e/man8/fs.8 new file mode 100644 index 00000000..7c53e72f --- /dev/null +++ b/static/plan9-4e/man8/fs.8 @@ -0,0 +1,678 @@ +.TH FS 8 +.SH NAME +fs, exsort \- file server maintenance +.SH SYNOPSIS +.PD 0 +.B help +[ +.I command ... +] +.PP +.B arp +.I subcommand +.PP +.B cfs +.I filesystem +.PP +.B check +.RI [ options ] +.PP +.B clri +.RI [ file ...] +.PP +.B cpu +.RI [ proc ] +.PP +.B create +.I path uid gid perm +.RB [ lad ] +.PP +.B cwcmd +.I subcommand +.PP +.B date +.RB [[ +- ] +.IR seconds ] +.PP +.B duallow +.RI [ uid ] +.PP +.B dump +.PP +.B files +.PP +.B flag +.I flag +[ +.I channel +] +.PP +.B fstat +[ +.I files +] +.PP +.B halt +.PP +.B hangup +.I channel +.PP +.B newuser +.I name +.RI [ options ] +.PP +.B noattach +.PP +.B passwd +.PP +.B profile +.RB [ 01 ] +.PP +.B remove +.RI [ files ...] +.PP +.B route +.I subcommand +.PP +.BR stat [ adesw ] +.PP +.B stats +.RB [[ - ] +.IR flags ...] +.PP +.B sync +.PP +.B time +.I command +.PP +.B trace +.RI [ number ] +.PP +.B users +.RI [ file ] +.PP +.B version +.PP +.B who +.RI [ user ...] +.PP +.B wormeject +[ +.I tunit +] +.PP +.B wormingest +[ +.I tunit +] +.PD +.PP +.B disk/exsort +.RB [ -w ] +.RI [ file ] +.SH DESCRIPTION +Except for +.IR exsort , +these commands are available only on the console of an +.IR fs (4) +file server. +.PP +The console requires the machine's password to be supplied before +accepting commands. Typing a control-D will cause +the server to request +the password again. +.PP +.I Help +prints a `usage string' for the named +.IR commands , +by default all commands. +Also, many commands print menus of their options if given +incorrect or incomplete parameters. +.PP +.I Arp +has two +.IR subcommands : +.B print +prints the contents of the ARP cache and +.B flush +flushes it. +.PP +.I Cfs +changes the current file system, that is, the file tree to which +commands +.RB ( check , +.BR clri , +.BR create , +.BR newuser , +.BR profile , +.BR remove , +and +.BR users ) +apply. +The initial +.I filesystem +is +.BR main . +.PP +.I Check +verifies the consistency of the current file system. +With no options it checks and reports the status. +It suspends service while running. +Options are: +.TF touch +.PD +.TP +.B rdall +Read every block in the file system (can take a +.I long +time). +Normally, +.I check +will stop short of the actual contents +of a file and just verify the block addresses. +.TP +.B tag +Fix bad +.IR tags ; +each block has a tag that acts as a backwards pointer for +consistency checking. +.TP +.B ream +Fix bad tags +and also clear the contents +of blocks that have bad tags. +.TP +.B pfile +Print every file name. +.TP +.B pdir +Print every directory name. +.TP +.B free +Rebuild the list of free blocks +with all blocks that are not referenced. +This option is only useful on non-cache/WORM +file systems. +If the filesystem was modified, the summary printed +at the conclusion of the check may not reflect the true +state of the freelist and may also print a list of +.I missing +blocks. +These +.I missing +blocks are actually on the free list and the true +state of the filesystem can be determined by running +.I check +with no arguments. +.TP +.B bad +Each block address that is out of range or duplicate is cleared. +Note that only the second and subsequent +use of a block is cleared. +Often the problems in a file system are +caused by one bad file that has a lot of +garbage block addresses. +In such a case, +it is wiser to use +.I check +to find the bad file +(by number of diagnostic messages) +and then use +.I clri +to clear the addresses in that file. +After that, +.I check +can be used to reclaim the free list. +.TP +.B touch +Cause every directory and indirect block not on the current WORM disk +to be advanced to the current WORM on the next dump. +This is a discredited idea to try to keep operating +on the knee of the cache working set. +Buy more cache disk. +.PP +.I Clri +clears the internal directory entry and abandons storage +associated with +.IR files . +It ignores the usual rules for sanity, such as checking against +removing a non-empty directory. +A subsequent +.B check +.B free +will place the abandoned storage in the free list. +.PP +.I Cpu +prints the CPU utilization and state of the processes in the file server. +If the name of a process type argument is given, +then CPU utilization for only those processes is printed. +.PP +.I Create +creates a file on the current file system. +.I Uid +and +.I gid +are names or numbers from +.BR /adm/users . +.I Perm +is the low 9 bits of the permission mode of the file, in octal. +An optional final +.BR l , +.BR a , +or +.BR d +creates a locked file, append-only file, or directory. +.PP +.I Cwcmd +controls the cached WORM file systems. The subcommands are: +.TP +.BI mvstate " state1 state2 " [ platter ] +States are +.BR none , +.BR dirty , +.BR dump , +.BR dump1 , +.BR error , +.BR read , +and +.BR write . +A +.B mvstate +.B dump1 +.B dump +will cause I/O errors in the last dump to be retried. +A +.B mvstate +.B dump1 +.B write +will cause I/O errors in the last dump to be retried in +reallocated slots in the next dump. +A +.B mvstate +.B read +.B none +will flush the cache associated with the WORM. +A +.B mvstate +.B dump +.B write +aborts the background process dumping to WORM; as a consequence it +leaves holes in the dump file system. +Other uses are possible but arcane. +The optional +.I platter +limits affected blocks to those on that platter. +.TP +.BR prchain " [\fIstart\fP] [\fLback\fP] +Print the chain of superblocks for the directory containing the +roots of the dumped file systems, starting at block number +.I start +(default 0) going forward (backwards if +.B back +is supplied). +.TP +.BR savecache " [\fIpercent\fP] +Copy the block numbers, in native endian longwords, of blocks in the +.B read +state to the file +.BR /adm/cache +for use by +.BR disk/exsort . +If an argument is given, +then that percent (most recently used) of each cache bucket +is copied. +.TP +.BR loadcache " [\fIdskno\fP] +Read +.B /adm/cache +and for every block there on WORM disk +.IR dskno , +read the block from WORM to the cache. +If +.I dskno +is not supplied, all blocks in +.B /adm/cache +are read. +.TP +.BR startdump \ [ 01 ] +Suspend +.RB ( 0 ) +or restart +.RB ( 1 ) +the background dump process. +.TP +.B touchsb +Verify that the superblock on the WORM is readable, ignoring the cached copy. +.TP +.B acct +Prints how many times each user has caused the system to allocate new space on the WORM; +the units are megabytes. +.TP +.B clearacct +Clears the accounting records for +.BR acct . +.PP +.I Date +prints the current date. It may be adjusted +using +.BI +- seconds\f1. +With no sign, it sets the date to the absolute number of seconds +since 00:00 Jan 1, 1970 GMT; with a sign it trims the current +time. +.PP +.I Duallow +sets permissions such that +the named +.I user +can read and search any directories. +This is the permission necessary to do a +.IR du (1) +command anywhere in the file system to discover disk usage. +.PP +.I Dump +starts a dump to WORM immediately for all file systems that have +a WORM associated. +File service is suspended while the cache is scanned; +service resumes when the copy to WORM starts. +.PP +.I Files +prints for every connection the number of allocated fids. +.PP +.I Fstat +prints the current status of each named +.IR file , +including uid, gid, wuid (uid of the last user to modify the file), +size, qid, and disk addresses. +.PP +.I Flag +toggles flags, initially all off: +.TF attachxx +.TP +.B arp +Report ARP activity. +.TP +.B attach +Report as connections are made to the file server. +.TP +.B chat +(Very noisy.) Print all 9P messages to and from the server. +.TP +.B route +Report received RIP packets. +.TP +.B ro +Report I/O on the WORM device. +.PD +.PP +If given a second numeric +.I channel +argument, +as reported by +.IR who , +the flag is altered only on that connection. +.PP +.I Halt +does a +.B sync +and halts the machine, returning to the boot ROM. +.PP +.I Hangup +clunks all the fids on the named +.IR channel , +which has the same format as in the output of the +.I who +command. +.PP +.I Newuser +requires a +.I name +argument. +With no options it adds user +.IR name , +with group leader +.IR name , +to +.B /adm/users +and makes the directory +.BI /usr/ name +owned by user and group +.IR name . +The options are +.TF =leaderxx +.TP +.B ? +Print the entry for +.IR name . +.TP +.B : +Add a group: add the name to +.B /adm/users +but don't create the directory. +By convention, groups are numbered starting from 10000, users from 0. +.TP +.I newname +Rename existing user +.I name +to +.IR newname . +.TP +.BI = leader +Change the leader of +.I name +to +.IR leader . +If +.I leader +is missing, remove the existing leader. +.TP +.BI + member +Add +.I member +to the member list of +.IR name . +.TP +.BI - member +Remove existing +.I member +from the member list of +.IR name . +.PD +.PP +After a successful +.I newuser +command the file server overwrites +.B /adm/users +to reflect the internal state of the user table. +.PP +.I Noattach +disables +.IR attach (5) +messages, in particular for system maintenance. +Previously attached connections are unaffected. +Another +.I noattach +will enable normal behavior. +.PP +.I Passwd +sets the machine's password and writes it in non-volatile RAM. +.PP +.I Profile +.B 1 +clears the profiling buffer and enables profiling; +.I profile +.B 0 +stops profiling and writes the data to +.B /adm/kprofdata +for use by +.B kprof +(see +.IR prof (1)). +If a number is not specified, the profiling state toggles. +.PP +.I Remove +removes +.IR files . +.PP +.I Route +maintains an IP routing table. The +.I subcommands +are: +.TF "add dest gate mask" +.TP +.B add \f2dest gate \fP[\f2mask\fP] +Add a static route from IP address +.I dest +using gateway +.I gate +with an optional subnet +.IR mask . +.TP +.B delete \f2dest\fP +Delete an entry from the routing table. +.TP +.B print +Display the contents of the routing table. +.TP +.B ripon +Enables the table to be filled from RIP packets. +.TP +.B ripoff +Disables the table from being updated by RIP packets. +.PD +.PP +The +.I stat +commands are connected with a service or device identified by the +last character of the name: +.BR d , +SCSI targets; +.BR e , +Ethernet controllers; +.BR w , +cached WORM. +The +.I stata +command prints overall statistics about the file system. +The +.I stats +command takes an optional argument identifying the characters +of +.I stat +commands to run. The option is remembered and becomes the +default for subsequent +.I stats +commands if it begins with a minus sign. +.PP +.I Sync +writes dirty blocks in memory to the magnetic disk cache. +.PP +.I Time +reports the time required to execute the +.IR command . +.PP +.I Trace +with no options prints the set of queue-locks held by each process in +the file server. If things are quiescent, there should be no output. +With an argument +.I number +it prints a stack traceback of that process. +.PP +.I Users +uses the contents of +.I file +(default +.BR /adm/users ) +to initialize the file server's internal representation of the users +structure. +Incorrectly formatted entries in +.I file +will be ignored. +If file is explicitly +.BR default , +the system builds a minimal functional users table internally; +this can help recover from disasters. +If the +.I file +cannot be read, you +.I must +run +.IP +.EX +users default +.EE +.PP +for the system to function. The +.B default +table looks like this: +.IP +.EX +-1:adm:adm: +0:none:adm: +1:tor:tor: +10000:sys:: +10001:map:map: +10002:doc:: +10003:upas:upas: +10004:font:: +10005:bootes:bootes: +.EE +.PP +.I Version +reports when the file server was last compiled and last rebooted. +.PP +.I Who +reports, one per line, the names of users connected to the file server and the +status of their connections. +The first number printed on each line is the channel number of the connection. +If +.I users +are given the output selects connections owned by those users. +.PP +.I Wormeject +moves the WORM disk in slot +.I tunit +to the output shelf. +.PP +.I Wormingest +moves the WORM disk from the input shelf to +slot +.IR tunit . +.PP +When the file server boots, it prints the message +.IP +.EX +for config mode hit a key within 5 seconds +.EE +.PP +If a character is typed within 5 seconds of the message appearing, +the server will enter config mode. +See +.IR fsconfig (8) +for the commands available in config mode. +The system also enters config mode if, at boot time, +the non-volatile RAM does not appear to contain a valid configuration. +.PP +.I Exsort +is a regular command to be run on a CPU server, not on the file server +console. +It reads the named +.I file +(default +.BR /adm/cache ) +and sorts the cache disk block numbers contained therein. +It assumes the numbers are 4-byte integers and guesses the +endianness by looking at the data. +It then prints statistics about the cache. +With option +.B -w +it writes the sorted data back to +.IR file . +.SH SOURCE +.B /sys/src/fs +.br +.B /sys/src/cmd/disk/exsort.c +.SH SEE ALSO +.IR fs (4) +.br +Ken Thompson, +``The Plan 9 File Server''. diff --git a/static/plan9-4e/man8/fsconfig.8 b/static/plan9-4e/man8/fsconfig.8 new file mode 100644 index 00000000..76ea6742 --- /dev/null +++ b/static/plan9-4e/man8/fsconfig.8 @@ -0,0 +1,249 @@ +.TH FSCONFIG 8 +.SH NAME +fsconfig \- configuring a file server +.SH SYNOPSIS +.B service +.I name +.PP +.B config +.I device +.PP +.B filsys +.I name +.I device +.PP +.B ream +.I name +.PP +.B recover +.I name +.PP +.B ip +.I ipaddr +.PP +.B ipgw +.I ipaddr +.PP +.B ipmask +.I ipaddr +.PP +.B ipauth +.I ipaddr +.PP +.B ipsntp +.I ipaddr +.PP +.B end +.SH DESCRIPTION +When a file server's configuration has not been set, +or by explicit request early in the server's initialization (see +.IR fs (8)), +the server enters `config mode'. The commands described here +apply only in that mode. They establish configuration constants +that are typically valid for the life of the server, and therefore +need be run only once. If the non-volatile RAM on the server +gets erased, it will be necessary to recreate the configuration. +.PP +In these commands, +.I ipaddr +is an IP address in the form +.BR 111.103.94.19 +and +.I name +is a text string without white space. +The syntax of a +.I device +is more complicated: +.TP +.BI w n1 . n2 . n3 +A SCSI disk on target id +.IR n2 , +unit +.IR n1 , +and partition +.IR n3 . +A single number specifies a unit, while two numbers specify +.IB unit . partition\f1, +with the missing numbers defaulting to zero. +Any one of the numbers may be replaced by +.BI < m - n > +to represent the values +.I m +through +.I n +inclusive. For example, +.B (w<1-4>) +is the concatenation of SCSI targets 1 through 4. +.TP +.BI l n1 . n2 . n3 +.TP +.BI r n1 . n2 . n3 +The same as +.BR w , +but leaving a single block at the beginning for a label +.BI ( l ), +or not. +These are are only really relevant when used as +.I device3 +in the +.B j +device (see below). +.TP +.BI ( device... ) +A pseudo-device formed from the concatenation of the +.I devices +in the list. The devices are +.I not +blank- or comma-separated. +.TP +.BI [ device... ] +A pseudo-device formed from the block-wise interleaving of the +.I devices +in the list. The size of the result is the number of devices times +the size of the smallest device. +.TP +.BI p device . n1 . n2 +A partition starting at +.IR n1 % +from the beginning of +.I device +with a length +.IR n2 % +of the size of the device. +Parenthesize +.I device +if it contains periods. +.TP +.BR j (\f2device1\ device2\f1...)\f2device3 +.I Device1 +is the SCSI juke box interface. +The +.IR device2 s +are the SCSI drives in the jukebox and +.I device3 +represents the demountable platters in the juke box. +.TP +.BI f device +A pseudo-WORM disk: blocks on +.I device +can be written only once and may not be read unless written. +.TP +.BI c device1device2 +A cached WORM. The first +.I device +is the cache, the second the WORM. +.TP +.BI o +(Letter o) The read-only (dump) file system +of the previously defined cached WORM file system. +.PP +The +.B service +command sets the textual name of the server as known in +the network databases. +.PP +The configuration information is stored in block zero on a +device whose device string is written in non-volatile RAM. +The +.B config +command identifies the +.I device +on which the information is recorded. +.PP +The +.I filsys +command configures a file system on +.I device +and calls it +.IR name . +.I Name +is used as the specifier in +.B attach +messages to connect to that file system. +(The file system +.CW main +is the one attached to if the specifier is null; see +.IR attach (5)). +.PP +The +.I ream +command initializes the named file system. It overwrites +any previous file system on the same device +and creates an empty root directory +on the device. +If +.I name +is +.BR main , +the file server, until the next reboot, +will accept +.B wstat +messages +(see +.IR stat (5)) +that change the owner and group of files, +to enable initializing a fresh file system from a +.IR mkfs (8) +archive. +.PP +For the +.I recover +command, the +named file system +must be a cached WORM. +.I Recover +clears the associated magnetic cache and initializes the file +system, effectively resetting its contents to the last dump. +.PP +The rest of the commands record IP addresses: the file server's address +.RI ( ip ), +the local gateway's +.RI ( ipgw ), +the local authentication server's +.RI ( ipauth ), +the local subnet mask +.RI ( ipmask ), +and the address of a system running an SNTP server. +.I Ipauth +should be +.B 0.0.0.0 +if the system is doing its own authentication rather than +calling an external authentication server. +.PP +The various configuration commands only record what to do; they write +no data to disk. The command +.I end +exits config mode and begins running the file server proper. +The server will then perform whatever I/O is required to establish +the configuration. +.SH EXAMPLE +Initialize a file server +.B kgbsun +with a single file system interleaved between SCSI targets 3 and 4. +.IP +.EX +service kgbsun +config w3 +filsys main [w<3-4>] +ream main +.EE +.PP +Initialize a file server +.B kremvax +with a single disk on target 0 partitioned as a cached pseudo-WORM +file system with the cache on the third quarter of the drive +and the pseudo-WORM on the interleave of the first, second, and +fourth quarters. +.IP +.EX +service kremvax +config p(w0)50.1 +filsys main cp(w0)50.25f[p(w0)0.25p(w0)25.25p(w0)75.25] +filsys dump o +ream main +.EE +.SH SOURCE +.BR /sys/src/fs/port/config.c +.SH "SEE ALSO +Ken Thompson, +``The Plan 9 File Server''. diff --git a/static/plan9-4e/man8/httpd.8 b/static/plan9-4e/man8/httpd.8 new file mode 100644 index 00000000..2e569b85 --- /dev/null +++ b/static/plan9-4e/man8/httpd.8 @@ -0,0 +1,196 @@ +.TH HTTPD 8 +.SH NAME +httpd, echo, save, imagemap, man2html \- HTTP server +.SH SYNOPSIS +.PP +.B ip/httpd/httpd +.RB [ -a +.IR srvaddr ] +.RB [ -d +.IR domain ] +.RB [ -n +.IR namespace ] +.RB [ -w +.IR webroot ] +.PP +.B ip/httpd/echo +.RB [ -b +.IR inbuf ] +.RB [ -d +.IR domain ] +.RB [ -r +.IR remoteip ] +.RB [ -w +.IR webroot ] +.RB [ -N +.IR netdir ] +.I method version uri +.RI [ search ] +.PP +.B ip/httpd/save +.RB [ -b +.IR inbuf ] +.RB [ -d +.IR domain ] +.RB [ -r +.IR remoteip ] +.RB [ -w +.IR webroot ] +.RB [ -N +.IR netdir ] +.I method version uri +.RI [ search ] +.PP +.B ip/httpd/imagemap +.RB [ -b +.IR inbuf ] +.RB [ -d +.IR domain ] +.RB [ -r +.IR remoteip ] +.RB [ -w +.IR webroot ] +.RB [ -N +.IR netdir ] +.I method version uri +.PP +.B ip/httpd/man2html +.RB [ -b +.IR inbuf ] +.RB [ -d +.IR domain ] +.RB [ -r +.IR remoteip ] +.RB [ -w +.IR webroot ] +.RB [ -N +.IR netdir ] +.I method version uri +.RI [ search ] +.SH DESCRIPTION +.I Httpd +serves the +.I webroot +directory of the file system described by +.I namespace +(default +.BR /lib/namespace.httpd ), +using version 1.1 of the HTTP protocol. +It announces the service +.I srvaddr +(default +.BR tcp!*!http ), +and listens for incoming calls. +.PP +.I Httpd +supports only the GET and HEAD methods of the HTTP protocol; +some magic programs support POST as well. +Persistent connections are supported for HTTP/1.1 or later clients; +all connections close after a magic command is executed. +The Content-type +(default application/octet-stream) +and Content-encoding +(default binary) +of a file are determined by looking for suffixes of the file name in +.BR /sys/lib/mimetype . +.PP +Each requested URI is looked up in a redirection table, read from +.BR /sys/lib/httpd.rewrite . +If a prefix of the URI matches a redirection path, +the URI is rewritten using a replacement path, +and a redirect is sent to the HTTP client. +If the replacement path does not specify a server name, +and the request has no explicit host, +then +.I domain +is the host name used in the redirection. +.PP +Before opening any file, +.I httpd +looks for a file in the same directory called +.BR .httplogin . +If the file exists, the directory is considered +locked and the client must specify a user name +and password machine a pair in the file. +.B .httplogin +contains a list of space or newline separated tokens, each +possibly delimited by single quotes. The first +is a domain name presented to the HTTP client. +The rest are pairs of user name and password. +Thus, there can be many user name/password pairs +valid for a directory. +.PP +If the requested URI begins with +.BI /magic/ server /\f1, +.I httpd +executes the file +.BI /bin/ip/httpd/ server +to finish servicing the request. +.IR Method +and +.IR version +are those received on the first line of the request. +.I Uri +is the remaining portion of the requested URI. +.I Inbuf +contains the rest of the bytes read by the server, +and +.I netdir +is the network directory for the connection. +There are routines for processing command arguments, +parsing headers, etc. in the httpd library, +.BR /sys/src/cmd/ip/httpd/libhttpd.a.$O . +See +.B httpd.h +in that directory and existing magic commands for more details. +.PP +.I Echo +is a trivial server that just returns the method, URI, any search, +the headers, and the message body sent by the client. +.PP +.I Save +writes a line to +.BI /usr/web/save/ uri .data +and returns the contents of +.BI /usr/web/save/ uri .html. +Both files must be accessible for the request to succeed. +The saved line includes the current time +and either the search string from a HEAD or GET +or the first line of the body from a POST. +It is used to record form submissions. +.PP +.I Imagemap +processes an HTML imagemap query. +It looks up a the point +.I search +in the image map file given by +.IR uri , +and returns a redirection to the appropriate page. +The map file defaults to NCSA format. +Any entries after a line starting with the word +.B #cern +are interpreted in CERN format. +.PP +.I Man2html +converts +.IR man (6) +format manual pages into html. +It includes some abilities to search the manuals. +.SH FILES +.TF /lib/namespace.httpd +.TP +.B /sys/lib/mimetype +content type description file +.TP +.B /lib/namespace.httpd +default namespace file for httpd +.TP +.B /sys/lib/httpd.rewrite +redirection file +.SH SOURCE +.B /sys/src/cmd/ip/httpd +.SH "SEE ALSO" +.I newns +in +.IR auth (2), +.IR listen (8) diff --git a/static/plan9-4e/man8/init.8 b/static/plan9-4e/man8/init.8 new file mode 100644 index 00000000..94c3a465 --- /dev/null +++ b/static/plan9-4e/man8/init.8 @@ -0,0 +1,87 @@ +.TH INIT 8 +.SH NAME +init \- initialize machine upon booting +.SH SYNOPSIS +.B /$cputype/init +[ +.B -ctm +] [ +.I command ... +] +.SH DESCRIPTION +.I Init +initializes the machine: it establishes the name space (see +.IR namespace (4) +and +.I newns +in +.IR auth (2)), +and environment (see +.IR env (3)) +and starts a shell +.RI ( rc (1)) +on the console. +If a +.I command +is supplied, that is run instead of the shell. +On a CPU server the invoked shell runs +.IR cpurc (8) +before accepting commands on the console; +on a terminal, it runs +.IR termrc +and then the user's profile. +Options +.B -t +(terminal) +and +.B -c +(CPU) +force the behavior to correspond to the specified service class. +Otherwise +.I init +uses the value of the environment variable +.B $service +to decide the service class. +.PP +.I Init +sets environment variables +.B $service +(either to the incoming value or according to +.B -t +or +.BR -c ), +.B $objtype +(to the value of +.BR $cputype ), +.B $user +(to the contents of +.BR #c/user ), +and +.B $timezone +(to the contents of +.BR /adm/timezone/local ). +.PP +With option +.B -m +.I init +starts only an interactive shell +regardless of the +.I command +or service class. +.PP +On a CPU server, +.I init +requires the machine's password to be supplied before starting +.I rc +on the console. +.PP +.I Init +is invoked by +.IR boot (8), +which sets the arguments as appropriate. +.SH SOURCE +.B /sys/src/cmd/init.c +.SH "SEE ALSO" +.IR rc (1), +.IR auth (2), +.IR boot (8) diff --git a/static/plan9-4e/man8/ipconfig.8 b/static/plan9-4e/man8/ipconfig.8 new file mode 100644 index 00000000..ef547979 --- /dev/null +++ b/static/plan9-4e/man8/ipconfig.8 @@ -0,0 +1,205 @@ +.TH IPCONFIG 8 +.SH NAME +ipconfig, rip \- Internet configuration and routing +.SH SYNOPSIS +.B ip/ipconfig +.RB [ -ndDrG ] +.RB [ -b +.IR baud ] +.RB [ -m +.IR mtu ] +.RB [ -g +.IR gateway ] +.RB [ -h +.IR hostname ] +.RB [ -x +.IR netmtpt ] +.I type +.I device +.RI [ verb ] +.RI [ local-addr ] +.RI [ mask ] +.RI [ remote-addr ] +.RI [ file-server-addr ] +.RI [ auth-server-addr ] +.PP +.B ip/rip +.RB [ -bdr ] +.RB [ -x +.IR netmtpt ] +.SH DESCRIPTION +.I Ipconfig +binds a device interface (default +.BR /net/ether0 ) +to a mounted IP stack (default +.BR /net ) +and configures the interface with a local address, a +mask, and a remote address. The addresses can be specified +in the command line or obtained via DHCP. If DHCP is +requested, it will also obtain the addresses of DNS +servers, NTP servers, gateways, a Plan 9 file server, +and a Plan 9 authentication server. If this is the first +interface on the IP stack, the information will be +written to +.B /net/ndb +in the form of an +.IR ndb (8) +entry. +.PP +.I Type +may be +.BR ether , +.BR ppp , +or +.BR gbe . +The +.B gbe +type is equivalent to +.B ether +except that it allows jumbo packets. +For +.B ppp +the device can be any byte stream device. +.PP +The verb (default +.IR add ) +determines the action performed. The verbs are: +.TP +.B add +if the device is not bound to the IP stack, bind it. +Add the given local address, mask, and remote address to the interface. +An interface may have multiple addresses. +.TP +.B remove +remove the address from the device interface. +.TP +.B unbind +unbind the device interface and all its addresses from the +IP stack. +.PP +The options are: +.TP +.B x +use the IP stack mounted at +.I netmtpt +instead of at +.BR /net . +.TP +.B g +the default gateway. +.TP +.B d +use DHCP to determine any unspecified configuration parameters. +.TP +.B r +by default, +.I ipconfig +exits after trying DHCP for 15 seconds with no answer. +This option directs +.I ipconfig +instead to fork a background +process that keeps trying forever. +.TP +.B h +the hostname to add to DHCP requests. Some DHCP +servers, such as the one used by COMCAST, will not respond +unless a correct hostname is in the request. +.TP +.B n +determine parameters but don't configure the interface. +.TP +.B b +the baud rate to use on a serial line +when configuring +.BR PPP . +.TP +.B D +turn on debugging. +.TP +.B G +use only generic DHCP options. Without this option, +.I ipconfig +adds to requests a Vendor Class option with value +.BI plan9_$ cputype +and also requests vendor specific options 128 and 129 which we +interpret as the Plan 9 file server and auth server. +Replies to these options contain a list of IP addresses for possible +file servers and auth servers. +.TP +.B m +the maximum IP packet size to use on this +interface. +.PP +If DHCP is requested, a process is forked +off to renew the lease before it +runs out. If the lease does run out, this +process will remove any configured addresses +from the interface. +.PP +.I Rip +runs the routing protocol RIP. +It listens for RIP packets on connected networks and +updates the kernel routing tables. +The options are: +.TP +.B b +broadcasts routing information onto the networks. +.TP +.B n +gathers routing information but doesn't write to the +route table. This is useful with +.B \-d +to debug a network. +.TP +.B x +use the IP stack mounted at +.I netmtpt +instead of at +.BR /net . +.TP +.B d +turn on (voluminous) debugging. +.PP +.SH EXAMPLE +Configure Ethernet 0 as the primary IP interface. +Get all addresses via DHCP. Start up a connection server +and DNS resolver for this IP stack. +.IP +.EX +% bind -b '#l0' /net +% bind -a '#I0' /net +% ip/ipconfig +% ndb/cs +% ndb/dns -r +.EE +.PP +Add a second address to the stack. +.IP +.EX +% ip/ipconfig ether /net/ether0 add 12.1.1.2 255.255.255.0 +.EE +.PP +At Lucent our primary IP stack is always to the company's internal +firewall-protected network. The following creates an external +IP stack to directly access the outside Internet. Note that the +connection server uses a different set of +.I ndb +files. This prevents us from confusing inside and outside name/address +bindings. +.IP +.EX +% bind -b '#l1' /net.alt +% bind -b '#I1' /net.alt +% ip/ipconfig -x /net.alt -g 204.178.31.1 ether /net.alt/ether1\\ + 204.178.31.6 255.255.255.0 +% ndb/cs -x /net.alt -f /lib/ndb/external +% ndb/dns -sx /net.alt -f /lib/ndb/external +% aux/listen -d /rc/bin/service.alt /net.alt/tcp +% aux/listen -d /rc/bin/service.alt /net.alt/il +.EE +.SH SOURCE +.B /sys/src/cmd/ip/ipconfig.c +.br +.B /sys/src/cmd/ip/rip.c +.SH "SEE ALSO" +.IR ndb (6) diff --git a/static/plan9-4e/man8/ipserv.8 b/static/plan9-4e/man8/ipserv.8 new file mode 100644 index 00000000..313a125f --- /dev/null +++ b/static/plan9-4e/man8/ipserv.8 @@ -0,0 +1,239 @@ +.TH IPSERV 8 +.SH NAME +telnetd, rlogind, rexexec, ftpd, imap4d \- Internet remote access daemons +.SH SYNOPSIS +.PP +.B ip/telnetd +.RB [ -adnptN ] +.RB [ -u +.IR user ] +.PP +.B ip/rlogind +.PP +.B ip/rexexec +.PP +.B ip/ftpd +.RB [ -adp ] +.RB [ -n +.IR namepace-file ] +.PP +.B ip/imap4d +.RB [ -ap ] +.RB [ -d +.IR smtpdomain ] +.RB [ -s +.IR servername ] +.PP +.SH DESCRIPTION +These programs support remote access across the Internet. All expect the +network connection to be standard input, output, and error. They are normally +started from scripts in +.B /rc/bin/service +(see +.IR listen (8)). +.PP +.I Telnetd +allows login from a remote client. +There are three types of login: +.TF anonymous +.TP +.I normal +Normal users log in by encrypting and returning a +challenge printed by +.IR telnetd . +The user can use either the +.IR netkey +program +(see +.IR passwd (1)) +or a SecureNet handheld authenticator to encrypt the challenge. +.B /lib/namespace +defines the namespace. +.TP +.I noworld +Users in group +.B noworld +in +.BR /adm/users +authenticate with a password in the clear. +.B /lib/namespace.noworld +defines the namespace. +.TP +.I anonymous +User +.B none +requires no authentication. +.B /lib/namespace +defines the namespace. +.PD +.PP +The options are: +.TP +.B a +allow anonymous login by +.B none +.TP +.B d +print debugging to standard error +.TP +.B p +don't originate any telnet control codes +.TP +.B n +turn on local character echoing and imply the +.B p +option +.TP +.B t +trusted, that is, don't authenticate +.TP +.B u +use +.I user +as the local account name +.TP +.B N +permit connections by `noworld' users only. +.PD +.PP +.I Rlogind +logs in using the BSD remote login protocol. +.I Rlogind +execs +.I telnetd +.B -nu +after completing its initial handshake. +.PP +.I Rexexec +executes a command locally for a remote client. It uses the +standard Plan 9 authentication (see +.IR authsrv (6)). +.PP +.I Ftpd +runs the Internet file transfer protocol. Users may transfer +files in either direction between the local and +remote machines. +As for +.IR telnetd , +there are three types of login: +.TF anonymous +.TP +.I normal +Normal users authenticate +via the same challenge/response as for +.IR telnetd . +.BI /usr/ username /lib/namespace.ftp +or, if that file does not exist, +.B /lib/namespace +defines the namespace. +.TP +.I noworld +Users in group +.B noworld +in +.B /adm/users +login using a password in the clear. +.B /lib/namespace.noworld +defines the namespace. +.TP +.I anonymous +Users +.B anonymous +and +.B none +require no authentication. +The argument to the +.B \-n +option (default +.IR /lib/namespace.ftp ) +defines the namespace. +Anonymous users may only store files in the subtree +below +.BR /incoming . +.PD +.PP +The options are: +.TP +.B a +allow anonymous access +.TP +.B n +the namespace for anonymous users (default +.BR /lib/namespace.ftp ) +.TP +.B d +write debugging output to standard error +.PP +.I Imap4d +provides access to a user's mailboxes via the IMAP4rev1 protocol. +Only files rooted in +.BI /mail/box/ username / +are accessible. +The list of subscribed mailboxes is contained in +.BI /mail/box/ username /imap.subscribed , +and initially contains only +.BR INBOX , +IMAP's name for the user's mailbox. +A shadow file, +.IB mailbox .imp , +is created for each mailbox examined. +.PP +The options are: +.TP +.B a +Assume the user is already authenticated. +By default, the user must authenticate using +CRAM-MD5 or +.IR securenet (8) +challenge/response authentication. +.TP +.B p +Allow login authentication. This option +should only be enabled for servers using +an encrypted connection, such as SSL, +and when enabled, all non-encrypted connections should be disallowed. +.I Imap4d +does not enforce this policy. +.TP +.B s +The server's name. +If none is provided, +.B cs +(see +.IR ndb (8)) +is queried or +.B /env/sysname +is used. +.TP +.B d +The local mail domain. +Defaults to the server +.B /env/site +in the mail server's domain. +.SH FILES +.B /lib/namepace +.br +.BI /usr/ username /lib/namespace.ftp +.br +.B /lib/namespace.world +.br +.B /lib/namespace.ftp +.br +.BI /mail/box/ username / mailbox +.br +.BI /mail/box/ username / mailbox .imp +.br +.BI /mail/box/ username /imap.subscribed +.SH SOURCE +.B /sys/src/cmd/ip/telnetd.c +.br +.B /sys/src/cmd/ip/rlogind.c +.br +.B /sys/src/cmd/ip/rexexec.c +.br +.B /sys/src/cmd/ip/ftpd.c +.br +.B /sys/src/cmd/ip/imap4d/ +.br +.SH "SEE ALSO" +.IR ftpfs (4) diff --git a/static/plan9-4e/man8/kfscmd.8 b/static/plan9-4e/man8/kfscmd.8 new file mode 100644 index 00000000..e2122a6f --- /dev/null +++ b/static/plan9-4e/man8/kfscmd.8 @@ -0,0 +1,198 @@ +.TH KFSCMD 8 +.SH NAME +kfscmd, ksync \- kfs administration +.SH SYNOPSIS +.B disk/kfscmd +.RB [ -n +.IR name ] +cmd ... +.PP +.B disk/ksync +.SH DESCRIPTION +.I Kfs +is a local user-level file server for a Plan 9 terminal with a disk. +.I Kfscmd +transmits commands to the +.I kfs +server (see +.IR kfs (4)). +The +.B -n +option changes the name of the kfs service to +.BI kfs. name +(by default, full name is just +.BR kfs ). +.PP +.I Ksync +executes the +.B sync +command for all active +.I kfs +servers. +.PP +The known commands are described below. +Note that some commands are multiple words and +should be quoted to appear as a single argument to +.IR rc (1). +.TP \w'\fLallowoff\ \fIn'u +.B allow +Turn permission checking off (to simplify administration). +.TP +.B allowoff +.TP +.B disallow +Turn permission checking on. +.TP +.B noauth +Disable authentication of users. +.TP +.B halt +Write all changed blocks and stop the file system. +.TP +.B start +The opposite of halt; restart the file system. +.TP +.B help +Print the list of commands. +.TP +.BI "rename " "file name" +Change the name of +.I file +to +.IR name . +.I Name +may be a single path element or a full path; if it is a full path, +every element along the path must exist except the last. +.TP +.BI "newuser " user +Add +.I user +to +.B /adm/users +and make the standard directories needed for booting. +.TP +.BI "remove " file +Remove +.I file +and place its blocks on the free list. +.TP +.BI "clri " file +Remove +.I file +but do not place the blocks on the free list. +This command can be used to remove files that have duplicated blocks. +The non-duplicate blocks can be retrieved by checking the file system +with option +.B f +(see below). +.TP +.BI create \ file\ owner\ group\ mode\ [adl] +Create the file. Owner and group are users in +.B /adm/users +and mode is an octal number. +If present, +.L a +creates an append only file, +.L d +creates a directory, and +.L l +creates a file that is exclusive-use. +.TP +.B sync +Write to disk all of the dirty blocks in the memory cache. +.TP +.B atime +Toggle whether atimes are updated as files and directories +are accessed. By default, atimes are updated. On laptops it can be +useful to turn off atime updates to reduce disk accesses. +.TP +.B stats +Report statistics about the performance of the file system. +.TP +.B user +Re-initialize authentication information by reading +.BR /adm/users . +.TP +.BI cfs " filsys +Change the `console' to the named file system (default is the main system). +.TP +.B chat +Toggle tracing of 9P messages. +.TP +.B check [PRdfprtw] +Check the file system. +The options are +.PD 0 +.RS +.TP +.B p +print the names of directories as they are checked. +.TP +.B P +print the names of all files as they are checked. +.TP +.B r +read all of the data blocks and check the tags. +.TP +.B f +rebuild the list of free blocks. +.TP +.B d +delete redundant references to a block. +.TP +.B t +fix bad tags. +.TP +.B c +fix bad tags and clear the contents of the block. +.TP +.B w +write all of the blocks that are touched. +.RE +.PD +.TP +.BI listen " [address] +Start a listener to serve the network at +.IR address , +default +.BR il!*!17008 . +This feature is intended to facilitate small networks of a couple +machines in the situation when convenience is more +important than performance. +This command is only useful on machines with +(possibly simulated) NVRAM, which needs to be readable +to the +.I kfs +processes; +see +.I readnvram +in +.IR authsrv (2). +The production file server +(see +.IR fs (4)) +is strongly encouraged for anything more than casual use. +.TP +.B noneattach +When listening to the network, the default behavior is that the user +.B none +may only attach over connections that have already +authenticated as someone else. +This prevents just anyone from being +able to dial your server and attach as +.BR none . +The +.B noneattach +command toggles whether +.B none +can attach without such a chaperone. +.PD +.SH SOURCE +.B /sys/src/cmd/disk/kfscmd.c +.br +.B /$objtype/bin/disk/ksync +.SH "SEE ALSO" +.IR kfs (4), +.IR mkfs (8), +.IR prep (8), +.IR sd (3) diff --git a/static/plan9-4e/man8/listen.8 b/static/plan9-4e/man8/listen.8 new file mode 100644 index 00000000..4e4c5378 --- /dev/null +++ b/static/plan9-4e/man8/listen.8 @@ -0,0 +1,172 @@ +.TH LISTEN 8 +.SH NAME +listen, il7, il9, il19, il565, il566, il17007, il17008, il17009, il17013, il17031, tcp7, tcp9, tcp19, tcp21, tcp23, tcp25, tcp53, tcp110, tcp113, tcp143, tcp513, tcp515, tcp564, tcp565, tcp566, tcp567, tcp993, tcp17007, tcp17009, tcp17013 \- listen for calls on a network device +.SH SYNOPSIS +.B aux/listen +.RB [ -q ] +.RB [ -d +.IR srvdir ] +.RB [ -t +.IR trustsrvdir ] +.RB [ -n +.IR namespace ] +.RI[ net +.RI [ name ]] +.SH DESCRIPTION +.I listen +announces itself to a network as +.I name +(by default the contents of +.BR /env/sysname ) +and listens for inbound calls to local services. +.I Net +is the network protocol on which to listen, by default +.BR /net/il . +The services available are executable files in +.I srvdir +or +.IR trustsrvdir . +If neither +.I srvdir +nor +.I trustsrvdir +is given, +.I listen +looks for executable files in +.BR /bin/service . +Services found in +.I srvdir +are executed as user +.BR none ; +services found in +.I trustsrvdir +as executed as the user who started +.IR listen . +Option +.B -q +suppresses affirmative log information; +option +.B -n +sets an alternate +.I namespace +file (default +.BR /lib/namespace ). +.PP +Service names are made by concatenating the name of +the network with the name of the service or port. +For example, +an inbound call on the TCP network for port 565 executes service +.BR tcp565 . +.PP +The following services are available in +.BR /bin/service . +.TF il17005\ tcp17005 +.TP +.B il19 tcp19 +.B chargen +service. +.TP +.B il17007 tcp17007 +serve a piece of the name space using the Plan 9 file system protocol, +with authentication (typically used by +.IR cpu (1)). +.TP +.B tcp564 +like 17007, without authentication (used by Unix +systems to see Plan 9 files). +.TP +.B il17008 +like 17007, but serves the root of the tree, forgoing the negotiation for which subtree to serve. +.TP +.B il17009 tcp17009 +remote execution. +.TP +.B "il17013 tcp17013" +server for +.IR cpu (1) +command. +.TP +.B il17031 +server for +.IR ramfs (4). +.TP +.B il565 tcp565 +report the address of the incoming call. +.TP +.B tcp21 +FTP daemon +.TP +.B tcp515 +LP daemon; see +.IR lp (8). +.TP +.B tcp23 +.B telnet +terminal connection. +.TP +.B tcp25 +mail delivery. +.TP +.B tcp513 +.B rlogin +terminal connection. +.TP +.B il7 tcp7 +echo any bytes received (bit mirror) +.TP +.B il9 tcp9 +consume any bytes received (bit bucket) +.TP +.B tcp53 +TCP port for DNS. +.TP +.B tcp110 +POP3 port. +.TP +.B tcp143 +IMAP4rev1 port. +.TP +.B tcp113 +.B Ident +port (always reports +.BR none ). +.TP +.B tcp567 +Plan 9 ticket service. +.PD +.PP +The following services are available in +.BR /bin/service.auth . +.TF il565\ tcp565 +.TP +.B tcp566 +check a SecureNet box. +.TP +.B il566 +authentication requests. +.TP +.B tcp993 +Secure IMAP4rev1 port. +.SH FILES +.TF /env/sysname +.TP +.B /net/il +by convention, IL device bind point +.TP +.B /net/tcp +by convention, TCP device bind point +.TP +.B /env/sysname +default announced name +.SH SOURCE +The source to +.I listen +is in +.BR /sys/src/cmd/aux/listen.c . +The other commands are +.IR rc (1) +scripts in +.BR /rc/bin/service . +.SH "SEE ALSO" +.IR authsrv (6), +.IR dial (2) diff --git a/static/plan9-4e/man8/lp.8 b/static/plan9-4e/man8/lp.8 new file mode 100644 index 00000000..f4502bc9 --- /dev/null +++ b/static/plan9-4e/man8/lp.8 @@ -0,0 +1,126 @@ +.TH LP 8 +.SH NAME +lp \- PostScript preprocessors +.SH DESCRIPTION +These programs are part of the +.IR lp (1) +suite. +Each corresponds to a +.I process +in the +.BI -p process +option of +.I lp +and exists as an +.IR rc (1) +script in +.B /sys/lib/lp/process +that provides an interface to a PostScript conversion program in +.BR /$cputype/bin/aux . +The list of processors follows; +after each description is a bracketed list of +.I lp +options to which the processor responds: +.TF \fIp9bitpost\fP +.TP +.I dpost +converts +.IR troff (1) +output for device +.SM post +to PostScript. +This is used for files troff'ed on our +.SM UNIX +systems that do not handle +.SM UTF +characters. +.RB [ DLcimnorxy ] +.TP +.I dvipost +converts +.IR tex (1) +output to PostScript. +.RB [ Lcinor ] +.TP +.I g3post +converts CCITT Group 3 FAX data to PostScript. +.RB [ DLm ] +.TP +.I gifpost +converts GIF image data to PostScript. +.RB [ DLm ] +.TP +.I generic +is the default processor. +It uses +.IR file (1) +to determine the type of input and executes the correct +processor for a given (input, printer) pair. +.TP +.I hpost +adds a header page to the beginning of a PostScript printer +job so that it may be separated from other jobs in the output bin. +The header has the image of the job's owner from the directory of faces (see +.IR face (6)). +Page reversal is also done in this processor. +.TP +.I jpgpost +converts JPEG image data to PostScript. +.RB [ DLm ] +.TP +.I noproc +passes files through untouched. +.TP +.I p9bitpost +.na +converts a Plan 9 image to PostScript, such as +.B /dev/screen +for the whole screen, +.B /dev/window +for that window's data, +and +.B /dev/wsys/.../window +for some other window's data. +.RB [ DLm ] +.ad +.TP +.I pdfpost +converts PDF data to PostScript. +.TP +.I post +passes PostScript through, adding option patches for paper tray information. +This does not always work with PostScript generated on other systems. +.TP +.I ppost +converts +.SM UTF +text to PostScript. +.RB [ DLcfilmnorxy ] +.TP +.I tr2post +converts +.IR troff (1) +output for device +.SM utf +(the default) to PostScript. +See +.B /sys/lib/troff/font/devutf +directory for troff font width table descriptions. +See also the +.B /sys/lib/postscript/troff +directory for mappings of +troff +.SM UTF +character space to PostScript +font space. +.RB [ DLcimnorxy ] +.SH SOURCE +.B /sys/src/cmd/postscript +.SH SEE ALSO +.IR lp (1) +.SH BUGS +The +.I file +command is not always smart enough to deal with certain file +types. +There are PostScript conversion programs that do not have processors to drive them. diff --git a/static/plan9-4e/man8/mk9660.8 b/static/plan9-4e/man8/mk9660.8 new file mode 100644 index 00000000..0f50b7fe --- /dev/null +++ b/static/plan9-4e/man8/mk9660.8 @@ -0,0 +1,231 @@ +.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 +(default +.BR /sys/lib/sysconfig/proto/allproto ) +from the file tree +.I src +(default +.BR / ). +The +.I proto +file is formatted as described in +.IR mkfs (8). +.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 +alos 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 +.IR dossrv (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 +.IR fs (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 -p plan9proto cdimage +.EE +.SH SOURCE +.B /sys/src/cmd/disk/9660 +.SH "SEE ALSO" +.I 9660srv +(in +.IR dossrv (4)), +.IR cdfs (4), +.IR mkfs (8) diff --git a/static/plan9-4e/man8/mkfs.8 b/static/plan9-4e/man8/mkfs.8 new file mode 100644 index 00000000..796539ab --- /dev/null +++ b/static/plan9-4e/man8/mkfs.8 @@ -0,0 +1,187 @@ +.TH MKFS 8 +.SH NAME +mkfs, mkext \- archive or update a file system +.SH SYNOPSIS +.B disk/mkfs +.RB [ -aprvxU ] +.RB [ -d +.IR root ] +.RB [ -n +.IR name ] +.RB [ -s +.IR source ] +.RB [ -u +.IR users ] +.RB [ -z +.IR n ] +.I proto ... +.PP +.B disk/mkext +.RB [ -d +.IR name ] +.RB [ -u ] +.RB [ -h ] +.RB [ -v ] +.RB [ -x ] +.I file ... +.SH DESCRIPTION +.I Mkfs +copies files from the file tree +.I source +(default +.BR / ) +to a +.B kfs +file system (see +.IR kfs (4)). +The kfs service is mounted on +.I root +(default +.BR /n/kfs ), +and +.B /adm/users +is copied to +.IB root /adm/users\f1. +The +.I proto +files are read +(see +.IR proto (2) +for their format) +and any files specified in them that are out of date are copied to +.BR /n/kfs . +.PP +.I Mkfs +copies only those files that are out of date. +Such a file is first copied into a temporary +file in the appropriate destination directory +and then moved to the destination file. +Files in the +.I kfs +file system that are not specified in the +.I proto +file +are not updated and not removed. +.PP +The options to +.I mkfs +are: +.TF "s source" +.TP +.B a +Instead of writing to a +.B kfs +file system, write an archive file to standard output, suitable for +.IR mkext . +All files in +.IR proto , +not just those out of date, are archived. +.TP +.B x +For use with +.BR -a , +this option writes a list of file names, dates, and sizes to standard output +rather than producing an archive file. +.TP +.BI "d " root +Copy files into the tree rooted at +.I root +(default +.BR /n/kfs ). +This option suppresses setting the +.B uid +and +.B gid +fields when copying files. +Use +.B -U +to reenable it. +.TP +.BI "n " name +Use +.RI kfs. name +as the name of the kfs service (default +.BR kfs ). +.TP +.B p +Update the permissions of a file even if it is up to date. +.TP +.B r +Copy all files. +.TP +.BI "s " source +Copy from files rooted at the tree +.IR source . +.TP +.BI "u " users +Copy file +.I users +into +.B /adm/users +in the new system. +.TP +.B v +Print the names of all of the files as they are copied. +.TP +.BI "z " n +Copy files assuming kfs block +.I n +(default 1024) +bytes long. +If a block contains only 0-valued bytes, it is not copied. +.PD +.PP +.I Mkext +unpacks archive files made by the +.B -a +option of +.IR mkfs . +The +.B -d +option specifies a directory (default +.BR / ) +to serve as the root of the unpacked file system. +The +.B -u +option, to be used only when initializing a new +.IR fs (4) +file system, sets the owners of the files created to correspond to +those in the archive and restores the modification times of the files. +(This is only permitted at the initial load of the files into a file +system.) +Each file on the command line is unpacked in one pass through the archive. +If the file is a directory, +all files and subdirectories of that directory are also unpacked. +When a file is unpacked, the entire path is created if it +does not exist. +If no files are specified, the entire archive is unpacked; +in this case, missing intermediate directories are not created. +The +.B -v +option prints the names and sizes of files as they are extracted; +.B -h +prints headers for the files on standard output +instead of unpacking the files. +.SH EXAMPLES +.PP +Make an archive to establish a new file system: +.IP +.EX +disk/mkfs -a -u files/adm.users -s dist proto > arch +.EE +.PP +Unpack that archive onto a new file system: +.IP +.EX +srv il!newfs +mount -c /srv/il!newfs /n/newfs +disk/mkext -u -d /n/newfs < arch +.EE +.SH SOURCE +.B /sys/src/cmd/disk/mkfs.c +.br +.B /sys/src/cmd/disk/mkext.c +.SH "SEE ALSO" +.IR prep (8), +.IR kfscmd (8), +.IR sd (3) diff --git a/static/plan9-4e/man8/mkpaqfs.8 b/static/plan9-4e/man8/mkpaqfs.8 new file mode 100644 index 00000000..691f4856 --- /dev/null +++ b/static/plan9-4e/man8/mkpaqfs.8 @@ -0,0 +1,52 @@ +.TH MKPAQFS 8 +.SH NAME +mkpaqfs \- make a compressed read-only file system +.SH SYNOPSIS +.B mkpaqfs +[ +.B -u +] [ +.B -b +.I blocksize +] [ +.B -l +.I label +] [ +.B -o +.I file +] [ +.I source +] +.SH DESCRIPTION +.I Mkpaqfs +copies files from the file tree +.I source +(default +.BR . ) +to a the +.IR paqfs (4) +file system archive +.IR file . +.PP +The files and directory structure are divided into +.I blocksize +(default +.BR 4096 ) +byte blocks. +Larger blocks make large files more compact but take longer to access. +.I Blocksize +must be in the range of 512 bytes to 52K bytes. +If the +.B -u +option is set, the blocks are not compressed. +Otherwise each block is compressed using the +.IR flate (2) +compression algorithm. +The +.B -l +option embeds a label of up to 32 bytes within the file header and may be +useful for identifying the file system. +.SH SOURCE +.B /sys/src/cmd/paqfs/mkpaqfs.c +.SH "SEE ALSO" +.IR paqfs (4) diff --git a/static/plan9-4e/man8/mksacfs.8 b/static/plan9-4e/man8/mksacfs.8 new file mode 100644 index 00000000..fbeb11c2 --- /dev/null +++ b/static/plan9-4e/man8/mksacfs.8 @@ -0,0 +1,38 @@ +.TH MKSACFS 8 +.SH NAME +mksacfs \- make a compressed file system +.SH SYNOPSIS +.B disk/mksacfs +.RB [ -u ] +.RB [ -b +.IR blocksize ] +.RB [ -o +.IR file ] +.I source +.SH DESCRIPTION +.I Mksacfs +copies files from the file tree +.I source +(default +.BR . ) +to a the +.IR sacfs (4) +file system archive +.IR file . +.PP +The files and directory structure are divided into +.I blocksize +(default +.BR 4096 ) +byte blocks. +Larger blocks make large files more compact but take longer to access. +.I Blocksize +must be at least 116. +If +.B -u +is given, the blocks are not compressed. +Otherwise each block is compressed using an efficient compression algorithm. +.SH SOURCE +.B /sys/src/cmd/disk/sacfs/mksacfs.c +.SH "SEE ALSO" +.IR sacfs (4) diff --git a/static/plan9-4e/man8/mouse.8 b/static/plan9-4e/man8/mouse.8 new file mode 100644 index 00000000..a3bb52ea --- /dev/null +++ b/static/plan9-4e/man8/mouse.8 @@ -0,0 +1,120 @@ +.TH MOUSE 8 +.SH NAME +aux/mouse, aux/accupoint \- configure a mouse to a port +.SH SYNOPSIS +.B aux/mouse +[ +.B -b +.I baud +] [ +.B -d +.I type +] [ +.B -n +] +.I port +.PP +.B aux/accupoint +.SH DESCRIPTION +.B Mouse +queries a mouse on a serial or PS2 port for +its type and then configures the port and the +mouse to be used to control the cursor. +.PP +.I Port +can be either a port number (e.g. +.B 0 +or +.BR 1 ) +or the string +.B ps2 +or +.BR ps2intellimouse . +The initialization can be automated by setting +.BR mouseport +in +.IR plan9.ini (8), +which will enable a call to +.I mouse +in +.B termrc +(see +.IR cpurc (8)). +.PP +The option +.B -d +provides a default mouse type should +.B mouse +fail to determine it. The +types are: +.IP C +Logitech type C mouse +.IP W +Logitech type W mouse +.IP M +Microsoft compatible mouse +.PP +The +.B -n +flag queries the mouse and reports its type but does not set the device type. +.PP +The +.B -b +flag sets the baud rate for communication; it is effectual only for serial mice. +.SH +.I Accupoint +is a process, to be used with +.IR pipefile (1), +that processes events from an AccuPoint II pointing device +with four buttons, such as on Toshiba Portégé 3440CT and 3480CT +laptops, converting events on the two extra buttons +(which appear as buttons 4 and 5 in the +.IR mouse (3) +interface) into a simulation of button 2. +These extra buttons on laptops are in turn simulations of Intellimouse +scrolling buttons and have peculiar properties: they generate +only `down' events that repeat automatically, like a keypad, in +an approximation of the Intellimouse scroll wheel. +.I Accupoint +overcomes this behavior to produce a reasonable approximation of +a normal mouse button 2: +it makes left button act like a regular button 2, but is slow to release (the +program must wait for a repeat time before it knows the button has been released), +while the right button generates a fast button 2 `click'. +To use +.IR accupoint , +add a line like this to +.B /usr/$user/lib/profile +or to a system-dependent configuration script in +.B termrc +(see +.IR cpurc (8)): +.EX +.IP +pipefile -dr /bin/aux/accupoint /dev/mouse +.EE +.PP +Before running +.IR accupoint , +the mouse should be configured as an +.B intellimouse +or +.BR ps2intellimouse . +.SH SOURCE +.B /sys/src/cmd/aux/mouse.c +.br +.B /sys/src/cmd/aux/accupoint.c +.SH SEE ALSO +.IR cons (3), +.IR cpurc (8), +.IR pipefile (1). +.SH BUGS +Due to the limitations of +.IR pipefile (1), +when running +.I accupoint +it is difficult restart +.IR rio (1) +if it has exited. + + diff --git a/static/plan9-4e/man8/na.8 b/static/plan9-4e/man8/na.8 new file mode 100644 index 00000000..eb0a111e --- /dev/null +++ b/static/plan9-4e/man8/na.8 @@ -0,0 +1,33 @@ +.TH NA 8 +.SH NAME +na \- assembler for the Symbios Logic PCI-SCSI I/O Processors +.SH SYNOPSIS +.B aux/na file +.SH DESCRIPTION +The SYM53C8XX series of PCI-SCSI I/O Processors contain +loadable microcode to control their operation. +The microcode is written in a language called SCRIPTS. +.I Aux/na +is an assembler for the SCRIPTS programming language. +It assembles SCRIPTS code in +.I file +into an array of assembled SCRIPTS +instructions, patches, defines and enums +that can be included in a C device driver. +.SH SOURCE +.TF /sys/src/cmd/aux/na +.TP +.B /sys/src/cmd/aux/na +.SH "SEE ALSO" +Symbios Logic, +``PCI-SCSI I/O Processors Programming Guide Version 2.1'' +.br +.TF /sys/src/9/*/sd53c8xx.c +.TP +.B /sys/src/9/*/sd53c8xx.n +SCRIPTS source code +.TP +.B /sys/src/9/*/sd53c8xx.c +driver for the SYM53C8XX series of PCI-SCSI controllers +.SH AUTHOR +Nigel Roles (ngr@9fs.org) diff --git a/static/plan9-4e/man8/ndb.8 b/static/plan9-4e/man8/ndb.8 new file mode 100644 index 00000000..322a1373 --- /dev/null +++ b/static/plan9-4e/man8/ndb.8 @@ -0,0 +1,459 @@ +.TH NDB 8 +.SH NAME +query, mkhash, mkdb, cs, csquery, dns, dnsquery, ipquery, dnsdebug, mkhosts \- network database +.SH SYNOPSIS +.B ndb/query +[ +.B -f +.I dbfile +] +.I "attr value" +[ +.I rattr +] +.br +.B ndb/ipquery +.I "attr value" +.I rattr... +.br +.B ndb/mkhash +.I "file attr" +.br +.B ndb/cs +[ +.B -n +] [ +.B -f +.I dbfile +] [ +.B -x +.I netmtpt +] +.br +.B ndb/csquery +[ +.B -s +] +[ +.B server +[ +.I addr... +] +] +.br +.B ndb/dns +[ +.B -rs +] [ +.B -f +.I dbfile +] [ +.B -x +.I netmtpt +] +.br +.B ndb/dnsquery +.br +.B ndb/dnsdebug +[ +.B -rx +] +[ [ +.BI @ server +] +.I domain-name +[ +.I type +] ] +.br +.B ndb/mkdb +.SH DESCRIPTION +The network database holds administrative information used by +network programs such as +.IR dhcpd (8), +.IR ipconfig (8), +.IR con (1), +etc. +.PP +.I Ndb/query +searches the database for an attribute of type +.I attr +and value +.IR value . +If +.I rattr +is not specified, all entries matched by the search are returned. +If +.I rattr +is specified, the value of the first pair with attribute +.I rattr +of all the matched entries is returned. +.PP +.I Ndb/ipquery +uses +.I ndbipinfo +(see +.IR ndb (2)) +to search for the values of the attributes +.I rattr +corresponding to the system +with entries of attribute type +.I attr +and +value +.IR value . +.PP +.I Ndb/mkhash +creates a hash file for all entries with attribute +.I attr +in database file +.IR file . +The hash files are used by +.I ndb/query +and by the ndb library routines. +.PP +.I Ndb/cs +is a server used by +.IR dial (2) +to translate network names. +It is started at boot time. +It finds out what networks are configured +by looking for +.B /net/*/clone +when it starts. +It can also be told about networks by writing +to +.B /net/cs +a message of the form: +.IP +.B "add net1 net2 ..." +.PP +.I Ndb/cs +also sets the system name in +.B /dev/sysname +if it can figure it out. +The options are: +.TP +.B -f +supplies the name of the data base file to use, +default +.BR /lib/ndb/local . +.TP +.B -x +specifies the mount point of the +network. +.TP +.B -n +causes cs to do nothing but set the system name. +.PP +.I Ndb/csquery +can be used to query +.I ndb/cs +to see how it resolves addresses. +.I Ndb/csquery +prompts for addresses and prints out what +.I ndb/cs +returns. +.I Server +defaults to +.BR /net/cs . +If any +.I addrs +are specified, +.I ndb/csquery +prints their translations and immediately exits. +The exit status will be nil only if all addresses +were successfully translated +The +.B -s +flag sets exit status without printing any results. +.PP +.I Ndb/dns +is a server used by +.I ndb/cs +and by remote systems to translate Internet domain names. +.I Ndb/dns +is started at boot time. +By default +.I dns +serves only requests written to +.BR /net/dns . +The options are: +.TP +.B -f +supplies the name of the data base file to use, +default +.BR /lib/ndb/local . +.TP +.B -x +specifies the mount point of the +network. +.TP +.B -s +also answer domain requests sent to UDP port 53. +.TP +.B -r +defer to other servers to resolve queries. +.PP +When the +.B -r +option is specified, the servers used come from the +.I dns +attribute in the database. For example, to specify a set of dns servers that +systems on the network +.IR mh-net : +.EX + +ipnet=mh-net ip=135.104.0.0 ipmask=255.255.0.0 + dns=ns1.cs.bell-labs.com + dns=ns2.cs.bell-labs.com +dom=ns1.cs.bell-labs.com ip=135.104.1.11 +dom=ns2.cs.bell-labs.com ip=135.104.1.12 + +.EE +.PP +The server for a domain is indicated by a database entry containing +both a +.I dom +and a +.I ns +attribute. +For example, the entry for the Internet root is: +.EX + +dom= + ns=A.ROOT-SERVERS.NET + ns=B.ROOT-SERVERS.NET + ns=C.ROOT-SERVERS.NET +dom=A.ROOT-SERVERS.NET ip=198.41.0.4 +dom=B.ROOT-SERVERS.NET ip=128.9.0.107 +dom=C.ROOT-SERVERS.NET ip=192.33.4.12 + +.EE +The last three lines provide a mapping for the +server names to their ip addresses. This is only +a hint and will be superseded from whatever is learned +from servers owning the domain. +.PP +The root of a domain subtree served by the local database is indicated +by an entry with an +.B soa +attribute. +For example, the Bell Labs CS research domain is: +.EX + +dom=cs.bell-labs.com soa= + refresh=3600 ttl=3600 + ns=plan9.bell-labs.com + ns=ns1.cs.bell-labs.com + ns=ns2.cs.bell-labs.com + mb=presotto@plan9.bell-labs.com + mx=mail.research.bell-labs.com pref=20 + mx=plan9.bell-labs.com pref=10 + +.EE +Here, the +.B mb +entry is the mail address of the person responsible for the +domain (default +.BR postmaster ). +The +.B mx +entries list mail exchangers for the domain name and +.B refresh +and +.B ttl +define the area refresh interval and the minimum TTL for +records in this domain. +.PP +Delegation of a further subtree to another set of name servers +is indicated by an +.B soa=delegated +attribute. +.EX + +dom=bignose.cs.research.bell-labs.com + soa=delegated + ns=anna.cs.research.bell-labs.com + ns=dj.cs.research.bell-labs.com + +.EE +Nameservers within the delegated domain (as in this example) +must have their IP addresses listed elsewhere in +.I ndb +files. +.PP +Wild-carded domain names can also be used. +For example, to specify a mail forwarder for all Bell Labs research systems: +.EX + +dom=*.research.bell-labs.com + mx=research.bell-labs.com + +.EE +`Cname' aliases may be established by adding a +.B cname +attribute giving the real domain name; +the name attached to the +.B dom +attribute is the alias. +`Cname' aliases are severely restricted; +the aliases may have no other attributes than +.B dom +and are daily further restricted in their use by new RFCs. +.EX + +cname=anna.cs.research.bell-labs.com dom=www.cs.research.bell-labs.com + +.EE +.I Ndb/dnsquery +can be used to query +.I ndb/dns +to see how it resolves requests. +.I Ndb/dnsquery +prompts for commands of the form +.IP +.I "domain-name request-type" +.LP +where +.I request-type +can be +.BR ip , +.BR mx , +.BR ns , +.BR cname , +.BR ptr .... +In the case of the inverse query type, +.BR ptr , +.I dnsquery +will reverse the ip address and tack on the +.B .in-addr.arpa +for you. +.PP +.I Ndb/dnsdebug +is like +.I ndb/dnsquery +but bypasses the local server. +It communicates via UDP with the domain name servers +in the same way that the local resolver would and displays +all packets received. +The query can be specified on the command line or +can be prompted for. +The queries look like those of +.I ndb/dnsquery +with one addition. +.I Ndb/dnsdebug +can be directed to query a particular name server by +the command +.BI @ name-server\f1. +From that point on, all queries go to that name server +rather than being resolved by +.IR dnsdebug . +The +.B @ +command returns query resolution to +.IR dnsdebug . +Finally, any command preceded by a +.BI @ name-server +sets the name server only for that command. +.PP +Normally +.I dnsdebug +uses the +.B /net +interface and the database file +.BR /lib/ndb/local. +The +.B -x +option directs +.I dnsdebug +to use the +.B /net.alt +interface and +.B /lib/ndb/external +file. +The +.B -r +option is the same as for +.IR ndb/dns . +.PP +.I Ndb/mkdb +is used in concert with +.IR awk (1) +scripts to convert +uucp systems files and IP host files +into database files. +It is very specific to the situation at Murray Hill. +.PP +When the database files change underfoot, +.I ndb/cs +and +.I ndb/dns +track them properly. Nonetheless, to keep the database searches efficient +it is necessary to run +.I ndb/mkhash +whenever the files are modified. +It may be profitable to control this by a frequent +.IR cron (8) +job. +.PP +.I Ndb/mkhosts +generates a BSD style +.BR hosts , +.BR hosts.txt , +and +.B hosts.equiv +files from an ndb data base file specified on the +command line (default +.BR /lib/ndb/local ). +For local reasons the files are called +.BR hosts.1127 , +.BR astro.txt , +and +.BR hosts.equiv . +.SH EXAMPLES +.EX +% ndb/query sys helix +sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot + ip=135.104.117.31 ether=080069020427 + proto=il +% ndb/dnsquery +> plan9.bell-labs.com ip +plan9.bell-labs.com ip 204.178.31.2 +> 204.178.31.2 ptr +2.31.178.204.in-addr.arpa ptr plan9.bell-labs.com +2.31.178.204.in-addr.arpa ptr ampl.com +> +.EE +.SH FILES +.TF /lib/ndb/local.*xxx +.TP +.B /lib/ndb/local +first database file searched +.TP +.B /lib/ndb/local.* +hash files for +.B /lib/ndb/local +.TP +.B /srv/cs +service file for +.I ndb/cs +.TP +.B /net/cs +where +.B /srv/cs +gets mounted +.TP +.B /srv/dns +service file for +.I ndb/dns +.TP +.B /net/dns +where +.B /srv/dns +gets mounted +.SH SOURCE +.B /sys/src/cmd/ndb +.SH SEE ALSO +.IR ndb (2) +.IR ndb (6) diff --git a/static/plan9-4e/man8/newuser.8 b/static/plan9-4e/man8/newuser.8 new file mode 100644 index 00000000..2d385245 --- /dev/null +++ b/static/plan9-4e/man8/newuser.8 @@ -0,0 +1,119 @@ +.TH NEWUSER 8 +.SH NAME +newuser \- adding a new user +.SH SYNOPSIS +.B /sys/lib/newuser +.SH DESCRIPTION +To establish a new user on Plan 9, +add the user's name to +.B /adm/users +by running the +.B newuser +command on the console of the file server +(see +.IR users (6) +and +.IR fs (8)). +Next, give the user a password using the +.B changeuser +command on the console of the authentication server +(see +.IR auth (8)). +At this point, the user can bootstrap a terminal using the new name and +password. +The terminal will only get as far as running +.BR rc , +however, as no +.B profile +exists for the user. +.PP +The +.IR rc (1) +script +.B /sys/lib/newuser +sets up a sensible environment for a new user of Plan 9. +Once the terminal is running +.BR rc , +type +.IP +.EX +/sys/lib/newuser +.EE +.PP +to build the necessary directories in +.B /usr/$user +and create a reasonable initial profile in +.BR /usr/$user/lib/profile +and +plumbing rules in +.BR /usr/$user/lib/plumbing +(see +.IR plumber (4)). +The script then runs the profile which, as its last step, brings up +.IR rio (1). +At this point the user's environment is established and running. +(There is no need to reboot.) +It may be prudent at this point to run +.IR passwd (1) +to change the password, depending on how the initial password was chosen. +.PP +The +.B profile +built by +.B /sys/lib/newuser +looks like this: +.IP +.EX +bind -a $home/bin/rc /bin +bind -a $home/bin/$cputype /bin +bind -c tmp /tmp +font = /lib/font/bit/pelm/euro.9.font +switch($service){ +case terminal + plumber + upas/fs + echo -n accelerated > '#m/mousectl' + echo -n 'res 3' > '#m/mousectl' + prompt=('term% ' ' ') + fn term%{ $* } + exec rio +case cpu + if (test -e /mnt/term/mnt/wsys) { + # rio already running + bind -a /mnt/term/mnt/wsys /dev + echo -n $sysname > /dev/label + } + bind /mnt/term/dev/cons /dev/cons + bind /mnt/term/dev/consctl /dev/consctl + bind -a /mnt/term/dev /dev + prompt=('cpu% ' ' ') + fn cpu%{ $* } + upas/fs + news + if (! test -e /mnt/term/mnt/wsys) { + # cpu call from drawterm + font=/lib/font/bit/pelm/latin1.8.font + exec rio + } +case con + prompt=('cpu% ' ' ') + news +} +.EE +.PP +Sites may make changes to +.B /sys/lib/newuser +that reflect the properties of the local environment. +.PP +Use the +.B -c +option of +.IR mail (1) +to create a mailbox. +.SH "SEE ALSO" +.IR passwd (1), +.IR rio (1), +.IR namespace (4), +.IR users (6), +.IR auth (8), +.IR fs (8) diff --git a/static/plan9-4e/man8/nfsserver.8 b/static/plan9-4e/man8/nfsserver.8 new file mode 100644 index 00000000..95394314 --- /dev/null +++ b/static/plan9-4e/man8/nfsserver.8 @@ -0,0 +1,164 @@ +.TH NFSSERVER 8 +.SH NAME +nfsserver, portmapper, pcnfsd, 9auth \- NFS service +.SH SYNOPSIS +.B aux/nfsserver +[ +.I rpc-options... +] +[ +.I nfs-options... +] +.br +.B aux/pcnfsd +[ +.I rpc-options... +] +.br +.B aux/portmapper +[ +.I rpc-options... +] +.SH DESCRIPTION +These programs collectively provide NFS access to Plan 9 file servers. +.IR Nfsserver , +.IR pcnfsd , +and +.I portmapper +run on a Plan 9 CPU server, and should be started in that order. +All users on client machines have the +access privileges of the Plan 9 user +.LR none . +.PP +The +.I rpc-options +are all intended for debugging: +.nr zz \w'\f5-a\f2 addr'+2n/1n +.TP \n(zz +.B -r +Reject: answer all RPC requests by returning the +.B AUTH_TOOWEAK +error. +.TP +.B -v +Verbose: show all RPC calls and internal program state, including 9P messages. +(In any case, the program creates a file +.BI /srv/ name .chat +where +.I name +is that of the program; echoing +.L 1 +or +.L 0 +into this file sets or clears the +.B -v +flag dynamically.) +.TP +.B -D +Debug: show all RPC messages (at a lower level than +.BR -v ). +This flag may be repeated to get more detail. +.TP +.B -C +Turn off caching: do not answer RPC requests using the +RPC reply cache. +.PP +The +.I nfs-options +are: +.TP \n(zz +.BI -a " addr" +Set up NFS service for the 9P server at network address +.IR addr . +.TP +.BI -f " file" +Set up NFS service for the 9P server at +.I file +(typically an entry in +.BR /srv ). +.TP +.B -n +Do not allow per-user authentication. +.TP +.BI -c " file" +.I File +contains the uid/gid map configuration. It is read at startup +and subsequently every hour (or if +.L c +is echoed into +.BR /srv/nfsserver.chat ). +Blank lines or lines beginning with +.L # +are ignored; lines beginning with +.L ! +are executed as commands; otherwise lines contain four fields +separated by white space: a regular expression (in the notation of +.IR regexp (6)) +for a class of servers, a regular expression for +a class of clients, a file of user id's (in the format of a Unix +password file), and a file of group id's (same format). +.PP +NFS clients must be in the Plan 9 +.B /lib/ndb +database. +The machine name is deduced from the IP address via +.BR ndb/query . +The machine name specified in the NFS Unix credentials +is completely ignored. +.PP +.I Pcnfsd +is a toy program that authorizes PC-NFS clients. All clients +are mapped to uid=1, gid=1 +.RB ( daemon +on most systems) regardless of name or password. +.SH EXAMPLES +A simple +.B /lib/ndb/nfs +might contain: +.PP +.EX +!9fs tcp!ivy +\&.+ [^.]+\e.cvrd\e.hall\e.edu /n/ivy/etc/passwd /n/ivy/etc/group +.EE +.PP +A typical entry in +.B /rc/bin/cpurc +might be: +.PP +.EX +aux/nfsserver -a il!bootes -a il!fornax -c /lib/ndb/nfs +aux/pcnfsd +aux/portmapper +.EE +.PP +Assuming the cpu server's name is +.BR eduardo , +the mount commands on the client would be: +.PP +.EX +/etc/mount -o soft,intr eduardo:bootes /n/bootes +/etc/mount -o soft,intr eduardo:fornax /n/fornax +.EE +.PP +Note that a single instance of +.I nfsserver +may provide access to several 9P servers. +.SH FILES +.TF /lib/ndb/nfs +.TP +.B /lib/ndb/nfs +List of uid/gid maps. +.TP +.B /sys/log/nfs +Log file. +.SH SOURCE +.B /sys/src/cmd/9nfs +.SH BUGS +It would be nice to provide authentication for users, but Unix systems +provide too low a level of security to be trusted in a Plan 9 world. +.SH SEE ALSO +RFC1057, +.I "RPC: Remote Procedure Call Protocol Specification, Version 2." +.br +RFC1094, +.I "NFS: Network File System Protocol Specification." diff --git a/static/plan9-4e/man8/pcmcia.8 b/static/plan9-4e/man8/pcmcia.8 new file mode 100644 index 00000000..027a7f99 --- /dev/null +++ b/static/plan9-4e/man8/pcmcia.8 @@ -0,0 +1,23 @@ +.TH PCMCIA 8 +.SH NAME +pcmcia \- identify a PCMCIA card +.SH SYNOPSIS +.B aux/pcmcia +[ +.I file +] +.SH DESCRIPTION +.B Aux/pcmcia +translates the PCMCIA information structure from +.I file +(default +.BR #y/pcm0attr ) +into a readable description and writes it to +standard output. +.SH FILES +.TF #y/pcm0attr +.TP +.B #y/pcm0attr +The attribute memory of the card in the PCMCIA slot. +.SH SOURCE +.B /sys/src/cmd/aux/pcmcia.c diff --git a/static/plan9-4e/man8/ping.8 b/static/plan9-4e/man8/ping.8 new file mode 100644 index 00000000..a78ba99c --- /dev/null +++ b/static/plan9-4e/man8/ping.8 @@ -0,0 +1,146 @@ +.TH PING 8 +.SH NAME +ping, gping, traceroute, hogports \- probe the Internet +.SH SYNOPSIS +.B ping +[ +.B -d +] [ +.B -i +.I interval +] [ +.B -s +.I size +] [ +.B -n +.I count +] +.I destination +.PP +.B gping +[ +.B -r +] [ +.B -l +] [ +.B -i +.I interval +] +.I destination +[ +.I destination +\&... ] +.PP +.B traceroute +[ +.B -dn +][ +.B -t +.I tries +] +.I dest +.PP +.B hogports +.B [\fImtpt\fP/]\fIproto\fP!\fIaddress\fP!\fIstartport\fP[-\fIendport\fP] +.SH DESCRIPTION +.I Ping +sends ICMP echo requests to a system and returns the time +for a response. It can be used to determine the network delay +and whether or not the destination is up. +.PP +The options are: +.TP +.B n +requests that a total of +.I count +messages be sent, default 32. +.TP +.B i +sets the time between messages +to be +.I interval +milliseconds, default 1000 ms. +.TP +.B s +sets the length of the message to be +.I size +bytes, ICMP header included. +The size cannot be smaller than 32 or +larger than 8192. The default is +64. +.TP +.B d +causes message numbers to be printed +so that one can see the order with which +messages are received and which are lost. +.PP +.I Gping +is a +.I ping +with a graphical display. It +presents separate graphs for each destination +specified. +.PP +The options are: +.TP +.B r +display round trip time in seconds. +This is the default. +.TP +.B l +display percentage of lost messages. +A message is considered lost if not +replied to in 10 seconds. The percentage +is an exponentially weighted average. +.TP +.B i +sets the time between messages +to be +.I interval +milliseconds, default 5000 ms. +.PP +Graphs can be dropped and added using +the button 3 menu. Clicking button 1 +on a datapoint displays the value of the +datapoint and the time it was recorded. +.PP +.I Traceroute +displays the IP addresses and average round trip times to all +routers between the machine it is run on and +.IR dest . +It does this by sending packets to +.I dest +with increasing times to live (TTL) in their headers. +Each router that a packet expires at replies with an ICMP +warning message. +The options are: +.TP +.B d +print debugging to standard error +.TP +.B n +just print out IP numbers, don't try to +look up the names of the routers. +.TP +.B t +send +.I tries +packets at each TTL value (default 1). +.PP +.I Hogports +announces on a range of ports to keep them from other processes. +For example, to keep anyone from making a vncserver visible on +the network mounted at +.BR /net.alt : +.EX + + ip/hogports /net.alt/tcp!*!5900-5950 +.EE +.SH SOURCE +.B /sys/src/cmd/ip/ping.c +.br +.B /sys/src/cmd/ip/gping.c +.br +.B /sys/src/cmd/ip/traceroute.c +.br +.B /sys/src/cmd/ip/hogports.c diff --git a/static/plan9-4e/man8/plan9.ini.8 b/static/plan9-4e/man8/plan9.ini.8 new file mode 100644 index 00000000..6cfb2b55 --- /dev/null +++ b/static/plan9-4e/man8/plan9.ini.8 @@ -0,0 +1,815 @@ +.TH PLAN9.INI 8 +.SH NAME +plan9.ini \- configuration file for PCs +.SH SYNOPSIS +.I none +.SH DESCRIPTION +When booting Plan 9 on a PC, the DOS program +.IR 9load (8) +first reads a DOS file +containing configuration information from the boot disk. +This file, +.BR plan9.ini , +looks like a shell script containing lines of the form +.PP +.EX + name=\f2value\fP +.EE +.LP +each of which defines a kernel or device parameter. +.PP +For devices, the generic format of +.I value +is +.PP +.EX + type=TYPE [port=N] [irq=N] [mem=N] [size=N] [dma=N] [ea=N] +.EE +.LP +specifying the controller type, +the base I/O port of the interface, its interrupt +level, the physical starting address of any mapped memory, +the length in bytes of that memory, the DMA channel, +and for Ethernets an override of the physical network address. +Not all elements are relevant to all devices; the relevant values +and their defaults are defined below in the description of each device. +.PP +The file is used by +.B 9load +and the kernel to configure the hardware available. +The information it contains is also passed to the boot +process, and subsequently other programs, +as environment variables +(see +.IR boot (8)). +However, values whose names begin with an asterisk +.B * +are used by the kernel and are not converted into environment variables. +.PP +The following sections describe how variables are used. +.SS \fLetherX=value\fP +This defines an Ethernet interface. +.IR X , +a unique monotonically increasing number beginning at 0, +identifies an Ethernet card to be probed at system boot. +Probing stops when a card is found or there is no line for +.BR etherX+1 . +After probing as directed by the +.BI ether X +lines, any remaining ethernet cards that can be automatically +detected are added. +Almost all cards can be automatically detected. +This automatic probing is only done by the kernel, not by +.IR 9load (8). +Thus, if you want to load a kernel over the ethernet, you need +to specify an +.B ether0 +line so that +.I 9load +can find the ethernet card, even if the kernel would +have automatically detected it. +.PP +Some cards are software configurable and do not require all options. +Unspecified options default to the factory defaults. +.PP +Known types are +.TP +.B ne2000 +Not software configurable. 16-bit card. +Defaults are +.EX + port=0x300 irq=2 mem=0x04000 size=0x4000 +.EE +The option (no value) +.B nodummyrr +is needed on some (near) clones to turn off a dummy remote read in the driver. +.TP +.B amd79c970 +The AMD PCnet PCI Ethernet Adapter (AM79C970). +(This is the ethernet adapter used by VMware.) +Completely configurable, no options need be given. +.TP +.B wd8003 +Includes WD8013 and SMC Elite and Elite Ultra cards. There are varying degrees +of software configurability. Cards may be in either 8-bit or 16-bit slots. +Defaults are +.EX + port=0x280 irq=3 mem=0xD0000 size=0x2000 +.EE +BUG: On many machines only the 16 bit card works. +.TP +.B elnk3 +The 3COM Etherlink III series of cards including the 5x9, 59x, and 905 and 905B. +Completely configurable, no options need be given. +The media may be specified by setting +.B media= +to the value +.BR 10BaseT , +.BR 10Base2 , +.BR 100BaseTX , +.BR 100BaseFX , +.BR aui , +and +.BR mii . +If you need to force full duplex, because for example the Ethernet switch does not negotiate correctly, +just name the word (no value) +.B fullduplex +or +.BR 100BASE-TXFD . +Similarly, to force 100Mbit operation, specify +.BR force100 . +Port 0x110 is used for the little ISA configuration dance. +.TP +.B 3c589 +The 3COM 3C589 series PCMCIA cards, including the +3C562 and the 589E. +There is no support for the modem on the 3C562. +Completely configurable, no options need be given. +Defaults are +.EX + port=0x240 irq=10 +.EE +The media may be specified as +.B media=10BaseT +or +.BR media=10Base2 . +.TP +.B ec2t +The Linksys Combo PCMCIA EthernetCard (EC2T), +EtherFast 10/100 PCMCIA cards (PCMPC100) and integrated controllers (PCM100), +the Netgear FA410TX 10/100 PCMCIA card +and the Accton EtherPair-PCMCIA (EN2216). +Completely configurable, no options need be given. +Defaults are +.EX + port=0x300 irq=9 +.EE +These cards are NE2000 clones. +Other NE2000 compatible PCMCIA cards may be tried +with the option +.EX + id=string +.EE +where +.B string +is a unique identifier string contained in the attribute +memory of the card (see +.IR pcmcia (8)); +unlike most options in +.BR plan9.ini , +this string is case-sensitive. +The option +.B dummyrr=[01] +can be used to turn off (0) or on (1) a dummy remote read in the driver +in such cases, +depending on how NE2000 compatible they are. +.TP +.B i82557 +Cards using the Intel 8255[789] Fast Ethernet PCI Bus LAN Controller such as the +Intel EtherExpress PRO/100B. +Completely configurable, no options need be given. +If you need to force the media, specify +one of the options (no value) +.BR 10BASE-T , +.BR 10BASE-2 , +.BR 10BASE-5 , +.BR 100BASE-TX , +.BR 10BASE-TFD , +.BR 100BASE-TXFD , +.BR 100BASE-T4 , +.BR 100BASE-FX , +or +.BR 100BASE-FXFD . +.TP +.B 2114x +Cards using the Digital Equipment (now Intel) 2114x PCI Fast Ethernet Adapter Controller, +for example the Netgear FA310. +Completely configurable, no options need be given. +Media can be specified the same was as for the +.BR i82557 . +Some cards using the +.B PNIC +and +.B PNIC2 +near-clone chips may also work. +.\" .TP +.\" .B ga620 +.\" Netgear GA620 and GA620T Gigabit Ethernet cards, +.\" and other cards using the Alteon Acenic chip such as the +.\" Alteon Acenic fiber and copper cards, +.\" the DEC DEGPA-SA and the SGI Acenic. +.\" Completely configurable. +.TP +.B wavelan +Lucent Wavelan (Orinoco) IEEE 802.11b +and compatible PCMCIA cards. +Compatible cards include the Dell TrueMobile 1150 +and the Linksys Instant Wireless Network PC Card. +Port and IRQ defaults are 0x180 and 3 respectively. + +These cards take a number of unique options to aid in +identifying the card correctly on the 802.11b network. +The network may be +.I "ad hoc" +or +.I managed +(i.e. use an access point): +.EX + mode=[adhoc, managed] +.EE +and defaults to +.IR managed . +The 802.11b network to attach to +.RI ( managed +mode) +or identify as +.RI ( "ad hoc" +mode), +is specified by +.EX + essid=string +.EE +and defaults to a null string. +The card station name is given by +.EX + station=string +.EE +and defaults to +.IR "Plan 9 STA" . +The channel to use is given by +.EX + channel=number +.EE +where +.I number +lies in the range 1 to 16 inclusive; +the channel is normally negotiated automatically. + +If the card is capable of encryption, +the following options may be used: +.EX + crypt=[off, on] +.EE +and defaults to +.IR on . +.EX + key\fIN\fP=string +.EE +sets the encryption key +.I n +(where +.I n +is in the range 1 to 4 inclusive) to +.IR string ; +this will also set the transmit key to +.I n +(see below). +.EX + txkey=number +.EE +sets the transmit key to use to be +.I number +in the range 1 to 4 inclusive. +If it is desired to exclude or include unencrypted packets +.EX + clear=[off, on] +.EE +configures reception and defaults to inclusion. + +The defaults are intended to match the common case of +a managed network with encryption and a typical entry would +only require, for example +.EX + essid=left-armpit key2=fishcalledraawaru +.EE +if the port and IRQ defaults are used. +These options may be set after boot by writing to the device's +.I ctl +file using a space as the separator between option and value, e.g. +.EX + echo 'key2 fishcalledraawaru' > /net/ether0/0/ctl +.EE +.TP +.B wavelanpci +PCI ethernet adapters that use the same Wavelan +programming interface. +Currently the only tested cards are those based on the +Intersil Prism 2.5 chipset. +.TP +.B 83815 +National Semiconductor DP83815-based adapters, notably +the Netgear FA311, Netgear FA312, and various SiS built-in +controllers such as the SiS900. +On the SiS controllers, the ethernet address is not detected properly; +specify it with an +.B ea= +attribute. +.\" .TP +.\" .B 83820 +.\" National Semiconductor DP83820-based gigabit ethernet adapters, notably +.\" the D-Link DGE-500T. +.TP +.B rtl8139 +The Realtek 8139. +.TP +.B 82543gc +The Intel RS-82543GC gigabit ethernet controller, +as found on the Intel PRO/1000[FT] server adapter. +The older non-[FT] cards based on the 82542 (LSI L2A1157) +chip are not supported, although support would probably be +easy to add. +.TP +.B smc91cxx +SMC 91cXX chip-based PCMCIA adapters, notably the SMC EtherEZ card. +.TP +.B sink +A +.B /dev/null +for ethernet packets \(em the interface discards sent +packets and never receives any. +This is used to provide a test bed for +some experimental ethernet bridging software. +.SS \fLusbX=type=uhci port=xxx irq=xxx\fP +This specifies the settings for a USB UHCI controller. +Like the ethernet controllers, USB controllers are autodetected +after scanning for the ones listed in +.IR plan9.ini . +Thus, most systems will not need a +.B usbX +line. +.SS \fLscsiX=value\fP +This defines a SCSI interface which cannot be automatically detected +by the kernel. +.PP +Known types are +.TP +.B aha1542 +The Adaptec 154x series of controllers (and clones). +Almost completely configurable, only the +.EX + port=0x300 +.EE +option need be given. +.PP +NCR/Symbios/LSI Logic 53c8xx-based adapters +and Mylex MultiMaster (Buslogic BT-*) adapters are +automatically detected and need no entries. +.PP +By default, the NCR 53c8xx driver searches for up to 32 controllers. +This can be changed by setting the variable +.BR *maxsd53c8xx . +.PP +By default the Mylex driver resets SCSI cards by using +both the hard reset and SCSI bus reset flags in the driver interface. +If a variable +.BR *noscsireset +is defined, the SCSI bus reset flag is omitted. +.SS Uarts +Plan 9 automatically configures COM1 and COM2, if found, +as +.B eia0 +(port 0x3F8, IRQ4) +and +.B eia1 +(port 0x2F8, IRQ3) +respectively. +These devices can be disabled by adding a line: +.EX + eia\fIX\fP=disabled +.EE +This is typically done in order to reuse the IRQ for +another device. +.PP +Plan 9 used to support various serial concentrators, +including the TTC 8 serial line card and various models +in the Star Gate Avanstar series of intelligent serial boards. +These are no longer supported; the much simpler +Perle PCI-Fast4, PCI-Fast8, and PCI-Fast16 controllers +have taken their places. +These latter cards are automatically detected +and need no configuration lines. +.PP +The line +.B serial=type=com +can be used to specify settings for a PCMCIA modem. +.SS \fLmouseport=value\fP +This specifies where the mouse is attached. +.I Value +can be +.TP +.B ps2 +the PS2 mouse/keyboard port. The BIOS setup procedure +should be used to configure the machine appropriately. +.TP +.B ps2intellimouse +an Intellimouse on the PS2 port. +.TP +.B 0 +for COM1 (currently not supported) +.TP +.B 1 +for COM2 (currently not supported) +.SS \fLmodemport=value\fP +Picks the UART line to call out on. +This is used when connecting to a file server over +an async line. +.I Value +is the number of the port. +.SS \fLpcmciaX=type=XXX irq=value\fP +If the default IRQ for the +PCMCIA +is correct, this entry can be omitted. The value of +.B type +is ignored. +.SS \fLconsole=value params\fP +This is used to specify the console device. +The default +value is +.BR cga ; +a number +.B 0 +or +.B 1 +specifies +.I COM1 +or +.I COM2 +respectively. +A serial console is initially configured with the +.IR uart (3) +configuration string +.B b9600 +.B l8 +.B pn +.BR s1 , +specifying 9600 baud, +8 bit bytes, no parity, and one stop bit. +If +.I params +is given, it will be used to further +configure the uart. +Notice that there is no +.B = +sign in the +.I params +syntax. +For example, +.EX + console=0 b19200 po +.EE +would use COM1 at 19,200 baud +with odd parity. +.SS \fLbootfile=value\fP +This is used to direct the actions of +.IR 9load (8) +by naming the device and file from which to load the kernel. +.SS \fLrootdir=dir\fP +.SS \fLrootspec=spec\fP +These are used by +.IR 9load (8) +to identify the directory +.I dir +to make the root directory for the kernel, and the +file system specifier +.I spec +(see +.B mount +in +.IR bind (2)) +on which it can be found. +These are usually used to test variant file systems for distributions, etc. +.SS \fLbootargs=value\fP +The value of this variable is passed to +.IR boot (8) +by the kernel as the name of the root file system. +For example, if the system is to run from a local +.IR kfs (4) +partition, the definition might read +.BR bootargs=local!#S/sdC0/fs . +.SS \fLcfs=value\fP +This gives the name of the file holding the disk partition +for the cache file system, +.IR cfs (4). +Extending the +.B bootargs +example, one would write +.BR cfs=#S/sdC0/cache . +.SS \fLbootdisk=value\fP +This deprecated variable was used to specify the disk used by +the cache file system and other disk-resident services. +It is superseded by +.B bootargs +and +.BR cfs . +.SS \fLpartition=value\fP +This defines the partition table +.IR 9load (8) +will examine to find disk partitioning information. +By default, a partition table in a Plan 9 partition +is consulted; if no such table is found, an old-Plan 9 +partition table on the next-to-last or last sector +of the disk is consulted. +A value of +.B new +consults only the first table, +.B old +only the second. +.SS \fL*maxmem=value\fP +This defines the maximum physical address that the system will scan when sizing memory. +By default the operating system will scan up to 768 megabytes, but setting +.B *maxmem +will limit the scan. +If the system has more than 768 megabytes, you must set +.B *maxmem +for the kernel to find it. +.B *maxmem +must be less than 1.75 gigabytes. +.SS \fL*kernelpercent=value\fP +This defines what percentage of available memory is reserved for the kernel allocation pool. +The remainder is left for user processes. The default +.I value +is +.B 30 +on CPU servers, +.B 60 +on terminals with less than 16MB of memory, +and +.B 40 +on terminals with memories of 16MB or more. +Terminals use more kernel memory because +.IR draw (3) +maintains its graphic images in kernel memory. +This deprecated option is rarely necessary in newer kernels. +.SS \fL*nomce=value\fP +If machine check exceptions are supported by the processor, +then they are enabled by default. +Setting this variable to +.B 1 +causes them to be disabled even when available. +.SS \fL*nomp=value\fP +A multiprocessor machine will enable all processors by default. +Setting +.B *nomp +restricts the kernel to starting only one processor and using the +traditional interrupt controller. +.SS \fL*ncpu=value\fP +Setting +.B *ncpu +restricts the kernel to starting at most +.I value +processors. +.SS \fL*pcimaxbno=value\fP +This puts a limit on the maximum bus number probed +on a PCI bus (default 255). +For example, a +.I value +of 1 should suffice on a 'standard' motherboard with an AGP slot. +This, and +.B *pcimaxdno +below are rarely used and only on troublesome or suspect hardware. +.SS \fL*pcimaxdno=value\fP +This puts a limit on the maximum device number probed +on a PCI bus (default 31). +.\" .SS \fL*nobios=\fP +.\" what does this do? something with pci +.SS \fLioexclude=value\fP +Specifies a list of ranges I/O ports to exclude from use by drivers. +Ranges are inclusive on both ends and separated by commas. +For example: +.EX + ioexclude=0x330-0x337,0x430-0x43F +.EE +.SS \fLapm0=\fP +This enables the ``advanced power management'' interface +as described in +.IR apm (3) +and +.IR apm (8). +The main feature of the interface is the ability to watch +battery life (see +.IR stats (8)). +It is not on by default because it causes problems on some laptops. +.SS \fLmonitor=value\fP +.SS \fLvgasize=value\fP +These are used not by the kernel but by +.I termrc +(see +.IR cpurc (8)) +when starting +.IR vga (8). +.SS \fL*dpms=value\fP +This is used to specify the screen blanking behavior of the MGA4xx +video driver. +Values are +.BR standby , +.BR suspend , +and +.BR off . +The first two specify differing levels of power saving; +the third turns the monitor off completely. +.SS \fLnvr=value\fP +This is used by a file server kernel to locate a file holding information +to configure the file system. +The file cannot live on a SCSI disk. +The default is +.B fd!0!plan9.nvr +(sic), +unless +.B bootfile +is set, in which case it is +.B plan9.nvr +on the same disk as +.BR bootfile . +The syntax is either +.BI fd! unit ! name +or +.BI hd! unit ! name +where +.I unit +is the numeric unit id. +This variant syntax is a vestige of the file server kernel's origins. +.SS \fLaudioX=value\fP +This defines a sound interface. +.PP +Known types are +.TP +.B sb16 +Sound Blaster 16. +.TP +.B ess1688 +A Sound Blaster clone. +.PP +The DMA channel may be any of 5, 6, or 7. +The defaults are +.EX + port=0x220 irq=7 dma=5 +.EE +.SS \fLfs=a.b.c.d\fP +.SS \fLauth=a.b.c.d\fP +These specify the IP address of the file and authentication server +to use when mounting a network-provided root file system. +They are used only if the addresses cannot be determined via DHCP. +.SH Multiple Configurations +.PP +A +.B plan9.ini +file may contain multiple configurations, +each within a block beginning with a line +.EX + [tag] +.EE +A special block with the tag +.B menu +gives a list of blocks from which the user may +interactively select the contents of +.BR plan9.ini . +There may also be multiple blocks with the tag +.B common +which will be included in all selections; +if any lines appear in +.B plan9.ini +before the first block, +they are treated as a +.B common +block. +.LP +Within the +.B menu +block the following configuration lines are allowed: +.SS \fLmenuitem=tag[, description] +The block identified by +.B tag +will appear in the presented menu. +The menu entry will consist of the +.B tag +unless the optional +.B description +is given. +.SS \fLmenudefault=tag[, timeout] +Identifies a default block to be given in the +menu selection prompt. +If the optional +.B timeout +is given (in seconds), +the default block will be selected if there is no user +input within the timeout period. +.SS \fLmenuconsole=value[, baud] +Selects a serial console upon which to present the menu +as no +.B console +or +.B baud +configuration information will have been processed yet +(the +.B plan9.ini +contents are still to be decided...). +.LP +In response to the menu being printed, +the user is prompted to select a menu item from the list. +If the numeric response is followed by a +.BR p , +the selected configuration is printed and the menu presented +again. +.LP +The line +.EX + menuitem=tag +.EE +is prefixed to the selected configuration as an aid to +user-level initialization scripts. +.SH EXAMPLES +.PP +A representative +.BR plan9.ini : +.IP +.EX +% cat /n/c:/plan9.ini +ether0=type=3C509 +mouseport=ps2 +modemport=1 +serial0=type=generic port=0x3E8 irq=5 +monitor=445x +vgasize=1600x1200x8 +% +.EE +.PP +Minimum CONFIG.SYS and AUTOEXEC.BAT files to use +COM2 as a console: +.IP +.EX +% cat /n/c:/config.sys +SHELL=COMMAND.COM COM2 /P +% cat /n/c:/autoexec.bat +@ECHO OFF +PROMPT $p$g +PATH C:\eDOS;C:\eBIN +mode com2:96,n,8,1,p +SET TEMP=C:\eTMP +% +.EE +.PP +Simple +.B plan9.ini +with multiple configurations: +.IP +.EX +[menu] +menuitem=vga, Plan 9 with VGA +menuitem=novga, Plan 9 no automatic VGA +menudefault=vga + +[vga] +monitor=multisync135 +vgasize=1024x768x8 + +[novga] + +[common] +ether0=type=i82557 +audio0=type=sb16 port=0x220 irq=5 dma=1 +.EE +.PP +With this, the following menu will be presented on boot: +.IP +.EX +Plan 9 Startup Menu: +==================== + 1. Plan 9 with VGA + 2. Plan 9 no automatic VGA +Selection[default==1]: +.EE +.PP +Selecting item 1 generates the following +.B plan9.ini +to be used by the remainder of the bootstrap process: +.IP +.EX +menuitem=vga +monitor=multisync135 +vgasize=1024x768x8 +ether0=type=i82557 +audio0=type=sb16 port=0x220 irq=5 dma=1 +.EE +.PP +and selecting item 2: +.IP +.EX +menuitem=novga +ether0=type=i82557 +audio0=type=sb16 port=0x220 irq=5 dma=1 +.EE +.SH "SEE ALSO" +.IR 9load (8), +.IR booting (8), +.IR boot (8) +.SH BUGS +Being able to set the console device to other than a +display is marginally useful on file servers; MS-DOS +and the programs which run under it are so tightly bound +to the display that it is necessary to have a display if any +setup or reconfiguration programs need to be run. +Also, the delay before any messages appear at boot time +is disconcerting, as any error messages from the BIOS +are lost. +.PP +This idea is at best an interesting experiment that needs another iteration. diff --git a/static/plan9-4e/man8/ppp.8 b/static/plan9-4e/man8/ppp.8 new file mode 100644 index 00000000..28e250bf --- /dev/null +++ b/static/plan9-4e/man8/ppp.8 @@ -0,0 +1,275 @@ +.TH PPP 8 +.SH NAME +ppp, pppoe, pptp, pptpd \- point to point protocol +.SH SYNOPSIS +.B ip/ppp +[ +.B -CPScdfu +][ +.B -b +.I baud +][ +.B -m +.I mtu +][ +.B -p +.I dev +][ +.B -s +.IR username : secret +][ +.B -x +.I netmntpt +][ +.B -t +.I modemcmd +] +[ +.I local +[ +.I remote +] ] +.PP +.B ip/pppoe +[ +.B -m +.I mtu +] +[ +.B -P +] +[ +.B -d +] +[ +.B -s +.IR username : secret +] +[ +.B -x +.I pppnetmntpt +] +.I etherdir +.PP +.B ip/pptp +[ +.B -P +] +[ +.B -d +] +[ +.B -s +.IR username : secret +] +[ +.B -w +.I window +] +[ +.B -x +.I pppnetmntpt +] +.I server +.PP +.B ip/pptpd +[ +.B -d +] [ +.B -p +.I pppnetmtpt +] [ +.B -w +.I window +] [ +.B -D +.I fraction +] +.I tcp-dir +.SH DESCRIPTION +The Point to Point Protocol is used to encapsulate Internet Protocol packets +for transfer over serial lines or other protocol connections. +.I Ppp +can run either as a client or, with the +.I \-S +option, as a server. The only differences between a client and a server is +that the server will not believe any local address the client tries to +supply it and that the server always initiates the authentication of the +client. +.PP +With no option, +.I ppp +communicates with the remote system via standard input and output. +This is useful if a program wants to use +.I ppp +in a communications stream. However, the normal mode is to +specify a communications device, usually a serial line with a modem. +.PP +PPP supports the following options: +.TP +.B p +communicate over +.I dev +instead of standard I/O +.TP +.B u +before starting the PPP porotcol with the remote end, shuttle +bytes between the device and standard I/O until an EOF on standard +input. This allows a user to start +.I ppp +and then type commands at a modem before +.I ppp +takes over +.TP +.B b +set the baud rate on the communications device +.TP +.B f +make PPP add HDLC framing. This is necessary when using +PPP over a serial line or a TCP connection +.TP +.B m +set the maximum transfer unit (default 1450) +.TP +.B P +use this as the primary IP interface; set the default +route through this interface and write it's configuration +to +.B /net/ndb +.TP +.B s +supplies the user name and secret +to be used in authenticating to the remote side. +The +.I username +is optional, the default being the local user id. +We support both PPP CHAP and MS CHAP +.TP +.B S +run as a server +.TP +.B x +use the IP stack mounted at +.I netmntpt +.TP +.B t +before starting the PPP protocol, write +.I modemcmd +to the device +.TP +.B c +disallow packet compression +.TP +.B C +disallow ip header compression +.PD +.PP +If both the +.I local +and +.I remote +addresses are specified, don't ask the other end for either +or believe it if it supplies one. If either is missing, get +it from the remote end. +.PP +.I Pppoe +is a PPP over ethernet (PPPoE) client. +It invokes +.I ppp +to start a PPP conversation which is +tunneled in PPPoE packets on +the ethernet device mounted at +.I etherdir +(default +.BR /net/ether0 ). +The options are: +.TP +.B A +insist on an access concentrator named +.I acname +during PPPoE discovery +.TP +.B S +insist on a service named +.I srvname +during PPPoE discovery +.TP +.B d +write debugging output to standard error, +and pass +.B -d +to +.I ppp +.TP +.B m +pass +.B -m +.I mtu +to +.IR ppp , +default 1492 +.TP +.B s +pass +.B -s +.IR username : secret +to +.I ppp +.TP +.B x +pass +.B -x +.I pppnetmntpt +to +.I ppp +.PD +.PP +.I Pptp +is a client for a PPTP encrypted tunnel. +.I Server +is the name of the server to dial. +.I Pptp +takes the same options as +.IR pppoe , +except for the lack of a +.B -m +option and the addition of a +.B -w +option. +The +.B -w +option specifies the local send window size +(default 16) in packets. +.PP +.I Pptpd +is the server side of a PPTP encrypted tunnel. +.I Tcpdir +is the directory of a TCP connection to the client. +The TCP connection is used to control the tunnel while +packets are sent back and forth using PPP inside of +GRE packets. +The options are: +.TP +.B d +write debugging output to standard error. +.TP +.B p +use the IP stack mounted at +.I pppnetmtpt +to terminate the PPP connection. +.TP +.B w +set the receive window to +.IR window . +.TP +.B D +drop +.I fraction +of the received packets. This is used for testing. +.PD +.SH SOURCE +.B /sys/src/cmd/ip/ppp +.br +.B /sys/src/cmd/ip/pptpd.c +.br +.B /sys/src/cmd/ip/pppoe.c diff --git a/static/plan9-4e/man8/prep.8 b/static/plan9-4e/man8/prep.8 new file mode 100644 index 00000000..e2b945bf --- /dev/null +++ b/static/plan9-4e/man8/prep.8 @@ -0,0 +1,657 @@ +.TH PREP 8 +.SH NAME +prep, fdisk, format, mbr \- prepare hard and floppy diskettes, flashes +.SH SYNOPSIS +.B disk/prep +[ +.B -abcfnprw +] +[ +.B -s +.I sectorsize +] +.I plan9partition +.PP +.B disk/fdisk +[ +.B -abfprw +] +[ +.B -s +.I sectorsize +] +.I disk +.PP +.B disk/format +[ +.B -dfvx +] +[ +.B -b +.I bootblock +] +[ +.B -c +.I csize +] +[ +.B -l +.I label +] +[ +.B -r +.I nresrv +] +[ +.B -t +.I type +] +.I disk +[ +.IR file ... +] +.PP +.B disk/mbr +[ +.B -m +.I mbrfile +] +.SH DESCRIPTION +A partition table is stored on a hard disk to specify the division of +the physical disk into a set of logical units. +On PCs, the partition table is stored at the end of the master boot record +of the disk. +Partitions of type +.B 0x39 +are Plan 9 partitions. +The names of PC partitions are chosen by convention from the type: +.BR dos , +.BR plan9 , +etc. +Second and subsequent partitions of the same type on a given disk are given +unique names by appending a number (or a period and a number if the name +already ends in a number). +.PP +Plan 9 partitions (and Plan 9 disks on non-PCs) are +themselves divided, using a textual partition table, called the Plan 9 partition table, in the second +sector of the partition (the first is left for architecture-specific boot data, such as PC boot blocks). +The table is a sequence of lines of the format +.BI part " name start end" \fR, +where +.I start +and +.I end +name the starting and ending sector. +Sector 0 is the first sector of the Plan 9 partition or disk, +regardless of its position in a larger disk. +Partition extents do not contain the ending sector, +so a partition from 0 to 5 and a partition from 5 to 10 +do not overlap. +.PP +The Plan 9 partition often contains a number of +conventionally named subpartitions. +They include: +.TF cache +.TP +.B 9fat +A small FAT file system used to hold +configuration information +(such as +.B plan9.ini +and +.BR plan9.nvr ) +and kernels. +This typically begins in the first sector +of the partition, and contains the partition +table as a ``reserved'' sector. +See the discussion of the +.B -r +option to +.IR format . +.TP +.B cache +A +.IR cfs (4) +file system cache. +.TP +.B fs +A +.IR kfs (4) +file system. +.TP +.B swap +A +.IR swap (8) +swap partition. +.PD +.PP +.I Fdisk +edits the PC partition table and is usually +invoked with a disk like +.B /dev/sdC0/data +as its argument, while +.I prep +edits the Plan 9 partition table +and is usually invoked with a disk partition +like +.B /dev/sdC0/plan9 +as its argument. +.I Fdisk +works in units of disk ``cylinders'': the cylinder +size in bytes is printed when +.I fdisk +starts. +.I Prep +works in units of disk sectors, which are almost always 512 bytes. +.I Fdisk +and +.I prep +share most of their options: +.TP +.B -a +Automatically partition the disk. +.I Fdisk +will create a Plan 9 +partition in the largest unused area on the disk, +doing nothing if a +Plan 9 partition already exists. +If no other partition on the disk is marked active (i.e. marked as the boot partition), +.I fdisk +will mark the new partition active. +.I Prep +will create +.BR 9fat , +.BR swap , +and +.B fs +partitions, doing +nothing if the disk +has already been partitioned. +If the +.B -c +option is present, +.I prep +will also create a +.B cache +partition. +If the +.B -n +option is present, +.I prep +will create a one-sector +.B nvram +partition. +.TP +.B -b +Start with a blank disk, ignoring any extant partition table. +.TP +.B -p +Print a sequence of commands that when sent to the disk device's +.B ctl +file +will bring the partition +table information kept by +the +.IR sd (3) +driver up to date. +Then exit. +.I Prep +will check to see if it is being called with a disk partition +(rather than an entire disk) as its argument; if so, it +will translate the printed sectors by the partition's offset +within the disk. +Since +.I fdisk +operates on a table of unnamed partitions, +it assigns names based on the partition type +(e.g., +.BR plan9 , +.BR dos , +.BR ntfs , +.BR linux , +.BR linuxswap ) +and resolves collisions by appending a numbered suffix. +(e.g., +.BR dos , +.BR dos.1 , +.BR dos.2 ). +.TP +.B -r +In the absence of the +.B -p +and +.B -w +flags, +.I prep +and +.I fdisk +enter an interactive partition editor; +the +.B -r +flag runs the editor in read-only mode. +.TP +.BI -s " sectorsize" +Specify the disk's sector size. +In the absence of this flag, +.I prep +and +.I fdisk +look for a disk +.B ctl +file and read it to find the disk's sector size. +If the +.B ctl +file cannot be found, a message is printed and +a sector size of 512 bytes is assumed. +.TP +.B -w +Write the partition table to the disk and exit. +This is useful when used in conjunction with +.B -a +or +.BR -b . +.PP +If neither the +.B -p +flag nor the +.B -w +flag is given, +.I prep +and +.I fdisk +enter an interactive partition editor that +operates on named partitions. +The PC partition table distinguishes between +primary partitions, which can be listed in the boot +sector at the beginning of the disk, +and secondary (or extended) partitions, arbitrarily +many of which may be chained together in place +of a primary partition. +Primary partitions are named +.BR p \fIn\fR, +secondary partitions +.BR s \fIn\fR. +The number of primary partitions plus number of contiguous chains of +secondary partitions cannot exceed four. +.PP +The commands are as follows. +In the descriptions, read ``sector'' as ``cylinder'' when using +.IR fdisk . +.TP +.B "a\fR \fIname\fR [ \fIstart\fR [ \fIend\fR ] ]" +Create a partition named +.I name +starting at sector offset +.I start +and ending at offset +.IR end . +The new partition will not be created if +it overlaps an extant partition. +If +.I start +or +.I end +are omitted, +.I prep +and +.I fdisk +will prompt for them. +.I Start +and +.I end +may be expressions using the operators +.BR + , +.BR - , +.BR * , +and +.BR / , +numeric constants, and the +pseudovariables +.B . +and +.BR $ . +At the start of the program, +.B . +is set to zero; each time a partition is +created, it is set to the end sector +of the new partition. +It can also be explicitly set using the +.B . +command. +When evaluating +.IR start , +.B $ +is set to one past the last disk sector. +When evaluating +.IR end , +.B $ +is set to the maximum value that +.I end +can take on without running off the disk +or into another partition. +Finally, the expression +.IB n % +evaluates to +.RI ( n × disksize )/100. +As an example, +.B a +.B . +.B .+20% +creates a new partition starting at +.B . +that takes up a fifth of the disk, +and +.B a +.B 1000 +.B $ +creates a new partition starting at +sector 1000 and +extending as far as possible. +.TP +.B ".\fR \fInewdot" +Set the value of the variable +.B . +to +.IR newdot , +which is an arithmetic expression as described +in the discussion of the +.B a +command. +.TP +.BI d " name" +Delete the named partition. +.TP +.B h +Print a help message listing command synopses. +.TP +.B p +Print the disk partition table. +Unpartitioned regions are also listed. +The table consists of a number of lines containing +partition name, beginning and ending sectors, +and total size. +A +.B ' +is prefixed to the names of partitions +whose entries have been modified but not written to disk. +.I Fdisk +adds to the end of each line a textual partition type, +and places a +.B * +next to the name of the active partition +(see the +.B A +command below). +.TP +.B P +Print the partition table in the format accepted by the disk's +.B ctl +file, which is also the format of the output of the +.B -p +option. +.TP +.B w +Write the partition table to disk. +.I Prep +will also inform the kernel of the changed +partition table. +The write will fail if any programs have any +of the disk's partitions open. +If the write fails (for this or any other reason), +.I prep +and +.I fdisk +will attempt to restore the partition table to +its former state. +.TP +.B q +Quit the program. +If the partition table has been modified but not written, +a warning is printed. +Typing +.B q +again will quit the program. +.PP +.I Fdisk +also has the following commands. +.TP +.BI A " name" +Set the named partition active. +The active partition is the one whose boot block is used +when booting a PC from disk. +.TP +.B e +Print the names of empty slots in the partition table, i.e., the +valid names to use when creating a new partition. +.PD +.PP +.I Format +prepares for use the floppy diskette or hard disk partition in the file named +.IR disk , +for example +.B /dev/fd0disk +or +.BR /dev/sdC0/9fat . +The options are: +.TP +.B -f +Do not physically format the disc. Used +to install a FAT file system on a +previously formatted disc. If +.I disk +is not a floppy device, this flag is a no-op. +.TP +.B -t +specify a density and type of disk to be prepared. +The possible +.I types +are: +.RS +.TP +.B 3½DD +3½" double density, 737280 bytes +.TP +.B 3½HD +3½" high density, 1474560 bytes +.TP +.B 5¼DD +5¼" double density, 368640 bytes +.TP +.B 5¼HD +5¼" high density, 1146880 bytes +.TP +.B hard +fixed disk +.PD +.PP +The default when +.I disk +is a floppy drive is the highest possible on the device. +When +.I disk +is a regular file, the default is +.BR 3½HD . +When +.I disk +is an +.IR sd (3) +device, the default is +.BR hard . +.RE +.TP +.B -d +initialize a FAT file system on the +.IR disk . +.TP +.B -b +use the contents of +.I bootblock +as a bootstrap block +to be installed in sector 0. +.PD +.PP +The remaining options have effect only when +.B -d +is specified: +.TP +.B -c +use a FAT cluster size of +.I csize +sectors when creating the FAT. +.TP +.B -l +add a +.I label +when creating the FAT file system. +.TP +.BI -r +mark the first +.I nresrv +sectors of the partition as ``reserved''. +Since the first sector always contains the +FAT parameter block, this really marks +the +.IR nresrv -1 +sectors starting at sector 1 as ``reserved''. +When formatting the +.B 9fat +partition, +.B -r +.B 2 +should be used to jump over the partition table sector. +.PD +.PP +Again under +.BR -d , +any +.I files +listed are added, in order, +to the root +directory of the FAT file system. The files are +contiguously allocated. +If a file is named +.BR 9load , +it will be created with the +.B SYSTEM +attribute set so that +.IR dossrv (4) +keeps it contiguous when modifying it. +.PP +.I Format +checks for a number of common mistakes; in particular, +it will refuse to format a +.B 9fat +partition unless +.B -r +is specified with +.I nresrv +larger than two. +It also refuses to format a raw +.IR sd (3) +partition that begins at offset zero in the disk. +(The beginning of the disk should contain an +.I fdisk +partition table with master boot record, +not a FAT file system or boot block.) +Both checks are disabled by the +.B -x +option. +The +.B -v +option prints debugging information. +.PP +The file +.B /386/pbs +is an example of a suitable +.I bfile +to make the disk a boot disk. +It gets loaded by the BIOS at 0x7C00, +reads the root directory into address 0x7E00, and looks at +the first root directory entry. +If that file is called +.BR 9LOAD , +it uses +single sector reads to load the file into address 0x10000 and then +jumps to the loaded file image. +The file +.B /386/pbslba +is similar, but because it uses LBA addressing (not supported +by all BIOSes), it can access more than the first 8.5GB of the disk. +.PP +.I Mbr +installs a new boot block in sector 0 (the master boot record) +of a disk such as +.BR /dev/sdC0/data . +This boot block should not be confused with the +boot block used by +.IR format , +which goes in sector 0 of a partition. +Typically, the boot block in the master boot record +scans the PC partition table to find an active +partition and then executes the boot block for +that partition. +The partition boot block then loads a bootstrap +program such as +.IR 9load (8), +which then loads the operating system. +If MS-DOS or Windows 9[58] is already installed +on your hard disk, the master boot record +already has a suitable boot block. +Otherwise, +.B /386/mbr +is an appropriate +.IR mbrfile . +It detects and uses LBA addressing when available +from the BIOS (the same could not +be done in the case of +.B pbs +due to space considerations). +If the +.I mbrfile +is not specified, a boot block is installed that +prints a message explaining that the disk is not bootable. +.SH EXAMPLES +Initialize the kernel disk driver with the partition information +from the FAT boot sectors. +If Plan 9 partitions exist, pass that partition information as well. +.IP +.EX +for(disk in /dev/sd??) { + if(test -f $disk/data && test -f $disk/ctl) + disk/fdisk -p $disk/data >$disk/ctl + for(part in $disk/plan9*) + if(test -f $part) + disk/prep -p $part >$disk/ctl +} +.EE +.PP +Create a Plan 9 boot floppy on a previously formatted diskette: +.IP +.EX +disk/format -b /386/pbs -df /dev/fd0disk /386/9load /tmp/plan9.ini +.EE +.PP +Initialize the blank hard disk +.BR /dev/sdC0/data . +.IP +.EX +disk/mbr -m /386/mbr /dev/sdC0/data +disk/fdisk -baw /dev/sdC0/data +disk/prep -baw /dev/sdC0/plan9 +disk/format -b /386/pbs -d -r 2 /dev/sdC0/9fat 9load 9pcdisk plan9.ini +.EE +.PP +.SH SOURCE +.B /sys/src/cmd/disk/prep +.br +.B /sys/src/boot/pc +.SH SEE ALSO +.IR floppy (3), +.IR sd (3), +.IR 9load (8) +.SH BUGS +.I Format +can create FAT12 and FAT16 +file systems, but not FAT32 file systems. +The boot block can only read from +FAT12 and FAT16 file systems. diff --git a/static/plan9-4e/man8/qer.8 b/static/plan9-4e/man8/qer.8 new file mode 100644 index 00000000..93d6ed6a --- /dev/null +++ b/static/plan9-4e/man8/qer.8 @@ -0,0 +1,226 @@ +.TH QER 8 +.SH NAME +qer, runq \- queue management for spooled files +.SH SYNOPSIS +.B qer +[ +.B -q +.I subdir +] +[ +.B -f +.I file +] +.I root tag reply args +.br +.B runq +[ +.B -adsE +] +[ +.B -f +.I file +] +[ +.B -q +.I subdir +] +[ +.B -l +.I load +] +[ +.B -t +.I time +] +[ +.B -r +.I nfiles +] +[ +.B -n +.I nprocs +] +.I root cmd +.SH DESCRIPTION +.I Qer +creates a control and a data file in a queue directory. +The control file contents consist of the +.IR tag , +.IR reply , +and +.I args +separated by spaces. +The data file contains the standard input to +.IR qer . +The files are created in the directory +.IR root / subdir , +where +.I subdir +is the argument to +.B -q +if present, else the contents of +.BR /dev/user . +The names of the control and data files differ only +in the first character which is `C' and `D' respectively. +.IR Mktemp (2) +is used to create the actual names of the control and +data file. +.P +Some commands, such as +.I fax +(see +.IR telco (4)), +must queue more files than just the data file. +Each +.I file +following a +.B \-f +flag is copied into the queue directory. The names +of the copies differ from the name of the data file +only in the first character. The first one is +starts with 'F', the second 'G', etc. +.P +.I Runq +processes the files queued by +.IR qer . +Without the +.B -a +option, +.I runq +processes all requests in the directory +.IR root / subdir , +where +.I subdir +is the argument to +.B -q +if present, else the contents of +.BR /dev/user . +With the +.B -a +it processes all requests. +Each request is processed by executing the command +.I cmd +with the contents of the control file as its arguments, +the contents of the data file as its standard input, and +standard error appended to the error file +.BR E.XXXXXX . +.P +The action taken by +.I runq +depends on the return status of +.IR cmd . +If +.I cmd +returns a null status, the processing is assumed successful and the +control, data, and error files are removed. +If +.I cmd +returns an error status containing the word +.LR Retry , +the files are left to be reprocessed at a later time. +For any other status, an error message is mailed +to the requester and the files are removed. +.I Runq +uses the +.I reply +field in the control file as +a mail address to which to send an error notification. +The notification contains the contents of the control +file to identify the failed request. +.P +To avoid reprocessing files too often, the following algorithm is used: +a data file younger than one hour will not be processed if its +error file exists and was last modified within the preceding 10 minutes. +A data file older than one hour will not be processed if its error +file exists and was last modified within the preceding hour. +The +.B -E +flag causes all files to be reprocessed regardless of +the file times. +.P +The +.B -d +option causes debugging output on standard error +describing the progress through the queues. +.P +The +.B -t +flags specifies the number of hours +that retries will continue after a send +failure. The default is 48 hours. +.P +The +.BR -r +flag limits the number of files that are processed in a single pass of a queue. +.I Runq +accumulates the entire directory containing a queue before processing any +files. When a queue contains many files and the system does not +have enough memory, +.I runq +exits without making progress. This flag forces +.I runq +to process the directory in chunks, allowing the queue to +be drained incrementally. It is most useful in combination with the +.I -q +flag. +.P +The +.BR -s , +.BR -n , +and +.B -l +flags are only meaningful with the +.B -a +flag. They control amount of parallelism that +is used when sweeping all of the queues. The argument following the +.B -n +flag specifies the number of queues that are swept +in parallel; the default is 50. The argument following the +.B -l +flag specifies the total number of queues that are being swept. +By default, there is no limit. The number of active sweeps +is cumulative over all active executions of +.IR runq . +The +.B -s +flag forces each queue directory to be processed by exactly +one instance of +.IR runq . +This is useful on systems that connect to slow +external systems and prevents all the queue sweeps from +piling up trying to process a few slow systems. +.PP +.I Runq +is often called from +.IR cron (8) +by an entry such as +.IP +.EX +0,10,20,30,40,50 * * * * kremvax + runq -a /mail/queue /mail/lib/remotemail +.EE +.LP +The entry must be a single line; it is folded here only so it fits on the page. +.SH FILES +.TF \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX +.TP +.B \fIroot\fP/\fIuser\fP +queue directory for +.I user +.TP +.B \fIroot\fP/\fIuser\fP/D.XXXXXX +data file +.TP +.B \fIroot\fP/\fIuser\fP/C.XXXXXX +control file +.TP +.B \fIroot\fP/\fIuser\fP/E.XXXXXX +error file +.TP +.B \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX +secondary data files +.SH SOURCE +.B /sys/src/cmd/upas/q +.SH "SEE ALSO" +.IR mail (1) diff --git a/static/plan9-4e/man8/rdarena.8 b/static/plan9-4e/man8/rdarena.8 new file mode 100644 index 00000000..071011ab --- /dev/null +++ b/static/plan9-4e/man8/rdarena.8 @@ -0,0 +1,30 @@ +.TH RDARENA 8 +.SH NAME +rdarena \- extract a Venti arena +.SH SYNOPSIS +.B venti/rdarena +[ +.B -v +] +.I venti.config +.I arena +.SH DESCRIPTION +.I Rdarena +extracts the named +.I arena +from the Venti system described by the +.IR venti.conf (6) +file +.I venti.config +and writes this arena to standard output. +This command is typically used to back up an arena to external media. +The +.B -v +option generates more verbose output on standard error. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti (8) +.SH BUGS +There is currently no way to restore a Venti system from a collection of extracted +arenas. diff --git a/static/plan9-4e/man8/reboot.8 b/static/plan9-4e/man8/reboot.8 new file mode 100644 index 00000000..0dd8f4d5 --- /dev/null +++ b/static/plan9-4e/man8/reboot.8 @@ -0,0 +1,20 @@ +.TH REBOOT 8 +.SH NAME +reboot \- reboot the system upon loss of remote file server connection +.SH SYNOPSIS +.B aux/reboot +[ +.I file +] +.SH DESCRIPTION +.I Reboot +stats +.IR file , +default +.BR /$\fIcputype\fP/init , +once a minute. If the stat times out, +.I reboot +reboots the system. This is used to restart diskless cpu +servers whenever their file server connection is broken. +.SH SOURCE +.B /sys/src/cmd/aux/reboot.c diff --git a/static/plan9-4e/man8/replica.8 b/static/plan9-4e/man8/replica.8 new file mode 100644 index 00000000..fa578c2a --- /dev/null +++ b/static/plan9-4e/man8/replica.8 @@ -0,0 +1,303 @@ +.TH REPLICA 8 +.SH NAME +applychanges, applylog, compactdb, updatedb \- simple client-server replica management +.SH SYNOPSIS +.B replica/compactdb +.I db +.br +.B replica/updatedb +[ +.B -cl +] +[ +.B -p +.I proto +] +[ +.B -r +.I root +] +[ +.B -t +.I now +.I n +] +[ +.B -u +.I uid +] +[ +.B -x +.I path +] ... +.I db +.br +.B replica/applylog +[ +.B -cnsuv +] +.I clientdb +.I clientroot +.I serverroot +[ +.I path ... +] +.br +.B replica/applychanges +[ +.B -nuv +] +[ +.B -p +.I proto +] +[ +.B -x +.I path +] ... +.I clientdb +.I clientroot +.I serverroot +[ +.I path ... +] +.SH DESCRIPTION +These four tools collectively provide simple log-based +client-server replica management. +The shell scripts described in +.IR replica (1) +provide a more polished interface. +.PP +Both client and server maintain textual databases of file system +metadata. Each line is of the form +.sp 0.5 +\h'0.25i' +.I path +.I mode +.I uid +.I gid +.I mtime +.I length +.sp 0.5 +Later entries for a +.I path +supersede previous ones. +A line with the string +.B REMOVED +in the +.I mode +field annuls all previous entries for that +.IR path . +The entries in a file are typically kept sorted by +.I path +but need not be. +These properties facilitate updating the database atomically +by appending to it. +.I Compactdb +reads in a database and writes out an equivalent one, +sorted by path and without outdated or annulled records. +.PP +A replica is further described on the server by a textual +log listing creation and deletion of files and changes +to file contents and metadata. +Each line is of the form: +.sp 0.5 +\h'0.25i' +.I time +.I gen +.I verb +.I path +.I serverpath +.I mode +.I uid +.I gid +.I mtime +.I length +.sp 0.5 +The +.I time +and +.I gen +fields are both decimal numbers, providing an ordering +for log entries so that incremental tools need not process +the whole log each time they are run. +The +.IR verb , +a single character, +describes the event: +addition of a file +.RB ( a ), +deletion of a file +.RB ( d ), +a change to a file's contents +.RB ( c ), +or a change to a file's metadata +.RB ( m ). +.I Path +is the file path on the client; +.I serverpath +the path on the server (these are different when the +optional fifth field in a proto file line is given; +see +.IR proto (2)). +.IR Mode , +.IR uid , +.IR gid , +and +.I mtime +are the files metadata as in the +.B Dir +structure (see +.IR stat (5)). +For deletion events, the metadata is that of the deleted file. +For other events, the metadata is that after the event. +.PP +.I Updatedb +scans the file system rooted at +.I root +for changes not present in +.IR db , +noting them by appending new entries to the database +and by writing log events to standard output. +The +.B -c +option causes +.I updatedb +to consider only file and metadata changes, ignoring file additions and deletions. +By default, the log events have +.I time +set to the current system time +and use incrementing +.I gen +numbers starting at 0. +The +.B -t +option can be used to specify a different time and starting number. +If the +.B -u +option is given, all database entries and log events will use +.I uid +rather than the actual uids. +The +.B -x +option (which may be specified multiple times) excludes the named path +and all its children from the scan. +If the +.B -l +option is given, the database is not changed and the +.I time +and +.I gen +fields are omitted from the log events; +the resulting output is intended to be a human-readable +summary of file system activity since the last scan. +.PP +.I Applylog +is used to propagate changes from server to client. +It applies the changes listed in a log +(read from standard input) +to the file system rooted at +.IR clientroot , +copying files when necessary from the file system rooted at +.IR serverroot . +By default, +.I replapplylog +does not attempt to set the uid on files; the +.B -u +flag enables this. +.I Applylog +will not overwrite local changes made to replicated files. +When it detects such conflicts, by default it prints an error describing +the conflict and takes no action. +If the +.B -c +flag is given, +.I replapplylog +still takes no action, but does so silently and will not +report the conflicts in the future. +(The conflict is resolved in favor of the client.) +If the +.B -s +flag is given, +.I replapplylog +overwrites the local changes. +(The conflict is resolved in favor of the server.) +.PP +.I Applychanges +is, in some sense, the opposite of +.IR applylog ; +it scans the client file system for changes, and applies +those changes to the server file system. +.I Applychanges +will not overwrite remote changes made to replicated files. +For example, if a file is copied from server to client and subsequently +changed on both server and client, +.I applychanges +will not copy the client's new version to the server, because +the server also has a new version. +.I Applychanges +and +.I applylog +detect the same conflicts; to resolve conflicts reported by +.IR applychanges , +invoke +.I applylog +with the +.B -c +or +.B -s +flags. +.SH EXAMPLE +One might +keep a client kfs file system up-to-date +against a server file system using these tools. +First, connect to a CPU server with a high-speed +network connection to the file server and scan +the server file system, updating the server database and log: +.EX + repl=$home/lib/replica + proto=/sys/lib/sysconfig/proto/portproto + db=$repl/srv.portproto.db + log=$repl/srv.portproto.log + + 9fs $fs + replica/updatedb -p $proto -r /n/$fs -x $repl $db >>$log + replica/compactdb $db >/tmp/a && mv /tmp/a $db +.EE +.PP +Then, update the client file system: +.EX + repl=$home/lib/replica + db=$repl/cli.portproto.db + log=$repl/srv.portproto.log + + 9fs $fs + 9fs kfs + replica/applylog $db /n/kfs /n/$fs <$log + replica/compactdb $db >/tmp/a && mv /tmp/a $db +.EE +.PP +The +.B $repl +directory is excluded from the sync so that multiple +clients can each have their own local database. +The shell scripts in +.B /rc/bin/replica +are essentially a further development of this example. +.PP +The Plan 9 distribution update program +operates similarly, but omits the first scan; +it is assumed that the Plan 9 developers run +scans manually when the distribution +file system changes. +The manual page +.IR replica (1) +describes this in full. +.SH SEE ALSO +.IR replica (1) +.SH BUGS +These tools assume that +.I mtime +combined with +.I length +is a good indicator of changes to a file's contents. diff --git a/static/plan9-4e/man8/scanmail.8 b/static/plan9-4e/man8/scanmail.8 new file mode 100644 index 00000000..ce639f72 --- /dev/null +++ b/static/plan9-4e/man8/scanmail.8 @@ -0,0 +1,447 @@ +.TH SCANMAIL 8 +.SH NAME +scanmail, testscan \- spam filters +.SH SYNOPSIS +.B upas/scanmail +[ +.I options +] +[ +.I qer-args +] +.I root +.B mail +.I sender system rcpt-list +.PP +.B upas/testscan +[ +.B -avd +] +[ +.B -p +.I patfile +] +[ +.I filename +] +.SH DESCRIPTION +.B Scanmail +accepts a mail message supplied on standard input, +applies a file of patterns to a portion of it, +and dispatches +the message based +on the results. +It exactly replaces the +generic queuing command +.IR qer (8) +that is executed from the +.IR rc (1) +script +.B /mail/lib/qmail +in the mail processing pipeline. +Associated with each pattern is an +.I action +in order of decreasing priority: +.in +5 +.TP 10 +.B dump +the message is deleted and a log entry is written to +.B /sys/log/smtpd +.TP 10 +.B hold +the message is placed in a queue for human inspection +.TP +.B log +a line containing the matching portion of the message is written to a log +.in -5 +.PP +If no pattern matches or only patterns with an action of +.B log +match, the message is accepted and +.I scanmail +queues the message for delivery. +.I Scanmail +meshes with the blocking facilities +of +.IR smtpd (6) +to provide several layers of +filtering on gateway systems. In all cases the sender +is notified that the message has been successfully +delivered, +leaving the sender unaware that the message has been potentially delayed or deleted. +.PP +.I Scanmail +accepts the arguments of +.IR qer (8) +as well as the following: +.TF filename +.TP +.B -c +Save a copy of each message in a +randomly-named file in +directory +.BR /mail/copy . +.TP +.B -d +Write debugging information to standard error. +.TP +.B -h +Queue +.I held +messages by sending domain name. +The +.B -q +option must specify a root directory; messages +are queued in subdirectories of this directory. +If the +.B -h +option is not specified, +messages are accumulated in a subdirectory of +.B /mail/queue.hold +named for the contents of +.BR /dev/user , +usually +.BR none . +.TF filename +.TP +.B -n +Messages are never held for inspection, but are delivered. Also known as +.IR "vacation mode" . +.TP +.BI -p " filename" +Read the patterns from +.I filename +rather than +.BR /mail/lib/patterns . +.TP +.BI -q " holdroot" +Queue deliverable messages in subdirectories of +.IR holdroot . +This option is the same as the +.B -q +option of +.IR qer (8) +and must be present if the +.B -h +option is given. +.TP +.B -s +Save deleted +messages. Messages are stored, one per randomly-named file, +in subdirectories of +.B /mail/queue.dump +named with the date. +.TP +.B -t +Test mode. The pattern matcher is applied but the message is +discarded and the result is not logged. +.TP +.B -v +Print the highest priority match. +This is useful +with the +.B -t +option for testing the pattern matcher without actually +sending a message. +.PD +.PP +.I Testscan +is the command line version of +.IR scanmail . +If +.I filename +is missing, it applies the pattern set to +the message on standard input. Unlike +.IR scanmail , +which finds the highest priority match, +.I testscan +prints all matches in the portion of the message under test. +It is useful for testing a pattern set or +implementing a personal filter +using the +.B pipeto +file in a user's mail directory. +.I Testscan +accepts the following options: +.TP +.B -a +Print matches in the complete input message +.TP +.B -d +Enable debug mode +.TP +.B -v +Print the message after conversion to canonical form +.RI ( q.v. ). +.TP +.BI -p " filename" +Read the patterns from +.I filename +rather than +.BR /mail/lib/patterns . +.SS Canonicalization +Before pattern matching, both programs convert a portion of +the message header and the beginning of the +message to a canonical form. The amount of the header +and message body processed are set by +compile-time parameters in the source files. +The canonicalization process converts letters to lower-case and +replaces consecutive spaces, tabs and newline characters +with a single space. HTML commands are +deleted except for the parameters following +.B A +.BR HREF , +.B IMG +.BR SRC , +and +.B IMG +.B BORDER +directives. Additionally, the following MIME escape sequences +are replaced by their ASCII +equivalents: +.PP +.EX + Escape Seq ASCII + ---------- ----- + =2e . + =2f / + =20 + =3d = +.EE +and the sequence +.I = +is elided. +.I Scanmail +assembles the sender, destination domain and recipient fields of +the command line into a string that is +subjected to the same canonical processing. +Following canonicalization, the command line and +the two long strings containing +the header and the message body are passed to the +matching engine for analysis. +.SS Pattern Syntax +The matching engine compiles the pattern set +and matches it to each canonicalized input string. +Patterns are specified one per line +as follows: +.PP +.EX + {*}\fIaction\fP: \fIpattern-spec\fP {~~\fIoverride\fP...~~\fIoverride\fP} +.EE +.PP +On all lines, a +.B # +introduces a comment; there is no way to escape this character. +.PP +Lines beginning with +.B * +contain a +.I pattern-spec +that is a string; otherwise, the the +.I pattern-spec +is a regular expression in the style of +.IR regexp (6). +Regular expression matching is many +times less efficient than string matching, so it is +wiser to enumerate several similar strings +than to combine them into a regular expression. +The +.I action +is a keyword terminated by a +.B : +and separated from the pattern by optional white-space. +It must be one of the following: +.TP 10 +.B dump +if the pattern matches, the message is deleted. If the +.B -s +command line option is set, the message is saved. +.TP 10 +.B hold +if the pattern matches, the message is queued in a subdirectory +of +.B /mail/queue.hold +for manual inspection. After inspection, the queue can be swept +manually using +.B runq +(see +.IR qer (8)) +to deliver messages that were inadvertently matched. +.TP 10 +.B header +this is the same as the +.B hold +action, except the pattern is only applied to the message header. +This optimization is useful for patterns that match header fields +that are unlikely to be present in the body of the message. +.TP 10 +.B line +the sender and a section of the message around the match are written to +the file +.BR /sys/log/lines . +The message is always delivered. +.TP 10 +.B loff +patterns of this type are applied only to the canonicalized command line. +When a match occurs, all patterns with +.B line +actions are disabled. This is useful for limiting +the size of the log file by excluding repetitive messages, such +as those from mailing lists. +.PP +Patterns are accumulated into pattern sets sharing the same action. +The matching engine applies the +.B dump +pattern set first, then the +.B header +and +.B hold +pattern sets, and finally the +.B line +pattern set. Each pattern set is applied three times: +to the canonicalized command line, to the message header, and +finally to the message body. The ordering of patterns +in the pattern file is insignificant. +.PP +The +.I pattern-spec +is a string of characters terminated by a +.BR newline , +.B # +or override indicator, +.BR ~~ . +Trailing white-space is deleted but +patterns containing leading or trailing white-space can +be enclosed in double-quote +characters. A pattern containing a double-quote +must be enclosed in double-quote +characters and preceded by a backslash. +For example, the pattern +.PP +.EX + "this is not \\"spam\\"" +.EE +.PP +matches the string \fLthis is not "spam"\fP. +The +.I pattern-spec +is followed by zero or more +.I override +strings. When the specific pattern matches, +each override is applied and +if one matches, it cancels the effect of the pattern. +Overrides must be strings; regular expressions are not supported. +Each override is introduced by the string +.BR ~~ +and continues until a subsequent +.BR ~~ , +.B # +or +.BR newline , +white-space included. +A +.B ~~ +immediately followed by a +.B newline +indicates a line continuation and further overrides continue +on the following line. +Leading white-space +on the continuation line is ignored. For example, +.PP +.EX + *hold: sex.com~~essex.com~~sussex.com~~sysex.com~~ + lasex.com~~cse.psu.edu!owner-9fans +.EE +.PP +matches all input containing the string +.B sex.com +except for messages that also contain the +strings in the override list. Often it +is desirable to override a pattern based on +the name of the sender or +recipient. For this reason, each override +pattern is applied to the header and the command line as well +as the section of the +canonicalized input containing the matching data. +Thus a pattern matching the command line or the header +searches both the command line and the header +for overrides while a match in the body searches +the body, header and command line for overrides. +.PP +The structure of the pattern file and the matching +algorithm define the strategy for detecting +and filtering unwanted messages. Ideally, a +.B hold +pattern selects a message for inspection and if it +is determined to be undesirable, a specific +.B dump +pattern is added to delete further instances +of the message. Additionally, it is often +useful to block the sender by updating the +.B smtpd +control file. +.PP +In this regime, patterns with a +.I dump +action, generally match phrases +that are likely to be unique. Patterns that +hold a message for inspection +match phrases commonly found in undesirable material and +occasionally in legitimate messages. Patterns +that log matches are less specific yet. In all +cases the ability to override a pattern by +matching another string, allows repetitive messages +that trigger the pattern, such as mailing lists, +to pass the filter after the first one is processed +manually. The +.B -s +option allows deleted messages to be salvaged +by either manual or semi-automatic review, supporting +the specification of more aggressive patterns. +Finally, the utility of the pattern matcher is not +confined to filtering spam; it is a generally useful +administrative tool for deleting inadvertently harmful +messages, for example, mail loops, stuck senders or viruses. +It is also useful for collecting or counting messages +matching certain criteria. +.SH FILES +.TF /mail/queue.dump/* +.TP +.B /mail/lib/patterns +default pattern file +.TP +.B /sys/log/smtpd +log of deleted messages +.TP +.B /mail/log/lines +file where +.I log +matches are logged +.TP +.B /mail/queue/* +directories where legitimate messages are queued for delivery +.TP +.B /mail/queue.hold +directory where held messages are queued for inspection +.TP +.B /mail/queue.dump/* +directory where +.I dumped +messages are stored when the +.B -s +command line option is specified. +.TP +.B /mail/copy/* +directory where copies of all incoming messages +are stored. +.SH SOURCE +.TP +.B /sys/src/cmd/upas/scanmail +.SH "SEE ALSO" +.IR mail (1), +.IR qer (8), +.IR smtpd (6) +.SH BUGS +.I Testscan +does not report a match when the body of a message +contains exactly one line. diff --git a/static/plan9-4e/man8/scuzz.8 b/static/plan9-4e/man8/scuzz.8 new file mode 100644 index 00000000..2aed5c94 --- /dev/null +++ b/static/plan9-4e/man8/scuzz.8 @@ -0,0 +1,370 @@ +.TH SCUZZ 8 +.SH NAME +scuzz \- SCSI target control +.SH SYNOPSIS +.B scuzz +[ +.B -q +] +[ +[ +.B -r +] +.I sddev +] +.SH DESCRIPTION +.I Scuzz +is an interactive program for exercising +raw SCSI devices. +Its intended purpose is to investigate and manipulate +odd devices without the effort of writing a special driver, +such as shuffling the media around on an optical jukebox. +It reads commands from standard input and applies them to a SCSI target +(other devices accessed through the +.IR sd (3) +interface, +such as ATA(PI) devices, +may also work). +If +.I sddev +is given on the command line, an +.B open +(see below) +is immediately applied to the target. +On successful completion of a command, +.BI ok " n +is printed, where +.I n +is the number of bytes transferred to/from the target; +the +.B -q +command line option suppresses the +.B ok +message. +.SS Commands +.TP +.BI help " command +.B Help +is rudimentary and prints a one line synopsis for the named +.IR command , +or for all commands if no argument is given. +.TP +.B probe +.B Probe +attempts an +.B inquiry +command on all SCSI units, +and prints the result preceded by the name of those +targets which respond. +.LP +The +.B help +and +.B probe +commands may be given at any time. +.TP +.BI open\ [ -r ] sddev +.B Open +must be given before any of the remaining commands will be accepted. +Internally, +unless the +.B -r +option is given, +.B open +issues +.B ready +then +.BR inquiry , +followed by a device class-specific command to determine the +logical block size of the target. +.I Sddev +is an +.IR sd (3) +device directory like +.IR /dev/sdC0 . +.TP +.B close +.B Close +need only be given if another target is to be opened in the current +session. +.LP +The remaining commands are in rough groups, +intended for specific classes of device. +With the exception of the +.BR read , +.BR write , +and +.B space +commands, +all arguments are in the style of ANSI-C integer constants. +.TP +.B ready +Test Unit Ready +checks if the unit is powered up and ready to do +.B read +and +.B write +commands. +.TP +.B rezero +Rezero +Unit requests that a disk be brought to a known state, +usually by seeking to track zero. +.TP +.B rewind +.B Rewind +positions a tape at the beginning of current partition +(there is usually only one partition, the beginning of tape). +.TP +.B reqsense +Request Sense retrieves Sense Data concerning an error or +other condition and is usually issued following the completion of a command +that had check-condition status. +.I Scuzz +automatically issues a +.B reqsense +in response to a check-condition status and prints the result. +.TP +.B format +Format +Unit performs a ``low level'' format of a disk. +.TP +.B rblimits +Read Block Limits +reports the possible block lengths for the logical unit. Tapes only. +.TP +.BI read " file nbytes +.B Read +transfers data from the target to the host. +A missing +.I nbytes +causes the entire device to be read. +.TP +.BI write " file nbytes +.B Write +transfers data from the host to the target. +A missing +.I nbytes +causes the entire input file to be transferred. +.IP +The first argument to the +.BR read +and +.BR write +commands specifies a source +.RB ( write ) +or destination +.RB ( read ) +for the I/O. +The argument is either a plain file name or +.B | +followed by a command to be executed by +.IR rc (1). +The argument may be quoted in the style of +.IR rc (1). +.TP +.BI seek " offset whence +.B Seek +requests the target to seek to a position on a disk, +arguments being in the style of +.IR seek (2); +.I whence +is 0 by default. +.IP +.I Scuzz +maintains an internal notion of where the current target +is positioned. +The +.BR seek , +.BR read , +.BR write , +.BR rewind , +.BR rezero , +and +.B wtrack +commands all manipulate the internal offset. +.TP +.BI filemark " howmany +Write Filemarks +writes one (default) or more filemarks on a tape. +.TP +.BI space\ [ -b ]\ [ -f ]\ [[ "--\fP]\fIhowmany\fP]" +.B Space +positions a tape forwards or backwards. +The arguments +specify logical block +.RB ( -b ) +or +filemark +.RB ( -f ) +spacing; +default is +.BR -b . +If +.I howmany +is negative +it specifies spacing backwards, +and should be preceded by +.B -- +to turn off any further +option processing. +Default is 1. +.TP +.B inquiry +.B Inquiry +is issued to determine the device type of a particular target, +and to determine some basic information about the implemented options and +the product name. +.TP +.BI modeselect bytes... +.TP +.BI modeselect6 bytes... +Mode +Select +is issued to set variable parameters in the target. +.I Bytes +given as arguments comprise all the data for the target; +see an appropriate manual for the format. +The default is the 10-byte form of the command; +modeselect6 is the 6-byte version. +.TP +.BI modesense\ [ page [ nbytes ]] +.TP +.BI modesense6\ [ page [ nbytes ]] +Mode +Sense +reports variable and fixed parameters from the target. +If no +.I page +is given, +all pages are returned. +.I Nbytes +specifies how many bytes should be returned. +The default is the 10-byte form of the command; +modesense6 is the 6-byte version. +.TP +.BI start\ [ code ] +.TP +.BI stop\ [ code ] +.TP +.BI eject\ [ code ] +.TP +.BI ingest\ [ code ] +.BR Start , +.BR stop , +.BR eject , +and +.B ingest +are synonyms for Start/Stop Unit with different default values of +.IR code . +Start/Stop Unit is typically used to spin up and spin down a rotating +disk drive. +.I Code +is 0 to stop, +1 to start and +3 to eject (if the device supports ejection of the medium). +.TP +.B capacity +Read Capacity reports the number of blocks and the block +size of a disk. +.LP +The following commands are specific to CD and CD-R/RW devices. +A brief description of each is given; see the SCSI-3 +Multimedia Commands (MMC) Specification for details of arguments +and interpretation of the results. +.TP +.BI blank\ [ track/LBA [ type ]] +Erase a CD-RW disk. +Type identifies the method and coverage of the blanking. +.TP +.BI rtoc\ [ track/session-number [ ses ]] +The Read TOC/PMA command transfers data from one of the tables of contents +(TOC or PMA) on the CD medium. +.TP +.B rdiscinfo +(Note the spelling.) +Provides information about disks, including incomplete CD-R/RW. +.TP +.BI rtrackinfo\ [ track ] +Provides information about a track, regardless of its status. +.TP +.B cdpause +.TP +.B cdresume +Pause/resume playback. +.TP +.B cdstop +Stop playback. +.TP +.BI cdplay\ [ track-number ]\ or\ [ -r [ "LBA\fP[\fIlength\fP]]]" +Play audio. +With no arguments, starts at the beginning of the medium. +If a track number is given, the table of contents is read +to find the playback start point. +If the +.B -r +option is given, block addressing is used to find the +playback start point. +.TP +.BI cdload\ [ slot ] +.TP +.BI cdunload\ [ slot ] +Load/unload a disk from a changer. +.TP +.B cdstatus +Read the mechanism status. +.LP +The following commands are specific to Media Changer devices. +A brief description of each is given; see the SCSI-3 +Medium Changer Commands (SMC) Specification for details of arguments. +.TP +.B einit +Initialize element status. +.TP +.BI estatus type [ length ] +Report the status of the internal elements. +Type 0 reports all element types. +.TP +.BI mmove transport\ source\ destination [ invert ] +Move medium. +.SH FILES +.TF /dev/sdXX/raw +.TP +.B /dev/\fIsdXX\fP/raw +raw SCSI interface for command, I/O, and status. +.SH SOURCE +.B /sys/src/cmd/scuzz +.SH "SEE ALSO" +.IR sd (3) +.br +.IR "Small Computer System Interface - 2 (X3T9.2/86-109)" , +Global Engineering Documents +.br +.IR "SCSI Bench Reference" , +ENDL Publications +.br +.IR "SCSI-3 Multimedia Commands (MMC) Specification" , +www.t10.org +.br +.IR "SCSI-3 Medium Changer Commands (SMC) Specification" , +www.t10.org +.SH BUGS +Only a limited subset of SCSI commands has been implemented (as needed). +.LP +Only one target can be open at a time. +.LP +LUNs other than 0 are not supported. +.LP +No way to force 6- or 10- byte commands. +.LP +Should be recoded to use +.IR scsi (2) +in order to get more complete sense code descriptions. +.LP +.I Scuzz +betrays its origins by spelling +.B rdiscinfo +with a +.B c +even though the devices it manipulates are spelled with a +.BR k . diff --git a/static/plan9-4e/man8/secstore.8 b/static/plan9-4e/man8/secstore.8 new file mode 100644 index 00000000..33835184 --- /dev/null +++ b/static/plan9-4e/man8/secstore.8 @@ -0,0 +1,47 @@ +.TH SECSTORE 8 +.SH NAME +secstored, secuser \- secstore commands +.SH SYNOPSIS +.br +.B auth/secstored +[-S servername] +[-s tcp!*!5356] +[-x] +.br +.B auth/secuser +username +.br +.PP +.SH DESCRIPTION +.PP +.I Secstored +serves requests from +.IR secstore (1). +The +.B -x +option announces on +.B /net.alt/tcp!*!5356 +instead of the default +.BR /net . +.PP +.I Secuser +is an administrative command that runs on the +secstore machine, normally the authserver, +to create new accounts and +to change status on existing accounts. +It prompts for account information such as +password and expiration date, writing to +.BR /adm/secstore/who/$uid . +.SH FILES +.B /adm/secstore/who/$uid +secstore account name, expiration date, verifier +.br +.B /adm/secstore/store/$uid/ +users' files +.br +.B /lib/ndb/auth +for mapping local userid to RADIUS userid +.SH SOURCE +.B /sys/src/cmd/auth/secstore +.SH SEE ALSO +.IR secstore (1) diff --git a/static/plan9-4e/man8/securenet.8 b/static/plan9-4e/man8/securenet.8 new file mode 100644 index 00000000..cdd4f23d --- /dev/null +++ b/static/plan9-4e/man8/securenet.8 @@ -0,0 +1,128 @@ +.TH SECURENET 8 +.SH NAME +securenet \- Digital Pathways SecureNet Key remote authentication box +.SH DESCRIPTION +The +.I SecureNet +box is used to authenticate connections to Plan 9 from a foreign system +such as a +Unix +machine or plain terminal. +The box, which looks like a calculator, +performs DES encryption with a key held in its memory. +Another copy of the key is kept on the authentication server. +Each box is protected from unauthorized use by a four digit PIN. +.PP +When the system requires SecureNet authentication, +it prompts with a numerical challenge. +The response is compared to one +generated with the key stored on the authentication server. +Respond as follows: +.PP +Turn on the box and enter your PIN at the +.B EP +prompt, +followed by the +.B ENT +button. +Enter the challenge at +.B Ed +prompt, +again followed +.BR ENT . +Then type to Plan 9 the response generated by the box. +If you make a mistake at any time, reset the box +by pressing +.BR ON . +The authentication server compares the response generated by the box +to one computed internally. If they match, the user is accepted. +.PP +The box will lose its memory if given the wrong PIN +five times in succession or if its batteries are removed. +.PP +To reprogram it, type a +.B 4 +at the +.B E0 +prompt. +.PP +At the +.B E1 +prompt, enter your key, which consists of eight three-digit octal numbers. +While you are entering these digits, +the box displays a number ranging from 1 to 8 on the left side of the display. +This number corresponds to the octal number you are entering, +and changes when you enter the first digit of the next number. +.PP +When you are done entering your key, press +.B ENT +twice. +.PP +At the +.B E2 +prompt, enter a PIN for the box. +.PP +After you confirm by retyping the PIN at the +.B E3 +prompt, you can use the box as normal. +.PP +You can change the PIN using the following procedure. +First, turn on the box and enter your current PIN at the +.B EP +prompt. +Press +.B ENT +three times; +this will return you to the +.B EP +prompt. +Enter your PIN again, followed by +.BR ENT ; +you should see a +.B Ed +prompt with a +.B - +on the right side of the display. +Enter a +.B 0 +and press +.BR ENT . +You should see the +.B E2 +prompt; follow the instructions above for entering a PIN. +.PP +The +.I SecureNet +box +performs the same encryption as the +.B netcrypt +routine +(see +.IR encrypt (2)). +The entered challenge, a decimal number between 0 and 100000, +is treated as a text string with trailing binary zero fill to 8 bytes. +These 8 bytes are encrypted with the DES algorithm. +The first four bytes are printed on the display as hexadecimal numbers. +However, when set up as described, +the box does not print hexadecimal digits greater than 9. +Instead, it prints a 2 for an A, B, or C, and a 3 for a D, E, or F. +If a +.B 5 +rather than a +.B 4 +is entered at the +.B E0 +print, the hexadecimal digits are printed. +This is not recommended, as letters are +too easily confused with digits on the +.I SecureNet +display. +.SH "SEE ALSO" +.IR encrypt (2), +.IR auth (2) +.br +Digital Pathways, Mountain View, California +.SH BUGS +The box is clumsy to use and too delicate. +If carried in a pocket, +it can turn itself on and wear out the batteries. diff --git a/static/plan9-4e/man8/snoopy.8 b/static/plan9-4e/man8/snoopy.8 new file mode 100644 index 00000000..cc4e225a --- /dev/null +++ b/static/plan9-4e/man8/snoopy.8 @@ -0,0 +1,170 @@ +.TH SNOOPY 8 +.SH NAME +snoopy \- spy on network packets +.SH SYNOPSIS +.B snoopy +[ +.B -?stdC +] [ +.B -f +.I filter-expression +] [ +.B -N +.I n +] [ +.B -h first-header +] [ +packet-file +] +.SH DESCRIPTION +.PP +.I Snoopy +reads packets from a packet source (default +.BR /net/ether0 ), +matches them to a filter (by default anything matches), and writes +matching packets to standard output either in human readable form (default) +or in a binary trace format that can be reinput to +.IR snoopy . +.PP +The human readable format consists of multiple lines per packet. +The first line contains the milliseconds since the +trace was started. Subsequent ones are indented with a tab +and each contains the dump of a single protocol header. The last line +contains the dump of any contained data. For example, a +.SM BOOTP +packet would look like: +.sp +.EX +324389 ms + ether(s=0000929b1b54 d=ffffffffffff pr=0800 ln=342) + ip(s=135.104.9.62 d=255.255.255.255 id=5099 frag=0000... + udp(s=68 d=67 ck=d151 ln= 308) + bootp(t=Req ht=1 hl=16 hp=0 xid=217e5f27 sec=0 fl=800... + dhcp(t=Request clientid=0152415320704e7266238ebf01030... +.EE +.PP +The binary format consists of: +.IP +2 bytes of packet length, msb first +.IP +8 bytes of nanosecond time, msb first +.IP +the packet +.PP +Filters are expressions specifying protocols to be traced +and specific values for fields in the protocol headers. +The grammar is: +.sp +.EX +expr : protocol + | field '=' value + | protocol '(' expr ')' + | '(' expr ')' + | expr '||' expr + | expr '&&' expr +.EE +.PP +The values for and can +be obtained using the +.B -? +option. It will list each known protocol, +which subprotocols it can multiplex to, +and which fields can be used for filtering. +For example, the listing for ethernet is currently: +.sp +.EX +ether's filter attr: + s - source address + d - destination address + a - source|destination address + t - type +ether's subprotos: + ip + arp + rarp + ip6 +.EE +.PP +The format of depends on context. In general, +ethernet addresses are entered as a string of hex +digits; IP numbers in the canonical `.' format for v4 and `:' format +for v6; and ports in decimal. +.PP +.IR Snoopy 's +options are: +.TP +.B -t +input is a binary trace file. The default assumes +a packet device, one packet per read. +.TP +.B -d +output will be a binary trace file. The default is +human readable. +.TP +.B -s +force one output line per packet. The +default is multiline. +.TP +.B -C +compute correct checksums and if doesn't match +the contained one, add a field +.B !ck=\fIxxxx\fP +where +.I xxxx +is the correct checksum. +.TP +.B -N +dump +.I n +data bytes per packet. The default is 32. +.TP +.B -f +use +.I filter-exression +to filter the packet stream. The default is +to match all packets. +.TP +.B -h +assume the first header per packet to be +.IR first-header . +The default is +.IR ether . +.SH EXAMPLES +the following would display only +.SM BOOTP +and +.SM ARP +packets: +.sp +.EX +% snoopy -f 'arp | bootp' +after optimize: ether( arp | ip( udp( bootp ) ) ) +.EE +.PP +The first line of output shows the completed filter +expression. +.I Snoopy +will fill in other protocols as necessary to complete +the filter and then optimize to remove redundant +comparisons. +.PP +To save all packets between 135.104.9.2 to 135.104.9.6 and +later display those to/from TCP port 80: +.sp +.EX +% ramfs +% snoopy -df 'ip(s=135.104.9.2&d=135.104.9.6)|\\ + ip(s=135.104.9.6&d=135.104.9.2)' > /tmp/quux + +% snoopy -tf 'tcp(sd=80)' /tmp/quux +.EE +.SH FILES +.TP +.B /net/ether +Ethernet device +.SH SOURCE +.B /sys/src/cmd/ip/snoopy +.SH BUGS +At the moment it only dumps ethernet packets because there's +no device to get IP packets without the media header. This will +be corrected soon. diff --git a/static/plan9-4e/man8/stats.8 b/static/plan9-4e/man8/stats.8 new file mode 100644 index 00000000..97716d6c --- /dev/null +++ b/static/plan9-4e/man8/stats.8 @@ -0,0 +1,145 @@ +.TH STATS 8 +.SH NAME +stats \- display graphs of system activity +.SH SYNOPSIS +.B stats +[ +.BI - option +] +[ +.I machine +\&... +] +.SH DESCRIPTION +.I Stats +displays a rolling graph of various statistics collected by the operating +system and updated once per second. +The statistics may be from a remote +.I machine +or multiple +.IR machines , +whose graphs will appear in adjacent columns. +The columns are labeled by the machine names and the number +of processors on the machine if it is a multiprocessor. +.PP +The right mouse button presents a menu to enable and disable the display +of various statistics; by default, +.I stats +begins by showing the load average on the executing machine. +.PP +The +lower-case +.I options +choose the initial set to display: +.TF [t]tlbpurge +.TP +.B "b battery +percentage battery life remaining. +.TP +.B "c context +number of process context switches per second. +.TP +.B +.B "e ether +total number of packets sent and received per second. +.TP +.B +.B "E etherin,out +number of packets sent and received per second, displayed as separate graphs. +.TP +.B "f fault +number of page faults per second. +.TP +.B "i intr +number of interrupts per second. +.TP +.B "l load +(default) system load average. +The load is computed as a running average of +the number of processes ready to run, multiplied by 1000. +.TP +.B "m mem +total pages of active memory. +The graph displays the fraction +of the machine's total memory in use. +.TP +.B +.B "n etherin,out,err +number of packets sent and received per second, and total number of errors, displayed as separate graphs. +.TP +.B "p tlbpurge +number of translation lookaside buffer flushes per second. +.TP +.B "s syscall +number of system calls per second. +.TP +.B "t tlbmiss +number of translation lookaside buffer misses per second. +.TP +.B "w swap +number of valid pages on the swap device. +The swap is displayed as a +fraction of the number of swap pages configured by the machine. +.TP +.B "8 802.11b +display the signal strength detected by the 802.11b wireless ether card; the value +is usually below 50% unless the receiver is in the same room as the transmitter, so +a midrange value represents a strong signal. +.PD +.PP +The graphs are plotted with time on the horizontal axis. +The vertical axes range from 0 to 1000, multiplied by the number of processors on the machine +when appropriate. +The only exceptions are +memory +and swap space, +which display fractions of the total available, and the Ethernet error count, +which goes from 0 to 10.. +If the value of the parameter is too large for the visible range, its value is shown +in decimal in the upper left corner of the graph. +.PP +Upper-case options control details of the display. +All graphs are affected; there is no mechanism to +affect only one graph. +.TP +.BI -S " scale +Sets a scale factor for the displays. A value of 2, for example, +means that the highest value plotted will be twice as large as the default. +.TP +.B -L +Plot all graphs with logarithmic +.I y +axes. +The graph is plotted so the maximum value that would be displayed on +a linear graph is 2/3 of the way up the +.I y +axis and the total range of the graph is a factor of 1000; thus the +.I y +origin is 1/100 of the default maximum value and the top of the graph is +10 times the default maximum. +.TP +.B -Y +If the display is large enough to show them, +place value markers along the +.I y +axes of the graphs. +Since one set of markers serves for all machines across the display, +the values in the markers disregard scaling factors due to multiple processors +on the machines. On a graph for a multiprocessor, +the displayed values will be larger +than the markers indicate. +The markers appear along the right, and the markers +show values appropriate to the rightmost machine; this only +matters for graphs such as memory that have machine-specific +maxima. +.PD +.SH FILES +.B /net/ether0/0/stats +.br +.B #c/swap +.br +.B #c/sysstat +.SH SOURCE +.B /sys/src/cmd/stats.c +.SH BUGS +Some machines do not have TLB hardware. diff --git a/static/plan9-4e/man8/swap.8 b/static/plan9-4e/man8/swap.8 new file mode 100644 index 00000000..09cea94a --- /dev/null +++ b/static/plan9-4e/man8/swap.8 @@ -0,0 +1,30 @@ +.TH SWAP 8 +.SH NAME +swap \- establish a swap file +.SH SYNOPSIS +.B swap +.I file +.SH DESCRIPTION +.I Swap +establishes a file or device for the system to swap on. +If +.I file +is a device, the device is used directly; if a directory, +a unique file is created in that directory on which to swap. +The environment variable +.B swap +is set to the full name of the resulting file. +The number of blocks available in the file or device +must be at least the number of swap blocks configured +at system boot time. +.PP +If a swap channel has already been set and no blocks +are currently valid in the file the old file will be +closed and then replaced. If any blocks are valid on +the device an error is returned instead. +.SH SOURCE +.B /sys/src/cmd/swap.c +.SH BUGS +Swapping to a file served by a user-level process, such as +.IR kfs (4), +can lead to deadlock; use raw devices or remote files instead. diff --git a/static/plan9-4e/man8/timesync.8 b/static/plan9-4e/man8/timesync.8 new file mode 100644 index 00000000..dcfd09a7 --- /dev/null +++ b/static/plan9-4e/man8/timesync.8 @@ -0,0 +1,95 @@ +.TH TIMESYNC 8 +.SH NAME +timesync \- synchronize the system clock to a time source +.SH SYNOPSIS +.B aux/timesync +[ +.B -a +.I accuracy +] +[ +.B -s +.I netroot +] +[ +.B -frnDdLil +] +[ +.I timeserver +] +.SH DESCRIPTION +.B Aux/timesync +synchronizes the system clock to a time source, by default a +file server. +The options are: +.TP +.B -f +synchronize to a file server. If +.I timeserver +is missing, use +.BR /srv/boot . +.TP +.B -r +synchronize to the local real time clock, +.BR #r/rtc . +.TP +.B -L +used with +.B -r +to indicate the real time clock is in +local time rather than GMT. This is +useful on PCs that also run the +Windows OS. +.TP +.B -n +synchronize to an NTP server. If +.I timeserver +is missing, dial the server +.BR udp!$ntp!ntp . +.TP +.B -D +print debugging to standard error +.TP +.B -d +put file containing last determined clock +frequency in directory +.IR dir , +default +.BR /tmp . +.TP +.B -i +stands for impotent. +.I Timesync +announces what it would do but doesn't do it. +This is useful for tracking alternate time sources. +.TP +.B -a +specifies the +.I accuracy +in nanoseconds to which the +clock should be synchronized. This determines +how often the reference clock is accessed. +.TP +.B -s +causes +.I timesync +to listen for UDP NTP requests on the +network rooted at +.IR netroot . +Up to 4 +.B -s +options are allowed. +.TP +.B -l +turns on logging to +.BR /sys/log/timesync . +.SH FILES +.TF /tmp/ts...timeserver +.TP +.B /tmp/ts...timeserver +where the last frequency guess is kept +.TP +.B /sys/log/timesync +log file +.SH SOURCE +.B /sys/src/cmd/aux/timesync.c diff --git a/static/plan9-4e/man8/tlssrv.8 b/static/plan9-4e/man8/tlssrv.8 new file mode 100644 index 00000000..fc23426b --- /dev/null +++ b/static/plan9-4e/man8/tlssrv.8 @@ -0,0 +1,38 @@ +.TH TLSSRV 8 +.SH NAME +tlssrv \- TLS server +.SH SYNOPSIS +.PP +.B tlssrv +.RB [ -k +.IR keydir ] +.RB [ -l +.IR logfile ] +.RB [ -r +.IR remotesys ] +target +.SH DESCRIPTION +.I Tlssrv +is a helper program, typically exec'd in a +.B /bin/service/ +file to establish an SSL or TLS connection before launching +the target server, for example IMAPS or HTTPS. +.PP +.I Keydir +holds the server certificate and private key. +.PP +The specified +.I logfile +is by convention the same as for the target server. +.I Remotesys +is mainly used for logging. When invoked from +.B /bin/service/ +it is written +.B -r'{cat +.BR $3/remote} . +.SH FILES +.TF /sys/lib/ssl +.SH SOURCE +.B /sys/src/cmd/tlssrv.c +.SH "SEE ALSO" +.IR listen (8) diff --git a/static/plan9-4e/man8/udpecho.8 b/static/plan9-4e/man8/udpecho.8 new file mode 100644 index 00000000..60117974 --- /dev/null +++ b/static/plan9-4e/man8/udpecho.8 @@ -0,0 +1,16 @@ +.TH UDPECHO 8 +.SH NAME +udpecho \- echo UDP packets +.SH SYNOPSIS +.PP +.B ip/udpecho +[ +.B -x +.I ext +] +.SH DESCRIPTION +.PP +Listen on UDP port 7 and echo back any packets +received. +This should only be run for testing since it can +be used to disguise the identity of someone doing a denial of service attack. diff --git a/static/plan9-4e/man8/update.8 b/static/plan9-4e/man8/update.8 new file mode 100644 index 00000000..2519f213 --- /dev/null +++ b/static/plan9-4e/man8/update.8 @@ -0,0 +1,127 @@ +.TH UPDATE 8 +.SH NAME +bootfloppy, bootplan9, bootwin9x, bootwinnt, personalize, setup.9fat, setup.disk, +setup.kfs, update \- administration for local file systems +.SH SYNOPSIS +.B pc/bootfloppy +.I floppydisk +.I plan9.ini +.br +.B pc/bootplan9 +.I /dev/sdXX +.br +.B pc/bootwin9x +.br +.B pc/bootwinnt +.br +.B pc/personalize +.br +.B pc/setup.9fat +.I /dev/sdXX/9fat +.I plan9.ini +.br +.B pc/setup.disk +.I /dev/sdXX +.I plan9.ini +.br +.B pc/update +.PD +.SH DESCRIPTION +These programs help maintain a file system on a local disk for a private machine. +.PP +.I Setup.disk +partitions a disk +and makes a new file system on the disk. +It then calls +.IR setup.9fat , +.IR update , +and +.I personalize +to initialize the file system. +.PP +.I Setup.9fat +formats the named +.I 9fat +partition, +installing +.BR /386/9load , +.BR /386/9pcdisk , +and the named +.I plan9.ini +file. +.PP +.I Update +copies the current kernel to the disk and updates +files on the local file system by copying them from the main file server +(named by the environment variable +.BR $fileserver ). +The files it updates are specified by the +.IR mkfs (8) +prototype file +.BR /sys/lib/sysconfig/proto/386proto . +.PP +.I Personalize +removes the contents of the +.B /usr +directory on the local disk and copies a minimal set of files for +the user who runs the command. +.PP +The boot scripts prepare various ways to bootstrap Plan 9. +.I Bootfloppy +creates a boot floppy containing +.BR 9load , +a zeroed 512-byte +.BR plan9.nvr , +and the named file as +.BR plan9.ini . +.I Bootplan9 +sets the +.B 9fat +partition to be the active partition, the one +used at boot time. +.I Bootwin9x +edits the files +.BR config.sys , +.BR msdos.sys , +and +.B autoexec.bat +on the drive mounted by +.B c: +to provide Plan 9 +as a boot menu option. +These system files are first backed up +as +.BR config.p9 , +.BR msdos.p9 , +and +.BR autoexec.p9 . +.I Bootwinnt +edits the Windows NT +boot loader menu contained in +the first FAT partition's +.I boot.ini +to provide Plan 9 +as an option. +It is first backed up as +.IR boot.p9 . +If backup files already exist, +.I bootwin9x +and +.I bootwinnt +do nothing. +.SH FILES +.TF /sys/lib/sysconfig/proto/ +.TP +.B /sys/lib/sysconfig/proto/ +.IR Mkfs (8) +prototype files. +.SH SOURCE +.B /rc/bin/pc/* +.SH "SEE ALSO" +.IR kfs (4), +.IR 9load (8), +.IR mkfs (8), +.IR prep (8), +.IR sd (3) +.br +``Installing the Plan 9 Distribution''. diff --git a/static/plan9-4e/man8/venti.8 b/static/plan9-4e/man8/venti.8 new file mode 100644 index 00000000..91bc9b99 --- /dev/null +++ b/static/plan9-4e/man8/venti.8 @@ -0,0 +1,196 @@ +.TH VENTI 8 +.SH NAME +venti \- an archival block storage server +.SH SYNOPSIS +.B venti/venti +[ +.B -dw +] +[ +.B -a +.I ventiaddress +] +[ +.B -B +.I blockcachesize +] +[ +.B -c +.I config +] +[ +.B -C +.I cachesize +] +[ +.B -h +.I httpaddress +] +[ +.B -I +.I icachesize +] +.SH DESCRIPTION +.I Venti +is a block storage server intended for archvial data. +In a Venti server, +the Sha1 hash of a block's contents acts as the block +identifier for read and write operations. +This approach enforces a write-once policy, preventing accidental or +malicious destruction of data. In addition, duplicate copies of a +block are coalesced, reducing the consumption of storage and +simplifying the implementation of clients. +.PP +Storage for +.I venti +consists of a data log and an index, both of which +can be spread across multiple files. +The files containing the data log are themselves divided into self-contained sections called arenas. +Each arena contains a large number of data blocks and is sized to +facilitate operations such as copying to removable media. +The index provides a mapping between the a Sha1 fingerprint and +the location of the corresponding block in the data log. +.PP +The index and data log are typically stored on raw disk partitions. +To improve the robustness, the data log should be stored on +a device that provides RAID functionality. The index does +not require such protection, since if necessary, it can +can be regenerated from the data log. +The performance of +.I venti +is typically limited to the random access performance +of the index. This performance can be improved by spreading the +index accross multiple disks. +.PP +The storage for +.I venti +is initialized using +.IR fmtarenas (8), +.IR fmtisect (8), +and +.IR fmtindex (8). +A configuration file, +.IR venti.conf (6), +ties the index sections and data arenas together. +.PP +A Venti +server is accessed via an undocumented network protocol. +Two client applications are included in this distribution: +.IR vac (1) +and +.IR vacfs (4). +.I Vac +copies files from a Plan 9 file system to Venti, creating an +archive and returning the fingerprint of the root. +This archive can be mounted in Plan 9 using +.IR vacfs . +These two commands enable a rudimentary backup system. +A future release will include a Plan 9 file system that uses +Venti as a replacement for the WORM device of +.IR fs (4). +.PP +The +.I venti +server provides rudimentary status information via +a built-in http server. The URL files it serves are: +.TP +.B stats +Various internal statistics. +.TP +.B index +An enumeration of the index sections and all non empty arenas, including various statistics. +.TP +.B storage +A summary of the state of the data log. +.TP +.B xindex +An enumeration of the index sections and all non empty arenas, in XML format. +.PP +Several auxiliary utilities aid in maintaining the storage for Venti. +With the exception of +.IR rdarena (8), +these utilities should generally be run after killing the +.I venti +server. +The utilities are: +.TP +.IR checkarenas (8) +Check the integrity, and optionally fix, Venti arenas. +.TP +.IR checkindex (8) +Check the integrity, and optionally fix, a Venti index +.TP +.IR buildindex (8) +Rebuild a Venti index. +.TP +.IR rdarena (8) +Extract a Venti arena and write to standard output. +.PP +Options to +.I venti +are: +.TP +.BI -a " ventiaddress +The network address on which the server listens for incoming connections. +The default is +.LR tcp!*!venti . +.TP +.BI -B " blockcachesize +The size, in bytes, of memory allocated to caching raw disk blocks. +.TP +.BI -c " config +Specifies the +Venti +configuration file. +Defaults to +.LR venti.conf . +.TP +.BI -C " cachesize +The size, in bytes, of memory allocated to caching +Venti +blocks. +.TP +.BI -d +Produce various debugging information on standard error. +.TP +.BI -h " httpaddress +The network address of Venti's built-in +http +server. +The default is +.LR tcp!*!http . +.TP +.BI -I " icachesize +The size, in bytes, of memory allocated to caching the index mapping fingerprints +to locations in +.IR venti 's +data log. +.TP +.B -w +Enable write buffering. This option increase the performance of writes to +.I venti +at the cost of returning success to the client application before the +data has been written to disk. Use of this option is recommended. +.PP +Note, the units for the various cache sizes above can be specified by appending a +.LR k , +.LR m , +or +.LR g +to indicate kilobytes, megabytes, or gigabytes respectively. +.SH SOURCE +.B /sys/src/cmd/venti +.SH "SEE ALSO" +.IR venti.conf (6), +.IR fmtarenas (8), +.IR fmtisect (8), +.IR fmtindex (8), +.IR vac (1), +.IR vacfs (4). +.IR checkarenas (8), +.IR checkindex (8), +.IR buildindex (8), +.IR rdarena (8) +.br +Sean Quinlan and Sean Dorward, +``Venti: a new approach to archival storage''. diff --git a/static/plan9-4e/man8/vga.8 b/static/plan9-4e/man8/vga.8 new file mode 100644 index 00000000..5344f328 --- /dev/null +++ b/static/plan9-4e/man8/vga.8 @@ -0,0 +1,189 @@ +.TH VGA 8 +.SH NAME +vga \- configure a VGA card +.SH SYNOPSIS +.B aux/vga +[ +.B -BcdilpvV +] +[ +.B -b +.I bios-string +] +[ +.B -m +.I monitor +] +[ +.B -x +.I file +] +[ +.I mode +[ +.I size +] +] +.SH DESCRIPTION +.B Aux/vga +configures a VGA controller for various display sizes and depths. +Using the monitor type specified in +.B /env/monitor +(default +.BR vga ) +and the +.I mode +given as argument +(default +.BR 640x480x1 ), +.B aux/vga +uses the database of known VGA controllers and monitors in +.B /lib/vgadb +(see +.IR vgadb (6)) +to configure +the display via the devices provided by +.IR vga (3). +The options are: +.TP +.BI -b " bios-string" +use the VGA database entry corresponding to +.I bios-string +(e.g. +\fL0xC0045="Stealth 64 DRAM Vers. 2.02"\fR) +rather than looking for identifying strings in the BIOS +memory. +.TP +.B -B +dump the BIOS memory (in hex) to standard output and exit. +.TP +.B -c +disable the use of the hardware graphics cursor. +(Since there is no software cursor, this disables the cursor entirely.) +.TP +.B -d +include the color palette in whatever actions are performed, +usually printing the contents. +.TP +.B -i +when used with +.B -p +display the register values that will be loaded. +.TP +.B -l +load the desired mode. +.TP +.BI -m " monitor" +override the +.B /env/monitor +value. +.B /env/monitor +is usually set by including it in the +.B plan9.ini +file read by the PC boot program +.IR 9load (8). +.TP +.B -p +print the current or expected register values at appropriate points depending on +other options. +.TP +.B -v +print a trace of the functions called. +.TP +.B -V +print a verbose trace of the functions called. +.TP +.B -x " file" +use +.I file +as the VGA database rather than +.BR /lib/vgadb . +.PP +.I Mode +is of the form +.IB X x Y x Z +, where +.IR X , +.IR Y , +and +.I Z +are numbers specifying the display height, width, and depth respectively. +The mode must appear in +.B /lib/vgadb +as a value for one of the monitor entries. +The usual modes are +.BR 640x480x[18] , +.BR 800x600x[18] , +.BR 1024x768x[18][i] , +.BR 1280x1024x[18][i] , +.BR 1376x1024x8 , +and +.BR 1600x1200x8 . +A trailing +.L i +indicates interlaced operation. +The default mode is +.BR 640x480x8 . +.I Size +is of the form +.I X x Y +and configures the display to have a virtual +screen of the given size. +The physical screen will pan to follow the mouse. +This is useful on displays with small screens, +such as laptops, but can be confusing. +.SH EXAMPLES +Change the display resolution: +.IP +.EX +aux/vga -l 1600x1200x8 +.EE +.PP +Print the current VGA controller registers. +It is usually best to redirect the output of a +.B -p +command to a file to prevent confusion caused by using the VGA +controller while trying to dump its state: +.IP +.EX +aux/vga -p >/tmp/x +.EE +.PP +Force the VGA controller to a known state: +.IP +.EX +aux/vga -m vga -l +.EE +.PP +Print the current VGA controller state and what would be loaded +into it for a new resolution, but don't do the load: +.IP +.EX +aux/vga -ip 1376x1024x8 >/tmp/x +.EE +.PP +.SH FILES +.TF /env/monitor +.TP +.B /env/monitor +display type (default +.IR vga ). +.TP +.B /lib/vgadb +VGA configuration file. +.SH SOURCE +.B /sys/src/cmd/aux/vga +.SH SEE ALSO +.IR vga (3), +.IR vgadb (6), +.IR 9load (8) +.SH BUGS +.B Aux/vga +makes every effort possible to verify that the mode it is about +to load is valid and will bail out with an error message +before setting any registers if it encounters a problem. +However, things can go wrong, especially when playing with a +new VGA controller or monitor setting. +It is useful in such cases to have +the above command for setting the controller to a known state +at your fingertips. -- cgit v1.2.3